[Docs] [txt|pdf] [Tracker] [Email] [Nits]
Versions: 00 01 draft-ietf-oauth-saml2-bearer
B. Campbell, Ed.
Internet-Draft Ping Identity Corp.
Intended status: Standards Track C. Mortimore
Expires: January 28, 2011 Salesforce.com
July 27, 2010
SAML 2.0 Bearer Assertion Profile for OAuth 2.0
draft-campbell-oauth-saml-00
Abstract
This specification defines the use of a SAML 2.0 bearer assertion as
means for requesting an OAuth 2.0 access token.
Status of this Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on January 28, 2011.
Copyright Notice
Copyright (c) 2010 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Campbell & Mortimore Expires January 28, 2011 [Page 1]
Internet-Draft OAuth SAML Bearer Assertion Profile July 2010
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 3
2. SAML Assertion Access Token Request . . . . . . . . . . . . . . 3
2.1. Client Requests Access Token . . . . . . . . . . . . . . . 4
2.2. Assertion Format and Processing Requirements . . . . . . . 5
2.3. Error Response . . . . . . . . . . . . . . . . . . . . . . 6
2.4. Example (non-normative) . . . . . . . . . . . . . . . . . . 7
3. Security Considerations . . . . . . . . . . . . . . . . . . . . 8
4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 8
Appendix A. Contributors . . . . . . . . . . . . . . . . . . . . . 8
5. References . . . . . . . . . . . . . . . . . . . . . . . . . . 8
5.1. Normative References . . . . . . . . . . . . . . . . . . . 8
5.2. Informative References . . . . . . . . . . . . . . . . . . 9
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 9
Campbell & Mortimore Expires January 28, 2011 [Page 2]
Internet-Draft OAuth SAML Bearer Assertion Profile July 2010
1. Introduction
The Security Assertion Markup Language (SAML) 2.0
[OASIS.saml-core-2.0-os], is an XML-based framework that provides a
means for a subject to be identified across security domains. The
SAML specification, while primarily targeted at providing cross
domain web browser single sign-on, was also designed to be modular
and extensible to facilitate use in other contexts. The Assertion,
an XML security token, is a fundamental construct of SAML that is
most often adopted for use in other protocols and specifications. An
assertion is generally issued by an identity provider and consumed by
a service provider who relies on its content to identify the subject
for security related purposes.
OAuth 2.0 [I-D.ietf.oauth-v2] provides a method for making
authenticated HTTP requests to a resource using an access token.
Tokens are issued to third-party clients by an authorization server
with the (sometimes implicit) approval of the resource owner. OAuth
defines multiple profiles for obtaining access tokens to support a
wide range of client types and user experiences. One such method is
the use of an assertion which supports the case when a client wishes
to exchange an existing security token for an access token. However
the Oauth 2.0 leaves the specific format and validation of the
assertion out of scope.
This specification profiles the specific use of a SAML 2.0 bearer
assertion in requesting an access token using the assertion
grant_type from OAuth 2.0. The format and processing rules for the
SAML assertion defined in this specification are intentionally
similar to those in the Web Browser SSO Profile defined in
[OASIS.saml-profiles-2.0-os] with the goal of reusing, to the extent
reasonable, concepts and patterns from that well established profile.
1.1. Notational Conventions
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 RFC 2119 [RFC2119].
Unless otherwise noted, all the protocol parameter names and values
are case sensitive.
2. SAML Assertion Access Token Request
A SAML assertion is used to request an access token when a client
wishes to utilize an existing trust relationship, expressed though
the semantics of the SAML assertion, to establish authorization
Campbell & Mortimore Expires January 28, 2011 [Page 3]
Internet-Draft OAuth SAML Bearer Assertion Profile July 2010
without directly involving the resource owner's approval at the
resource server.
The process by which the client obtains the assertion is out of
scope.
+--------+ +---------------+
| | | |
| |>--(A)-- SAML 2.0 Assertion ----->| Authorization |
| Client | | Server |
| |<--(B)---- Access Token ---------<| |
| | | |
+--------+ +---------------+
Figure 1: Assertion Access Token Request
The request/response flow illustrated in Figure 1 includes the
following steps:
(A) The client sends an access token request to the authorization
server and includes a SAML 2.0 assertion.
(B) The authorization server validates the assertion per the
processing rules defined in this specification and issues an
access token.
2.1. Client Requests Access Token
The client requests an access token by making an HTTP "POST" request
to the token endpoint using an assertion as an access grant. The
client makes an access token request, as defined in the OAuth, with
the following parameter definitions taking precedence in the
constructed URI:
assertion_type
REQUIRED. The value of the assertion_format parameter MUST be
"http://oauth.net/assertion_type/saml/2.0/bearer"
assertion
REQUIRED. The value of the assertion parameter MUST contain a
single SAML 2.0 Assertion. The SAML assertion XML data MUST be
encoded using base64url, where the encoding adheres to the
definition in Section 5 of RFC4648 [RFC4648] and where the
padding bits set to zero. To to avoid the need for subsequent
encoding steps (by "application/x-www-form-urlencoded"
Campbell & Mortimore Expires January 28, 2011 [Page 4]
Internet-Draft OAuth SAML Bearer Assertion Profile July 2010
[W3C.REC-html401-19991224], for example), the base64url encoded
data SHOULD NOT be line wrapped and pad characters ("=") SHOULD
NOT be included.
2.2. Assertion Format and Processing Requirements
The authorization server MUST validate the assertion according to the
criteria below and, if valid, issues an access token response as
described in [I-D.ietf.oauth-v2]. The access token SHOULD be issued
only for the subject of the assertion
o The Assertion's <Issuer> element MUST contain a unique identifier
for the entity that issued the assertion; the Format attribute
MUST be omitted or have a value of
"urn:oasis:names:tc:SAML:2.0:nameid-format:entity".
o The assertion MUST contain a <Subject> element that identifies the
resource owner for whom the access token is being requested.
o The <Subject> element MUST contain a single <SubjectConfirmation>
element and it MUST have a Method attribute with a value of
"urn:oasis:names:tc:SAML:2.0:cm:bearer".
o The <SubjectConfirmation> element MUST contain a single
<SubjectConfirmationData> element.
o The <SubjectConfirmationData> element MUST have a Recipient
attribute with a value indicating the token endpoint URL of the
authorization server. The authorization server MUST verify that
the value of the Recipient attribute matches the token endpoint
URL (or an acceptable alias) to which the assertion was delivered.
o The <SubjectConfirmationData> element MUST have a NotOnOrAfter
attribute that limits the window during which the assertion can be
confirmed. The authorization server MUST verify that the
NotOnOrAfter instant has not passed, subject to allowable clock
skew between systems.
o The <SubjectConfirmationData> element MUST NOT contain a NotBefore
attribute.
o The <SubjectConfirmationData> element MAY also contain an Address
attribute limiting the client address from which the assertion can
be delivered. Verification of the Address is at the discretion of
the authorization server.
o If the assertion issuer authenticated the subject, the assertion
SHOULD contain a single <AuthnStatement> representing that
Campbell & Mortimore Expires January 28, 2011 [Page 5]
Internet-Draft OAuth SAML Bearer Assertion Profile July 2010
authentication event.
o If the assertion was issued with the intention that the client act
autonomously on behalf of the subject, an <AuthnStatement> SHOULD
NOT be included.
o Other statements, in particular, <AttributeStatement> elements MAY
be included in the assertion.
o The assertion MUST contain an <AudienceRestriction> element with
an <Audience> element containing a URI reference that identifies
the authorization server, or the service provider SAML entity of
its controlling domain, as an intended audience. The
authorization server MUST verify that it is an intended audience
for the assertion.
o The authorization server MAY ensure that bearer assertions are not
replayed, by maintaining the set of used ID values for the length
of time for which the assertion would be considered valid based on
the NotOnOrAfter attribute in the <SubjectConfirmationData>.
o The assertion MUST be digitally signed by the issuer and the
authorization server MUST verify the signature.
o Encrypted elements MAY appear in place of their plain text
counterparts as defined in [OASIS.saml-core-2.0-os].
o The authorization server MUST verify that the assertion is valid
in all other respects per [OASIS.saml-core-2.0-os].
2.3. Error Response
If the assertion is not valid, or its subject confirmation
requirements cannot be met, the the authorization server MUST
construct an error response as defined in [I-D.ietf.oauth-v2]. The
value of the error parameter MUST be the "invalid_grant" error code.
The authorization server MAY include additional information regarding
the reasons the assertion was considered invalid using the
error_description or error_uri parameters.
Campbell & Mortimore Expires January 28, 2011 [Page 6]
Internet-Draft OAuth SAML Bearer Assertion Profile July 2010
For example:
HTTP/1.1 400 Bad Request
Content-Type: application/json
Cache-Control: no-store
{
"error":"invalid_grant",
"error_description":"invalid signature"
}
2.4. Example (non-normative)
Though non-normative, the following examples illustrate what a
conformant assertion and access token request would look like.
Below is an example SAML 2.0 Assertion (whitespace formatting is for
display purposes only):
<Assertion IssueInstant="1970-01-01T00:00:00.000Z"
ID="ef1xsbZxPV2oqjd7HTLRLIBlBb7"
Version="2.0"
xmlns="urn:oasis:names:tc:SAML:2.0:assertion">
<Issuer>https://saml-idp.example.com</Issuer>
<ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
[...omitted for brevity...]
</ds:Signature>
<Subject>
<NameID
Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">
brian@example.com
</NameID>
<SubjectConfirmation
Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
<SubjectConfirmationData
NotOnOrAfter="1970-01-01T00:05:00.000Z"
Recipient="https://authz.example.net/token.oauth2"/>
</SubjectConfirmation>
</Subject>
<Conditions>
<AudienceRestriction>
<Audience>https://saml-sp.example.net</Audience>
</AudienceRestriction>
</Conditions>
</Assertion>
Campbell & Mortimore Expires January 28, 2011 [Page 7]
Internet-Draft OAuth SAML Bearer Assertion Profile July 2010
Figure 2: Example SAML 2.0 Assertion
To present the assertion shown in the previous example as part of an
access token request, for example, the client makes the following
HTTPS request (line breaks are for display purposes only):
POST /token.oauth2 HTTP/1.1
Host: authz.example.net
Content-Type: application/x-www-form-urlencoded
grant_type=assertion&assertion_type=http%3A%2F%2Foauth.net%2Fasse
rtion_type%2Fsaml%2F2.0%2Fbearer&assertion=PEFzc2VydGlvbiBJc3N1ZU
[...omitted for brevity...]b24-PC9Db25kaXRpb25zPjwvQXNzZXJ0aW9uPg
Figure 3: Example Request
3. Security Considerations
No additional considerations beyond those described within the OAuth
2.0 Protocol [I-D.ietf.oauth-v2] and in the Security and Privacy
Considerations for the OASIS Security Assertion Markup Language
(SAML) V2.0 [OASIS.saml-sec-consider-2.0-os].
4. IANA Considerations
This document has no actions for IANA.
Appendix A. Contributors
The following people contributed wording and concepts to this
document: Patrick Harding, Peter Motyka, Peter Saint-Andre and David
Waite
5. References
5.1. Normative References
[I-D.ietf.oauth-v2]
Hammer-Lahav, E., Ed., Recordon, D., and D. Hardt, "The
OAuth 2.0 Protocol", Jun 2010.
[OASIS.saml-core-2.0-os]
Cantor, S., Kemp, J., Philpott, R., and E. Maler,
Campbell & Mortimore Expires January 28, 2011 [Page 8]
Internet-Draft OAuth SAML Bearer Assertion Profile July 2010
"Assertions and Protocol for the OASIS Security Assertion
Markup Language (SAML) V2.0", OASIS Standard saml-core-
2.0-os, March 2005.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data
Encodings", RFC 4648, October 2006.
5.2. Informative References
[OASIS.saml-profiles-2.0-os]
Hughes, J., Cantor, S., Hodges, J., Hirsch, F., Mishra,
P., Philpott, R., and E. Maler, "Profiles for the OASIS
Security Assertion Markup Language (SAML) V2.0", OASIS
Standard OASIS.saml-profiles-2.0-os, March 2005.
[OASIS.saml-sec-consider-2.0-os]
Hirsch, F., Philpott, R., and E. Maler, "Security and
Privacy Considerations for the OASIS Security Markup
Language (SAML) V2.0", OASIS Standard saml-sec-consider-
2.0-os, March 2005.
[W3C.REC-html401-19991224]
Hors, A., Raggett, D., and I. Jacobs, "HTML 4.01
Specification", World Wide Web Consortium
Recommendation REC-html401-19991224, December 1999,
<http://www.w3.org/TR/1999/REC-html401-19991224>.
Authors' Addresses
Brian Campbell (editor)
Ping Identity Corp.
Email: brian.d.campbell@gmail.com
Chuck Mortimore
Salesforce.com
Email: cmortimore@salesforce.com
Campbell & Mortimore Expires January 28, 2011 [Page 9]
Html markup produced by rfcmarkup 1.129c, available from
https://tools.ietf.org/tools/rfcmarkup/