KPN Mobile Connect API

API reference on SwaggerHub

Introduction

The Mobile Connect API allows your website or application to give your customer (the end-user) the option to log into websites and apps on any device without having to remember usernames or passwords. Your customer is safely identified through a mobile phone number, with the level of security of your choosing.

Mobile Connect is standardized by the GSMA and 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. You can make use of the following packages:

  • Standard package: For authentication and authorization requests where your customer starts the request himself.
  • Premium package: For authentication and authorization requests where requests are started by a server using your customer's mobile phone number.

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

Conceptual model

Conceptual model

  1. Service Provider sends Authorization request to Mobile Connect platform (ID Gateway).
  2. Mobile Connect platform sends Authentication request to user. User gives consent to request (LoA 2) by pressing OK on the mobile phone or gives consent to request (LoA 3) by entering the 5-digit Personal Code and pressing OK on the mobile phone.
  3. Response from mobile phone is sent back to Mobile Connect platform.
  4. Mobile Connect platform sends Authorization Code to Service Provider.
  5. Service Provider requests Access Token by providing the received Authorization Code.
  6. Mobile Connect platform replies with Access Token and ID Token and PCR.

Note: Personal information of your customer is not shared with your website or application, so this process is completely safe for your customer.

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.

Your customer

The end-user using your application or web service.

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.

Prerequisites

  • You have good knowledge of OAuth 2.0 and OpenID Connect.
  • You have tested the Mobile Connect API in the GSMA sandbox.
  • You accepted the Mobile Connect Marketing License Agreement from GSMA (via developer mobileconnect.io).
  • Your application supports HTTP/1.1 API clients.
  • You have an account for the Mobile Connect API via KPN API Store.

Features and constraints

Features

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

Getting started

To start using the Mobile Connect API for your website or application, take the following steps:

  1. Create an account with the KPN API Store.
  2. Create an app with the Mobile Connect API on your My Apps page.
  3. Apply for production and fill in the form.
  4. Receive feedback via e-mail about the next steps (1 working day).
  5. Proceed through the steps.
  6. Use the API with the credentials provided.

Setting up your third-party accounts

In order to start using the Mobile Connect API in production, you will need an account with the GSMA developer platform and sign the GSMA Marketing License Agreement. Follow these steps:

  1. Create an account with the GSMA developer portal.
  2. Register the application in the GSMA developer portal.
  3. Download and install the GSMA's SDKs or use your own preferred openid connect clients, configure them and make test calls.
  4. Test Mobile Connect with the demo setup. See Test with the Demo setup
  5. Take a look at Implementation and Security best practices.
  6. 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).
  7. Test the application in the sandbox environment of the GSMA and make your first call.

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   Your customer Public Key.
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 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.   ●    
SIM Application Toolkit   Sim Toolkit 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, 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 app access 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 can be used for access. With SMS, the PIN is not supported and only Mobile Connect Authenticate is available, not Authenticate Plus.

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, mc_v2.0 recommended
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

How to...

Test with the Demo setup

  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 localhost as redirect_uri.
  4. The demo setup accepts the following client_names: demo, service, login, pay, test, bevestig

Set up two-factor authentication for your customers

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.
  • A Mobile Connect Premium package (access to your customer's telephone number).


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

  • Your customer is redirected to the Mobile Connect login after the authentication with username plus password. 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 telephone number 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_v2.0&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:

{
    "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:

{
     "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, you should verify the login_hint via the hashed_login_hint as returned in the JWT.

{
    "hashed_login_hint": <sha256 hash of login_hint>
}

The JWT returns the PCR in the sub field. The service provider stores the PCR in your customer's account in the user database for future verification. 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 login 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. You will need the:

  • Standard package Mobile Connect or
  • Premium package Mobile Connect

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.

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_v2.0'

Optional

The login without passwords functionality can also be used with the Premium package, adding the login_hint with your customer's phone number, for example:

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_v2.0&login_hint=MSISDN:<phone number>'
  • The Mobile Connect API allows a fallback from the PIN number to the 'OK' button login, by setting acr_values=3 2. This triggers the verification via the PIN number. If the PIN number is not available, it uses the 'OK' button.
  • The verified level is returned in the JSON Web Token (JWT) as acr with a value of 2 for the 'OK' button and 3 for the PIN number.

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.

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_v2.0&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: This functionality can also be used with the Premium package, adding the login_hint with your customer's phone number:

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_v2.0&binding_message=<message on both devices>&context=<message on mobile>&login_hint=MSISDN:<phone-number>&client_name=<your client_name>'