Key Concepts

ID Tokens

In order to preserve your user's privacy and enable an easier integration with Pinn, our SDKs and web API handle the implementation details of authenticating users on your behalf. To that effect, ID Tokens are used to provide your app backend cryptographic proof that a given user authenticated with a certain set of factors. The way we do that is built around a well-known specification contained in the Open ID Connect framework.

Open ID Connect - ID Token

When you perform auth using our mobile SDK your app will receive an id_token value once a user has successfully authenticated. With our Web SDK the id_token will be POST'ed to an endpoint of your choice for validation. In both scenarios your backend should consume and verifying the ID Token, after which you backend might grant the user a session.

Verifying an ID Token

Before processing any of the ID token claims, your backend MUST verify the ID token cryptographically. The token is signed using the same secret key that your backend uses to communicate with the Pinn API. Once the ID token has been successfully verified, you should inspect the provided claims to identify and authenticate the user.

Essential Claims

The following detail describes required claims in the ID token that will be provided to allow your app to sufficiently identify and authenticate a user.

Claim Description Example
sub The Pinn User ID of the end user that authenticated usr_1vuGMwANshWxwEaCYaeBkBvn
iss The host name of the service that issued the ID token https://pinnapis.com
iat The time at which the token was generated from the issuer 1547237127
exp The time at which the token should be considered expired 1547237157
auth_time The time at which the user began authentication, use iat for the time at which authentication was successfully completed 1547237100
log_id Log identifier that can be used to look up information specific to an authentication event log_3h8hIYgIxX7BbxVFWVYnOGdm
amr This critical claim details a list of all auth methods used for this authentication. You MUST check this claim to enforce that certain auth methods were utilized, if you fail to do so then any valid Pinn token will allow the user to gain access. ["local_biometric", "either_palm"]

The amr claim provides critical proof to your backend on how a user authenticated, you should ensure this claim contains at minimum all the factors you are expecting in a given auth scenario. Our SDKs allow for developers to initiate various auth flows, however it is imperative that your backend enforces the auth factors used via the ID Token.

!

Note

For development you can use a JWT inspector like the one found at jwt.io to dissect and analyze and ID token returned from Pinn

JWT Libraries

We recommend using a published and tested JWT library in the language of your choice to handle Pinn ID tokens, this reduces the friction dramatically when it comes to verifying a token.

Example Implementation

The following code snippet is an example of how an ID token can be verified before processing the claims, your implementation should handle safe storage and access of the Pinn secret key:

    import jwt


    class IDTokenVerificationError(Exception):
        pass


    class IDToken(object):
        """Provides functionality for verifying an incoming Pinn ID token."""

        @staticmethod
        def verify(id_token, amr):
            """
            Validates the signature and ensures all amr values are present in the token.

            If successful all verified claims are returned from this function as a python dictionary.
            """
            secret_key = "<my_secret_key>"
            try:
                claims = jwt.decode(id_token, key=secret_key)
            except Exception as e:
                raise IDTokenVerificationError("Invalid signature: " + str(e))
            if not set(amr).issubset(set(claims['amr'])):
                raise IDTokenVerificationError('`amr` was invalid and did not contain all methods required. Requested: {}, Received: {}'.format(amr, claims['amr']))
            return claims
    

Next

These key concepts will come in handy! Start developing with the mobile platform you prefer, either iOS or Android.

?

Questions?

We are here to help! Contact us with any development related questions at dev@pinn.ai and we'll reach back in a timely manner.