I'm gong to join the growing list of people attaching a potential I-D
to an email due to he cut off time for the I-D submissions. Attached
is a draft that aims to tightly define the particular format of a SAML
2.0 bearer assertion in requesting an access token using the assertion
grant_type. I've been working with Chuck at Salesforce.com on this
and the primary goal is to have some documentation or specification
that is sufficient to facilitate interoperability between
independently developed implementations or products. This, of
course, wouldn't preclude using SAML in other ways - it would only
provide one concrete definition to implement against.
I intend to submit this as an I-D when the submission process reopens.
Any feedback from this group would be appreciated as well as
thoughts about this eventually becoming a working group draft.
Thanks,
Brian Campbell
B. Campbell, Ed.
Internet-Draft Ping Identity Corp.
Intended status: Standards Track C. Mortimore
Expires: January 14, 2011 Salesforce.com
July 13, 2010
SAML 2.0 Bearer Assertion Profile for OAuth 2.0
draft-campbell-oauth-saml-00-f
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 14, 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 14, 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 14, 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.
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
without directly involving the resource owner's approval at the
resource server.
The process by which the client obtains the assertion is out of
Campbell & Mortimore Expires January 14, 2011 [Page 3]
Internet-Draft OAuth SAML Bearer Assertion Profile July 2010
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"
[W3C.REC-html401-19991224], for example), the base64url encoded
data SHOULD NOT be line wrapped and pad characters ("=") SHOULD
NOT be included.
Campbell & Mortimore Expires January 14, 2011 [Page 4]
Internet-Draft OAuth SAML Bearer Assertion Profile July 2010
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
authentication event.
o If the assertion was issued with the intention that the client act
autonomously on behalf of the subject, an <AuthnStatement> SHOULD
Campbell & Mortimore Expires January 14, 2011 [Page 5]
Internet-Draft OAuth SAML Bearer Assertion Profile July 2010
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 MUST 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.
For example:
HTTP/1.1 400 Bad Request
Content-Type: application/json
Cache-Control: no-store
{
"error":"invalid_grant",
"error_description":"invalid signature"
}
Campbell & Mortimore Expires January 14, 2011 [Page 6]
Internet-Draft OAuth SAML Bearer Assertion Profile July 2010
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">
[email protected]
</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>
Figure 2: Example SAML 2.0 Assertion
Campbell & Mortimore Expires January 14, 2011 [Page 7]
Internet-Draft OAuth SAML Bearer Assertion Profile July 2010
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,
"Assertions and Protocol for the OASIS Security Assertion
Markup Language (SAML) V2.0", OASIS Standard saml-core-
Campbell & Mortimore Expires January 14, 2011 [Page 8]
Internet-Draft OAuth SAML Bearer Assertion Profile July 2010
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-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]
Raggett, D., Hors, A., 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: [email protected]
Chuck Mortimore
Salesforce.com
Email: [email protected]
Campbell & Mortimore Expires January 14, 2011 [Page 9]
_______________________________________________
OAuth mailing list
[email protected]
https://www.ietf.org/mailman/listinfo/oauth
