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:
In the current release, the Mobile Connect API offers the top two categories: authentication and authorization.
This API is only available in production due to security reasons related to the nature of this API.
Conceptual model
- 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.
- You contact the Discovery Service, which searches for mobile providers through GSMA.
- The Discovery Service gives you the address of the mobile operator’s ID Gateway that you need to send the authentication request to.
- You send the authentication request to the the mobile provider.
- The mobile operator sends the login request to the user’s authentication device.
- The authentication response to the login request is sent back to the mobile operator.
- The mobile operator sends the authentication response back to you as the service provider.
- 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:
- Something only the user knows.
- Something only the user is or has.
Your customer
The end-user using your application or web service.
Requirements
- 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
- Create an account with the GSMA developer portal.
- Register the application in the GSMA developer portal.
- Optional: Download and install the GSMA's SDKs or use your own preferred openid connect clients, configure them and make test calls.
- Take a look at
Implementation and Security best practices
. - 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).
- Test the application in the sandbox environment of the GSMA and make your first call.
Setting up your KPN API Store account
Make sure you've read Getting Started for more info on how to register your application and start trying out our APIs.
- Create an account with the KPN API Store.
- Create a project with the Mobile Connect API on your My Projects page.
- Test your project with the demo credentials in the demo environment. See Test with the demo environment.
- Apply for production and fill in the form.
- Receive feedback via e-mail about the next steps (1 working day).
- Proceed through the steps (including signing a contract with KPN).
- Use the API with the credentials provided.
Authentication
The Mobile Connect authentication is made per request.
- Make an authentication request to retrieve the authentication credentials for the token request. As credentials, use the
client_id
andclient_secret
from your sandbox page in the My API Store. - 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: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 alogin_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.
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.
Information and test sandbox can be accessed on the Mobile Connect Developers page.
Setting up your GSMA developer account
- Find out more about the discovery API: https://developer.mobileconnect.io/discovery-api#.
- Create an account with the GSMA developer portal at https://developer.mobileconnect.io.
- Register an account in the GSMA developer portal.
- Create an app.
- With the credentials of the app you can address the GSMA sandbox with discovery and mobile connect test site.
- Implement and test the Discovery calls (and Mobile Connect).
- Test the application in the sandbox environment of the GSMA and make your first call.
- To request access to operator networks go to: Request access to operator networks.
- Continue with requests for KPN Mobile Connect (if not done yet) via KPN API Store.
How to...
Test with the demo environment
- Use the endpoints from the demo environment.
- The intended audience
aud
is not your APIStoreclient_id
but a sharedclient_id
updated by the APIStore. The intended audience will always be:odRmlfWY0CWcHOo8RcrKO6wTg2jwrqe0
. - The
redirect_url
is not verified. Please use your own URLs or local host asredirect_uri
. - The demo environment accepts the following
client_names
:demo
,service
,login, pay
,test, bevestig
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.
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.
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
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 |
The combined max. length of
binding_message
andcontext
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. |
HTTP response headers
The following tables display the standard response headers that are returned with each API response:
Standard response field name | Description |
---|---|
sunset | This field will be populated with the deprecation details. By default the value is n/a. |
api-version | Indicates the API version you have used. |
quota-interval | Used to specify an integer (for example, 1, 2, 5, 60, and so on) that will be paired with the quota-time-unit you specify (minute, hour, day, week, or month) to determine a time period during which the quota use is calculated. For example, an interval of 24 with a quota-time-unit of hour means that the quota will be calculated over the course of 24 hours. |
quota-limit | Number of API calls an user can make within a given time period. If this limit is exceeded, the user will be throttled and API requests will fail. |
quota-reset-UTC | All quota times are set to the Coordinated Universal Time (UTC) time zone. |
quota-time-unit | Used to specify the unit of time applicable to the quota. For example, an interval of 24 with a quota-time-unit of hour means that the quota will be calculated over the course of 24 hours. |
quota-used | Number of API calls made within the quota. |
strict-transport-security | The HTTP Strict-Transport-Security (HSTS) response header lets a website tell browsers that it should only be accessed using HTTPS, instead of using HTTP. All present and future subdomains will be HTTPS for a maximum of 1 year and access is blocked to pages or sub domains that can only be served over HTTP including HSTS preload lists of web browsers. Strict-Transport-Security: max-age=31536000; includeSubDomains; preload. |
Access control field name | Description |
access-control-allow-credentials | Tells browsers whether to expose the response to frontend JavaScript when the request's credentials mode (Request.credentials) is include. When a request's credentials mode (Request.credentials) is include, browsers will only expose the response to frontend JavaScript if the Access-Control-Allow-Credentials value is true. Boolean. |
access-control-allow-origin | Indicates whether the response can be shared with requesting code from the given origin. |
access-control-allow-headers | Used in response to a pre-flight request which includes the Access-Control-Request-Headers to indicate which HTTP headers can be used during the actual request. |
access-control-max-age | Indicates how long the results of a pre-flight request (that is the information contained in the Access-Control-Allow-Methods and Access-Control-Allow-Headers headers) can be cached. |
access-control-allow-methods | Indicates which HTTP methods are allowed on a particular endpoint for cross-origin requests.For example: GET, PUT, POST, DELETE. |
content-length | The Content-Length entity header indicates the size of the entity-body, in bytes, sent to the recipient. |
content-type | The Content-Type entity header the client what the content type of the returned content actually is. |