# **URL Based Discovery for Trust Frameworks using SIOP**

## **Problem Statement**

OpenID Connect Core 1.0 [standardizes SIOP](https://openid.net/specs/openid-connect-core-1_0.html#SelfIssued), specifying a required URL scheme of `openid:` for the authorization endpoint and the fixed value of `https://self-issued.me` as the issuer. These defaults have presented significant adoption challenges.

Today, if a service provider or relying party would like to support a choice for users to manage their identity with a locally installed application, it is poor user experience to link them to an `openid:` endpoint where the experience is an error if no such applications are installed. Even less desirable would be for an SIOP application to have been installed to accept that scheme but which is only designed for a specialized use-case, breaking any other usages on that device.

These challenges have received renewed interest due to the desire to utilize SIOP as the foundation for decentralized identity wallet protocols. By leveraging the widely adopted OpenID Connect standard, new SIOP-based wallet solutions can build upon almost a decade of OpenID protocol experience in solving complex and critical identity flows.

SIOP adoption should easily interoperate across different implementations and roles, but in practice there is likely to be significant security and trust barriers between verticals with their own additional requirements. The scope of discovery within each one of these vertical or specialized use-case "trust frameworks" will be limited to just those applications and providers which support them (for example, [SMART Health Cards](https://github.com/smart-on-fhir/health-cards).

## **Overview**

This draft is proposing a practical solution to accomplish a discovery process that has a graceful user experience with usable fallbacks. It leverages the native platform capabilities to open an installed application if available and present a web page if not.

In order to accomplish a workable discovery process with only the capabilities currently available on the popular platforms each trust framework is required to implement their own shared solution. This involves building and maintaining a common site for that framework with a purpose similar to self-issued.me and accountchooser.com, but with a more involved management process to maintain metadata about which SIOP-based resources (native apps or PWAs) are supported.

This shared site will require governance specific to that vertical for approving new applications to be discovered. Each discoverable solution will have its metadata incorporated into the site's `.well-known/` files for linking into installed native apps as well as descriptions and links to install apps or use PWAs.

## **Link-into-App**

The alternative to protocol handlers that most major app platforms promote is associating a website to a native app for automatically handling links. In iOS/macOS this is called [Universal Links](https://developer.apple.com/ios/universal-links/), on Android it’s [App Links](https://developer.android.com/training/app-links), and on Windows it’s [Website to App Linking](https://docs.microsoft.com/en-us/windows/uwp/launch-resume/web-to-app-linking).

These techniques are extremely similar, they require the association from a website to a native app to be published on the site as a `.well-known/` JSON file. That association file contains the unique identifiers or signatures of one or more apps and configures which paths on the given website will be handled natively by any app if installed.

If no apps are installed it is just a normal web link handled by the default system browser. This allows degradation where the user is presented with a trust framework's instructions to choose and install an app or offered any web-based solutions. When an associated app is installed, any navigation to the site+path from the browser or another app on the platform will be handled natively, passing through the full request URL including any query parameters.

## **Discovery Flow**

The ideal flow based on these available solutions is:

1. Any Service Provider or Relying Party supporting discovery can simply generate one or more URLs to a specific trust framework's shared site with a path and query string embedding details of that request.
2. The user will navigate to one of the proffered URLs from the RP.
3. Redirection of the user to this URL will either trigger their platform to open an installed native app that is registered to handle the request, or it will render a page served from that site display a list of native applications to install or web-based solutions to choose from.
4. Given an installed app, it will handle the request by providing any user experience or consent choices – and then perform the requested callback instructions to complete the discovery process.
5. If the application is not able to satisfy the request, it must send the user back to the selected shared site for additional options. The shared site can provide an HTML page listing other applications or PWAs that could satisfy the original request.

This last step requires that supporting apps voluntarily provide this fallback and do not intercept or log requests that they pass through. The burden of ensuring good behavior would fall upon each trust framework's management process for selecting which apps are registered with and available through the shared site. If successful this will be a positive self-reinforcement as bad behavior would remove them from the discovery process, but there is still a human cost of moderating and reviewing related requests and reports.

### **Multiple Apps**

There is an open issue when a user has chosen to install multiple apps on a device that are part of the same trust framework. In this scenario, the framework site's list of applications can only provide a priority on which app to link into, where the first listed-and-installed application in the metadata will receive the request.

For this scenario, Ping Identity is working on a solution to support on-device discovery of installed capable apps from within native applications. This would allow any relying party app to request credentials with a chooser interface of installed apps. Installed applications receiving a via the shared domain could be required to present this selection prompt as well, making any one app act as the shim to support selection from the others.

## **Next Steps**

This proposal is likely to become a simple practical implementation guide. There isn't any actual standards-track path intended as it's just documenting a way of accomplishing a usable discovery mechanism for any given trust framework.