beta
KPN

Mobile Connect - KPN

KPN

Let users log in securely with a single PIN

The faster and easier new standard in digital authentication

  • Identity

Discovery API reference on SwaggerHub Mobile Connect API reference on Postman

Introduction

Mobile Connect is a new service that lets you log in to websites and apps on any device without having to remember user names or passwords. You are safely identified through your mobile phone number.

Mobile Connect is standardized by the GSMA. The current version of the standard describes the following product categories:

  • Authentication
  • Authorization
  • Identity
  • Attributes

In the current release of KPN’s Mobile Connect offering, the KPN Mobile Connect portfolio has 2 packages: Standard package and Premium Package. Standard package can only be used for authentication and authorization requests where the user starts the request himself. With the Premium package, which also supports authentication and authorization, requests are started by a server using the end-users mobile phone number.

Portfolio status

Mobile Connect consists of two APIs: the Discovery API and the Mobile Connect API. The Discovery API allows your application or web service to discover the details of customer’s operator and provides the endpoints and credentials that you will need to make the Mobile Connect API calls. The Mobile Connect API is the one that you will use for authentication, authorization, identity and attributes services.

It is not necessary to use the Discovery API if you already know the end users’ Mobile Connect endpoint and already have the necessary credentials. If you are working on a service for a single operator, they will provide you with your credentials and the endpoint you should use.

Conceptual model authentication

Mobile Connect is largely based on OpenID Connect. A basic understanding of OpenID Connect and Oauth2 is assumed for implementation of Mobile Connect.

Mobile Connect allows a website or application to give users the option to log in using Mobile Connect. Typically, the user takes action to initiate the process. The website or application is notified and uses the Mobile Connect Discovery service to find out which mobile operator is serving the user. Once the serving operator is known, the website or application initiates an authentication request with that operator. The operator then sends a challenge to the user on their mobile phone. It can be sent using different technologies such as SMS, SIM apps or even smartphone apps. The user simply responds by tapping 'ok' for normal security (LoA2). This confirms the device has a SIM card in it.

If the user responds successfully to the challenge, the operator confirms to the website or application that the authentication is successful, upon which the website or application allows the user access. This process is called the Mobile Connect Authentication flow.

Most websites such as webshops, healthcare and banks will need higher security (LoA3). Mobile Connect provides this by challenging the user to enter a known PIN. This service is called Mobile Connect Authenticate Plus.

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 postpaid users are provided with an NFC SIM card. Installed base users with older SIM cards can be upgraded by a SIM card swap.

If the user 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.

Conceptual model

  1. User clicks on Mobile Connect button to access service.
  2. Application requests user operator details from the Discovery service.
  3. Discovery responds with operator details.
  4. Application makes an authentication request to the user operator, using OpenID with Mobile Connect profile.
  5. Operator sends authentication request to user.
  6. User authenticates himself using his mobile device.
  7. A PCR specifying a specific user is returned.
  8. Access granted or denied.

Definitions

Authentication

The process or action of verifying the identity of a user. In Mobile Connect, the mobile network operator is the provider of the authentication service.

Authenticator

The method by which this verification takes place.

   Authenticator   Description   LoA2   LoA3  
   SMS+URL   The user verifies themselves by clicking on a link in an SMS.   ●    
   SIM Application Toolkit   A Sim Toolkit session is initiated allowing the user to verify himself.   ●   ●  


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

At 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.

During a Mobile Connect authentication for LoA2, the user will be prompted and will need to respond on their mobile device* to prove that they are in possession of the device (the credentials). As defined, LoA2 only provides some confidence that we know for sure that the user has access to the mobile device.

We also describe this as "Something you have".

If the application using the Mobile Connect API is on the mobile data network at the time of the request, the user may not have to respond to a prompt to prove that they are in possession of the device as this can be done by the mobile network. This is referred to as seamless authentication.

Level of Assurance 3

At 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.

With Mobile Connect Authentication Plus (LoA3), the user will be required to enter a secret PIN that they agreed on beforehand. This process provides security that a user that enters the PIN is the same person to which the identity was assigned, as only that person should know the PIN.

We describe this as "Something you have and something you know". It is possible to replace the "something you know" second factor in an LoA3 authentication with for "Something you are" provided by bio-metric factors such as a fingerprint . This is dependant on mobile network operators local authenticator implementations.

OpenID Connect

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

PCR

Pseudonymous Customer Reference. A unique identifier that Mobile Connect uses to reference a specific user. A PCR is used to ensure that user privacy is protected while offering the developer security that a PCR represents an actual user.

PIN

Personal Identification Number – random 5 digit number known by the user.

Prerequirements

When using this API, knowledge of OpenID Connect is assumed and a GSMA developer account is required. The GSMA developer account gives access to a Mobile Connect sandbox to create a test setup, the Mobile Connect Discovery service, and the GSMA Marketing License Agreement.

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

Features

  • Easy to use: Only phone number is required to login.
  • Private and secure: No personal information about the user is shared with the website or application. The user uses his mobile device to prove his digital identity and then verify it.

Getting started

To start using Mobile Connect 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 mail about the next steps.
  5. Proceed through the steps.
  6. Use the API with the credentials provided.

Setting up your third party accounts

Discovery and onboarding GSMA developer portal

The GSMA discovery offers a service to determine what operator to contact for the Mobile Connect functionality by returning the operator specific Mobile Connect endpoints.

It’s up to you whether you use the GSMA discovery in the authentication process or direct all requests to the KPN Mobile Connect solution.

To make starting with Mobile Connect as easy as possible, KPN will start by supporing all Dutch mobile numbers (+316xx). We advice you to start using the KPN Mobile Connect platform directly and switch to using the GSMA discovery when Mobile Connect for becomes available at Dutch Telco's or when it becomes relevant for your website or application.

An example when it might become relevant for your website or application is when it requires authentication plus or authorization plus (using LoA3 with pincode). KPN will offer support for non-KPN group operators, but can’t add LoA3 pin verification for non-KPN group customers. A switch to the GSMA discovery will then be needed.

When not using the GSMA discovery page, the Mobile Connect process starts with the authentication request directed to the KPN endpoints. The discovery setup is optional.

When using a GSMA discovery page (e.g. the UX discovery), the process will be similar to the GSMA sandbox processes.

Request the discovery endpoints and credentials in the GSMA developer portal (https://developer.mobileconnect.io).

Note: With KPN customers, a website or application can only use the GSMA EU discovery endpoint: https://eu.discover.mobileconnect.io. With this URL the GSMA makes sure that personal data never leaves the EU.

Getting your GSMA account

In order to use GSMA discovery service, you need to follow the following 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. 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 GSM and make your first call

How to...

Request authentication

The authentication request is followed by a token request which returns a unique id (PCR) for the user + website or application + (optionally) specific service. This id has to be added to the local user registration (or the user db) on the website or application, and is used to verify the user in further authentications.

The token request also returns a JWT id_token which returns info related to the authentication, especially what LoA level and sim card status.

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 validaty of the JWT you can download the certificate via the KPN API Store.

  • As most but not all phones follow GSMA guidelines for Mobile Connect in relation to phone lock-screens, your website or application should not rely on the phone lock-screen functionality. Some phones 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. Mobile Connect 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 KPN Mobileconnect platform.
state   STATE_TOKEN   Unique session token set by Service Provider. Mobile Connect will return same state token for Service Provider verification.
client_id   SPID   Unique ID for 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 KPN 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.


Authorization 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 KPN Mobile Connect 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   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   Mobile Connect 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 user Attributes. Also can be reused for accessing other protected resources.


Id_token parameters

Parameter Description
Auth_time Time of user 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 or user, here the PCR.
Upk User 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 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.


Request authorization

The authorization request requires more information on top of the information provided for the authentication request. This information is shared to the users 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 KPN 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_authz"   Scope is changed to mc_authz.
client_name   A short name to identify your website or application, which will be displayed on the user's device during the authorization flow. This short name is created when the application is registered on the GSMA developer portal. 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 the user authentication device. Example: “Transfer $100”.


Authorization result response

The user'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 have to 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.

API versions

Version   Description
R2   Initial version