Mobile Integration Guidelines

Requirements to Take to Account When Programming the Mobile Application

Register, during installation, its own customized URI scheme (e.g., yourapp://...) in the mobile's operating system.
Start OAuth 2.0 authorization in the WebView.
Monitor the WebView's URL to intercept the Mobile ID's URI scheme (by default, mobileid://...).
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.
Launch the Mobile ID application, opening the modified URI in the system.
Process incoming URLs that use the customized scheme (yourapp://...), retrieving the original callback URL from the parameter.
Open the original callback URL in the WebView so the authorization server can take over again and complete the OAuth authorization.
Monitor the WebView URL to intercept the OAuth redirect URI, which indicates the completion of the authorization phase.

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

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, and the interactions between the application, the WebView and the UAE PASS Mobile ID application, entail the following steps.

“YourApp” starts an OAuth 2.0 authorization flow in an embedded WebView. It uses, for example, OAuth 2.0 landing page as the redirect URI. OAuth 2.0 start URL. Example :
“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.
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.
"YourApp" detects the Mobile ID scheme. The URL has the following format, where and are the callback URLs from UAE PASS Mobile ID to UAE PASS Identity Server. Original Mobile ID URL (partial): uaepass://...? successURL= & failureURL= & ...
“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= &failureURL=yourapp:///resume_authn?url= & ...
“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.
The Mobile ID application interacts with the user to prompt them to authenticate through face verification.
Once the user has authenticated through face verification, 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.
YourApp processes the incoming URL, verifies that it observes the above syntax and obtains the original callback URL from the url parameter.
“YourApp” opens the above URL in the WebView. This URL, which always uses the https scheme, sends the WebView back to UAE PASS Identity Server.
It continues interacting with the user in the WebView until it finishes the authentication (or cancels it if an error occurs). For example, face verification is not working at the given time
The requests authorization from the user for granting “YourApp” access to the requested scopes, also within the WebView.
Lastly, the OAuth 2.0 authorization finishes and redirects the WebView back to the redirect URI. OAuth Redirect URL. Example: https://<<your_redirect_uri>>? code=4515...e0ba&state=3dd9...8cd4
“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.
“YourApp” 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.)
“YourApp” accesses the protected resource(s) by invoking the HTTP API of the resource server with the access token and/or stores the token for subsequent calls to the HTTP API.
“YourApp” resumes interaction with the user.

PreviousMobile Integration NextUse-Case Guidelines

Last updated 11 days ago

Was this helpful?

Requirements to Take to Account When Programming the Mobile Application

Start OAuth 2.0 authorization in the WebView.

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

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.

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

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

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

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

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

Protocol and Interactions between the Mobile Application and Mobile ID.

“YourApp” starts an OAuth 2.0 authorization flow in an embedded WebView. It uses, for example, OAuth 2.0 landing page as the redirect URI. OAuth 2.0 start URL. Example :

“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.

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.

"YourApp" detects the Mobile ID scheme. The URL has the following format, where and are the callback URLs from UAE PASS Mobile ID to UAE PASS Identity Server. Original Mobile ID URL (partial): uaepass://...? successURL= & failureURL= & ...

“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= &failureURL=yourapp:///resume_authn?url= & ...

“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.

The Mobile ID application interacts with the user to prompt them to authenticate through face verification.

Once the user has authenticated through face verification, 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.

YourApp processes the incoming URL, verifies that it observes the above syntax and obtains the original callback URL from the url parameter.

“YourApp” opens the above URL in the WebView. This URL, which always uses the https scheme, sends the WebView back to UAE PASS Identity Server.

It continues interacting with the user in the WebView until it finishes the authentication (or cancels it if an error occurs). For example, face verification is not working at the given time

The requests authorization from the user for granting “YourApp” access to the requested scopes, also within the WebView.

Lastly, the OAuth 2.0 authorization finishes and redirects the WebView back to the redirect URI. OAuth Redirect URL. Example: https://<<your_redirect_uri>>? code=4515...e0ba&state=3dd9...8cd4

“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.

“YourApp” 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.)

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

“YourApp” resumes interaction with the user.