Skip to main content

Inter-App Consent Flow

Inter-App Consent Flows are standard OAuth 2.0 consent flows. Using Inter-App URI communication enable OAuth consent flows between any combination of native apps and websites, i.e. App2App, App2Web, Web2App and Web2Web.

The concept is specified in the Best Current Practice OAuth 2.0 for Native Apps (RFC 8252).

This blueprint shows how Inter-App Consent Flows are expected to work with bLink Consent 2.0 and CaaS.

In addition the blueprint gives technical hints and guidelines for the implementation of native apps.

Conceptual view​

App to app Source: openid.net

Overview​

This overview focuses on the relevant steps for Inter-App consent flows shown in the red boxes.

Overview CF2

OAuth2 Authorization Code Grant Flow​

StepDescription
8.Back-end Server creates authorization endpoint URL using a redirect URI capable of being receipt by the Service Consumer App.
9.App uses platform specific APIs to open the authorization endpoint URL (further details below).
10.Operating system of mobile device checks whether the authorization endpoint URL is registered by a Service Provider App.
11.If so, this app is launched with the url. If not, the url is opened in the user-agent (which typically leads to the web application of the Service Provider).
...User defining and signing the consent
18.The Service Provider App uses platform specific APIs to open the redirect URI (further details below).
19.O perating system of mobile device checks whether the redirect URI is registered by a Service Consumer App.
20.If so, this app is launched with the URI and the app forwards the authorization code to the Service Consumer to initiate the token request. If there is no app registered for the URI, the URI is opened in the user-agent (which typically leads to the web application of the Service Consumer).

Overview​

This overview focuses on the relevant steps for Inter-App consent flows with CaaS shown in the red boxes.

Overview CaaS

Pushed Authorization Request Flow (green bullets)​

StepDescription
A.Back-end server posts permission request to CaaS.

B.

CaaS creates (or updates) a permission using the clientId, userId, username, providerId, scope and optional externalReference from the request. CaaS generates a redirect URI and a state and adds them to the permission. The permission is stored and returned to the back-end server.

C.Back-end server stores the permission in the context of user.
StepDescription
D.

CaaS redirects back to back-end server indicating the status of the OAuth2 consent flow (via the Consumer App).

E.

Depending on status of OAuth2 consent flow the back-end server uses the externalReference to retrieve the updated permission from CaaS and handle it's own state.

OAuth2 Authorization Code Grant Flow (red boxes)​

StepDescription
8.

Back-end Server creates authorization endpoint URL using a redirect URI capable of being receipt by the Service Consumer App.

9.App uses platform specific APIs to open the authorization endpoint URL (further details below).
10.

Operating system of mobile device checks whether the authorization endpoint URL is registered by a Service Provider App.

11.

If so, this app is launched with the url. If not, the url is opened in the user-agent (which typically leads to the web application of the Service Provider).

...User defining and signing the consent
18.The Service Provider App uses platform specific APIs to open the redirect URI (further details below).
19.

Operating system of mobile device checks whether the redirect URI is registered by a Service Consumer App.

20.

In the case of CaaS there is no app registered for the URI, since it points to CaaS. The URI is opened in the user-agent and the flow continues with CaaS.

Pre-requisites​

General​

The Best Current Practice considers the browser as the recommended user-agent (see technical integration aspects for iOS and Android below)

Service Consumer Application​

The Service Consumer App SHALL open the authorization endpoint URL in either an external browser or a custom browser tab (or similar). It is not allowed to use a user-agent that gives full control to the Service Consumer app (i.e. WebViews SHALL NOT be used).

In any case it is required that the URL and the green lock item are shown so that the user can verify the correctness of the destination domain.

The Service Consumer App SHALL register a claimed "https" scheme URI to allow for the resumption of the flow in the app.

Service Provider Application​

If the Service Provider provides an application, it SHALL open the redirect URI in the same way as the Service Consumer app opens the authorization endpoint URL (no WebViews allowed).

The Service Provider App SHALL register the authorization endpoint url as a claimed "https" URL to allow initiation of consent flow in the app.

Additionally the Service Provider SHOULD implement the claimed authorization endpoint URLs in his web-application as well. So to handle the case where no Service Provider app is installed on the device (most likely this url forwards or redirects to the "real" authorization endpoint url or to a informational/support page).

Technical implementation guidelines​

Android​

Initialize the Service Provider authorization endpoint URL​

  • in step 9 above
  • use a Custom Tab as user-agent
Reasoning:
  • Custom Tabs in Android «make transitions between native and web content more seamless without having to resort to a WebView”
  • Custom Tabs allow users to see the URL that is loaded, and to see the SSL verification lock icon to check the correct certificate, basically giving users confidence before entering their sensitive credentials (username and password) and allowing them to perform the checks that our security awareness guidelines recommend them.

Example authorization endpoint URL:

  • https://consent.mybank.com/consent/c/cls/auth?response_type=code&client_id=<YOUR_CLIENTID>&redirect_uri=<YOUR_REDIRECT_URI>&state=<YOUR_STATE>&scope=<YOUR_SCOPE>&username=<YOUR_USER_ID>&provider_id=<YOUR_PROVIDER_ID>
References:

Allow Service Provider App to launch automatically during Login​

  • Service Provider should implement Google App Links to achieve this.
  • No further action required for Service Consumer on Android.
Reasoning:
  • This is mandatory for the flow to work correctly, i.e. to automatically open the Service Provider App during the Login flow.

Add app in the referrer​

Reasoning:
  • For easy debugging and usage analytics, the Package Name and version shall be written into the referrer.
  • Allows Service Provider to distinguish between mobile and desktop devices.
References:

Do not override the default user agent​

Reasoning:
  • The user agent shall not be overridden.
  • Service Provider Login and Consent may not work correctly if the default user Agent from «Custom Tabs» is overwritten.

Handle the non-happy flow: User closes the Custom Tab before the redirect from Service Provider to the Service Consumer​

  • Service Consumer app shall launch the Custom Tab Activity using Activity Result APIs. Eventually the app may use the underlying "s tartActivityForResult()" and "onActivityResult()" APIs on the Activity class (or any contract that fits the needs) .
Reasoning:
  • When the user clicks on «X» before the process is fully completed, the app will receive a result with a result_code « RESULT_CANCELED ».
References:

Handle the happy flow: Have the redirect_uri handled correctly.​

  • The redirect_uri set in step 8 above is intercepted by the native app implementation.
  • The recommended way is to utilize claimed "https" scheme URI Redirection, i.e. create a Google App Link.
References:

iOS​

Initialize the Service Provider authorization endpoint URL​

  • in step 9 above
  • use a ASWebAuthenticationSession or a SFSafariViewController as user-agent
  • when using ASWebAuthenticationSession set prefersEphemeralWebBrowserSession = true
Reasoning:
  • Prevent sharing of user’s cookies or other browser data for enhanced privacy of Service Consumer app users.

Example authorization endpoint URL:

  • https://consent.mybank.com/consent/c/cls/auth?response_type=code&client_id=<YOUR_CLIENTID> &redirect_uri=<YOUR_REDIRECT_URI>&state=<YOUR_STATE>&scope=<YOUR_SCOPE>&username=<YOUR_USER_ID> &provider_id=<YOUR_PROVIDER_ID>
References:

Allow Service Provider App to launch automatically during Login​

  • Service Provider should implement Universal Link to achieve this.
  • Should be allowed by default in the context of ASWebAuthenticationSession.
  • When user returns back to the app, the Authentication Session (that loads the Service Provider App) should still be displayed, polling for a successfully authenticated session and later displaying the consent.
Reasoning:
  • This is mandatory for the flow to work correctly, i.e. to automatically open the Service Provider App during the Login flow.

Add app in the referrer​

  • Not supported by iOS.

Do not override the default user agent​

Reasoning:
  • The user agent shall not be overridden.
  • Service Provider Login and Consent may not work correctly if the default user Agent from «Custom Tabs» is overwritten.

Handle the non-happy flow: User dismisses the View in the app before the redirect from Service Provider to the Service Consumer​

  • Handle in the callback the error «canceledlogin»
References:

Handle the happy flow: Have the redirect_uri handled correctly.​

  • The redirect_uri set in step 8 above is intercepted by the native app implementation.
  • The recommended way is to utilize claimed "https" scheme URI Redirection, i.e. create an Universal Link.
  • Native app picks up by link, reads out the auth_code parameters and later dismiss the ASWebAuthenticationSession manually by calling cancel() on it (see reference)
References:

Further References​

Last updated on