1. Requirements to Take to Account When Programming the Mobile Application
Specifically, the mobile application (YourApp) must be programmed to perform the following tasks:
- Register, during installation, its own customized URI scheme (e.g., yourapp://...) in the mobile's operating system.
- Start OAuth 2.0 authorization (or OpenID Connect authentication) with EIDAS in the WebView.
- Monitor the WebView's URL to intercept the eParaksts mobile URI scheme eparakstsid://... In the eParaksts mobile URI, change the callback URLs so they use the URI scheme of YourApp instead of the one received, propagating the original callback URL via a parameter.
- Launch the eParaksts mobile 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.
2. Protocol and Interactions between the Mobile Application and eParaksts mobile
The complete protocol, including the OAuth 2.0 messages that the mobile application exchanges with EIDAS, and the interactions between the application, the WebView and the eParaksts mobile 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.)
- YourApp starts an OAuth 2.0 authorization flow with EIDAS in an embedded WebView. It uses, for example, eParakst login page as the redirect URI.
- YourApp monitors the WebView's URL to intercept the Mobile ID's URI customized scheme (by default, eparakstsid://...) and detect the redirect URL.
- Following a few WebView redirects, the identity provider starts the authentication with eParaksts mobile in the same device. To do this, it edits the WebView's URL with a URL based on the eParaksts mobile scheme.
- YourApp detects the eParaksts mobile scheme. The URL has the following format, where <url1> and <url2> are the callback URLs from eParaksts mobile to EIDAS.
- 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.
- YourApp invokes the mobile's operating system to open the above URL. This launches the eParaksts mobile application (assuming it is installed in the mobile), sending it the URL.
- The eParaksts mobile application interacts with the user to prompt them to authenticate.
- Once the user has authenticated, the eParaksts mobile 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. This URL has the following format:
YourApp opens the above URL in the WebView. This URL, which always uses the https scheme, sends the WebView back to EIDAS.
EIDAS continues interacting with the user in the WebView until it finishes the authentication (or cancels it if an error occurs).
EIDAS 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 EIDAS redirects the WebView back to the redirect URI.
- 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 andreturn to interacting with the user in its native interface.
- YourApp invokes EIDAS to exchange the authorization code for an access token.
- YourApp accesses the protected resource(s) by invoking the HTTP API of the EIDAS resource server with the access token and/or stores the token for subsequent calls to the HTTP API.
- YourApp resumes interaction with the user.