Private-Use URI Scheme Redirection


Private-Use URI Scheme Redirection is defined in OAuth 2.0 for Native Apps (RFC 8252)

Many mobile and desktop computing platforms support inter-app communication via URIs by allowing Applications to register Private URI Scheme (sometimes colloquially referred to as "custom URI scheme") like "com.example.app". When the browser or another app attempts to load a URI with a Private URI Scheme, the Application that registered it is launched to handle the request.

To perform an OAuth 2.0 Authorization Request with a Private-Use URI Scheme Redirection, the Native application launches the browser with a standard Authorization Request, but one where the redirection URI utilizes a Private URI Scheme it registered with the Operating System.

When choosing a URI scheme to associate with the app, apps MUST use a URI Scheme based on a DNS Domain name under their control, expressed in Reverse domain name notation, as recommended by Section 3.8 of RFC 7595 for Private URI Schemes.

For example, an app that controls the domain name "app.example.com" can use "com.example.app" as their scheme. Some Authorization Servers assign client identifiers based on DNS Domain names, for example,

which can also be used as the DNS Domain name for the scheme when reversed in the same manner.

A URI Scheme such as "myapp", however, would not meet this requirement, as it is not based on a DNS Domain name.

When there are multiple Applications by the same publisher, care must be taken so that each URI Scheme is unique within that group. On platforms that use Application identifiers (GUID) based on reverse domain name notation, those identifiers can be reused as the Private URI Scheme for the redirect_uri to help avoid this problem.

Following the requirements of Section 3.2 of RFC 3986, as there is no naming authority for Private-Use URI Scheme Redirection, only a single slash ("/") appears after the scheme component. A complete example of a redirect URI utilizing a Private URI Scheme is:

When the Authorization Server completes the request, it redirects to the client's redirection URI as it would normally. As the redirection URI uses a private-use URI scheme, it results in the Operating System launching the native application, passing in the URI as a launch parameter. Then, the native application uses normal processing for the Authorization Response.
Private-Use URI Scheme Redirection has no requirement that the Private URI Scheme is a DNS Domain under the Application developer's control. Therefore Claimed Https Scheme URI Redirection is RECOMMENDED
Private-Use URI Scheme Redirection uses uses URI (ie NOT HTTP redirection) and App-claimed HTTPS URI Redirection uses URL (ie HTTP redirection).

The Custom URI scheme patterns are supported on the Operating Systems.

More Information#

There might be more information for this subject on one of the following: