Custom URI scheme


Custom URI scheme is URI Scheme (as defined by RFC 3986) that a native application creates and registers with the Operating System (and is NOT a standard URI scheme like "https:" or "tel:").

RFC 7595 #

RFC 7595 defines Private URI Scheme

RFC 8252 #

RFC 8252 defines

Claimed "https" Scheme URI Redirection#

Some Operating Systems allow apps to claim "https" scheme RFC 7230 URIs in the domains they control. When the browser encounters a Custom URI scheme, instead of the page being loaded in the browser, the Native application is launched with the URI supplied as a launch parameter.

Such Custom URI scheme URIs can be used as redirect_uris by Native applications. They are indistinguishable to the Authorization Server from a regular web-based client redirect_uri. An example is:

As the redirect_uri alone is not enough to distinguish OAuth Public Client native applications OAuth Public Client from OAuth Confidential Clients, it is REQUIRED in RFC 7230 Section 8.4 that the OAuth Client type be recorded during OAuth 2.0 Client Registration to enable the Authorization Server to determine the OAuth 2.0 Client Type and act accordingly.

App-claimed HTTPS URI Redirection URIs have some advantages compared to other native application redirect options in that the identity of the destination app is guaranteed to the Authorization Server by the Operating System. For this reason, native applications SHOULD use them over the other options where possible.

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

Custom URI scheme Namespace Considerations#

When selecting which URI scheme to associate with the app, apps SHOULD pick a scheme that is globally unique and Collision-Resistant Name, and which they can assert ownership over.

To avoid clashing with existing schemes in use, using a scheme that follows the reverse domain name notation pattern applied to a domain under the app publishers control is RECOMMENDED. Such a scheme can be based on a DNS Domain they control, or the OAuth client identifier in cases where the authorization Server issues client identifiers that are also valid DNS subdomains. The chosen scheme MUST NOT clash with any IANA registered scheme. You SHOULD also ensure that no other app by the same publisher uses the same URI Scheme.

URI Schemes using reverse domain name notation are hardened against collision. They are unlikely to clash with an officially IANA registered scheme or unregistered de-facto scheme, as these generally don't include a period character, and are unlikely to match your domain name in any case. They are guaranteed not to clash with any OAuth client following these naming guidelines in full.

Some Operating Systems use globally unique bundle or package names that follow the reverse domain name notation pattern. In these cases, the app SHOULD register that bundle id as the custom scheme. If an app has a bundle id or package name that doesn't match a DNS Domain under the control of the app, the app SHOULD NOT register that as a Custom URI scheme, and instead create a Custom URI scheme based off one of their DNS Domain names.

For example, an app whose publisher owns the top level domain name "example.com" can register "com.example.app:/" as their custom scheme. An app whose Authorization Server issues client identifiers that are also valid domain names, for example "client1234.usercontent.idp.com", can use the reverse domain name notation of that DNS Domain as the scheme, i.e. "com.idp.usercontent.client1234:/". Each of these examples are Custom URI scheme which are likely to be unique, and where the publisher can assert ownership.

As a counter-example, using a simple Custom URI scheme like "myapp:/" is not guaranteed to be unique and is NOT RECOMMENDED.

In addition to uniqueness, basing the Custom URI scheme off a name that is under the control of the app's publisher can help to prove ownership in the event of a dispute where two apps register the same Custom URI scheme (such as if an app is Mallory). For example, if two apps registered "com.example.app:", the true owner of "example.com" could petition the app store operator to remove the counterfeit app. This petition is harder to prove if a generic URI scheme was chosen.

Custom scheme redirects are not real useful!#

John Bradley on the OAuth 2.0 mailing list:
Getting a trusted Authorization Server to say you are Tripit or some trusted client when you are really a bad guy is becoming a real problem.
This is however not directly connected to the client mix up issue, and needs to be addressed separately.

One thing we added to dynamic client registration was a software statement that can lock down redirect URI for a given client.
In the case of Mobile Connect for  Mobile network operators the proposal is to have a trusted registration authority that validates clients and issues them software statements to register at individual AS.

Validating the developer/client will probably need to be a business process, more stringent than just getting a developer account based on an email address.   One possibility might be to check if the redirect URI has a EV certificate indicating the organization, or trust frameworks set up to register clients for conformance with European data protection laws (yes with safe harbour going away something like that might be required by AS to keep on the good side of the law.  Germany did take a run at this once, but it did not work for the internet in a practical way)

The biggest issue will probably be identifying native apps.  Custom scheme redirects are not real useful.

On iOS and Android(beta) there are now ways for an app to claim a https: URI that is controlled by the developer. https://tools.ietf.org/html/draft-ietf-oauth-native-apps-00#page-9
That in combination with software statements might be a useful way to identify the client and display something useful at the AS.

We need to do more work on this in my opinion.

John B.
URI that is controlled by the developer. https://tools.ietf.org/html/draft-ietf-oauth-native-apps-00#page-9 refers to App-claimed HTTPS URI Redirections

More Information#

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