| P. Madsen | |
| Ping Identity | |
| A. Jain | |
| VMware | |
| A. Zmolek | |
| Enterproid | |
| T. Bradley | |
| Ping Identity | |
| Sep 18, 2014 |
OpenID Connect Native Application Token Agent API Bindings 1.0
draft-native-application-api-bindings-01
OpenID Connect 1.0 is a simple identity layer on top of the OAuth 2.0 protocol. It allows Clients to verify the identity of the End-User based on the authentication performed by an Authorization Server, as well as to obtain basic profile information about the End-User in an interoperable and RESTful manner.
The OpenID Connect Native Application Token Agent API Bindings 1.0 is a profile of the OpenID Connect Standard 1.0 specification designed to enable 'authorization agents' on devices, ie native applications that obtain OAuth access tokens on behalf of other native applications.
OpenID Connect Native Application Token Agent API Bindings 1.0 is a profile of the OpenID Connect Core 1.0 [OpenID.Core] specification that stipulates how a specialized OpenID Connect Client called an Token Agent can obtain tokens on behalf of other installed native applications - thereby provisioning tokens to those applications and so enabling a Single SignOn experience for End-Users. The API Bindings specification describes the communication between the Token Agent and native applications in different deployment environments.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119].
Throughout this document, values are quoted to indicate that they are to be taken literally. When using these values in protocol messages, the quotes MUST NOT be used as part of the value.
This specification uses the terms "Access Token", "Refresh Token", "Authorization Code", "Authorization Grant", "Authorization Server", "Authorization Endpoint", "Client", "Client Identifier", "Client Secret", "Protected Resource", "Resource Owner", "Resource Server", and "Token Endpoint" defined by OAuth 2.0 [RFC6749]. This specification also defines the following terms:
More and more applications, both enterprise on-prem and cloud-based, are accessed through REST APIs in addition to, or instead of, browser-based access. Mobile clients will be a key consumer of such APIs. Native installed applications (e.g for iOS , Android, BlackBerry, etc devices) offer an important alternative to web or browser-based applications. Both models have their pros/cons.
OAuth 2.0 is an authentication & authorization framework for such REST APIs. Critically, OAuth 2.0 is explicitly designed to support the variety of different client types that will be accessing REST APIs - both applications running on web servers within the enterprise calling out to the cloud/partners etc, as well as applications running on mobile phones belonging to employees and customers. OAuth supports this variety of client types by defining multiple mechanisms for 'getting a token', the different mechanisms acknowledging the constraints of particular client types.
For accessing protected resources behind an API using OAuth for authentication, the mobile application requires an access token - this to be presented on the HTTP calls to the API.
The high-level sequence by which the client obtains and uses an access token is:
The presumption is that each native application client will perform the above steps. When a User has multiple native applications on their device (as is more and more the case) this may be an unacceptable usability burden.
This burden can be reduced by introducing an 'authorization agent' (TA) onto the device. Rather than each native application directly obtaining its own OAuth tokens, the direct token retrieval is assumed by the authorization agent, with the tokens then handed over to the native applications for their normal use. Rather than the user individually authenticating and authorizing each native application, they do so only for the authorization agent - this then bootstrapping subsequently obtaining tokens for the other native applications. Because the User only authenticates and authorizes the authorization agent, the usability burden is significantly reduced.
The TA model is shown below
+-------------+
| Device |
| +--------+ | +-------------+
| | |-------- Login & Authorization (1)---------->| |
| | | | | |
| | Token |<------ Primary Tokens for TA - (2)----------| |
| | Agent | | | AS |
| | |---- Request Secondary tokens for apps (3)-->| |
| | | | | |
| | |<-------Secondary Tokens for apps (4)--------| |
| | | | +-------------+
| +--------+ | /\ /\
| /\ | | |
| | Pass | Validate tokens (7)
| |Tokens | | |
| \/ (5) | \/ |
| +--------+ | +-----+ |
| | App1 | -|--------- API Call with token (6)--------> | RS1 | |
| +--------+ | +-----+ \/
| +--------+ | +---------+
| | App2 | -|--------- API Call with token (6)--------> | RS2 |
| +--------+ | +---------+
| +--------+ | +------------+
| | App3 | -|--------- API Call with token (6)--------> | RS3 |
| +--------+ | +------------+
+-------------+
Figure 1
Note: the token validation of Step 7 may require a call to the issuing AS (as shown) or may be achieved locally via a digital signarture verification.
A TA must be able to obtain tokens (both primary & secondary) from Authorization Servers. This specification profiles the OpenID Connect Standard 1.0 specification for those interactions. The TA engages in messaging with the relevant Authorization Servers according to this profile in order to obtain the secondary OAuth access tokens on behalf of other native applications.
The authorization agent model can be applied for two different categories of native applications
While both scenarios imply the User authenticating and authorizing each native application individually, in the first case the User would interact with the same AS each time. In the latter, it would be different ASs.
This section outlines how an TA might pass secondary access tokens to corresponding native applications, or how the native application might request of the TA such a secondary access token.
Once it has obtained a secondary access token for a particular native application, the TA MUST deliver that secondary access token to that application.
The TA MUST NOT deliver a secondary access token to an application for which it was not issued.
This profile does not stipulate a particular mechanism for the delivery of the secondary access token, depending as it does on the mobile OS support for inter-app messaging.
One mechanism supported by both iOS and Android is the use of custom URL schemes. In this model, a native appliction registers itself with the mobile OS as the handler for URLs in a given scheme - when the OS subsequently sees URLs in this scheme, it hands them over to the native application.
To use this model, each native application that wants TA integration must register itself as the handler for a unique URL scheme.
Follows is the Android mechanism
<activity android:name=".MyAppRegisterAccount" android:label="@string/addAccount" >
<intent-filter>
<action android:name="android.intent.action.VIEW"/>
<category android:name="android.intent.category.DEFAULT"/>
<category android:name="android.intent.category.BROWSABLE"/>
<data android:scheme="nativeapp" />
</intent-filter>
</activity>
The same URL scheme identifier must be configured into the AS and AppInfo endpoint when the native application is configured so that access tokens can be appropriately targeted.
After obtaining an access token for a particular native application, the TA builds a URL in the corresponding custom scheme that includes the token.
The URL MUST
For instance
nativeapp://new_token?access_token=PeRTSD9RQrbiuoaHVPxV41MzW1qS
A TA SHOULD support an native application being able to request of the TA an access token, as compared to the TA handing an unsolicited access token to an application.
One mechanism to achive this is that, upon installation, the TA register itself as the handler for URLs with a particular scheme.A native applicaton can construct URLs in that scheme as a means of requesting of the TA that an access token be obtained.
TBD
TBD
This document makes no requests of IANA.
| [OpenID.Implicit] | Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., Mortimore, C. and E. Jay, "OpenID Connect Implicit Client Profile 1.0", July 2013. |
The following have contributed to the development of this specification.
Copyright (c) 2014 The OpenID Foundation.
The OpenID Foundation (OIDF) grants to any Contributor, developer, implementer, or other interested party a non-exclusive, royalty free, worldwide copyright license to reproduce, prepare derivative works from, distribute, perform and display, this Implementers Draft or Final Specification solely for the purposes of (i) developing specifications, and (ii) implementing Implementers Drafts and Final Specifications based on such documents, provided that attribution be made to the OIDF as the source of the material, but that such attribution does not indicate an endorsement by the OIDF.
The technology described in this specification was made available from contributions from various sources, including members of the OpenID Foundation and others. Although the OpenID Foundation has taken steps to help ensure that the technology is available for distribution, it takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this specification or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any independent effort to identify any such rights. The OpenID Foundation and the contributors to this specification make no (and hereby expressly disclaim any) warranties (express, implied, or otherwise), including implied warranties of merchantability, non-infringement, fitness for a particular purpose, or title, related to this specification, and the entire risk as to implementing this specification is assumed by the implementer. The OpenID Intellectual Property Rights policy requires contributors to offer a patent promise not to assert certain patent claims against other contributors and against implementers. The OpenID Foundation invites any interested party to bring to its attention any copyrights, patents, patent applications, or other proprietary rights that may cover technology that may be required to practice this specification.
[[ To be removed from the final specification ]]
-01
-02