Overview

At the beginning…

Before doing anything

• As Service Provider you have to define:

  • A callback URL to receive authorization codes
  • An application name to be identified by end-users
  • Success and error callback URLs for Fast Tracking (optional)

• With this information, Mobile Connect will provide you with:

  • Application credentials: client_id and client_secret
  • 3 end-points: authorization, token and userinfo URLs

  • Security keys:

    • ID Token signature key
    • Login hint encryption key (optional)

Authorization Request

Authorization Request: Considerations

• Service Provider will identify each authentication by “state” and “nonce” parameters

  • They should be random and unique for every authentication

• Login hint generation (optional):

  1. Take msisdn including country code without “+” character
  2. Add a “|” character and random characters till completing a 128-byte string
  3. Encrypt the string by using RSA algorithm (PKCS1 v1.5 scheme) with the public key provided by Mobile Connect
  4. Serialize the resulting binary in hexadecimal representation
  5. Add “ENCR_MSISDN:” prefix to serialized string

Authorization Code

Authorization Code: Considerations

• “state” parameter value should match an existing authentication transaction in Service Provider

• If any error happened during the authentication process, the redirection URI would receive the following parameters:

  • state
  • error
  • error_description

Authorization Token: Considerations

• HTTP Basic authentication. The Authorization header is constructed as follows:

  • The client_id and client_secret are combined with a single colon
  • The resulting string is encoded using the RFC2045-MIME variant of Base64
  • The authorization method “Basic” and a space is then put before the encoded string

Token Response

{
"access_token": "SlAV32hkKG",
"token_type": "Bearer",
"refresh_token": "8xLOxBtZp8",
"expires_in": 3600,
"id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjFlOWdkazcifQ.ewogImlzc yI6ICJodHRwOi8vc2VydmVyLmV4YW1wbGUuY29tIiwKICJzdWIiOiAiMjQ4Mjg5NzYxMDAxIiwKICJhdWQiOiAiczZCaGRSa3F0MyIsCiAibm9uY2UiOiAibi0wUzZV3pBMk1qIiwKICJleHAiOiAxMzExMjgxOTcwLAogImlhdCI6IDEzMTEyODA5NzKfQ.ggW8hZ1EuVLuxNuuIJKX_V8a_OMXzR0EHR9R6jgdqrOOF4daGU96Sr_P6qJp6IcmD3HP99Obi1PRscwh3LO146waJ8IhehcwL7F09JdijmBqkvPeB2T9CJNqeGpegccMg4vfKjkM8FcGvnzZUN4_KSP0aAp1tOJ1zZwgjxqGByKHiOtX7TpdQyHE5lcMiKPXfEIQILVq0pc_E2DzL7emopWoaoZTF_m0_N0YzFC6g6EJbOEoRoSK5hoDalrcvRYLSrQAZZKflyuVCyixEoV9GfNQC3_osjzw2PAithfubEEBLuVVk4.XUVrWOLrLl0nx7RkKU8NXNHq-rvKMzqg"
}

Token Response: Considerations

• “id_token” field value is encoded as a JWT. See more information about JWT at:

  • https://jwt.io/

• The JWT signature should be verified with the public key provided by Mobile Connect

ID Token

ID Token: Considerations

• Check session and lifetime fields
• The “nonce” attribute value should match the “nonce” parameter value of the authorization request

UserInfo

Userinfo: Considerations

• The “sub” attribute value should match the “sub” attribute value of the ID token
• If a login hint was used in authorization request, the msisdn should match the “phone_number” attribute value included in userinfo response

Fast Tracking (Optional): Considerations

• Use it when you get an authorization callback with parameters:

  • error = access_denied
  • error_description containing “authentication failed”

• Three available flows: New tab, new window or redirection

• URL parameters:

  • login_hint: see format in authorization request section
  • id (redirection flow only): identifier of the service and provided by Mobile Connect

Fast Tracking (Optional): New window/tab

Fast Tracking (Optional): Redirection