Overview

A token is a software object which represents the right to perform some operation. For example: you have an authentication system where a user logs on. When the system has authenticated the user, instead of repeating this process for every request, a token is created that represents the fact that the user has the right to access the system. This token is then used in subsequent requests.

Types of tokens in Mobile Connect

Mobile Connect supports two1 tokens types – Identity (ID) Tokens and Access Tokens. Both of these are granted by an operator Identity Gateway (IDGW).

Access Token

Represents the web application’s stateless permission to access the protected resource after successful authorization.

The Access Token is returned during the Get Token call of the Authorization flow. The token should be sent whenever the web application wants to access a protected resource. Once the access token permissions are verified the access token permissions, the web application will be allowed to access the protected resources.

The Access Token can be represented in multiple formats; e.g., it could be a string or a JSON Web Token (JWT).

ID Token

The ID Token contains important security information about the authentication of the end-user.
The user will have provided consent for the release of this information and the information contained in the ID token can be trusted if the application/web service obtaining the token can verify its signature. ID Tokens must be in JSON Web Token (JWT) format (see JSON Web Token (JWT) page for further details).

Features of the ID token:
  • asserts the identity of the user, called subject in OpenID (sub parameter). It contains a globally unique identifier called Pseudonymous Customer Reference (PCR). See The PCR page for further details;
  • specifies the issuing authority, or issuer identifier (iss parameter);
  • is generated for a particular audience, i.e. client (aud parameter);
  • has an issue time (iat parameter) and an expiration time (exp parameter);
  • specifies when (auth_time parameter) and how, in terms of strength (acr parameter), the user was authenticated. See Level of Assurance page for further details about the strength of the authentication;
  • contains a value to associate the application/web service session with the ID Token (nonce parameter);
  • has an Authentication Methods References (AMR) which indicates the authentication method used (amr parameter). See AMR values page for further details;
  • has an access token hash value (at_hash parameter);
  • is digitally signed, so can be verified by the intended recipients;
  • might include additional requested details about the subject, such as name or email address.

ID Token Validation

In order to use the ID Token for the end-user authentication, authorisation or in the requests to the PremiumInfo endpoint in the other Mobile Connect products, the application/web service should perform the validation of the ID Token.

In order to validate an ID Token, you can manually implement all the checks mentioned below. Your application or web-service needs to verify the signature of the token, as well as validate the claims of the token. These steps can be done only after you have retrieved the JSON Web Key Set (JWKS) from the Authorization Server and have decoded the ID Token.

Alternatively, most JWT libraries perform the token validation automatically. Please refer the following page to find the relevant library for your platform and programming language: jwt.io/#libraries-io.

If you opt for the manual validation of the ID Token please follow the steps described below.

  1. Retrieve The JSON Web Key Set

    To validate a JWT, the JSON Web Key Set (JWKS) needs to be retrieved from your Authorization Server and parsed. Your Authorization Server contains the jwks_uri, which you can use to get the JWKS from. JWKS should be checked periodically and cached by your application / web-service.

  2. Decode the ID Token

    Since the ID Token is represented in a JWT format, you will have to decode it in order to read the information it contains (i.e. to see the claims of the token).

    A list of libraries you can use do decode the ID Token can be found on the JWT website: jwt.io/#libraries-io.

  3. Verify the ID Token’s Signature

    Since the ID Token signature always includes the hash of the header and the payload, in order to verify the signature you should know the hashing algorithm specified in the header of the JWT. To check if the signature matches your expectations, decode the JWT and retrieve the alg property of the JWT header.

    You can also use one of the libraries from here: jwt.io/#libraries-io.

  4. Validate the ID Token’s Claims

    Once you verify the ID Token’s signature, the next step is to validate the standard claims of the ID Token’s payload.

    To perform the validation, retrieve the claims from the decoded ID Token and check if they meet the description mentioned in the table below.

  5. Claim

    Usage

    Explanation

    Example

    iss

    REQUIRED

    Issuer Identifier for the Issuer of the response. An Issuer Identifier is a case sensitive URL using the HTTPS scheme that contains scheme, host, and optionally, port number and path components but no query or fragment components. The value of the parameter must exactly match the Issuer Identifier of the IDGW obtained during the Discovery flow.

    https://server.example.com

    sub

    REQUIRED

    Subject identifier. A locally unique identifier of the end-user used by the SP. This identifier is also called the PCR. The value of the sub parameter from the PremiumInfo response must be equal to that from the token response. Please refer to The PCR section for further information on how to handle the PCR.

    24400320

    aud

    REQUIRED

    Intended audience for the ID Token. A valid 'aud' parameter contains client_id of the SP registered at the Issuer identified by the iss (issuer) Claim as an audience. The 'aud' may be presented as an array with more than one element. In this case, the SP should verify that an azp parameter is present.

    s6BhdRkqt3

    exp

    REQUIRED

    Expiration time after which the ID Token must not be accepted for processing. The recommended lifespan for the ID Token is 10 seconds. The value of this parameter represents the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time. The current time must be before the time presented by the exp claim.

    1522329175

    iat

    REQUIRED

    Time when the ID Token was issued. The value if this parameter represents the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time. This claim can be used to reject tokens that were issued too far away from the current time, i.e. the time passed since the issue of the ID Token exceeds the exp value.

    1522329165

    auth_time

    REQUIRED

    Time when the end-user was authenticated. If the time elapsed since the last end-user's authentication is exceeds that indicated by the max_age parameter, then the end-user must be prompted for re-authentication.

    1970-01-01T0:0:0Z

    nonce

    REQUIRED

    This parameter associates the SP's session with the ID Token, to avoid the replay attacks. The value must be same as the nonce used in the Authentication request

    cee18fcb-cb3a-46b9-88ec-6ab79d9d0da0

    at_hash

    REQUIRED

    Hash value of the Access Token. This value of the claim should be equal to the base64url encoding of the left-most 128 bits of the hashed Access Token.

    3HBUgtnyp5IYZTJS_A885g

    acr

    REQUIRED

    Level of Assurance achieved by the IDGW during the authentication flow. The value must be equal to one of those indicated in the acr_values parameter from the Authentication Request.

    2

    amr

    REQUIRED

    Authentication Methods References. This is a string containing the authentication methods used in the Authentication flow. The authentication methods used must be relevant to the Level of Assurance indicated in the acr claim.

    "sms", "user"

    azp

    OPTIONAL

    REQUIRED if the audience to the ID Token is different to the Authorised Party.

    Authorised party (Service Provider, SP) to which the ID Token is issued. The SP must verify that its client_id is the value of this claim.

    GSMA

    displayed_data

    OPTIONAL

    REQUIRED when scope is “openid mc_authz”

    Data displayed on the Authentication device. The value of the claim must contain the values of client_name, binding_message and context parameters from the Authentication request

    henry_tsptestapp0-kyc binding-kyc context

    dts

    OPTIONAL

    REQUIRED when displayed_data is returned and acr_values = 4

    Data signed. The data which was signed with the private key owned by the end-user's SIM card. This parameter is used to validate the Authentication session. The value of the claim should contain the values from the displayed_data and dts_time parameters.

    MFwwDQYJKoZIhvcNAQEBBQAbSUT9/Q2uBfGRau6/XJy

    upk

    OPTIONAL

    REQUIRED when displayed_data is returned and acr_values = 4

    User Public Key or User certificate / reference to the certificate that was used to sign the dts parameter.

    'f6:61:a8:27:35:cf:4c:6d:13:22:70:cf:4c:c8:a0:23'

    dts_time

    OPTIONAL

    REQUIRED when displayed_data is returned and acr_values = 4

    Time when the text was signed. The value of the parameter represents the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time.

    1970-01-01T0:0:0Z

    hashed_login_hint

    REQUIRED

    Hashed login_hint or login_hint_token value to mitigate security threats. If the request is made using login_hint, then the hashed login_hint value must be returned in the hashed_login_hint value. If the request contains login_hint_token parameter, then the IDGW must return hashed login_hint_token value.

    0x0200C6FAAFFE9C6BAA377C6E74DF8FC9819860E54B


    The use of tokens in the authorisation process

    The schema below represents the OpenID Connect authorisation flow. It shows how, with the use of tokens, the application or web service is granted access to protected resources.

     

     

    Pre-condition: the end-user clicks the activation button 'Mobile Connect Log-in' in the application/web service.

    1. The application/web service prepares the OpenID Connect Authentication/Authorisation request and sends it to the Authorisation endpoint at the IDGW, passing the needed data about the end-user and the application/web service2.
    2. The IDGW asks the end-user to authenticate themselves by displaying the appropriate message on the phone screen.
    3. The end-user provides consent and confirms the authentication.
    4. The IGGW generates an Authentication Code and sends it to the application/web service.
    5. The application/web service prepares a token request to the Token endpoint at the IDGW passing the Authentication Code.
    6. The IDGW validates the Authentication Code and generates tokens (the Access Token and the ID Token) and returns them to the application or web service.
    7. If needed, the application/web service calls the UserInfo/PremiumInfo endpoint at the IDGW using the Access Token to prove its right to access the protected resource.
    8. The IDGW respond depends on the Access Token status:
      1. if the Access Token is still valid, the IDGW sends the information required in the call;
      2. if the Access Token has been expired, the IDGW sends the appropriate notification to the application/web service; the process then must start over from the very beginning (step 1).

    1Other token types exist within the OpenID Connect standard (e.g. Refresh Token or Revoke Token) but are not supported by Mobile Connect.

    2Authentication/Authorisation request must contain the query parameters. The values of the query parameters are then define the permissions of the issued Access Token. Please see Mobile Connect API page for further details about the query parameters in the Authentication/Authorisation request.