Authentication

AUTHORISATION ENDPOINT

GET /{endpoint_from_discovery}/{?client_id,client_name,response_type,scope,acr_values,state,nonce,display}

Example URI

GET /https:/telstar.com/mobileconnect/oidc/auth/?
client_id=73958620&client_name=test_app2&response_type=code&scope=openid mc_authn&
acr_values=3 2&state=3a1d38b1&nonce=cee18fcb&display=page

URI Parameters

endpoint_from_discovery string (required)
Example: https://telstar.com/mobileconnect/oidc/auth
This token represents the URL returned from a successful discovery request. This will appear in the discovery requests links array, with a rel of authorization.
client_id string (required)
Example: 73958620d779-4fdc-bc09-7d521af91278
This is the client_id field from the Discovery Response.
client_name string (required)
Example: test_app2
This is the application short name returned in the Discovery Response
response_type string (required)
Example: code
The value MUST be code, to indicate that the grant type flow to be used is Authorisation Code. It also indicates that the access_token (and id_token) be returned in exchange of code.
scope string (required)
Example: openid mc_authn
Space delimited and case-sensitive list of ASCII strings for OAuth 2.0 scope values. OIDC Authorisation request MUST contain the scope value “openid”. The other optional values for scope in OIDC are: [mc_authn, mc_authz, mc_identity_signup, mc_identity_phonenumber, mc_identity_nationalid, profile, email, address, phone, offline_access]
redirect_uri string (required)
Example: https://example.com/sign_in_callback
The redirect_uri that you have provided during the application creation. The response from the Authorization flow will be redirected to this URI.
acr_values string (required)
Example: 3 2
Authentication Context class Reference. Space separated string that specifies the Authentication Context Reference to be used during authentication processing. The LOA required by the RP/Client for the use case can be used here. The values appear as order of preference. The acr satisfied during authentication is returned as acr claim value.

The recommended values are the LOAs as specified in ISO/IEC 29115 Clause 6 – 1, 2, 3, 4 – representing the LOAs of LOW, MEDIUM, HIGH and VERY HIGH. It’s important to note that mobile connect currently only supports LOAs 2 & 3.

The acr_values are indication of what authentication methods to used by the IDP. The authentication methods to be used are linked to the LOA value passed in the acr_values. The IDP configures the authentication method selection logic based on the acr_values.

state string (required)
Example: 3a1d38b1
54bc-4383-bfc9-a6926fc2644b

Value used by the client to maintain state between request and callback. A security mechanism as well, if a cryptographic binding is done with the browser cookie, to prevent Cross-Site Request Forgery.
nonce string (required)
Example: cee18fcb
cb3a-46b9-88ec-6ab79d9d0da0

String value used to associate a client session with the ID Token. It is passed unmodified from Authorisation Request to ID Token. The value SHOULD be unique per session to mitigate replay attacks.
display string (optional)
Example: page
ASCII String value to specify the user interface display for the Authentication and Consent flow. The values can be:
  • page: Default value, if the display parameter is not added. The UI SHOULD be consistent with a full page view of the User-Agent.
  • popup: The popup window SHOULD be 450px X 500px [wide X tall].
  • touch: The Authorisation Server SHOULD display the UI consistent with a “touch” based interface.
  • wap: The UI SHOULD be consistent with a “feature-phone” device display.
prompt string (optional)
Example: consent
Space delimited, case-sensitive ASCII string values to specify to the Authorisation Server whether to prompt or not for reauthentication and consent. The values can be:
  • none: MUST NOT display any UI for reauthentication or consent to the user. If the user is not authenticated already, or authentication or consent is needed to process the Authorisation Request, a login_required error is returned. This can be used as a mechanism to check existing authentication or consent.
  • login: SHOULD prompt the user for reauthentication or consent. In case it cannot be done, an error MUST be returned.
  • consent: SHOULD display a UI to get consent from the user.
  • select_account: In the situations, where the user has multiple accounts with the IDP/Authorisation Server, this SHOULD prompt the user to select the account. If it cannot be done, an error MUST be returned.
  • mobile: The request should show no UI and simply hold the authorization request open until out-of-band authorization has been completed.
binding message string (required)
Example: transaction 100
Required if scope=openid mc_authz. App provided plain text reference or ID to interlock the consumption device and authorization device. The message will be displayed on the consumption device and the mobile device. Empty values are allowed.
context string (required)
Example: Transfer $100 to bob
Required if scope=openid mc_authz. App provided message which will be displayed on the authorization device and must be provided.
max_age number (required)
Example: 300
Specifies the maximum elapsed time in seconds since last authentication of the user. If the elapsed time is greater than this value, a reauthentication MUST be done. When this parameter is used in the request, the ID Token MUST contain the auth_time claim value.
ui_locales string (required)
Example: es
ES es (string) - Space separated list of user preferred languages and scripts for the UI as per RFC5646. This parameter is for guidance only and in case the locales are not supported, error SHOULD NOT be returned.
claims_locales string (required)
Example: es
Space separated list of user preferred languages and scripts for the Claims being returned as per RFC5646. This parameter is for guidance only and in case the locales are not supported, error SHOULD NOT be returned.
id_token_hint string (required)
Example: long_jwt_token
Generally used in conjunction with prompt=none to pass the previously issued ID Token as a hint for the current or past authentication session. If the ID Token is still valid and the user is logged in then the server returns a positive response, otherwise SHOULD return a login_error response. For the ID Token, the server need not be listed as audience, when included in the id_token_hint.
login_hint string (required)
Example: ENCR_MSISDN:23153464dsfgh
An indication to the IDP/Authorisation Server on what ID to use for login.

The login_hint can contain the MSISDN, the Encrypted MSISDN, or a PCR from a previously issued id token.

  • ENCR_MSISDN:: Value should be set to the subscriber_id from the Discovery Response.
  • PCR:: Value should be set to a PCR (Pseudo-anonymous Customer Reference) from a previous Authorization run
  • MSISDN:: Value should be set to a full MSISDN including country code, e.g. 447700900907
login_hint_token string (required)
Example:
The “login_hint_token” produced by the Discovery service is an encrypted JSON Web Token JWT [RFC7519] that contains a user hint for an individual MNO. This token is typically created by an MODRNA discovery service if a user has entered an MSISDN during the discovery process. The “login_hint_token” SHALL be used by the client as login hint with the particular MNO.
version string (required)
Example: mc_v1.1
A string value used to identify the profile version. The default value for Mobile Connect is “mc_v1.1”, this is used for existing authentication only deployments. Future values will support “mc_v2.0”.

Request

Headers

Authentication: Basic base64(<operator_specific_client_id>:<operator_specific_client_secret>)

Response 302

Headers

Location: https://operator.com/signin

RETURN TO REDIRECT_URI

GET /{redirect_url}{?state,code,error,error_description}

This endpoint documents the data which will be sent to the applications registered redirect_uri upon completion or failure of an authorization attempt.

Example URI

GET /https:/example.com/sign_in_callback?state=12324tsfdsdf&code=2d902ae7&error=error_name&error_description=error description

URI Parameters

state string (required)
Example: 12324tsfdsdf
The state string which was passed in to the original request
code string (required)
Example: 2d902ae7
A one use Authorisation Code as per OAuth 2.0. To be used as parameter in Token request to exchange for Tokens
error string (required)
Example: error_name
Should there be an error, this parameter will be set and code will not be present in the results.
error_description string (required)
Example: error description
Should be an error description which can inform the application what went wrong.

 

Access Tokens

TOKEN ENDPOINT

POST /{op_token_endpoint}

Upon making a successful request to the Authorization endpoint and recieving a one-time code via the redirect_url, the code can be exchanged with the token endpoint to gain an access_token and a signed id_token.

Example URI

POST /https:/operator.com/oidc/token

URI Parameters

op_token_endpoint string (required)
Example: https://operator.com/oidc/token
This is the operators token endpoint which is returned in the discovery request, under links, with rel="token".

Request

Headers

Authentication: Basic base64(<operator_specific_client_id>:<operator_specific_client_secret>)

Body

{
  "grant_type": "authorization_code",
  "code": "2d902ae7-c393-48fb-b30c-60ae10dc838e",
  "redirect_uri": "https://example.com/signin_callback"
}

Schema

{
  "type": "object",
  "properties": {
    "grant_type": {
      "type": "string",
      "description": "Currently this must be set to `authorization_code`."
    },
    "code": {
      "type": "string",
      "description": "A auth code returned from a successful authorization request."
    },
    "redirect_uri": {
      "type": "string",
      "description": "The redirect_uri value MUST match the one sent in the authorization request."
    }
  },
  "required": [
    "grant_type",
    "code",
    "redirect_uri"
  ],
  "": "http://json-schema.org/draft-04/schema#"
}

Response 200

Body

{
  "access_token": "c333504b-953d-4a2f-b82c-d3584d030f2b",
  "token_type": "bearer",
  "id_token": "<jwt_string>",
  "expires_in": "1475744978",
  "refresh_token": "d5828439-6ace-4e5c-93ab-d880e8f68d34"
}

Schema

{
  "type": "object",
  "properties": {
    "access_token": {
      "type": "string",
      "description": "OAuth 2.0 access_token used to get the PremiumInfo/ UserInfo object from the PremiumInfo/UserInfo endpoint and can be reused for accessing other protected resources, if required. This parameter MUST be utilized using either the Authorization header field or a form-encoded POST body parameter."
    },
    "token_type": {
      "type": "string",
      "description": "MUST be "bearer" as defined in RFC 6749 section 7.1 and RFC6750."
    },
    "id_token": {
      "type": "string",
      "description": "This the additional token used in OIDC to provide the identity token claim. The ID Token value associated with the authentication session, and it is a security token that contains Claims about the Authentication of an End-User by an Authorization Server when using a Client, and potentially other requested Claims. The format of the ID Token is a JSON Web Token (JWT)."
    },
    "expires_in": {
      "type": "string",
      "description": "A unix timestamp representing the time at which the token will cease to be valid."
    },
    "refresh_token": {
      "type": "string",
      "description": "OAuth 2.0 refresh token to get the new access tokens using the same authorization grant through a grant_type parameter."
    }
  },
  "required": [
    "access_token",
    "token_type",
    "id_token"
  ],
  "": "http://json-schema.org/draft-04/schema#"
}

 

Premium Info

PREMIUMINFO

POST /{op_premiuminfo_endpoint}{?token}

Premium info allows an application to access user information. Which user information can be accessed is determined by scopes used in the original authorization request.

The currently accepted scopes which will result in data being available on this API endpoint are

  • mc_identity_signup which provides the attributes: [family_name, given_name, preferred_username, picture, website, gender, birth_date, locale, email, email_verified]
  • mc_identity_phonenumber which provides: [phone_number, phone_number_verified]
  • mc_identity_nationalid which provides [national_identifier, family_name, given_name, birth_date, address]

More than one of these scopes can be requested in the original request, which will result in more attributes being returned in the premium info request (it will be a union of all scopes attributes).

If none of the appropriate scopes have been used during the authorization step, an error response will be returned.

As per the other operator endpoints, this endpoint it authenticated with the operator specific basic auth.

Example URI

GET /https:/operator.com/oidc/premiuminfo?token=d5828439-6ace-4e5c-93ab-d880e8f68d36

URI Parameters

op_premiuminfo_endpoint string (required)
Example: https://operator.com/oidc/token
This is the operators premium info endpoint which is returned in the discovery request, under links, with rel="tokenrevoke".
token string (required)
Example: d5828439-6ace-4e5c-93ab-d880e8f68d36
An access_token gained from the Token Endpoint.

Request

Headers

Authentication: Basic base64(<operator_specific_client_id>:<operator_specific_client_secret>)

Response 200

Body

{
  "phone_number": "+441234567890",
  "phone_number_alternative": "+441234567891",
  "title": "Mr",
  "given_name": "Richard",
  "family_name": "Hendricks",
  "middle_name": "Hello, world!",
  "street_address": "1, the street",
  "city": "London",
  "state": "Berkshire",
  "postal_code": "W1 8PL",
  "country": "United Kingdom",
  "email": "rich@gmail.com",
  "birth_date": "1970-01-01",
  "national_identifier": "1970-01-01"
}

Schema

{
  "type": "object",
  "properties": {
    "phone_number": {
      "type": "string",
      "description": "The users MSISDN, present if the `mc_identity_phonenumber` scope has been added."
    },
    "phone_number_alternative": {
      "type": "string",
      "description": "The users alterntaive MSISDN, present if the `mc_identity_signup` scope has been added."
    },
    "title": {
      "type": "string",
      "description": "The users salutation, may be present if `mc_identity_nationalid` or `mc_identity_signup` scopes have been added, though is optional."
    },
    "given_name": {
      "type": "string",
      "description": "The users given name, present if `mc_identity_nationalid` or `mc_identity_signup` scopes have been added"
    },
    "family_name": {
      "type": "string",
      "description": "The users family name, present if `mc_identity_nationalid` or `mc_identity_signup` scopes have been added"
    },
    "middle_name": {
      "type": "string",
      "description": "The users middle name, may be present if `mc_identity_nationalid` or `mc_identity_signup` scopes have been added, though is optional."
    },
    "street_address": {
      "type": "string",
      "description": "The users street address, present if `mc_identity_nationalid` or `mc_identity_signup` scopes have been added"
    },
    "city": {
      "type": "string",
      "description": "The users city, may be present if `mc_identity_nationalid` or `mc_identity_signup` scopes have been added, though is optional."
    },
    "state": {
      "type": "string",
      "description": "The users state/county, present if `mc_identity_nationalid` or `mc_identity_signup` scopes have been added, though is optional."
    },
    "postal_code": {
      "type": "string",
      "description": "The users postal code, present when the `mc_identity_signup` scope has been used."
    },
    "country": {
      "type": "string",
      "description": "The users country code, present when the `mc_identity_signup` scope has been used."
    },
    "email": {
      "type": "string",
      "description": "The users email, may be present if `mc_identity_nationalid` or `mc_identity_signup` scopes have been added, though is optional."
    },
    "birth_date": {
      "type": "string",
      "description": "The users date of birth, present if the `mc_identity_nationalid` scope was used."
    },
    "national_identifier": {
      "type": "string",
      "description": "The users date of birth, present if the `mc_identity_nationalid` scope was used."
    }
  },
  "": "http://json-schema.org/draft-04/schema#"
}

Response 401

Body

{
  "error": "access_denied",
  "error_description": "the selected scopes do not allow access"
}