Subject: [OAUTH-WG] Proposed language for section 2.2 on Client Assertions

From: Yaron Goland <[email-masked]>
Date: Mon, 26 Jul 2010 20:22:28 +0000

The following is proposed language for inclusion in the spec as section 2.2. I would like to thank Brian Campbell, Brain Eaton, Chuck Mortimore, Dirk Balfanz, Eric Sachs, Justin Smith and Marius Scurtescu for taking the time to review and improve this proposal. Please note that the named folks contributed the good ideas and I just focused on introducing anything that is broken.

So what does the group think? +1? -1?

                Thanks,
                                Yaron

2.2 Assertion Client Credentials

While Client Passwords provide a simple mechanism for authenticating clients they require that a secret, the password, be sent over the network. Even when the network connection is encrypted sending secrets over a network connection is considered a potentially serious security threat. In scenarios where security is at a premium, it is preferred to use mechanisms such as Hash-based Message Authentication Codes (HMACs) or digital signatures that do not require sending secrets across the wire. The most common way to use HMACs or digital signatures is in assertions. Therefore this section defines how to authenticate a client using an assertion instead of a password.

The following parameters are used when a client authenticates itself using an assertion:

client_assertion_type
                REQUIRED. The format of the assertion as defined by the authorization server.  The value MUST be an absolute URI.
client_assertion
                REQUIRED. The client assertion.
For example (line breaks are for display purposes only):

                POST /token HTTP/1.1
                Host: server.example.com
                Content-Type: application/x-www-form-urlencoded

                grant_type=authorization_code&
                client_assertion=PHNhbWxwOl...[omitted for brevity]...ZT4%3D&
                client_assertion_type=urn%3Aoasis%3Anames%sAtc%3ASAML%3A2.0%3Aassertion&
                redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb

In the previous example the client is submitting an authorization code to a token endpoint using a SAML assertion to authenticate itself.

The client_id and client_secret parameters MUST NOT be used with the client_assertion and client_assertion_type parameters.

Requests for end user authorization as defined in section 3 are required to contain a client_id parameter. If the response to the authorization request is a code then that code is submitted to a token endpoint to obtain an access token. For this flow to work with assertions there must exist some mechanism to map the value in the client_id parameter of the authorization request to the assertion that is subsequently submitted with the code to get an access token. How this works with any particular assertion type is out of scope for this document. However, any document that defines how to use an assertion of a particular type with OAuth 2.0 MUST define how to map the value from the client_id parameter in the authorization request to a value or values in the assertion subsequently submitted with the code to obtain an access token.

Token endpoints MUST reject assertions that do not contain HMAC/signed values that identify that the assertion is specifically intended to be consumed by the receiving endpoint. This requirement is typically met by some value in the assertion such as audience or recipient which contains the token endpoint's URI or other agreed upon identifier.

Token endpoints MUST reject assertions that do not contain HMAC/signed values that identify the entity that generated the assertion. This requirement is typically met by some value in the assertion such as issuer which contains a URI or other agreed upon identifier that identifies the entity that generated the assertion.

Token endpoints MUST reject assertions that do not contain HMAC/signed values that identify when the assertion is to expire as an absolute time. This requirement is typically met by some value in the assertion such as expiration that contains a UTC date/time value or equivalent time stamp identifying when the assertion will expire. Token endpoints MUST reject assertions whose expiration time is beyond a certain limit in the future. The definition of that limit MUST be based on the security requirements of the resource being protected. The limits to choose for any particular type of resource/data are application specific and depend upon a combination of what technologies are being used, what key policies are being followed, what laws may apply, etc. and therefore are out of scope for this document.

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Mon, 26 Jul 2010 14:08:24 -0700

By not incorporating the client_id parameter, you are preventing this client authentication mode from being used with the end-user authorization endpoint. In -09 I tried to separate the client_id from the client_secret, basically moving the client_id to the token endpoint as an endpoint parameter, and only using client_secret as the authentication method (which at the time was in-line with your earlier proposal).

I understand that in many assertions, the client identifier is established internally, but this approach will completely prevent using the assertion client authentication method with other flows that involve getting a code.

EHL

From: [email-masked] [mailto:[email-masked]] On Behalf Of Yaron Goland
Sent: Monday, July 26, 2010 1:22 PM
To: [email-masked]
Subject: [OAUTH-WG] Proposed language for section 2.2 on Client Assertions

                Thanks,
                                Yaron

client_assertion_type

                POST /token HTTP/1.1
                Host: server.example.com

---

From: Brian Eaton <[email-masked]>
Date: Mon, 26 Jul 2010 15:51:21 -0700

On Mon, Jul 26, 2010 at 2:08 PM, Eran Hammer-Lahav <[email-masked]> wrote:
> I understand that in many assertions, the client identifier is established
> internally, but this approach will completely prevent using the assertion
> client authentication method with other flows that involve getting a code.

I'm pretty sure that's exactly the opposite of what Yaron was trying to achieve.

client_id will continue to be passed on the authorization URL.

No client_id will be passed on the token endpoint, because it's either
insecure, or not necessary.  The assertion has to contain the client
identifier.

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Mon, 26 Jul 2010 16:11:14 -0700

How do you link the client_id using in the authorization endpoint with the client assertion using in the token endpoint?

EHL

> -----Original Message-----
> From: Brian Eaton [mailto:[email-masked]]
> Sent: Monday, July 26, 2010 3:51 PM
> To: Eran Hammer-Lahav
> Cc: Yaron Goland; [email-masked]
> Subject: Re: [OAUTH-WG] Proposed language for section 2.2 on Client
> Assertions
> 
> > I understand that in many assertions, the client identifier is
> > established internally, but this approach will completely prevent
> > using the assertion client authentication method with other flows that
> involve getting a code.
> 
> insecure, or not necessary.  The assertion has to contain the client identifier.

---

From: Brian Eaton <[email-masked]>
Date: Mon, 26 Jul 2010 16:18:45 -0700

> How do you link the client_id using in the authorization endpoint with the client assertion using in the token endpoint?

In theory:

"any document that defines how to use an assertion of a particular
type with OAuth 2.0 MUST define how to map the value from the
client_id parameter in the authorization request to a value or values
in the assertion subsequently submitted with the code to obtain an
access token."

In practice: you do it the same way you handle any kind of identity
assertion.  There is some combination of issuer and subject and
signature that ends up producing an identity that you trust.

---

From: Brian Campbell <[email-masked]>
Date: Tue, 27 Jul 2010 06:48:52 -0600

A client_id parameter would still be presented in the end user
authorization request. The text Brian E. quoted is what mandates any
specifications/documents/agreements that define how to use client
assertions must also define the association between the client_id and
some field(s) in the assertion.

If someone sees a cleaner way to deal with client identity on the user
authorization request when using assertions to authenticate the client
to the token endpoint, please speak up and lets discuss it.   However,
in general I do feel it's important to have better defined support in
the core OAuth spec to allow for client authentication methods beyond
just password.

-Brian

On Mon, Jul 26, 2010 at 5:18 PM, Brian Eaton <[email-masked]> wrote:
> _______________________________________________
> OAuth mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/oauth
>

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Tue, 27 Jul 2010 08:35:45 -0700

Makes sense. Personally, I don't have any preference on including it or not.

EHL

> From: [email-masked] [mailto:[email-masked]] On Behalf
> Of Brian Campbell
> Sent: Tuesday, July 27, 2010 5:49 AM
> To: oauth
> A client_id parameter would still be presented in the end user authorization
> request. The text Brian E. quoted is what mandates any
> assertions must also define the association between the client_id and some
> field(s) in the assertion.
> 
> in general I do feel it's important to have better defined support in the core
> OAuth spec to allow for client authentication methods beyond just
> password.
> 
> -Brian
> 
> >> How do you link the client_id using in the authorization endpoint with the
> client assertion using in the token endpoint?
> >
> > In theory:
> >