OAuth 2.0 Token Exchange: an STS for the REST of us
Ping Identity
brian.d.campbell@gmail.com
Independent
ve7jtb@ve7jtb.com
Security
OAuth Working Group
RFC
Request for Comments
I-D
Internet-Draft
Delegation
Impersonation
STS
on-behalf-of
act-as
An OAuth 2.0 framework for exchanging security tokens enabling authorization servers to act as lightweight HTTP and JSON based security token services.
A security token service (STS) is a service capable of validating and issuing security tokens, which enables web service clients
to obtain appropriate temporary access credentials for resources in heterogeneous environments or across security domains.
Clients have historically used
WS-Trust
as the protocol to interact with an STS for token exchange.
However WS-Trust is a fairly heavyweight framework which uses XML, SOAP, WS-Security, XML-Signatures, etc. while
the trend in modern web development has been towards more lightweight services utilizing RESTful patterns and JSON.
The OAuth 2.0 Authorization Framework
and
OAuth 2.0 Bearer Tokens
have emerged as popular standards for authorizing and
securing access to HTTP and RESTful resources but do not provide all that is needed to support generic STS interactions.
This specification defines a lightweight protocol extending OAuth 2.0 that enables clients to request and obtain security tokens from authorization servers acting in the role of an STS. There is support for
enabling one party to act on behalf of another as well as enabling one party to delegate constrained authority to another.
Similar to OAuth 2.0, this specification focuses on client developer simplicity and requires only an HTTP client and JSON parser, which are nearly universally available in modern development environments.
The STS protocol defined in this specification is not itself RESTful (an STS doesn't lend itself particularly well to a REST approach) but does
utilize communication patterns and data formats that should be more palatable to developers accustom to working with RESTful systems.
A new security token request grant type and the associated specific parameters for a security token request to the token endpoint are defined by this specification.
A security token response is a normal
OAuth 2.0 response from the token endpoint with some additional parameters defined herein to provide information to the client.
The security tokens obtained from an STS could be used in a variety of contexts, the specifics of which are beyond the scope of this document.
The scope of this specification is limited to the definition of a framework and basic wire protocol for an STS style token exchange utilizing OAuth 2.0.
The syntax, semantics and security characteristics of the tokens themselves (both those presented to the AS and those obtained by the client)
are explicitly out of scope and no requirements are placed on the trust model in
which an implementation might be deployed. Additional profiles may provide more detailed requirements around the specific nature of the parties and trust involved,
whether signatures and/or encryption of tokens is required, etc., however, such details will often be policy decisions made with respect
to the specific needs of individual deployments and will be configured or implemented accordingly.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in
RFC 2119.
This specification uses the terms "authorization server"
"token endpoint", "access token request", "access token response", and "client"
defined by OAuth 2.0.
When principal A impersonates principal B, A is given all
the rights that B has within some defined rights context.
Whereas, with delegation semantics, principal A still has its own identity
separate from B and it is explicitly understood that while B
may have delegated its rights to A, any actions taken are
being taken by A and not B. In a sense, A is an agent for B.
Delegation semantics are therefore different than
impersonation semantics, with which it is sometimes
confused. When principal A impersonates principal B, then in
so far as any entity receiving such a token is concerned, they are
actually dealing with B. It is true that some members of the
identity system might have awareness that impersonation is
going on but it is not a requirement. For all intents and
purposes, when A is impersonating B, A is B.
A security token with delegation semantics is requested using this framework by including
both an on_behalf_of token and an act_as token in the request. The on_behalf_of token represents the identity of the party on
behalf of whom the token is being requested while the act_as token represents the identity of the party to whom the access rights of
the returned token are being delegated. In this case, the token returned to the client will contain claims about both parties.
A security token with impersonation semantics is requested using this framework by including
an on_behalf_of token in the request and omitting the act_as token. The on_behalf_of token represents the identity of the party on
behalf of whom the token is being requested the token returned to the client will contain claims about that party.
A client requests a security token by making a token request to the authorization server's token endpoint using the extension grant type mechanism defined
in Section 4.5 of OAuth 2.0.
Client authentication to the authorization server is done using the normal mechanisms provided by OAuth 2.0.
Section 2.3.1 of The OAuth 2.0 Authorization Framework defines password-based authentication of the client,
however, client authentication is extensible and other mechanisms are allowed.
For example, and
define client authentication using SAML Assertions and JSON Web Tokens respectively. Other mechanisms, such as TLS client authentication, are also possible.
The supported methods of client authentication and whether or not to allow unauthenticated or unidentified clients are deployment decisions that are at the discretion of the authorization server.
The client makes a general security token request to the token endpoint with an extension
grant type by including the
following parameters using the application/x-www-form-urlencoded
format with a character encoding of UTF-8 in the HTTP request entity-body:
REQUIRED. The value urn:ietf:params:oauth:grant-type:security-token-request
indicates that it is a security token request.
REQUIRED.
Indicates the location of the service or resource where the client intends to use the requested security token.
The value MUST be an absolute URI as defined by Section 4.3 of . The URI MAY include a
query component but MUST NOT include a fragment component. When applicable, the value of this parameter also typically informs the
audience restrictions on the returned security token.
OPTIONAL.
A list of space-delimited, case-sensitive strings that allow the client to specify the desired scope of requested
security token in the context of the service or resource indicated by the aud parameter.
OPTIONAL.
Identifier for the type of the requested security token. For example, a JWT can be requested with the identifier
urn:ietf:params:oauth:token-type:jwt,
which is defined in JSON Web Token.
If the requested type is unspecified, the returned token type is at the discretion of the
authorization server and may be dictated by knowledge of the requirements of the service or resource whose location is
indicated by the aud parameter.
REQUIRED.
The value of this request parameter is a security token which represents the identity of the party on behalf of whom the request is being made.
Typically the subject of this token will be the primary subject of the security token returned in response to this request.
REQUIRED.
An identifier that indicates the type of the security token sent with the on_behalf_of parameter.
OPTIONAL.
The value of this request parameter is a security token which represents the identity of the party that is authorized to use the requested security token.
When this parameter is present, it indicates that the client wants a token that contains claims about two distinct entities:
1) the entity represented by the token in the on_behalf_of parameter as the primary subject and 2)
the entity represented by this token as a party who is authorized to act on behalf of that subject.
REQUIRED when the act_as parameter is present in the request but MUST NOT be included otherwise.
The value of this parameter is
an identifier that indicates the type of the security token sent with the act_as parameter.
The authorization server responds to a security token request with a normal OAuth 2.0 response from the token endpoint as defined in
Section 5 of RFC 6749. Additional details and explanation are provided in the following subsections.
If the request is valid and meets all policy and other criteria of the authorization server,
a successful token response is constructed by adding the following parameters
to the entity-body of the HTTP response using the "application/json"
media type as defined by and an HTTP 200 status code. The
parameters are serialized into a JavaScript Object Notation (JSON)
structure by adding each parameter at the top level.
Parameter names and string values are included as JSON strings.
Numerical values are included as JSON numbers. The order of
parameters does not matter and can vary.
REQUIRED. The security token issued by the authorization server in response to the security token request.
The access_token parameter from Section 5.1 of RFC 6749 is used here
to carry the requested security token, which allows this token exchange framework to use the existing OAuth 2.0 request
and response constructs defined for the token endpoint.
REQUIRED. An identifier for the general type of the returned security token.
For example, if the security token is a JWT, this value of the security_token_type is
urn:ietf:params:oauth:token-type:jwt.
REQUIRED. A case insensitive value describing the type of the token issued as discussed in
Section 7.1 of RFC 6749. Note that this value is different from
the value of the security_token_type and provides the client with information
about how to utilize the token to access protected resources. For example, a value of Bearer as defined
in indicates that the security token is a bearer token and the client can simply
present it as is without any additional proof of eligibility beyond the contents of the token itself.
A value of PoP, on the other hand, indicates that use of the token will require demonstrating possession of a
cryptographic key associated with the security token ( describes the PoP
token type).
RECOMMENDED. The validity lifetime, in seconds, of the issued security token. For
example, the value 3600 denotes that the token will
expire in one hour from the time the response was generated.
OPTIONAL, if the scope of the security token is identical to the scope requested by the client;
otherwise, REQUIRED.
NOT RECOMMENDED.
Refresh tokens will typically not be issued in response to a urn:ietf:params:oauth:grant-type:security-token-request grant type requests.
If either the on_behalf_of or act_as
tokens are invalid for any reason, or are unacceptable based on policy, the authorization server
MUST construct an error response as defined in Section 5.2 of OAuth 2.0
The value of the error
parameter MUST be the invalid_grant error code. The authorization
server MAY include additional information regarding the reasons for the error using the error_description or
error_uri parameters.
[[ TODO: at least two examples, with and without act_as, showing a request/response exchange and including some relevant internal details of the tokens involved ]]
[[ TODO ]]
The urn:ietf:params:oauth:grant-type:security-token-request
Grant Type is to be registered in the
IANA urn:ietf:params:oauth registry established in .
[[ TODO ]]
Other parameters like requested_security_token_type,
on_behalf_of, on_behalf_of_token_type, act_as,
etc. need to be registered in the appropriate registries.
The aud parameter needs to be registered too but that may well get done in and
aud may/does have wider applicability so perhaps deserves it's own little spec?
WS-Trust 1.4 (incorporating Approved Errata 01)
OpenID Connect Core 1.0
[Some] decisions to be made with potential associated draft updates:
Are the constructs for expressing delegation and impersonation the 'right' ones? Do they provide sufficient flexibility while
being reasonably understandable and implementable?
Does it really make sense to use the act_as and on_behalf_of terms? They come with some baggage.
More guidance on what delegation should look like in the returned token? I.e. refer to azp in ? Or something else?
Do we need to codify if/how the identity of the client end up in returned token? Should it be an AS decision? A special case of delegation/act_as? Something else?
Does the error response need a way to convey additional information beyond what OAuth 2.0 provides?
Exactly how the presentation of PoP or other non-bearer tokens works. Should a challenge-response mechanism be considered rather than trying to stuff the whole PoP into a single request?
The author wishes to thank Michael Jones for bringing forth the concept
of OAuth 2.0 Token Exchange with . This draft borrows heavily
from Jones' work while striving to provide a syntax that is more
consistent with OAuth 2.0, which will hopefully be
more familiar to developers and easier to understand and implement.
The author also wishes to thank John Bradley for his endless patience and willingness to share his expertise.
[[ to be removed by the RFC Editor before publication as an RFC ]]
-01
Add Bradley as an author.
-00
Gotta start somewhere...