1

SDG-UAEPass Digital ID Authentication Integration

using Oauth2

Document version 0.9

Created Date: 15th Aug 2019
 2

Table of Contents
Document Control................................................................................................................................................................... 3
Document History ............................................................................................................................................................... 3
Introduction .............................................................................................................................................................. 4
Chapter 1: Web Application Integration ...................................................................................................................... 5
1. How to use UAEPASS for browser based flow-using OAuth2 for web applications? .................................................. 5
2. Pre Requisites from SP ................................................................................................................................................ 6
3. Endpoints .................................................................................................................................................................... 6
4. Integration Steps ......................................................................................................................................................... 6
4.1 Obtain the (OAuth2) access code........................................................................................................................ 6
4.2 Obtaining the Access Token .............................................................................................................................. 10
4.3 Obtaining Authenticated User Information from the Access Token................................................................. 13
4.4 Web Single Sign-On (SSO) and Logout user session from UAE PASS................................................................. 15
5. User Linking Scenarios and Guidelines...................................................................................................................... 16
Chapter 2: Mobile Application Integration ................................................................................................................ 18
1. Pre requisites ............................................................................................................................................................ 18
2. Requirements to Take to Account When Programming the Mobile Application ..................................................... 18
3. Protocol and Interactions between the Mobile Application and Mobile ID................................................................ 19
Appendix-A .............................................................................................................................................................. 22
Appendix-B .............................................................................................................................................................. 22
 3

Document Control

Document History

Date Version Author(s) Description

04-04-2018 0.1 Yusuf Khan Initial Draft
Added Attributes list, updated API response and more
25-09-2018 0.1 Yusuf Khan
details.
Enhanced document and added logout and linking
05-01-2019 0.2 Yusuf Khan
details.
Updated the UAE PASS application link for Android
01-08-2019 0.3 Jayshree Pujari
new version on staging.
06-08-2019 0.3 Jayshree Pujari Added the production logout url
15-08-2019 0.3 Rinku Singh Updated Error Codes for Obtaining Authorization
19-09-2019 0.4 Jayshree Pujari Updated the scope and attribute list
25-09-2019 0.5 Rinku Singh Updated Logout redirect URL with parameters
13-10-2019 0.6 Jayshree Pujari Updated the Staging App links for Android and iOS
20-10-2019 0.7 Jayshree Pujari Updated the attribute list (Added two new fields)
03-11-2019 0.8 Jayshree Pujari Updated the Access Token Error codes
10-11-2019 0.9 Jayshree Pujari Updated the Sample response and added QR code
29-07-2020 1.0 Jayanth Malipeddy • Updated login url for Mobile Integration
• Updated link for sample and staging
applications
• Updated the Mobile Integration chapter with
the new android security steps.
 4

Introduction
This document describes the SP integration guide with “UAE PASS” a Nationwide Digital Identity and Digital Signature
platform using the Oauth2 protocol.

The Audience of this document is those who want to integrate with this API using REST standards, this document
describes the operations available and the corresponding input and output parameters when invoking these operations.

Below here is the list of HTTP status codes that will return as response.

HTTP Status Codes Description

200 Success and response is received
204 No Content
400 Not all required parameters provided.
405 Method not allowed. Invalid method sent for calling the
API.
401 Unauthorized, Invalid or no credentials provided
403 Forbidden. Invalid credentials i.e. Wrong username or
password
404 Not Found
500 Server Error.
503 Service Under maintenance
 5

Chapter 1: Web Application Integration

1. How touse UAEPASSfor browser-based flow-using OAuth2 for web applications?

This section explains how to integrate the web applications allowing UAEPASS user to authenticate from third party web
application.

Below is the high-level flow:

Figure 1
 6

2. Pre Requisites from SP

Below are the prerequisites before starting the integration:

1. An overview and technical session to be conducted by UAE PASS team with integrating entity or Service Provider
(SP hereafter).
2. UAE PASS team to share the “Authentication Integration Questionnaire” to Service Provider team in orderto
fill and provide requested information for generating the appropriate credentials.
3. Sample UAE PASS App should be shared by SDG and installed on SP owned device(s).
4. Enroll sample test users in UAE PASS mobile app for SP team development and testing.

3. Endpoints
Since the integration is based on OAuth2, below are the standard endpoints of UAE PASS for QA and Production
environment:

Environment Endpoints
• Authorization Endpoint : https://qa-id.uaepass.ae/trustedx-authserver/oauth/main-as
QA • Token Endpoint : https://qa-id.uaepass.ae/trustedx-authserver/oauth/main-as/token
• User Info Endpoint : https://qa-id.uaepass.ae/trustedx-resources/openid/v1/users/me

• Authorization Endpoint : https://id.uaepass.ae/trustedx-authserver/oauth/main-as

• Token Endpoint : https://id.uaepass.ae/trustedx-authserver/oauth/main-as/token
Production
• User Info Endpoint : https://id.uaepass.ae/trustedx-resources/openid/v1/users/me

4. Integration Steps

The authentication scenario is achieved by the consuming Service provider application by performing the below steps:

(Thedetails for configuration shall besharedby UAEPASSteam inordertoconfigurethevaluesaccordingly asmentioned

in below steps)

4.1 Obtain the (OAuth2) access code

Redirect to below URL in order to initiate login with UAEPASS from the SP application. The user shall be presented
with UAEPASS authentication page and continue authentication at UAEPASS.

On success/failure the control will return back to the calling SP app callback URL with appropriate status. In case of
success the SP web app will receive the “code” at the callback URL of SP (which is pre-configured in UAEPASS).
(Just changethe"redirect_uri" and"client_id" appropriately asper your environment andother parameters as
applicable)
 7

As per above diagram (Figure 1), below is the sequence flow along with the details:

1. The SP web application needs to send a browser 302 redirect request to UAEPASS (Authorization) Server
endpoint along with the below mentioned parameter and as per below sample request.

Redirect URL:
https://qa-id.uaepass.ae/trustedx-authserver/oauth/main-as?redirect_uri={redirect uri as
agreed}&client_id={client
id}&response_type=code&state=ShNP22hyl1jUU2RGjTRkpg==&scope=urn:uae:digitalid:profile:general&ac
r_values=urn:safelayer:tws:policies:authentication:level:low&ui_locales=en

i. On successful redirection, UAEPASS login page shall display and the user can provide his/her identifier directly
on UAEPASS login page.
ii. UAEPASS will send push notification to UAEPASS Mobile App installed in user’s device to confirm the
authentication request by providing the PIN or any other configured method in his/her mobile device.

iii. After successful authentication, UAEPASS shall send redirect to the “redirect_uri” URL (which is callback URL
of SP configured at UAEPASS platform) containing the “code”. This code can used by the SP web application to
obtain the access token issued to the authenticated user.

Note: Entity is allowed to add only one redirect URI to configure in UAEPASS Stage or Production servers.

iv. The SP web application shall handle this parameter from callback URL and call the below mentioned API in
next section using the obtained code in order to obtain the “access_token”.

Request

Request Parameter Details :

Name Type Usage Description

response_type query Required Must take the value, which indicates that an code
authorization code is requested.
redirect_uri query Required Redirect URI to the application. The application waits to
receive at this URI the authorization or authentication
response message with the authorization code.

client_id query Required Identifier of the client application. .(To be shared by

UAEPASS team)
state query Recommended We recommend using this parameter to safeguard
against CSRF attacks.

The application can also include additional information

in this parameter, such as the URL to which the browser
is to be redirected when the authorization or
authentication finishes. (To include multiple data in the
value of this parameter, the application must serialize it
as it sees fit.)
 8

scope query Required List of values, separated by spaces, that represent the
scope of the authorization that the application wants to
obtain. It queries the scopes required for accessing the
resources or services in question.(To be shared by
UAEPASSteam if its value otherthan as specified in
sample above)
acr_values query Optional Defines conditions for authenticating the user (minimum
levels or specific flows) who must authorize the access.
(To be used as specified in sample or check with UAE
PASS team for more details)
ui_locales Query Optional Language parameter to be sent in order to render
English or Arabic login pages of UAEPASS and below are
the possible values:
• English page : en
• Arabic pages : ar

Authentication Request

Redirect URL:
https://qa-id.uaepass.ae/trustedx-authserver/oauth/main-as?redirect_uri={redirect uri as agreed}&client_id={client
id}&response_type=code&state=ShNP22hyl1jUU2RGjTRkpg==&scope=urn:uae:digitalid:profile:general&acr_values=urn:
safelayer:tws:policies:authentication:level:low&ui_locales=en

Response
Authentication Response

Once the authentication or SSO of the user is complete, and the user has granted authorization, the application
receives an HTTP GET request of the following type from the user's browser. This HTTP request is an OAuth 2.0
authorization response or an OpenID Connect authentication response. The application receives this request at
the redirect URL specified in the authorization or authentication request message (the redirect_uri parameter)
or in the registered redirect URL.

GET {redirection_uri_path}?code={code}&state={state} HTTP/1.1

Host: {redirection_uri_host}
where “redirection_uri_path” is the redirect URI to the application.

Response Parameter Details:

Name Description
code Authorization code. Denotes the authorization that the
user granted to the application. The application must use
this code to obtain the access token and (in the case of
OpenID Connect) the ID token.
state The same value that the application includes in the
authorization or authentication request message.
 9

Error Management

If an error occurs during this step (i.e. authorization phase), UAE PASS does not return an Authorization
Response to the application. Instead it returns an error. In certain cases, the error is displayed directly in the
user's browser. In all cases, the administrator can obtain details on the error that occurred by browsing the log
records in the administration console.

There could be two scenarios on error management behavior:

• Errors without Redirection to the Client Application

If the authorization request is invalid because it includes an unregistered client identifier or a forbidden
redirect URL, UAE PASS displays a generic error message in the user's browser advising the user to
contact the administrator. In these cases, and for reasons of security, no redirection to the application is
performed. To diagnose this problem, the UAE PASS administrator must be contacted in order to
browse the log records.

• Errors with Redirection to the Client Application

If the authorization request fails for another reason, for example, because the user canceled the
authentication process, UAE PASS redirects the browser to the specified redirect URI and adds in the
following parameters, which are described in the standard. In this case, it is the client application's
responsibility to inform the user that an error has occurred (except where the authentication is
canceled).
o error: Error code. See the standard and the list below for more details.
o error_description: Additional description of the error. Not required.
o state: The same value that the application included in the Authorization Request message.

The following are the values supported and the meanings of error and error_description (if there is one) for
some of the common errors:
o invalid_request, InvalidSignIdentityTypeException: The value of
parameter sign_identity_id corresponds to a signing identity which is not recognized because its
type is undefined (identity is not certified).
o invalid_request, UnrecognizedAuthnRequirementsException: None of the authentication
requirements specified in the acr_values parameter are recognized.
o access_denied (without error_description): The user canceled the authentication process or
did not give authorization. In this case, we recommend that the client application does not
display any error message to the user.
o access_denied, RiskyAuthnContextException: The user was denied access because they were
accessing in a context of risk. This error occurs when the context analysis returns a rejectresult
and the authentication flow does not have a fallback for this case.
o access_denied, DisabledSignIdentity: The user was denied access to sign on server because the
requested signing identity is disabled.
o access_denied, LockedSignIdentity: The user was denied access to sign on server because the
requested signing identity is locked.
o access_denied, MissingDigestsSummaryException: The user was denied access to sign on
server because the requested signing identity is enabled via HSM and requires
the digests_summary and digests_summary_algorithm parameters.
o login_required: The user must be authenticated. This error can occur when the combination of
authentication requirements (requested and configured) result in one or more flows of only
reauthentication but the user has still not started a session in the identity provider. Or when the
application specified the prompt=none parameter, but interaction with the user is required.
 10

o invalid_scope: One of the scopes requested by the application is not included in this list of
scopes provided by the authorization server or has not been enabled for the authorization code
grant flow. This error also occurs if the application did not request any scope and the server has
no default scope defined for this type of grant.

Example
Below is an example of an authorization error response. Ellipses have been included to facilitate reading.
GET /oauth/back?error=access_denied&state=3dd9...8cd4 HTTP/1.1
Host: www.demoapp.com

4.2 Obtaining the Access Token

As per above diagram, the SP web application needs to obtain the access token from the available “code” which is
received after authentication from UAEPASS in above step i.

Below here is the API detail to exchange the token:

POST https://qa-id.uaepass.ae/trustedx-authserver/oauth/main-as/token
Authorization: Basic {credentials}
Content-Type: application/x-www-form-urlencoded; charset=UTF-8

Parameters:
grant_type=authorization_code&redirect_uri={your callback URL}&code={code obtained in login first step}

Request
Request Parameter Details :

Name Type Usage Description

grant_type query Required Must have the value as “authorization_code”.
redirect_uri query Required Redirect URI to the application. The application waits to
receive at this URI the authorization or authentication
response message with the authorization code.

code query Required Authorization code received in the previous

authorization response

Response

In response, UAE PASS issues a bearer-type OAuth 2.0 access token and returns it in a JSON structure.
JSON object containing the access token, associated information and (if the scope was openid requested) an ID
token.

{
"access_token" : {string},
"token_type" : "Bearer",
 11

"expires_in" : {number},
"scope" : {string},
"id_token" : {string}
}

Response Parameter Details:

Name Description
access_token Access token generated by UAE PASS
token_type Type of access token. Always has the “Bearer” value.
expires_in Lifetime (in seconds) of the access token.
scope Scopes granted to those to which the access token is
associated, separated by spaces.

Error Management

If the access token issue request cannot be processed (because the request is invalid, the authentication of the
client application fails, the authorization code expired, etc.), UAE PASS returns an error response in the format
specified by the standard. The response normally (except in the cases described below) has an HTTP 400 (Bad
Request) status code and a JSON data structure with the following parameters:
• error: Error code. See the standard and the list below for more details.
• error_description: Additional description of the error. Not required.
• error_uri: Always omitted. UAE PASS does not use this parameter.

The following are the values supported and the meanings of “error” and “error_description” (if there is one) for
some of the common errors:
• invalid_client, unsupportedAuthenticationScheme: The authentication scheme specified in the
Authorization HTTP header is not supported. TrustedX currently only supports the basic scheme (HTTP
Basic authentication scheme) specified in RFC 2617. In this case, the HTTP status code returned is 401
(Unauthorized).

• invalid_client, invalidCredentials: The client application cannot be authenticated with the credentials
included in the Authorization HTTP header. This may be because there is no Client Application configured
in TrustedX with the identifier specified or because the entity exists but the secret does not match the
configured secret. The HTTP status code returned is 401 (Unauthorized).

• invalid_client, unregisteredClient: The client application is not registered. This error is usually observed
due to misconfiguration of client credentials.

• unsupported_grant_type: The value of the grant_type parameter in the request is not supported.
TrustedX currently only supports the authorization_code type.

• invalid_grant, codeNotFound: The authorization code specified in the code parameter of the request was
not issued in a recent authorization response or has expired.

• invalid_grant, expiredCode: The authorization code specified in the code parameter of the request has
expired.
 12

• invalid_grant, codeNotIssuedToClientId: The authorization code specified was issued for a different client
application than that identified in the Authorization HTTP header.

• invalid_grant, redirectUriMismatch: The authorization code specified was issued for an authorization
request associated to a redirect URL different from the URL specified in the redirect_uri parameter of the
request.

• invalid_grant, invalidOrExpiredCode: The authorization code specified in the code parameter of the
request has expired or invalid.

• invalid_scope: Only for the client credentials grant flow. One of the scopes requested by the application is
not included in this list of scopes provided by the authorization server or has not been enabled for the
client credentials grant. This error also occurs if the application did not request any scope and the server
has no default scope defined for this type of grant.

If an internal error occurred in the server, a JSON response is not returned. Instead, an HTTP 500 (Internal
Server Error) status code is returned In these cases, the TrustedX administrator must browse the log records to
identify the problem.

Example

Below is an example of a token issue error response. Ellipses and line breaks have been included to facilitate
reading.

HTTP/1.1 401 Unauthorized

Content-Type: application/json;charset=utf-8
Cache-Control: no-store, no-cache, must-revalidate
Pragma: no-cache

{
"error" : "invalid_client",
"error_description" : "invalidCredentials"
}
 13

4.3 Obtaining Authenticated User Information from the Access Token

Once the access token obtained, it can be used to fetch the authenticated user’s information from the UAE PASS
User Info API secured with bearer token i.e. access token as per previous step.

Request:
Below here is the API detail:

GET https://qa-id.uaepass.ae/trustedx-resources/openid/v1/users/me
Authorization: Bearer {access token recieved in previous step}

Response
(Note: This response may change as per the scope and list of attributes allowed to share with your application)
{
"sub": "800F475AC0E7A9ED01B2D5D2C25A59B3"
"userType": "SOP3",
"fullnameAR": "‫"جون سميث‬,
"fullnameEN": "John Smith",
"gender": "Male",
"lastnameEN": "Smith",
"nationalityAR": "‫"الهند‬,
"firstnameEN": "John",
"idn": "784000000000000",
" idType": "ID",
"email": "[email protected]",
"spuuid": "b1320896-fb2e-5140-baf0-fa915eb9be5d",
nationalityEN": "IND",
"firstnameAR": " ‫"جون‬,
"lastnameAR": "‫"سميث‬,
"acr": "urn:safelayer:tws:policies:authentication:level:high",
"mobile": "9715555555555",
"titleEN": "Dr."
"titleAR": ".‫"د‬
"amr": [
"urn:safelayer:tws:policies:authentication:adaptive:methods:mobileid",
"urn:uae:authentication:method:verified"
]
 14
Step ii and iii are shown pictorially below as sequence diagram:
 15

4.4 Web Single Sign-On (SSO) and Logout user session from UAE PASS

Single Sign-On:
UAE PASS also offers web single sign on automatically in user’s browser agent. Once the authentication is successful
a browser SSO session is established automatically i.e. if the user tries to open a new tab in same browser and tries
to login with UAE PASS in another web application then the user is not asked for authentication again unless the
session is expired or the user logs out specifically.

Logout from UAE PASS:

It is necessary to logout the user from UAE PASS also in case the user is logging out from SP web application.
In order to logout the user’s UAE PASS session from the browser, simply redirect on below mentioned URL where
“redirect_uri” is the value of your web application where the control will be transferred back after logging out from
UAE PASS after logout.

{The highlighted section should be replaced by URL of Relying party where the response will be sent after logout
from UAEPASS}

Logout URLs:

Environment Logout URLs

QA https://qa-id.uaepass.ae/trustedx-authserver/digitalid-idp/logout?redirect_uri=http://localhost:8080/logout

Production https://id.uaepass.ae/trustedx-authserver/digitalid-idp/logout?redirect_uri={redirect uri as agreed}

In case additional parameter has to be passed in logout “redirect_uri, then encoded value of redirect_uri to be
passed.

Below is a sample:

https://qa-id.uaepass.ae/trustedx-authserver/digitalid-idp/logout?redirect_uri=https%3A%2F%2Ffanyv88.com%3A443%2Fhttp%2Flocalhost%3A8080%2Flogout%26x%3D1
 16

5. User Linking Scenarios and Guidelines

Service Providers delegate the authentication and authorization processes to UAE PASS. By doing so, Service Providers
should be able to identify UAE PASS users and link them to their internal user repository through key attributes shared
by UAE PASS. Every profile in UAE PASS has a unique identifier (UUID) that could be used as a key attribute to link users
in Service Providers repository. In addition to the UUID, email and phone number attributes could be used when dealing
with Basic profiles (SOP1), and Emirates ID (or Passport number) when dealing with Verified users (SOP2 and SOP3).

Note

At any time, users on UAE PASS can update their email and mobilenumber after verifying that the user is in possession
of the email address or mobile number. As such, if Service Providers depend on mobile number or email address from
UAE PASS to link users, this link becomes orphaned once the user change the values on UAE PASS.

Service Provider UAE PASS

SP User UAE PASS LinkedID Basic Profile – Shared attributes

uuid = 123456789
Omar Roe 112233445
Email = [email protected]
John Doe 123456789 Mobile = +971555555555
Name = John Doe
Etc. DOB = 03/05/1990
Etc.

Figure 1: Account Linking

We are detailing here few use cases and SP can handle accordingly:

Use Case 1: User logged in using his UAE PASS Account and the user is having an existing account in SP
application then allow user to connect its SP user account with UAE PASS account,
{Integrating parties should support two modes as applicable.}

Automatic Linking:

Incase Automatic Accounts Linking is adopted"thisisapplicable if therelying party maintainsthe IDN number
of the Emirates ID (or any other common attributes) for local users and in this case the link happens depending
on the IDN"
 17

Other attributes like date of birth, passport number or any shared attribute between the User Profile in UAE
PASS and Relying Party are also recommended to be used to uniquely identify user if applicable.

Note: For linking, it is recommended to use “uuid” attribute returned by UAE PASS for user linking
purposes for subsequent visits.
Manual Linking:

In case Manual Linking is adopted, the user should be challenged by the Relying Party application with his
Relying Party's account username and password (or any other authentication mechanism) and on successful
authentication the linking can be achieved by storing the linking attributes (e.g. uuid, idn etc.) at Relying Party
side. This is one time activity and should be done only on first linking attempt.

Note: For linking, it is recommended to use “uuid” attribute returned by UAE PASS for user linking
purposes for subsequent visits.

Use Case 2: User haslogged in using his UAE PASS Account, and the user is non-existing user in Relying Party
applicationthenallow theuser toregister andcreateaccount usingtheUser Informationretrieved from UAE
PASS.
Auto Populate Form: User is creating an account with entity and he has not logged in using UAE PASS, entity
should give the end user the option to auto populate entity User Form using the UAE PASS Authentication
Service.

Registerusing UAEPASSoption: UAEPASScanbeusedtopopulate LocalUser Registration Formfor Relying

party registration.

Use Case 3 : User Types Handling:

On Successful authentication at UAE PASSthecontrol is sent backto SP irrespective ofuser type. The SPshouldhandle
the authorization or flow at their end as per the user types and their business.

SOP1 : In case of SOP1, UAE PASS will not return the Emirates ID number attribute as the user has still not verified
his/her emirates ID at this stage. SP should handle in case SOP1 is not allowed at their by showing the appropriate
error message.
 18

Chapter 2: Mobile Application Integration

If the application installed is a mobile application, additional steps are required to support the integration with
the UAE PASS Mobile ID application. The information in this section applies when:

1. Pre requisites:
• The installed application is an Android or iOS mobile application.

• The installed application uses a Web View for integrating the OAuth 2.0 flow (not the system's browser) and

In this type of integration, the Web View cannot interact with other mobile applications in the system (in particular,
with the UAE PASS Mobile application only). It can only interact with the application in which it is embedded. This
means that the application that must open UAE PASS App when the identity provider specifies doing so in the
WebView. Furthermore, the application must intercept the UAE PASS Mobile ID callback URL and load it in the
WebView. Otherwise, after the interaction with Mobile ID has finished, the system's browser would open. To do
this, the RP application must use its own URI scheme.

2. Requirements to Taketo Account When Programming the Mobile Application

Specifically, the mobile application (YourApp) must be programmed to perform the following tasks:

1. Register, during installation, its own customized URI scheme (e.g., yourapp://...) in the mobile's operating
system.

2. Start OAuth 2.0 authorization (or OpenID Connect authentication) with TrustedX in the WebView.

3. Monitor the WebView's URL to intercept the Mobile ID's URI scheme (by default, mobileid://...).

4. In the Mobile ID's URI, change the callback URLs so they use the URI scheme of yourapp instead of https,
propagating the original callback URL via a parameter.

5. Launch the Mobile ID application, opening the modified URI in the system.

6. Process incoming URLs that use the customized scheme (yourapp://...), retrieving the original callback URL from
the parameter.

7. Open the original callback URL in the WebView so the authorization server can take over again and complete the
OAuth authorization.

8. Monitor the WebView URL to intercept the OAuth redirect URI, which indicates the completion of the
authorization phase.

Note: See the documentation for the mobile's operating system for how to perform these tasks, in particular the
communication between applications using customized URI schemes.
 19

3. Protocol and Interactions between the Mobile Application and Mobile ID

The complete protocol, including the OAuth 2.0 messages that the mobile application exchanges with UAE PASS
TrustedX, and the interactions between the application, the WebView and the UAE PASS Mobile ID application,
entail the following steps. (To facilitate reading, some of the URLs below are shown only partially, include extra
spaces and/or include parameters where the reserved character escaping is omitted.)

1. “YourApp” starts an OAuth 2.0 authorization flow with TrustedX in an embedded WebView. It uses, for
example, TrustedX's OAuth landing page as the redirect URI. OAuth start URL (example):

https://qa-id.uaepass.ae/trustedx-authserver/oauth/main-
as?redirect_uri=https://your_redirect_uri&client_id=your_client_id&state=ShNP22hyl1jUU2RGjTRkp
g==&response_type=code&scope=urn:uae:digitalid:profile:general&acr_values=urn:digitalid:authen
tication:flow:mobileondevice

2. “YourApp” monitors the WebView's URL to intercept the UAE PASS Mobile ID's URI customized scheme (by
default, uaepass://...) and detect the redirect URL.

3. Following a few WebView redirects, the identity provider starts the authentication with Mobile ID in the
same device. To do this, it edits the WebView's URL with a URL based on the Mobile ID's scheme.

4. YourApp detects the Mobile ID scheme. The URL has the following format, where <url1> and <url2> are the
callback URLs from UAE PASS Mobile ID to UAE PASS Identity Server. Original Mobile ID URL (partial):

uaepass://...? successURL=<url1> & failureURL=<url2> & ...

5. In staging environment, change the uaepass package id to: ae.uaepass.mainapp.qa and above URL as:

uaepassqa://...? successURL=<url1> & failureURL=<url2> & ...

6. “YourApp” rewrites the above URL so that the callback URLs refer to its customized scheme (let's assume it
is yourapp), including the original URL in a parameter. For example, the edited callback URLs can follow the
yourapp:///resume_authn syntax with a url parameter for the original URL. Modified Mobile ID URL
(example).

uaepass://...? successURL=yourapp:///resume_authn?url=<url1>
&failureURL=yourapp:///resume_authn?url=<url2> & ...

in staging:
uaepassqa://...? successURL=yourapp:///resume_authn?url=<url1>
&failureURL=yourapp:///resume_authn?url=<url2> & ...

7. “YourApp” invokes the mobile's operating system to open the above URL. This launches the Mobile ID
application (assuming it is installed in the mobile), sending it the URL.
 20
8. The Mobile ID application interacts with the user to prompt them to authenticate. (During this phase,
Mobile ID makes HTTP calls to the TrustedX signature services, not shown in the diagram.)

9. Once the user has authenticated, the Mobile ID application finalizes and invokes the mobile's operating
system to open the callback URL (successURL if the authentication finished correctly and failureURL if an
error occurred). This brings the YourApp application back to the foreground.

10. YourApp processes the incoming URL, verifies that it observes the above syntax and obtains the original
callback URL from the url parameter.
11. “YourApp” opens the above URL in the WebView. This URL, which always uses the https scheme, sendsthe
WebView back to UAE PASS Identity Server.

12. TrustedX continues interacting with the user in the WebView until it finishes the authentication (or cancels it
if an error occurs). For example, by requesting a second factor (if there is one)

13. TrustedX requests authorization from the user for granting “YourApp” access to the requested scopes, also
within the WebView. (This step is omitted if the scopes were configured with implicit consent.)

14. Lastly, the OAuth 2.0 authorization finishes and TrustedX redirects the WebView back to the redirect URI.
OAuth Redirect URL (example)

https://<<your_redirect_uri>>? code=4515...e0ba&state=3dd9...8cd4

15. “YourApp”, which was monitoring the WebView for detecting the above redirect URI, extracts the
authorization code (or information on any error that occurred) from the code parameter. At this point, the
application can destroy the WebView (see Cookies and SSO about this) and return to interacting with the
user in its native interface.

16. “YourApp” invokes TrustedX to exchange the authorization code for an access token. (Given what we said
above, and because a mobile application cannot maintain secrets, YourApp includes only its client_id in the
HTTP authorization header of the access token request message.)

17. “YourApp” accesses the protected resource(s) by invoking the HTTP API of the TrustedX resource serverwith
the access token and/or stores the token for subsequent calls to the HTTP API.

18. “YourApp” resumes interaction with the user.

 21

The following diagram illustrates the above steps:

Figure: Native App Integration Sequence Diagram

 22

Appendix-A

Android :
Staging Apps
Links

iOS:

Sample Basic Install the staging app and follow the “Sign up” process to create the Basic account
Account Creation yourself

Sample Verified After completing the above step and testing with basic profile, share the identifier (e.g.
Account Creation mobile or email or emirates id number) to us in order to step up from back end.

Android: toolkit\3. Technical Toolkit

Sample UAEPASS
App to App v1.5\Staging and Sample Apps\Android Sample

UAEPASS App to App

iOS: \toolkit\3. Technical Toolkit v1.5\Staging

 23
and Sample Apps\iOS Staging app

Appendix-B

UAEPASS List of Attributes

No. Attribute Name Description User Type

1 userType Level of assurance. ALL (SOP1,2 &3)

2 Mobile Verified phone number ALL (SOP1,2 &3)

3 Email Verified email ALL (SOP1,2 &3)

4 UUID UAE PASS Unique User Identifier ALL (SOP1,2 &3)
5 SOP2 And SOP 3 only that with
SPUUID SmartPass Unique User Identifier
SmartPass verified account
6 Idn Verified Emirates ID number SOP2 And SOP 3 only
7 fullnameEN Full name (English) ALL (SOP1,2 &3)
8 fullnameAR Full name (Arabic) ALL (SOP1,2 &3)
9 firstnameEN Given name (English) ALL (SOP1,2 &3)
10 firstnameAR Given name (Arabic) ALL (SOP1,2 &3)
11 lastnameEN Given name (English) ALL (SOP1,2 &3)
12 lastnameAR Given name (Arabic) ALL (SOP1,2 &3)
13 nationalityEN Nationality (English) SOP2 And SOP 3 only
14 nationalityAR Nationality (Arabic) SOP2 And SOP 3 only
15 Gender Gender SOP2 And SOP 3 only
16 idType ID Type SOP2 And SOP 3 only
17 titleEN Title (English) SOP2 And SOP 3 only
18 titleAR Title (Arabic) SOP2 And SOP 3 only