Introduction

The Mobile Connect API allows your website or application to give your customers (the end-users) the option to log into websites and apps with their mobile phones and Two-factor authentication (2FA). You can login on any device without having to remember usernames or passwords. Your customer is safely identified through their mobile phone number with the level of security of your choosing (PIN or OK button).

Mobile Connect is standardized by the GSMA and specifications available in the GSMA developer portal. The current version of the standard describes the following product categories:


Portfolio status

In the current release, the Mobile Connect API offers the top two categories: authentication and authorization.

Note: This API is only available in production due to security reasons related to the nature of this API.


Conceptual model

Conceptual model

  1. User presses the button to log into the service provider’s website (your website) with Mobile Connect. You as a service provider then show a screen, supplied by the GSMA Discovery Service, asking the user to enter their mobile phone number.
  2. You contact the Discovery Service, which searches for mobile providers through GSMA.
  3. The Discovery Service gives you the address of the mobile operator’s ID Gateway that you need to send the authentication request to.
  4. You send the authentication request to the the mobile provider.
  5. The mobile operator sends the login request to the user’s authentication device.
  6. The authentication response to the login request is sent back to the mobile operator.
  7. The mobile operator sends the authentication response back to you as the service provider.
  8. If the response is positive and you grant permission, you can then display the requested information on the user’s device.


Definitions

Authentication

The process or action of verifying the identity of your customer. With the Mobile Connect API, the mobile network operator of your customer is the provider of the authentication service.

Authenticator

The method by which this verification takes place.

Discovery Service

Discovery Service is the process of determining an end-user's Mobile Connect Identity Provider, for example the Operator ID Gateway.

GSMA

GSMA or Global System for Mobile Communications, is a body to support and promote mobile operators using the GSM (Global System for Mobile communications) standard for cellular networks.

Jwks_uri

Metadata entry expressed as a URI for the OpenID Connect Identity Provider (IDP)'s JWK set or OAuth client.

Level of Assurance (LoA)

Level of Assurance, describes the degree of confidence in the processes leading up to and including an authentication. It provides assurance that the entity claiming a particular identity, is the entity to which that identity was assigned. The greater the risk associated with an erroneous authentication, the higher the Level of Assurance recommended.

Level of Assurance 2

With Level of Assurance 2 (LoA2), there is some confidence in the asserted identity of the entity. LoA2 is used when moderate risk is associated with erroneous authentication. Successful authentication will be dependent upon the entity proving, through a secure authentication protocol, that the entity has control of an agreed credential.

Level of Assurance 3

With Level of Assurance 3 (LoA3), there is high confidence in an asserted identity of the entity. LoA3 is used where a substantial risk is associated with erroneous authentication. Identity proofing procedures shall be dependent upon verification of identity information.

OpenID Connect

An identity layer on top of the existing OAuth 2.0 protocol, which allows websites or applications to authenticate your customer through an authorization server, and request and receive information about authenticated sessions and customers. Mobile Connect adopted OpenID Connect as the base protocol and framework because of its openness and robustness.

PCR

The Pseudonymous Customer Reference (PCR is a unique identifier that the Mobile Connect API uses to reference a pairing between a specific customer account and a specific application or web service. A PCR is used to ensure that customers privacy is protected while ensuring that a PCR represents an actual customer.

PIN

The PIN or Personal Identification Number is a random 5-digit number known by your customer.

Service provider

For the Mobile Connect API a service provider is a website or application, meaning the party using the Mobile Connect API.

2FA

Two-factor authentication. It is a method of confirming users' claimed identities by using a combination of 2 different factors:

  1. Something only the user knows.
  2. Something only the user is or has.

Your customer

The end-user using your application or web service.


Prerequisites

  • You have good knowledge of OAuth 2.0 and OpenID Connect.
  • Your application supports HTTP/1.1 API clients.
  • You need to encode your authentication URL parameters properly using for example the encodeURIComponent() JavaScript function.
  • You have an account for the Mobile Connect API via KPN API Store.


Features

  • Login with phone number authentication your customer.
  • Level of Assurance 2 and 3 or a combination for fallback use.


Getting started

In order to start using the Mobile Connect API, you will need:

  • an account with the GSMA developer platform and sign the GSMA Marketing License Agreement.
  • an account in the KPN API Store.

Follow the steps below to set up these accounts:

Setting up your GSMA developer account

  1. Create an account with the GSMA developer portal.
  2. Register the application in the GSMA developer portal.
  3. Optional: Download and install the GSMA's SDKs or use your own preferred openid connect clients, configure them and make test calls.
  4. Take a look at Implementation and Security best practices.
  5. Sign the GSMA Marketing License Agreement on the GSMA developer portal and download the Mobile Connect Brand Assets (buttons etc. to place on the website).
  6. Test the application in the sandbox environment of the GSMA and make your first call.


Setting up your KPN API Store account.

  1. Create an account with the KPN API Store.
  2. Create a project with the Mobile Connect API on your My Projects page.
  3. Test your project with the demo credentials in the demo environment. See Test with the demo environment.
  4. Apply for production and fill in the form.
  5. Receive feedback via e-mail about the next steps (1 working day).
  6. Proceed through the steps (including signing a contract with KPN).
  7. Use the API with the credentials provided.


Authentication

The Mobile Connect authentication is made per request.

  1. Make an authentication request to retrieve the authentication credentials for the token request. As credentials, use the client_id and client_secret from the My Apps page in the KPN API Store.
  2. Make a token request to retrieve the Pseudonymous Customer Reference (PCR) and a JSON Web Token (JWT) id_token.

The unique identifier (PCR) must be added to the local customer registration (or the customer database) on the website or application. It is used to verify your customer in further authentications.

The JWT id_token retrieves information related to the authentication, especially the Level of Assurance (LoA) level and SIM card status and contains the PCR as sub.

Security recommendations

  • You should always validate the JWT and verify the LoA level, the hashed_login_hint (premium packages) and other info from this token to assure the correct authentication method, audience and request were used. In order to verify the validity of the JWT you can download the certificate via our store.
  • As most but not all smartphones follow GSMA guidelines for the Mobile Connect API in relation to lock-screens, your website or application should not rely on the lock-screen functionality. Some smartphones are known to allow the applet popup push through the screen lock. In order to enforce proper security, always use LoA3 when in doubt.


Authentication request parameters

Parameter Values   Description
scope openid mc_authn   Value must contain and begin with value openid. The Mobile Connect API v2.0 requires extra information on the scope requested, in this case scope=openid mc_authn.
response_type code The value MUST be “code”, to indicate that the grant type flow to be used is Authorization Code. It also indicates that the access_token (and id_token) will be returned in exchange of “code”.
redirect_uri CUSTOM_URL Specified URL where request is rerouted with Authorization request response. Must match the setting configured in the Mobile Connect platform.
state STATE_TOKEN Unique session token set by the service provider. The Mobile Connect API will return same state token for service provider verification.
client_id SPID Unique ID for the service provider. Must match the service provider as received from the registration form in the KPN API Store.
acr_values 2 or 3 Number specifying LoA level. 2 = Yes/No, 3 = with PIN. Or “3 2”, PIN with fallback to Yes/No question.
nonce ID TOKEN String value used to associate a client session with the ID Token. It is passed unmodified from Authorization Request to ID Token. The value SHOULD be unique per session to mitigate replay attacks.
login_hint Optional field (for premium package only) the service provider should use login_hint to provide the MSISDN in login_hint parameter. The login_hint It is entered as: MSISDN: when the service provider has the MSISDN available, otherwise the MSISDN will be requested by the Mobile Connect platform. Example: login_hint=MSISDN:1234567890. Note: If using login_hint make sure to verify the login_hint_hash in the response for correct response.


Authentication result response

The customers web browser at the consumption device is redirected to the URL which was stated with the redirect_uri parameter in the request. State and nonce parameters are returned in the URL and have to be verified by the service provider to identify that the response is coming from the correct source and transaction. The code parameter in the request is the authorization token to be used in the Access Token request.

Request access token

In this POST request code parameter value from the authentication request is used in the body to get the token authentication information. The service provider credentials must be provided in Authorization: Basic header.


Access token request parameters

Parameter Values Description
grant_type authorization_code The value must be set to authorization_code.
redirect_uri CUSTOM_URL The service provider specified URL where request is redirected with access token request response. Value must be the same as in Authorization request and must match the service provider redirect_url from the registration form.
code AUTHORIZATION_CODE The Mobile Connect API authorization call returned Authorization Code.


Access token response parameters

Parameter Description
id_token Additional token used to provide the Identity token claim; contains additional information like LoA level, audience etc that must be verified by the service provider to ensure the required authentication level. Should be verified on correctness via jwks_uri endpoint.
access_token Used for getting your customer attributes. Can be reused for accessing other protected resources.


Id_token parameters

Parameter Description
Auth_time   Time your customer authentication. Number of seconds from 1970-01-01T0:0:0Z (if max age was used in request this is shown).
Exp   Expiration time for the ID Token. Number of seconds from 1970-01-01T0:0:0Z.
Sub   Subject identifier. Unique identifier of your customer, here the PCR.
Upk   User Public Key or User certificate. Reference to the certificate that was used to sign the dts parameter.
Dts_time   The time of signing. Its represented as the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time specified.
Aud   Intended audience for the ID Token. Contains client_id value.
Iss   Issuer endpoint of the Mobile Connect platform.
Iat   Time of issue of the ID Token. Number of seconds from 1970-01-01T0:0:0Z.
Acr   Authentication Context Class Reference, LoA level (2 or 3).
dts   The signed data with the user’s private key.


Authorization

The authorization request requires more information on top of the information provided for the authentication request. This information is shared to the user's mobile device and requires the name of the relevant website or application (client_name). The client_name has to match the application name provided in the Mobile Connect registration form.

Just like the LoA level, the binding_message and the context information is returned in the id_token jwt and should be verified and stored for future reference of proof.


Authorization request parameters

Parameter   Values   Description
scope   openid mc_auth Scope is changed to mc_authz.
client_name   A short name to identify your website or application, which will be displayed on your customer's device during the authorization flow. This short name is created when you apply for production. Example: appName.
binding_message   Plain text provided by you, to interlock the consumption device and authorization device for a better and more secure user experience. The message will be displayed on both devices.
context   A transaction or action-based message from your website or application that will be displayed on your customer's authentication device. Example: Transfer $100.

Authorization result response

Your customer's web browser on the mobile device is redirected to the URL which was provided with redirect_uri parameter in the request. state and nonce parameters are returned in the URL and must be verified by your website or application to identify that the response is coming from the correct source and transaction. The code parameter in the request is the authorization token to be used in the Access Token request.


Level of Assurance

The method of your customer's authentication that you apply depends on the Level of Assurance you want:

Authenticator Description   LoA2   LoA3  
SMS+URL Customers verify themselves by clicking on a link in an SMS and confirming the authentication on a web page.   ●    
SIM Appl SIM App session is initiated allowing customers to verify themselves.   ●   ●  


Mobile Connect Authentication flow (LoA2)

Typically, your customer takes action to initiate the process. Your website initiates an authentication request with that operator. The operator then sends a challenge to your customer on their mobile phone. It can be sent using different technologies such as SMS+URL, SIM apps or even smartphone apps. Your customer responds by tapping 'OK' for normal security (Level of Assurance 2 or LoA2). This confirms the device has a SIM card in it. If your customer responds successfully to the challenge, the operator confirms to your website or application that the authentication is successful, upon which your website or application allows your customer access.

Mobile Connect Authenticate Plus (LoA3)

Most websites such as web shops, healthcare and banks will need higher security with Level of Assurance 3. The Mobile Connect API provides this by challenging your customer to enter a known PIN.

KPN works mainly with the SIM app and SMS+URL app authentication technologies. The SIM app is an applet that runs in the SIM card in the mobile phone. It works with most modern mobile phones. The SIM app supports both Authenticate and Authenticate Plus. For the SIM app, a state-of-the-art SIM card (NFC SIM card) is needed that provides enough memory to store the SIM app. All new post-paid customers are provided with an NFC SIM card. Installed base customers with older SIM cards can be upgraded by a SIM card swap.

Either the service provider has access to the telephone number of your customer (usually entered by your customers themselves, or not:

  • If the service provider has no access to your customer's telephone number, the authorization_endpoint can be used with and without a login_hint.
  • If there is no login_hint, the Mobile Connect API will ask your customers for their telephone number. The service provider will never see the telephone number.

Note: If your customer does not have a NFC SIM card, SMS+URL can be used for authentication.


Parameters and URLs

Live environment

Term   Value  
openid-configuration   https://mc.kpn.com/idp/kpn/oidc/mc/.well-known/openid-configuration
authorization_endpoint   https://mc.kpn.com/idp/kpn/oidc/mc/authorize
token_endpoint   https://mc.kpn.com/idp/kpn/oidc/mc/token
jwks_uri   https://mc.kpn.com/idp/kpn/oidc/mc/jwks.json
user_endpoint   https://mc.kpn.com/idp/kpn/oidc/mc/userinfo
premiuminfo_endpoint   https://mc.kpn.com/idp/kpn/oidc/mc/premiuminfo
Versions supported   mc_di_r2_v2.3, mc_v2.0. Recommended: mc_di_r2_v2.3
Scopes supported   openid, openid mc_authn, openid mc_authz

Demo environment

Term   Value  
authorization_endpoint   https://api-prd.kpn.com/mobileconnect/kpn/authorize
token_endpoint   https://api-prd.kpn.com/mobileconnect/kpn/token


Mobile Connect Discovery service (optional)

Mobile Connect is implemented by the end-user's Mobile Telecom provider. A Service Provider needs to direct the calls to the correct endpoints as provided by this Telecom provider. The GSMA offers a service where a Service Provider can discover what API endpoints to use for what mobile phone number.

These Discovery APIs can be addressed with or without the end-users phone number.

Note: Information and test sandbox can be accessed on the Mobile Connect Developers page.


Setting up your GSMA developer account

  1. Find out more about the discovery API: https://developer.mobileconnect.io/discovery-api#.
  2. Create an account with the GSMA developer portal at https://developer.mobileconnect.io.
  3. Register an account in the GSMA developer portal.
  4. Create an app.
  5. With the credentials of the app you can address the GSMA sandbox with discovery and mobile connect test site.
  6. Implement and test the Discovery calls (and Mobile Connect).
  7. Test the application in the sandbox environment of the GSMA and make your first call.
  8. To request access to operator networks go to: Request access to operator networks.
  9. Continue with requests for KPN Mobile Connect (if not done yet) via KPN API Store.


How to...

Test with the demo environment

  1. Use the endpoints from the demo environment.
  2. The intended audience aud is not your APIStore client_id but a shared client_id updated by the APIStore. The intended audience will always be: odRmlfWY0CWcHOo8RcrKO6wTg2jwrqe0.
  3. The redirect_url is not verified. Please use your own URLs or local host as redirect_uri.
  4. The demo environment accepts the following client_names: demo, service, login, pay, test, bevestig

Note: The number of calls in the demo environment is limited to 100 calls per day.


Set up 2FA for your customers combined with traditional passwords

Two-factor authentication (2FA) allows you to use the Mobile Connect API as a second factor next to the traditional username plus password login. You will need:

  • A primary authentication method. For example, username and password.
  • You will need to request access as a Trusted Service Provider, so you are allowed to process telephone numbers.

Initial setup

  • At activation of the two-factor authentication, a Mobile Connect authentication is triggered, which verifies your customer.
  • Your customer receives a pop-up on the mobile phone and simply responds by tapping 'OK'.
  • After successful authentication, store the phone number and the Pseudonymous Customer Reference (PCR).

Regular use

  • After authentication the customer with user name and password you redirect to the Mobile Connect login (including the phone number) at LoA2. This pushes a verification pop-up on your customer's mobile phone.
  • Your customer simply responds by tapping 'OK'.

As a service provider you should:

  • Integrate the Mobile Connect Authentication API call (mc_authn) using your customer's telephone number.
  • Trigger the initial verification. This verification will return the unique identifier PCR. Store the PCR together with the user in the user database to verify future authentications.
  • At subsequent logins, trigger the same Mobile Connect Authentication API call with the stored telephone number to verify the stored PCR.
^^Mobile Connect Authentication API call^^
curl 'https://mc.kpn.com/idp/kpn/oidc/mc/authorize?client_id=<your apistore client_id>&response_type=code&scope=openid mc_authn&redirect_uri=<your callback url>&state=<your session state>&nonce=<your nonce>&acr_values=2&version=mc_di_r2_v2.3&login_hint=MSISDN:<phone-number>'

This call results in a callback to your redirect_uri with the parameters:

  • state: Verify with <your state> from the authentication call.
  • code: Authorization code in uuidv4 format. This code is used in the Access Token API call.
^^Mobile Connect Access Token API call^^
curl -X POST https://mc.kpn.com/idp/kpn/oidc/mc/token \
    -H 'Content-Type: application/x-www-form-urlencoded' \
    -H 'Authorization: Basic <basic_auth of your client_id and client_secret> \
    -d grant_type=authorization_code&code=<authorization code from previous call>&redirect_uri=<your callback url>

This call results in a JSON response:

^^Response^^
{
    "access_token": <uuidv4 access_token for userinfo call>,
    "expires_in": 3600,
    "token_type": "Bearer",
    "id_token": <jwt>
}

For two-factor authentication, only the id_token jwt is of interest. The service provider verifies the JWT via the jwks_uri.

For more information on Mobile Connect JWT verification, see Parameters and URLs and Mobile Connect tokens.

JWT verification is available via any library. The JWT payload has the following structure:

^^JWT payload^^
{
     "sub": <PCR of your customer and your application>,
     "acr": <2 or 3 depending on OK button or PIN code verification performed>,
}

To avoid attacks changing request parameters, verify the login_hint via the hashed_login_hint as returned in the JWT.

^^Hashed login hint^^
{
    "hashed_login_hint": <sha256 hash of login_hint>
}

The JWT returns the PCR in the sub field. A new Mobile Connect authentication request will always return this PCR for your application.

Note: To verify the returned PCR in the sub field in the JWT to the PCR stored in the user database, add the same Mobile Connect authentication call in your account verification process, instead of adding the PCR to the database.


Set up 2FA without passwords for your customers

With this setup your customer will no longer use traditional usernames and passwords, but you use Mobile Connect entirely for the login, typically, with a Mobile Connect PIN.

The calls are largely like the two-factor authentication example. See 'Mobile Connect Authentication API call' under Set up two-factor authentication for your customers.

Initial setup

When your customer logs in with Mobile Connect and the PCR is not known in your user database you can offer the customer to either create a new account or to connect Mobile Connect to an already existing account.

Regular use

  • Your customer can login with Mobile Connect.
  • Your customer enters his phone number and receives a PIN pop-up on his mobile phone.
  • Based on the PCR, you can direct your customer to his account.

Service provider activities:

  • Add the Mobile Connect button in the login process initiating the Mobile Connect Authentication call.
  • At the initial setup, store the PCR as returned from the Mobile Connect API.
  • At login, verify this PCR to identify your customer.

Note: Not all phone numbers support PIN verification yet. The Mobile Connect API supports fallback to lower level of authentication depending on the capabilities of the SIM card. If PIN is not supported, you will receive an error.

For example: Call verifying the PIN number at your customer's mobile phone (if available). It fails otherwise.

^^Verify PIN number^^
curl 'https://mc.kpn.com/idp/kpn/oidc/mc/authorize?client_id=<your apistore client_id>&response_type=code&scope=openid mc_authn&redirect_uri=<your callback url>&state=<your session state>&nonce=<your nonce>&acr_values=3&version=mc_di_r2_v2.3'


Set up Mobile Connect Authorization Product

The Mobile Connect API offers a functionality to add extra information on the device your customer is using (for example a laptop browser) and on the device used for authentication (the mobile phone). These texts can be used to set a reference between the mobile device and the authentication device, so your customer can verify that the messages on the mobile phone as part of the login process, and/or add information related to the action confirmation.

This function is available as the 'Mobile Connect authorization product' (mc_authz). The authorization product can be used as alternative to the authentication product used for two-factor authentication and login without passwords use cases. It can also be used as a standalone product.

The sequences of calls is similar to the Mobile Connect authentication, adding:

  • a new scope: scope=openid mc_authz
  • a short name to identify you: client_name
  • a message shown in the browser and on the mobile phone: binding_message
  • a message shown on the mobile phone: context
  • an extra verification step, as both messages are returned in the JWT as displayed_data

Note: Verify and store these messages for future reference.

^^Mobile Connect Authorization^^
curl 'https://mc.kpn.com/idp/kpn/oidc/mc/authorize?client_id=<your apistore client_id>&response_type=code&scope=openid mc_authz&redirect_uri=<your callback url>&state=<your session state>&nonce=<your nonce>&acr_values=2&version=mc_di_r2_v2.3&binding_message=<message on both devices>&context=<message on mobile>&client_name=<your client_name>'


Examples:

Parameter   Possible values
binding_message   Transaction-ID: 1234-1141
context   login to service provider app or transfer $100
client_name demo

Note: The combined max. length of binding_message and context is 93 bytes UTF-8.

Optional for Trusted Service Providers: This functionality can also use the login_hint parameter with your customer's phone number:

^^Mobile Connect Authorization with login hint^^
curl 'https://mtc.kpn.com/idp/kpn/oidc/mc/authorize?client_id=<your apistore client_id>&response_type=code&scope=openid mc_authz&redirect_uri=<your callback url>&state=<your session state>&nonce=<your nonce>&acr_values=2&version=mc_di_r2_v2.3&binding_message=<message on both devices>&context=<message on mobile>&login_hint=MSISDN:<phone-number>&client_name=<your client_name>'


Return codes

Code   Description
200   Success.
201   Created.
202   Accepted.
302   Found. Link in location header.
400   Bad request.
401   Unauthorized.
403   Forbidden.
404   Not found.
405   Method not allowed.
412   Precondition failed.
429   Too many requests.
500   Internal server error.
502   Bad gateway.
503   Service unavailable.