Preliminary

The Direct Match ID France API allows Service Providers (SPs) to compare the information they have in their database for a particular user with that is known by the user’s telco operator in their own KYC records (name, address…).

This document provides quick links to the following contents:

1. Prerequisites
2. List of available resources
3. Compliancy with standards
4. OAuth 2.0 Access Token request
5. MatchID API request
6. List of errors

Prerequisites

The following steps must be carried out in order to call the Direct MatchID France API:

• create an application (or reuse an existing one),
• subscribe to Direct MatchID France API offer on Orange Developer portal,
• generate a public/private RS256 key pair. The private key will allow you to sign the JWT assertion,
• register the public key (JWKS) in the Setting section of the App details page of Orange Developer portal,
• buid the JWT assertion and sign it with your private key,
• request an OAuth 2.0 access token (POST /token) from the JWT assertion previously generated (according to OAuth 2.0 'jwt_bearer' grant type [RFC7523]),
• Submit customer's data (POST /matchid, with required MSISDN number) to be checked based on Orange KYC's records.

List of available resources

Resources are available from Internet network, using the following secure endpoints.

1/ OAuth 2.0 Authorization Server

The Discovery endpoint allows your application to retrieve the configuration metadata of the OAuth 2.0 Authorization server.

resources
- Discovery request [GET]: https://api.orange.com/oauth-jwt/fr/v1/.well-known/oauth-authorization-server

The Token endpoint allows your application to request a new OAuth 2.0 access token

resources
- Token request [POST]: https://api.orange.com/oauth-jwt/fr/v1/token

2/ Direct Match ID France API

The Match ID endpoint allows your application to compare the information given by a particular user with those known by Orange Telco operator in its KYC database.

resources
- Match ID request [POST]: https://api.orange.com/direct-matchid/fr/v1/matchid

Compliancy with standards

1/ JSON Web Key (JWK)

a/ Definition

As defined by [RFC7517], a JSON Web Key (JWK) is a JSON data structure that represents a cryptographic key (typically RSA). These keys can be either asymmetric or symmetric, and they can hold both public and private information about the key.

The section 4 of the https://tools.ietf.org/html/rfc7517 specification define the common parameters of a key.

• kty (required): identifies the cryptographic algorithm family used with the key. E.g. 'RSA'.
• use (optional): identifies the intended use of the public key. The "use" parameter is employed to indicate whether a public key is used for encrypting data or verifying the signature on data. E.g. 'sig'.
• alg (optional): identifies the algorithm intended for use with the key. E.g. RS256.
• kid (optional): used to mach a specific key. E.g. sFXa-BPYtbCLWk2aeycb9HTM701AATKMZKsn9ss1OUU.

The section 6.3.1 of the https://tools.ietf.org/html/rfc7518 specification define the specific parameters of a public RSA key.

• n: the modulus value for the RSA public key. It is represented as a Base64urlUInt-encoded value. E.g. q21s7KxUIk4Od8YhymUGb8xDKTj_D3JDYEAII9EER4AMIXbRB1wQ6zrC0V_U/../tuAmUrV3vqW4TUpkByX5Tye-1--rW96ddvd8ap_-orKqmc9iEMvansR0UN6BYoFebQKJj-sxp8w
• e : the exponent value for the RSA public key. It is represented as a Base64urlUInt-encoded value. E.g. AQAB

b/ Usage

As defined by RFC7523, the JSON Web Key (JWT) profile for OAuth 2.0 Authorization Grant flow is requiring RSA key pair:

• The RS256 private key will be used to sign the JWT assertion to be posted to the OAuth 2.0 Authorization request (POST /token) according to OAuth 2.0 JWT Bearer grant flow [RFC7523]
• The RS256 public key (formatted as a JWKS document) will be registered with the OAuth 2.0 Authorization server using Orange developer portal (App details page / Setting tab). This public key will be used to validate the integrity of the provided JWT assertion.

c/ Examples

Below a RSA key pair that similar to the one to be used by your application to implement the OAuth 2.0 JWT Bearer grant flow.

Private RS256 key (JWKS format):

{
  "p": "_0OJqvplp0nWb6mXH5FUUrWnfOyZLbfJ2h9tgZvNTjUMAryq-eWCi0TiNF9I-rO2NsWYf6e-LMzD2l3a_Jaqbm91cvjk-PbzSsTuo7-jszx_P0mFqJVaGtRCQL-a_1d2H_T6WO0ZXLT5K1JwfFqH-5DZyWS1VobwkeqysQ8M1IM",
  "kty": "RSA",
  "q": "tvCpu8uU6f_sWybFIOGCMSHaDphoaaWp8lGC-ueGXUfFjJIJAMP9WmfXwMZxzt/../MiMPb9b-l_HPdMWKHKWa-gFFDpGMAZuqa25z4MKrdNOSir3BPjbn-kUot4AfR_5APFP2E",
  "d": "NaqO0vffU0TxigYVA6qTp7C2AfDjD3qF_O0tIk347E81UP7rNGStWdNU2D4ikkS7-4QB9J638P0liSRTN43mc1eTKa-YSYDG/../sGSbyuDY4mDcLXTdM34vkp998g_Vrm9zhCnmBJVluFP4hvnBCLePBbWoa0Q2-Nq4xgUUP2QZmntLxqldGIWzfdVMUumKZ80nAqS3QOs99fwML4XDGH7ozYnvMiVql45ElqUXLsWiO8ZrZ5LbyuES2Xs7DK7k4vqU87x2HdTqeGWixQfkFm51l2KwQ",
  "e": "AQAB",
  "use": "sig",
  "kid": "rwewBsA2aZ3wLTCTYYqUZEEQ-2pLwXWJYPBdGv8g4c8",
  "qi": "hyWklpkjsawUoVWYAZmi9vrtQBJQo0hPat73a-MOU_njB6FIqNy_X5ouuOswJ2u7Vdw/../tfCp2ihhluWZTYl1iVfzu78vKJLJ2ab4ng6anl567EBLuwRJAl1Cgzhog-PRT0tkYJMlGIg",
  "dp": "6ztn4GJDzzfiHqCgHX0lwdqY8CxwtIrLvvB7T5cuSUXlPZhzzzpLZOAjvLOaYz29Sxg/../VG_SubRY8YjE_KliKcGGFGdLids3T77FMraUuFtcMoY13jPxWGfrNrn4Xo_kX359_qr_P4lNU",
  "alg": "RS256",
  "dq": "dBPgnzheFNw-rNe83VA5u9Mu-XPbTK3BV_BAm9OsfiO8RaWj8MhrSaH6VGeWbxrgW_RPPN5X1fIXcBcGcGFtQG0k0rqkYA1ST5DN71ywpUETLp-J-GcyGksOijnV6Q4t2XaK3NRL2g6UycXlSg90fQBhnwt-yKGWVCc_vv5legE",
  "n": "tmn8b3WFffcrBKD2IbFBqO6kfPOSi-_7ABvAGkb4ZVWRPkl6to_Db3-rmow4JFFJfkfL9hPYATxnzlB96.//.VutBIqdDz3X2uzIVRmMTV0KgonQadSR5fip-s1qsqNoJnmU2784UygTCuMJAcFhQ1zltj1jQCBq2mljiNqRdCwEUDz3F4KjuYONH8Cida1s4fzigqZ8x_NKrRerKVPdMsZzeAgOqCuLPeYqcDPujdbm1yVCBn0fFoxBRAQs7TZhKvfmN2C0TT7ffCow"
}

Public RS256 key (JWK format):

{
  "kty": "RSA",
  "e": "AQAB",
  "use": "sig",
  "kid": "rwewBsA2aZ3wLTCTYYqUZEEQ-2pLwXWJYPBdGv8g4c8",
  "alg": "RS256",
  "n": "tmn8b3WFffcrBKD2IbFBqO6kfPOSi-_7ABvAGkb4ZVWRPkl6to_Db3-rmow4JFFJfkfL9hPYATxnzlB96/../VutBIqdDz3X2uzIVRmMTV0KgonQadSR5fip-s1qsqNoJnmU2784UygTCuMJAcFhQ1zltj1jQCBq2mljiNqRdCwEUDz3F4KjuYONH8Cida1s4fzigqZ8x_NKrRerKVPdMsZzeAgOqCuLPeYqcDPujdbm1yVCBn0fFoxBRAQs7TZhKvfmN2C0TT7ffCow"
}

d/ Toolings

Cryptographic libraries exist to generate RSA key pair.

The following settings are required when generating a RSA key pair for JWT signature/validation.

• the key algorith, which should be RS256 (i.e. "alg"= "RS256"),
• the key length, which should be 2048 bits,
• the key use, which should be signature (i.e. "use"= "sig"),
• the key identifier, which is generally the thumbprint of the private key (SHA-256).

As an example: jsrasign opensource free JavaScript cryptographic library that supports JSON Web Signature(JWS)/Token(JWT)/Key(JWK).

// Generate asymetric keys pair (RS256)
kp1 = KEYUTIL.generateKeypair("RSA", 2048);

// Get private key
jwkPrvKey = KEYUTIL.getJWKFromKey(kp1.prvKeyObj);
jwkPrvKey.use = "sig";
jwkPrvKey.alg = "RS256";
jwkPrivKey.kid = KJUR.jws.JWS.getJWKthumbprint(jwkPrvKey);

// Get public key
jwkPubKey = KEYUTIL.getJWKFromKey(kp1.pubKeyObj);
jwkPubKey.use = "sig";
jwkPubKey.alg = "RS256";

More information can be found here

• How to generate a JSON Web Key (JWK) (source: Connect2Id.com)

For manual testing with jwt.io tool, JSON Web Key generators like mkjwk - Simple JSON Web Key generator can be used to generate RS256 key pair in JWK format and to the JWKS JSON document.

As an example: set the key size (=2048), the key use (=signature), the algorithm (=RS256: RSA + SHA-256) and the key identifier (SHA-256).

On 'Generate' button click, the tool generates 3 assets that can be easily copied.

The private key (JWK) is displayed on the left. The public key (JWK) is displayed on the right. In the center, you will find the JWKS JSON document with both private & public keys.

WARNING: Before registering the JWKS JSON document on the Orange Developer portal, for the application you created, you should update it manually so that the JWKS JSON document contains the public key (JWK) only.

2/ JSON Web Key Set (JWKS)

a/ Definition

As defined by RFC7517, a JSON Web Key Set (JWKS) is a JSON document that represents a set of cryptographic keys (e.g. RSA) in JWK format.

As an example: a JWKS JSON document with public RSA key.

{
  "keys" : [{
    "kty": "RSA",
    "e": "AQAB",
    "use": "sig",
    "kid": "rwewBsA2aZ3wLTCTYYqUZEEQ-2pLwXWJYPBdGv8g4c8",
    "alg": "RS256",
    "n": "tmn8b3WFffcrBKD2IbFBqO6kfPOSi-_7ABvAGkb4ZVWRPkl6to_Db3-rmow4JFFJfkfL9hPYATxnzlB96/../VutBIqdDz3X2uzIVRmMTV0KgonQadSR5fip-s1qsqNoJnmU2784UygTCuMJAcFhQ1zltj1jQCBq2mljiNqRdCwEUDz3F4KjuYONH8Cida1s4fzigqZ8x_NKrRerKVPdMsZzeAgOqCuLPeYqcDPujdbm1yVCBn0fFoxBRAQs7TZhKvfmN2C0TT7ffCow"
  }]
}

b/ Usage

The JWKS JSON document (or a URL that is pointing to your JWKS JSON document) must have been registered on our Orange Developer portal. The Token request will fail if the public is not registered. This document must only contain the RS256 public key in JWK format.

Let's consider the following 'JWT Assertion Demo App' application, with an active subscription to Direct Match ID API offer.

On 'app details' page, you will get the clientID identifier (see Summary tab).

The client_secret is made available but it will not necessary by your application to authenticate towards our OAuth 2.0 Authorization server.

The 'Setting' tab allows you to register your JWKS JSON document or the URI that is pointing to this JSON document.

See 'Keystore (JWKS format) section below.

Case #1: JSON document content is provided

Case #2: JSON document URL is provided. The URL must be reachable from Internet without authentication (public).

JWT profile for OAuth2 authorization grant

a/ Definition

As defined by [RFC7519], JSON Web Token (JWT) is a compact, URL-safe means of representing claims to be transferred between two parties. The claims in a JWT are encoded as a JSON object that is used as the payload of a JSON Web Signature (JWS) structure or as the plaintext of a JSON Web Encryption (JWE) structure, enabling the claims to be digitally signed or integrity protected with a Message Authentication Code (MAC) and/or encrypted.

JWTs represent a set of claims as a JSON object that is encoded in a JWS and/or JWE structure.

• This JSON object is the JWT Claims Set
• As per Section 4 of [RFC7519], the JSON object consists of zero or more name/value pairs (or members), where the names are strings and the values are arbitrary JSON values. These members are the claims represented by the JWT
• The member names within the JWT Claims Set are referred to as Claim Names
• The corresponding values are referred to as Claim Values

Our OAuth 2.0 Authorization server's implementation partially complies with the [RFC7523] specification (i.e. JSON Web Token (JWT) profile for OAuth 2.0 Client Autentication and Authorization Grant) that defines how a client should use a JSON Web Token (JWT) Bearer Token as a means for requesting an OAuth 2.0 access token as well as for client authentication (see Note).

NOTE: The use of a JWT Bearer Token for client authentication is NOT SUPPORTED by our OAuth 2.0 Autorization Server.

b/ Usage

Step N°0: Prerequisites

RSA key pair is generated and the public key is registered to our OAuth 2.0 Authorization server using Orange developer portal.

Step N°1: JWT assertion build

Your application will have to build the JWT assertion that is bound of a header, a body and a signature.

a/ Header

b/ Payload

Below an example of JWT assertion:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InJ3ZXdCc0EyYVozd0xUQ1RZWXFVWkVFUS0ycEx3WFdKWVBCZEd2OGc0YzgifQ.eyJpc3MiOiJKR2hPQWpTTEd1eU1kOFhOQVRMNWtoMFRocE1mR1pGOCIsImNsaWVudF9pZCI6IkpHaE9BalNMR3V5TWQ4WE5BVEw1a2gwVGhwTWZHWkY4Iiwic3ViIjoiMzM2MDAwMDAwMDAiLCJzdWJfdHlwZSI6Ik1TSVNETiIsInNjb3BlIjpbImF0cF9reWNfcGxhaW4iXSwiYXVkIjoiaHR0cHM6Ly9vcGVuaWQub3JhbmdlLmZyIiwianRpIjoiU3Y3VnZxSU1odUxJZDJ6aDd0VHlTeEUwMUlIbm1aYVdEVGxKTnRkSUFXZyIsImlhdCI6MTY0NzYwNjU2OCwiZXhwIjoxNjQ3NjEwMTY4fQ.aGbyEkDec62OOgaGk2OSivAX6-O2NiDl6SpTGPiidug4q62Wr5NBmB6lvCaiFaiybryKWX7TugSTo6j3-JNycs66pwraoFeOts9vsh6lpCZmXooqWtcb5o6imVN5jlA4Tv4VjkRR5f2-Ix1BxBtbRDfekI1etiZPjdlfMyPmUmwVtzAZQSuRCWgig3os0NtnVkHqFWwTJGfIDKdtzWQVD4n8pY3fsdTEnnjGFXr05Kb2GGU3XKpE-8P84I8bMBpglop_uPXot1B1ouiwSMR9x59qOVj-YqQa6I_BGylnSERe-ym7mkYbF6VOkIX3ONTw4STBGByUH3aWq6-dc4SfIg

The jwt.io tool is used here to decode the JWT. We added to RS256 public key (JWK format) to verify the signature of the JWT assertion.

TIPS: For timestamps (i.e. 'iat' and 'exp' properties), the tool may help you if you are using jwt.io tool for building the JWT assertion manually for you own unitary tests.

Step N°2: Access token request

To use a Bearer JWT as an authorization grant, the client uses an access token request as defined in Section 4 of the OAuth Assertion Framework [RFC7521] with the following specific parameter values and encodings:

As an example:

curl -X POST \
     -H "Accept: application/json" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer \       
     &assertion=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InJ3ZXdCc0EyYVozd0xUQ1RZWXFVWkVFUS0ycEx3WFdKWVBCZEd2OGc0YzgifQ.eyJpc3MiOiJKR2hPQWpTTEd1eU1kOFhOQVRMNWtoMFRocE1mR1pGOCIsImNsaWVudF9pZCI6IkpHaE9BalNMR3V5TWQ4WE5BVEw1a2gwVGhwTWZHWkY4Iiwic3ViIjoiMzM2MDAwMDAwMDAiLCJzdWJfdHlwZSI6Ik1TSVNETiIsInNjb3BlIjpbImF0cF9reWNfcGxhaW4iXSwiYXVkIjoiaHR0cHM6Ly9vcGVuaWQub3JhbmdlLmZyIiwianRpIjoiU3Y3VnZxSU1odUxJZDJ6aDd0VHlTeEUwMUlIbm1aYVdEVGxKTnRkSUFXZyIsImlhdCI6MTY0NzYwNjU2OCwiZXhwIjoxNjQ3NjEwMTY4fQ.aGbyEkDec62OOgaGk2OSivAX6-O2NiDl6SpTGPiidug4q62Wr5NBmB6lvCaiFaiybryKWX7TugSTo6j3-JNycs66pwraoFeOts9vsh6lpCZmXooqWtcb5o6imVN5jlA4Tv4VjkRR5f2-Ix1BxBtbRDfekI1etiZPjdlfMyPmUmwVtzAZQSuRCWgig3os0NtnVkHqFWwTJGfIDKdtzWQVD4n8pY3fsdTEnnjGFXr05Kb2GGU3XKpE-8P84I8bMBpglop_uPXot1B1ouiwSMR9x59qOVj-YqQa6I_BGylnSERe-ym7mkYbF6VOkIX3ONTw4STBGByUH3aWq6-dc4SfIg" /
     https://api.orange.com/oauth-jwt/fr/v1/token 

On success, the HTTP response status will be set to 200 OK, and the body will be a JSON object containing the following fields:

• token_type (required): the token type. Fixed: Bearer.
• access_token (required): the access token to be used to retrieve end-user's claims, by setting the header as follows: Authorization: Bearer {access_token}.
• expires_in (required): the token validity in seconds. It is the expiration time of the access token in seconds from the time of generation of the response (for example, 3600 seconds).

At the end, you should receive JSON data similar to:

HTTP/1.1 200 OK
Content-Type:application/json

{
   "token_type": "Bearer",
   "access_token": "OFR_JGhOAjSLGuyMd8XNATL5kh0ThpMfGZF8_75d853e5786967799d3b8f96bc8a3431/../db5c67bd02f81ee1dc58b20370ae5fa",
   "expires_in": 3600
}

On error, the HTTP response status will be ste to 4xx or 5xx depending on the cause of th error.

For example, if the JWT is not valid, or the current time is not within the token's valid time window for use, the OAuth 2.0 authorization server will construct an error response as defined in OAuth 2.0 [RFC6749]. The value of the "error" parameter MUST be the "invalid_grant" error code. Additional information regarding the reasons the JWT was considered invalid is provided using the "error_description" parameter.

As an example: JWT assertion validation failure due to missing public key (kid) in the JWKS document.

HTTP/1.1 400 Bad Request
Content-Type:application/json

{
  "error": "invalid_grant",
  "error_description": "JWS Validation failed, [JWS] statelessVerify - Error: no key found signature ko"
}

See List of errors for further details.

Direct MatchID France API

a/ Definition

The Direct MatchID France API allows Service providers to compare the information they have in their database for a particular user with that is known by the user’s telco operator in their own KYC records.

b/ Usage

A POST /matchid request to the Direct MatchID France API endpoint with the user’s information it holds in its database. The Authorization header with Bearer token (obtained from the OAuth 2.0 Authorization Server) is required according to the HTTP Bearer authentication scheme.

• List of input data (JSON object):

As an example:

curl -X POST \
     -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer OFR_JGhOAjSLGuyMd8XNATL5kh0ThpMfGZF8_75d853e57/../dc58b20370ae5fa" \
     -d "{ \
           "msisdn": "33600000000", \
           "given_name": "Christine", \
           "family_name" : "Dumontel", \
           "birthdate" : "1978-11-25", \
           "address" : { \
             "street_address" : "11 rue des Lilas", \
             "locality" : "Paris", \
             "postal_code" : "75018", \
             "country" : "France" \
           }, \
           "email" : "christ178.dumontel@orange.fr" \
         } \
     https://api.orange.com/direct-matchid/fr/v1/matchid

On success, the Direct MatchID France API returns a response message with HTTP 200 (OK) status code + output data (JSON object)

Below the properties of the JSON object in the response message:

NOTE: the matching score is calculated based on the Jaro–Winkler distance that is a string metric measuring an edit distance between two sequences. More information can be found here.

As an example:

HTTP/1.1 200 OK
Content-Type: application/json
X-OAPI-Request-Id: opopecballrt01-25890-18319326-1

{
  "given_name_score": 100,
  "family_name_score" : 100,
  "birthdate_score" : 100,
  "address" : {
    "street_address_score" : 83.5,
    "locality_score" : 100,
    "postal_code_score" : 100,
    "country_score" : 100
  },
  "email_score" : 100
}

On error, the Direct MatchID France API returns an error response message with HTTP 4xx/5xx status code + error details (JSON object: error/error_description)

As an example: missing mandatory parameter

HTTP/1.1 400 Bad Request
Content-Type: application/json
X-OAPI-Request-Id: opopecballrt01-25890-18319326-1
 
{
  "error":"invalid_request",
  "error_description":"REQUIRED parameter msisdn is missing."
}

See List of errors for further details.

List of errors

Token endpoint

Below is a list of errors that your application may receive when calling the OAuth2.0 Authorization server's Token endpoint.

The following list of errors fully complies with OAuth 2.0 specification. See [OAUTH] for further details.

NOTE 1: The request is missing a required parameter, includes an unsupported parameter value (other than grant type), repeats a parameter, includes multiple credentials, utilizes more than one mechanism for authenticating the client, or is otherwise malformed.

NOTE 2: The request is missing a required parameter, includes an unsupported parameter value (other than grant type), repeats a parameter, includes multiple credentials, utilizes more than one mechanism for authenticating the client, or is otherwise malformed.

NOTE 3: The authorization grant type is not supported by the OAuth 2.0 authorization server. Must be: 'urn:ietf:params:oauth:grant-type:jwt-bearer'.

NOTE 4: The 'client_id' in the JWT assertion (payload) is missing or doesn't match with a registered client.

Direct MatchID endpoint

Below is a list of errors that your application may receive when calling the Direct Match ID endpoint.

The following list of errors fully complies with OAuth 2.0 specification. See [OAUTH] for further details.

NOTE 1: The request is missing a required parameter (header, body parameter, etc.).

NOTE 2: the MSISDN number provided in the JWT assertion must match with a valid and eligible Orange subscriber.