Verification Flow
From the prior pages, you should now have the authorization code for the user. This is either the QR code value for in-person or the redirect code you receive in your handler for the standard digital flow.
You can now fetch the authentication details for the user, by exchanging the code and valid app configuration details. Be sure to keep the client secret secret. The response will contain all authentication details, including a verificationResponse.
Verifying Ownership Requirements and Claim Criteria
IMPORTANT: Note ownership requirements and claims must be checked server-side. The additional parameters specified in the URL / client-side are just for display purposes and are not cached with the request and may potentially be manipulated by a malicious user.
For ownership requirements, you should specify them via options.ownershipRequirements. Alternatively, you could self check requirements yourself.
For claims, you must specify the claimId. If it is a non-indexed (on-demand) claim, you can just use the simulateClaim option to simulate and check criteria at verify time. Alternatively, you can use the checkClaimedMinOnce flag to see if the user to be signed in has at least one successful claim for that ID. If you need more advanced checks than just >= 1 successful claim or passes simulation, you will have to do that on your end. See the snippet below.
Access Tokens vs None
If you specified API authorization scopes to be able to access, we return access tokens and refresh tokens for you to perform this functionality. In other words, scopes.length > 0.
Otherwise, we do not return anything, and you will just receive the user crypto address in the response. You will then handle everything else on your end (session handling, etc).
If no access tokens are to be needed, we will simply return the user address as the access token for comaptibility with tools (just so the access token is not blank).
See more o the following page.
Verification Example
IMPORTANT: What is verified vs not?
It is important to note that BitBadges only checks from a cryptographic standpoint and does not implement any application specific logic. We handle checking the user's signature and verifying ownership of specified badges / attestations (if any), verifying well-formedness, etc.
Any other custom requirements need to be handled by you separately (e.g. stamping users hands, checking IDs, etc.).
It is also critical that you prevent replay attacks, man-in-the-middle attacks, and flash ownership attacks (if verifying with assets) with best practices.
Proof of address ownership via their authenticated BitBadges account
Asset ownership criteria is met for the address (if requested via options.ownershipRequirements).
Claim criteria was met according to the options provided.
Anything specified in the verify challenge options
Issued at is not too long ago if options.isssuedAtTimeWindowMs is specified. Defaults to 10 minutes.
Additional app-specific criteria needed for signing in
While we do our best to maintain the well-formedness and verification of attestations, attestations might be custom uploaded, be an unsupported schema type, etc, or we might even have a bug. As best practice, you should always verify on your end. Don't trust, verify!
If you need to check BitBadges core ones (scheme == 'bbs' || scheme == 'standard'), you should use the SDK's verifyAttestation function.
If it is a third-party upload, see the corresponding documentation.
Does not check the content of the attestation messages
Does not check if attestation.createdBy is the expected issuer (we check that they validly issued the attestation with correct signatures, but only you know who this is supposed to be).
Does not handle sessions or check any session information. Does not handle any stateful data either (e.g. preventing replay attacks or flash ownership attacks). This should be implemented on your end. You may use information provided like claim numbers, access token expirations, etc to help you in handling your sessions.
If requesting otherSignIns, you should verify that you receive a response (username / ID) for the requested sign-ins and not trust the response blindly. This is a client-side parameter so could potentially be tampered with maliciously. BitBadges verifies requests as-is, so a manipulated request will get a manipulated verification.
Flash Ownership Attacks
If authenticating with assets, you should be aware of flash ownership attacks. Basically, two sign ins at different times would be approved if the badge is transferred between the time of the first sign in and the second one. You may have to implement a one use per badge approach. Or, you can make the badges non-transferable during the time period of sign ins. See here for more information.
Last updated