Appendix B. Platform-Specific Implementation Details
This document primarily defines best practices in a generic manner, referencing techniques commonly available in a variety of environments. This non-normative section documents implementation details of the best practice for various operating systems.
The implementation details herein are considered accurate at the time of publishing but will likely change over time. It is hoped that such a change won't invalidate the generic principles in the rest of the document and that those principles should take precedence in the event of a conflict.
B.1. iOS Implementation Details
Apps can initiate an authorization request in the browser, without the user leaving the app, through the "SFSafariViewController" class or its successor "SFAuthenticationSession", which implement the in-app browser tab pattern. Safari can be used to handle requests on old versions of iOS without in-app browser tab functionality.
To receive the authorization response, both private-use URI scheme (referred to as "custom URL scheme") redirects and claimed "https" scheme URIs (known as "Universal Links") are viable choices. Apps can claim private-use URI schemes with the "CFBundleURLTypes" key in the application's property list file, "Info.plist", and "https" scheme URIs using the Universal Links feature with an entitlement file in the app and an association file hosted on the domain.
Claimed "https" scheme URIs are the preferred redirect choice on iOS 9 and above due to the ownership proof that is provided by the operating system.
A complete open-source sample is included in the AppAuth for iOS and macOS [AppAuth.iOSmacOS] library.
B.2. Android Implementation Details
Apps can initiate an authorization request in the browser, without the user leaving the app, through the Android Custom Tab feature, which implements the in-app browser tab pattern. The user's default browser can be used to handle requests when no browser supports Custom Tabs.
Android browser vendors should support the Custom Tabs protocol (by providing an implementation of the "CustomTabsService" class), to provide the in-app browser tab user-experience optimization to their users. Chrome is one such browser that implements Custom Tabs.
To receive the authorization response, private-use URI schemes are broadly supported through Android Implicit Intents. Claimed "https" scheme redirect URIs through Android App Links are available on Android 6.0 and above. Both types of redirect URIs are registered in the application's manifest.
A complete open-source sample is included in the AppAuth for Android [AppAuth.Android] library.
B.3. Windows Implementation Details
Both traditional and Universal Windows Platform (UWP) apps can perform authorization requests in the user's browser. Traditional apps typically use a loopback redirect to receive the authorization response, and listening on the loopback interface is allowed by default firewall rules. When creating the loopback network socket, apps SHOULD set the "SO_EXCLUSIVEADDRUSE" socket option to prevent other apps binding to the same socket.
UWP apps can use private-use URI scheme redirects to receive the authorization response from the browser, which will bring the app to the foreground. Known on the platform as "URI Activation", the URI scheme is limited to 39 characters in length, and it may include the "." character, making short reverse domain name based schemes (as required in Section 7.1) possible.
UWP apps can alternatively use the Web Authentication Broker API in Single Sign-on (SSO) mode, which is an external user-agent designed for authorization flows. Cookies are shared between invocations of the broker but not the user's preferred browser, meaning the user will need to log in again, even if they have an active session in their browser; but the session created in the broker will be available to subsequent apps that use the broker. Personalizations the user has made to their browser, such as configuring a password manager, may not be available in the broker. To qualify as an external user-agent, the broker MUST be used in SSO mode.
To use the Web Authentication Broker in SSO mode, the redirect URI must be of the form msapp://{appSID} where "\{appSID\}" is the app's security identifier (SID), which can be found in the app's registration information or by calling the "GetCurrentApplicationCallbackUri" method. While Windows enforces the URI authority on such redirects, ensuring that only the app with the matching SID can receive the response on Windows, the URI scheme could be claimed by apps on other platforms without the same authority present; thus, this redirect type should be treated similarly to private-use URI scheme redirects for security purposes.
An open-source sample demonstrating these patterns is available [SamplesForWindows].
B.4. macOS Implementation Details
Apps can initiate an authorization request in the user's default browser using platform APIs for opening URIs in the browser.
To receive the authorization response, private-use URI schemes are a good redirect URI choice on macOS, as the user is returned right back to the app they launched the request from. These are registered in the application's bundle information property list using the "CFBundleURLSchemes" key. Loopback IP redirects are another viable option, and listening on the loopback interface is allowed by default firewall rules.
A complete open-source sample is included in the AppAuth for iOS and macOS [AppAuth.iOSmacOS] library.
B.5. Linux Implementation Details
Opening the authorization request in the user's default browser requires a distro-specific command: "xdg-open" is one such tool.
The loopback redirect is the recommended redirect choice for desktop apps on Linux to receive the authorization response. Apps SHOULD NOT set the "SO_REUSEPORT" or "SO_REUSEADDR" socket options in order to prevent other apps binding to the same socket.