P. Madsen | |
Ping Identity | |
A. Jain | |
VMware | |
W. Denniss | |
J. Bradley, Ed. | |
Ping Identity | |
May 22, 2015 |
Authorization Cross Domain Code 1.0
draft-acdc-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 acdc grant allows a Authorization Server to issue a grant that can be redeemed by a token endpoint that is not tightly coupled to the issuing Authorization server.
A single Authorization Server (AS) authorization endpoint may in this way support multiple token endpoints, those endpoints may be in diffrent policy domains, including ones run by Software as a Service providers.
Authorization Cross Domain Code 1.0 is a profile of the OpenID Connect Core 1.0 [OpenID.Core] specification that stipulates how a Client can obtain single use tokens that can be exchanged for access & refresh tokens at federated token endpoints.
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 ACDC model is shown below
+-------------+ | Device | | +--------+ | +-----------+ | | |-------- Login & Authorization (1)--------->| | | | | | | | | | App |<------ ACDC for app- (2)-------------------| | | | | | | AS 1 | | | | | | | | | | | | | | | | | | | | | | | +-----------+ | | | | | | | | | | | | +-----------+ | | |---- Request Secondary tokens for app (3)-->| | | | | | | AS 2 | | | |<-------Secondary Tokens for apps (4)-------| | | | | | +-----------+ | | | | /\ /\ | | | | | | | | | | Validate tokens (6) | | | | | | | | | | +---------+ | | | -|--------- API Call with token (5)-------> | RS2 | | +--------+ | +---------+ +-------------+
Figure 1
Note: the token validation of Step 6 may require a call to the issuing AS (as shown) or may be achieved locally via a digital signarture verification.
ACDC tokens can be obtained in two ways:
When an authorization server creates a ACDC token, it needs to indicate what token_endpoint it will be used at.
This section defines a new paramater that is used by the client to indicate what protected resource at which resource server it wants to access if requesting a access token, or which token_endpoint if requesting a ACDC grant. This information may subsequently also communicated by the authorization server securely to the resource server, for example within the audience field of the access token or ACDC token.
The client constructs the ACDC token request to the token endpoint by adding the 'aud' parameter using the "application/x-www-form-urlencoded" format with a character encoding of UTF-8 in the HTTP request entity-body.
The URI included in the aud parameter MUST be an absolute URI as defined by Section 4.3 of [RFC3986]. It MAY include an "application/x-www-form-urlencoded" formatted query component (Section 3.4 of [RFC3986] ). The URI MUST NOT include a fragment component.
The ABNF syntax for the 'aud' element is defined in Appendix C.
If requesting a code or acdc token the value of the 'aud' paramater MUST be the absolute URI of the token_endpoint that the resulting token is to be presented to. Failing to provide the propper URI may cause the token to be rejected by the token_endpoint.
The client constructs the ACDC token request to the authorization endpoint by adding the 'aud' parameter to the query string of the authorization request.
The URI included in the aud parameter MUST be an absolute URI as defined by Section 4.3 of [RFC3986]. It MAY include an "application/x-www-form-urlencoded" formatted query component (Section 3.4 of [RFC3986] ). The URI MUST NOT include a fragment component.
The ABNF syntax for the 'aud' element is defined in Appendix C.
If requesting a acdc token the value of the 'aud' paramater MUST be the absolute URI of the token_endpoint that the resulting token is to be presented to. Failing to provide the propper URI may cause the token to be rejected by the token_endpoint.
This section registers a new Response Type, the acdc , in accordance with the stipulations in the OAuth 2.0 specification, Section 8.4. The intended purpose of the acdc is that it MUST provide an assertion of the scopes authorized by the Resource Owner as understood by the Authorization Server. The assertion MUST specify a targeted audience, e.g. the target AS and SHOULD contain the identity of the Resource Owner as understood by the Authorization Server.
This section registers a new Grant Type, the urn:ietf:params:oauth:grant-type:jwt-acdc
This isa profile of the JWT Authorization grant defined in Sec 4 of [RFC7523]
JWT authorization grants may be used with or without client authentication or identification. Whether or not client authentication is needed in conjunction with a JWT authorization grant, as well as the supported types of client authentication, are policy decisions at the discretion of the authorization server. However, if client credentials are present in the request, the authorization server MUST validate them.
The cnf element MUST be present in the JWT. The default confirmation method is PKCE. Other Proof of possession methods may be defined as extensions, but are out of scope for this document.
The pkce element is present in the JWT, the AS must require the code_verifyer to be present in the request and validate it according to the PKCE [I-D.ietf-oauth-spop] specification.
If the JWT is not valid, or the current time is not within the token's valid time window for use, the authorization server constructs an error response as defined in OAuth 2.0 [RFC6749]. The value of the "error" parameter MUST be the "invalid_grant" error code. The authorization server MAY include additional information regarding the reasons the JWT was considered invalid using the "error_description" or "error_uri" parameters.
For example:
HTTP/1.1 400 Bad Request Content-Type: application/json Cache-Control: no-store { "error":"invalid_grant", "error_description":"Audience validation failed" }
Figure 2
The ACDC Token is a single use security token that contains Claims about the authorization grant. The ACDC Token is represented as a JSON Web Token (JWT) [RFC7519].
The ACDC Token is used to communicate authorization information between authorization servers. The user is passed as the value of sub is scoped to the iss.
The ACDC Token is audience restricted to a remote AS via the aud (audience) Claim.
The cnf claim from JWT POP communicates the PKCE code_challange and code_challange_method. If code_challange_method is not included the default is "S256". The code_challange_method "plain" MUST NOT be used.
The scopes claim is an array of scopes that the AS has granted for this client.
The sid claim is a string identifying the user session as understood by the AS. In the case of a native application this SHOULD identify the device.
The following is a non-normative example of a base64url decoded ACDC Token with the remote AS as the value of aud and the client_id as the value of azp (with line wraps for display purposes only):
{ "iss": "https://server.example.com", "sub": "24400320", "azp": "client-ID", "aud": "https://server.partner.com", "exp": 1311281970, "iat": 1311280970, "sid": "Work iPhone", "cnf":{ "code_challange" : "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM", "code_challange_method" : "S256" }, "scopes" : [ "scope1" , "scope2" ] }
TBD
TBD
This document makes no requests of IANA.
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.
This section provides Augmented Backus-Naur Form (ABNF) syntax descriptions for the elements defined in this specification using the notation of [RFC5234].
The ABNF syntax is defined as follows where by the "URI-reference" definition is taken from [RFC3986]:
[[ To be removed from the final specification ]]
-01