Security

API Authentication – SP to UAEPASS

UAEPASS APIs are secured with a client credential token. To obtain this token, API consumers must be onboarded as a service provider by the UAEPASS operations team. Upon onboarding, they receive a client ID and client secret, which are used to generate the token as per the specified process.

Generating client credential tokens

API URL	https://stg-ids.uaepass.ae/oauth2/token
Source	Service Provider (Data owner)
Target	UAEPASS
Sample cURL	curl --location 'https://stg-ids.uaepass.ae/oauth2/token' \ --header 'Authorization: Basic *********************' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'scope=urn:uae:digitalid:backend_api:manage_user_consent openid ' \ --data-urlencode 'grant_type=client_credentials'
Method	POST
Security	(CCG) Client Credentails Grant
Headers	Authorization: {Basic with client credentials} – base64(clientid:client_secret) – to be obtained from UAEPASS operations team. Content-Type: {Standard form url encoded type for token}

Request Payload

curl --location 'https://stg-ids.uaepass.ae/oauth2/token' \ 
--header 'Authorization: Basic *********************' \ 
--header 'Content-Type: application/x-www-form-urlencoded' \ 
--data-urlencode 'scope=urn:uae:digitalid:backend_api:manage_user_consent openid ' \ 
--data-urlencode 'grant_type=client_credentials' 

Response Payload

Sample success response	{ "access_token": "4d6861ed-aa8d-31e3-acff-df3413ee68bf", "scope": "openid urn:uae:digitalid:backend_api:manage_user_consent", "id_token": "eyJ4NXQiOi…” "token_type": "Bearer", "expires_in": 3600 }

Values of X-UP-AccessToken & Authorization headers

The value of access_token from the above response should be used for the header ‘X-UP-AccessToken’.

Similarly, the value of id_token should be used to populate the value of the header ‘Authorization’.

API Authentication – UAEPASS to SP

Callback API invoked by UAEPASS to notify SP about a consent decision made by user is protected by API Key. A value for this API key must be agreed upon and shared with UAEPASS via secured channel.

This will be populated in the value of the header X-API-Key

In addition to the X-API-KEY, we can also send an authorization header with basic credentials, depending on the service provider’s configuration in UAEPASS and it is optional based on service requirement.

API nonrepudiation – HMAC

To guarantee that request body of the API(s) have not been modified inflight, and that the origin of the API invocations is legitimate. HMAC (HmacSHA256) has been used.

Fields included in creating the HMAC tokens.

1. API request body

2. Value of Request header: X-Timestamp

Raw input to HMAC to generate HMAC token -> header[X-Timestamp] + request body json.

Kindly note that both SP & UAEPASS must agree on the above implementation to make HMAC verification possible on both ends. Once HMAC tokens are generated, they should be added as the value of the header ‘X-UAEPASS-Signature’.