OAuth 2.0 User Authentication and Consent For Clients
draft-hunt-oauth-v2-user-a4c-01

Abstract

This specification defines a new OAuth2 endpoint that enables user authentication session and consent information to be shared with client applications.

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 February 28, 2014.

Copyright Notice

Copyright (c) 2013 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.

Table of Contents

• 1. Introduction
• 1.1. Requirements Language
• 2. Authenticate Code Grant
• 2.1. Authentication Request
• 2.2. Authentication Response
• 2.2.1. Error Responses
• 2.3. Access Token Request
• 2.4. Access Token Response
• 3. Privacy Considerations
• 4. Acknowledgements
• 5. IANA Considerations
• 6. Security Considerations
• 7. References
• 7.1. Normative References
• 7.2. Informative References
• Authors' Addresses

1. Introduction

Section 4.1 of the OAuth 2.0 Authorization Framework [RFC6749] defines the "Authorization Code Grant" flow which defines a redirect flow, typically via a web browser, that enables confidential clients to obtain access and refresh tokens. As part of this flow, resource owners are authenticated via the user agent so that their consent may be obtained. This flow defines the "Authentication Code Grant" extension which enables clients to request re-authentication and makes authentication session information available to the client in a standardized format.

This document focuses on extending OAuth2 to provide authentication session information only. The specification does not define a standardized resource owner profile information API. It is assumed that other APIs such as the SCIM API [I-D.ietf-scim-api] or Open Identity Connect [OIDC] could be used for this purpose. As part of the session information, a subject profile URL may optionally be provided.

1.1. Requirements Language

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].

2. Authenticate Code Grant

The Authentication Code Grant type is used in exactly the same manor as the Authorization Code Grant Section 4.1 [RFC6749] and has the same features and conditions. The Authorization Code Grant extends the features available by making it possible for clients to test and request re-authenticaiton and authorization as well as obtain login session information at the end of the grant flow.

2.1. Authentication Request

In addition to the parameters defined in Section 4.1.1 [RFC6749], the following additional parameters are defined:

min_alv

OPTIONAL. A value of "1", "2", "3", or "4". The minimum requested authentication assurance level as defined by [ISO29115] (see also [NIST_SP-800-63-2]). If the authorization server is unable to meet or exceed the requested authentication assurance level, the server SHALL return an unsupported_response_type error per section 4.1.2.1 [RFC6749]. [[should there be a specific error_uri value for alv not supported?]] When the value is omitted, the authorization server MAY choose any authentication assurance level.

prompt

OPTIONAL. Space delimited, case sensitive list of ASCII string values that specifies whether the Authorization Server prompts the End-User for reauthentication and consent. The defined values are:

none

The suthorization server MUST NOT display any authentication or consent user interface pages. An error is returned if the End-User is not already authenticated or the Client does not have pre-configured consent for the requested Claims or does not fulfill other conditions for processing. This can be used as a method to check for existing authentication and/or consent.

login

Regardless of the current user authentication state, the Authorization Server SHOULD prompt the End-User for reauthentication. If it cannot prompt the End-User, it MUST return an error.

select_account

The Authorization Server SHOULD prompt the End-User to select a user account. This allows an End-User who has multiple accounts at the Authorization Server to select amongst the multiple accounts that they might have current sessions for. If it cannot prompt the End-User, it MUST return an error.

hint

OPTIONAL. A helpful text message that should be displayed to the user during a re-authentication or re-authorization process.

    GET /authenticate?
    response_type=code
    &client_id=s6BhdRkqt3
    &redirect_uri=https%3A%2F%2Fclient.example.com%2Fcb
    &state=af0ifjsldkj
    &prompt=login
    Host: server.example.com

For xample, the client directs the user-agent to make the following HTTP request using TLS (with extra line breaks for display purposes only):

The authorization server MUST:

• Perform the normal OAuth2 authorization process,
• MAY elect not to request consent if no access token is to be issued (i.e. this is an authentication only request),
• MUST re-authenticate the user if prompt contains the parameter "login",
• MUST obtain consent from the user if prompt contains the parameter "consent", and,
• MUST return an error if prompt contains "none" and the user is not currently authenticated.

2.2. Authentication Response

The response is identical to the one described in Section 4.1.2 [RFC6749].

2.2.1. Error Responses

In addition to those defined in Section 4.1.2.1 [RFC6749], an additional "error" type is defined. "unauthenticated_user", MUST be returned after an authentication request parameter prompt is provided containing value "none" and the user is found to be currently unauthenticated.

2.3. Access Token Request

The access token request is identical to the one described in Section 4.1.3 [RFC6749]. In cases where there is no associated resource API and an access token is not to be issued, the normal OAuth2 token request is still made.

2.4. Access Token Response

If the access token request is valid and authorized, the authorization server issues an access token and optional refresh token as described in Section 5.1 [RFC6749]with the exception that the issuance of access_token is OPTIONAL. If the request client authentication failed or is invalid, the authorization server returns an error response as described in Section 5.2.

In addition to the parameters described in Section 5, a JSON Web Token (JWT) [I-D.ietf-oauth-json-web-token] known as an id_token is returned containing the following possible claims:

sub

REQUIRED. An identifier for the authenicated subject. The same identifier MUST be return for the same authenticated user on the same client_id. The authenticated user's "sub" value MAY change for different client_id values.

profile

OPTIONAL. A URL which can be used to access the authenticated subject user profile data. The URL MUST point to the same user profile as the one that was authenticated. The URL MUST be valid for the duration of the associated access token and refresh_tokens lifetimes. [[Editors note: Should this be a structured value to indicate the API type (SCIM, OIDC, HTML) and to optionally return multiple API representations]]

amr

OPTIONAL. Authentication Methods References. JSON array of strings that are identifiers for authentication methods used in the authentication. For instance, values might indicate that both password and OTP authentication methods were used. The definition of particular values to be used in the amr Claim is beyond the scope of this specification. Parties using this claim will need to agree upon the meanings of the values used, which may be context-specific. The amr value is an array of case sensitive strings. The following is a list of valid values:

pwd

Password authentication, either by user or service if client_secret is used.

rsa

If authentication was based on the proof of an rsa key. This includes if authentication was performed by a self-signed JWT with a service owned x509 certificate.

rsa

One time password.

mfa

Multiple factor authentication was used. When this is used the other authentication methods will also be included.

fed

A federated authentication assertion (e.g. JWT or SAML) was used.[[should original federated assertion be attached?]]

none

No authentication was performed. [[This would not really be used for the amr, but an equivalent claim that indicates the client authentication method. So for native clients ‘none’ would be the auth method]]

auth_time

REQUIRED. The time at which the subject user was authenticated expressed in number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time. See [RFC3339] for details regarding date/times in general and UTC in particular. 'lat' MAY be a time earlier than when the session information was issued as defined by 'iat".

iat

REQUIRED. The time at which the response or the session token was issued expressed in number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time. See [RFC3339] for details regarding date/times in general and UTC in particular.[RFC3339] for details regarding date/times in general and UTC in particular.

exp

REQUIRED. The time at which the user authenticated session (login) expires expressed in number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time. See [RFC3339] for details regarding date/times in general and UTC in particular. Note "expires_in" referes to the normal access token lifespan whereas "exp" refers to the lifespace of the user login session.

alv

OPTIONAL. The authentication assurance level as described by [ISO29115] (see also [NIST_SP-800-63-2]).

iss

REQUIRED for session token. An identifier representing the issuer of the authentication. MAY be the authorization endpoint URL.

aud

REQUIRED for session_token. Contains the client_id of the client receiving the assertion.

     HTTP/1.1 200 OK
     Content-Type: application/json;charset=UTF-8
     Cache-Control: no-store
     Pragma: no-cache
     {
       "access_token":"2YotnFZFEjr1zCsicMWpAA",
       "token_type":"example",
       "expires_in":3600,
       "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
       "id_token":"eyJhbGciOiJub25lIn0.
eyAic3ViIjoiNWRlZGNjOGItNzM1Yy00MDVmLWUwMjlmIiwicHJvZmlsZSI6Imh0
dHBzOi8vZXhhbXBsZS5jb20vVXNlcnMvNWRlZGNjOGItNzM1Yy00MDVmLWUwMjlm
IiwiYXV0aF90aW1lIjoiMTM2Nzk1NjA5NiIsImV4cCI6IjEzNjgwNDI0OTYiLCJh
bHYiOiIyIiwiaWF0IjoiMTM2Nzk1NjA5OCIsImlzcyI6Imh0dHBzOi8vc2VydmVy
LmV4YW1wbGUuY29tIiwiYXVkIjoiczZCaGRSa3F0MyIsImV4YW1wbGVfc2Vzc2lv
bl9wYXJhbWV0ZXIiOiJleGFtcGxlX3ZhbHVlIn0=."
     }

An non-normative example successful response using session (with carriage returns for readability):

As per the JWT specification, the encoded id_token is separated into parts by the ".", the first part (eyJhbGciOiJub25lIn0) indicates the signature algorithm and in this case decodes as:

{"alg":"none"}

The claimset is then decoded as:

{
  "sub":"5dedcc8b-735c-405f-e029f",
  "profile":"https://example.com/Users/5dedcc8b-735c-405f-e029f",
  "auth_time":"1367956096",
  "exp":"1368042496",
  "alv":"2",
  "iat":"1367956098",
  "iss":"https://server.example.com",
  "aud":"s6BhdRkqt3",
  "example_session_parameter":"example_value"
}

If the id_token contains the claim alv and its value is higher than "2", the id_token MUST be signed (has a signature alg value other than "none) AND validated.

All claims defined above MUST be understood before proceeding. Additional claims/parameters that are not understood MAY be ignored.

The client MUST confirm the "auth_time" is not future dated and "exp" is not a date currently in the past.

3. Privacy Considerations

Profile url values issued in the id_token and MAY be directed identifiers. In other words, the identifier/url returned is valid only for the "aud" indicated. This prevents multiple clients and non-OAuth clients from being able to gather and correlate information about individuals authenticated by the OAuth Authrization Server.

4. Acknowledgements

Thanks to members of the OAuth WG for their contributions and comments.

5. IANA Considerations

No IANA request registration is anticipated at this time.

6. Security Considerations

This draft carries the same risk profiles as those outlined in the Security Considerations for [RFC6749] and OAuth2 Threat Model [RFC6819].

7. References

7.1. Normative References

7.2. Informative References

Authors' Addresses