A Three-legged OAuth Flow

Number Verify (CAMARA) uses a three-legged OAuth flow. A three-legged OAuth process involves three parties: the end-user (or resource owner), the client (the third-party application), and the server (or authorization server):

1. Get an authorization code
2. Exchange the authorization code for an access token
3. Match the mobile number

For more information on OAuth, see OAuth 2.0 RFC 6749, section 4.1 (external website).

Get an Authorization Code

1. Make a request to Vodafone’s “/bc-authorize” endpoint.
2. Vodafone's API validates the client_id provided.
3. Vodafone obtains the mobile number of the user (of the application using the mobile network).
   This is achieved by the Vodafone returning a series of HTTP redirects that the application should follow.
4. Vodafone provides an authorization code back to the application.

Authorization request example

GET 'https://apistagingref.developer.vodafone.com/openIDConnectCIBA/v1/bc-authorize' \
Content-Type: application/x-www-form-urlencoded \
Accept: application/json \
redirect_uri=https%3A%2F%2Fexample.com%2Fmc &client_id=asQIujGX4tD9eBMgeO8LnzyRnalkTGoG &scope=dpv:FraudPreventionAndDetection#number-verification:verify &response_type=code

Authorization response example

HTTP/1.1 302 Found
Location: https://sp.example.com?code=SplxlOBeZQQYbYS6WxSbIA
&state=af0ifjsldkj &correlation_id=42da5b19-457a-4d30-a5c4-038c62dccbb0

Get an Access Token

In order to use this API, you must exchange the authorization code for an access token.

The token is valid for 59 minutes and 59 seconds. It can be used for multiple requests.

The bearer tokens can only be used for a specific country. For example: If you generate a token for a UK mobile number (MSISDN), you cannot use it to query a German number.

If the request is valid, the API returns an access_token, along with expiry and scope information.

This access token can then be used in one or more requests, for as long as the token remains valid.

If the request is not valid, the APIs returns an error message.

To exchange the authorization code for an access token:

1. Make a “/token” request.
2. Validate the “id_token” within the response. This to ensure it was issued from the correct authorization server, the correct client_id, and in a timely manner.

Token request example

curl POST 'https://apistagingref.developer.vodafone.com/openIDConnectCIBA/v1/token' 
Authorization: Basic ZTcxNWE2OTYtYTY3OS00YmFhLTk3ODctYTU0ZmYlMTFhNmQ4OjdhMzM3OGI5LWZkMTQtNGNhYy1hZTc 3LTkwZGVmZmZkYWQ5Yg==
code=w4tngz6O&state=1234&redirect_uri=https://sp.example.com &grant_type=authorization_code

Token response example

200 OK
Server: VF
Content-Type: application/json
Content-Length: 165
Cache-Control: no-store
Pragma: no-cache.
Content-Length: xx.
Content-Type: application/json
{
"access_token": "OohPZluqx9NYtkTA3Ok6yfRmIECi", "token_type": "Bearer",
 "expires_in": 3599,
"id_token": "eyJraWQiOiJhcGl4IiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJhdF9oYXNoIjoia0V3dzB SdF81dk8tZGo5UjFoY0dlQSIsInN1YiI6IjZmODVjM2EyLTRlY2EtNGM4Yy1hNDI4LWQ0NjNlNmIxNz NmNiIsImNyaWQiOiIyOTQ4NDUyNSIsImFtciI6WyJTTVNfVVJMX09LIl0sImlzcyI6Imh0dHBzOi8vY XBpc3RhZ2luZ3JlZi5kZXZlbG9wZXIudm9kYWZvbmUuY29tIiwibm9uY2UiOiIxMjM0NTY3OCIsImF1 ZCI6ImU3MTVhNjk2LWE2NzktNGJhYS05Nzg3LWE1NGZmZTExYTZkOCIsImFjciI6InVybjp2b2RhZm9 uZTpsb2E6YnJvbnplOnNtc3VybCIsImF6cCI6ImU3MTVhNjk2LWE2NzktNGJhYS05Nzg3LWE1NGZmZT ExYTZkOCIsImF1dGhfdGltZSI6IjE1NjUzNTI3MjAiLCJleHAiOjE1NjUzNTYzNjgsImlhdCI6MTU2N TM1Mjc2OCwianRpIjoiNGFlMTJlNzMtMDY4Yi00ZTUyLWJmMmMtOWUyNjdiNGQ3NDNmIn0.U3MO6FFr 3l0G6_TvmlbpGyxVPxZKCQyvB_1J5TFeA8Jlx7KhE1nf9LDVw22eX2X6- 1ogqKLGXl_4Q3ou0p_lMk2z8uFGulHB4Xv51qAMdLwA9XPfoW7j2fVaoRdjSDWQbNpurpyC0sHWsSJt -
O4SP_All1_PTtv8MBlIPJyLpFsSU3cAnbQcXQ8NQ5FqNfAlgj11ejsxBOzr8UaT0wYMOCapz8V89FmQ 9F7fj- YpNoco4r8G_KSkjjbSWL4FdTbxTQ2iBNAKtoaTN2bmbVfUaADMJDDdTeLTJerpNbi4LVlqkvhKiSWzI UOBf_10FKt4KUffnx4AK_IAvS49nwwt5w"
}

Decoding the id_token gives the following JWT header and payload:

{
  "kid": "apix",
  "typ": "JWT",
  "alg": "RS256"
} {
"at_hash": "kEww0Rt_5vO-dj9R1hcGeA",
"sub": "6f85c3a2-4eca-4c8c-a428-d463e6b173f6", "amr": [
"SEAM_OK" ],
"iss": "https://apistagingref.developer.vodafone.com", "nonce": "12345678",
"aud": "e715a696-a679-4baa-9787-a54ffe11a6d8", "acr": "2",
"azp": "e715a696-a679-4baa-9787-a54ffe11a6d8", "auth_time": "1565352720",
"exp": 1565356368,
"iat": 1565352768,
"jti": "4ae12e73-068b-4e52-bf2c-9e267b4d743f"
}

Using the Sandbox

The test phone number should be converted to a hashed format and added to the body of API. 

To create the hash use SHA-256 (hexadecimal representation) with the mobile phone number in E.164 format (starting with country code). Number must be prefixed with '+'.

{
"hashedPhoneNumber": "6dd5d20f257c1f3620662454064e3aa25ba9a6c7a4d1e99e965bbadd3a7e07d6"
}