Providing User Authentication Information to OAuth 2.0 Clients

Section 4.1 of the OAuth 2.0 Authorization Framework 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 an Authentication Code Grant extension, which enables clients to request authentication of the End-User and makes information about the authentication that was performed available to the client in a standard format. This document extends the OAuth 2.0 authorization request and response messages for the Authorization Code flow to also request authentication of the End-User and to return information about the authentication performed. The interactions defined by this specification are intentionally compatible with the OpenID Connect protocol. This specification does not define a resource owner profile information API. It is assumed that other APIs such as the SCIM API or the OpenID Connect UserInfo Endpoint could be used for this purpose.

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.

This specification uses the terms "Access Token", "Authorization Code", "Authorization Endpoint", "Authorization Grant", "Authorization Server", "Client", "Client Authentication", "Client Identifier", "Client Secret", "Grant Type", "Protected Resource", "Redirection URI", "Refresh Token", "Resource Owner", "Resource Server", "Response Type", and "Token Endpoint" defined by OAuth 2.0, the terms "Claim", "Claim Name", "Claim Value", and "JSON Web Token (JWT)" defined by JSON Web Token (JWT), the term "User Agent" defined by RFC 2616. This specification also defines the following terms: OAuth 2.0 Authorization Request using extension parameters and scopes defined by this specification to request that the End-User be authenticated by the Authorization Server to the Client. Information that the Relying Party can require before it makes an entitlement decision with respect to an authentication response. Such context can include, but is not limited to, the actual authentication method used or level of assurance such as ISO/IEC 29115 entity authentication assurance level. Set of authentication methods or procedures that are considered to be equivalent to each other in a particular context. Identifier for an Authentication Context Class. Specific means by which authentication is performed. In some cases, more than one authentication method may be used for a single authentication event. Identifier for an Authentication Method. Human participant. JSON Web Token (JWT) that contains Claims about the Authentication event. It MAY contain other Claims. Entity that issues a set of Claims.

The Authentication Code Grant type is used in exactly the same manner as the Authorization Code Grant in Section 4.1 and has the same features and conditions. This specification extends the features available by making it possible for clients to test and request authentication and authorization as well as to obtain information about the authentication performed via the Authorization Code flow.

In addition to the parameters defined in Section 4.1.1, the following additional parameters are defined: 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: The authorization 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. 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. 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. OPTIONAL. Requested Authentication Context Class Reference values. Space-separated string that specifies the acr values that the Authorization Server is being requested to use for processing this Authentication Request, with the values appearing in order of preference. The Authentication Context Class satisfied by the authentication performed is returned as the acr Claim Value. OPTIONAL. Requested Authentication Method Reference values. Space-separated string that specifies the amr values that the Authorization Server is being requested to use for processing this Authentication Request, with the values appearing in order of preference. The Authentication Methods used for the authentication performed are returned as the amr Claim Value. OPTIONAL. A value of "1", "2", "3", or "4". The minimum requested authentication assurance level as defined by (see also ). The value actually achieved is returned as the alv claim value, or if no defined authentication assurance level is achieved, an alv claim SHOULD NOT be returned. When the min_alv request parameter is not used, the authorization server MAY choose any authentication assurance level or use none. OPTIONAL. A helpful text message that should be displayed to the End-User during the authentication process. [[ NOTE: It's not clear what the use case for this is or how internationalization of the string would be performed. ]] For example, the client directs the User Agent to make the following HTTP request using TLS (with extra line breaks for display purposes only):

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 The authorization server MUST: Perform the normal OAuth 2.0 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 End-User if prompt contains the parameter login, MUST obtain consent from the End-User if prompt contains the parameter consent, and MUST return an error if prompt contains none and the End-User is not currently authenticated.

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

In addition to those defined in Section 4.1.2.1, an additional error type is defined. The error value login_required MUST be returned after an authentication request parameter prompt is provided containing value none and the End-User is found to be currently unauthenticated.

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

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 with the exception that the issuance of an 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) known as an ID Token is returned using the id_token parameter containing the following claims: REQUIRED. An identifier representing the issuer of the authentication. This MAY be the authorization endpoint URL. REQUIRED. An identifier for the authenticated subject. The same identifier MUST be returned for the same authenticated End-User on the same Client ID. The authenticated End-User's sub value MAY change for different Client ID values. REQUIRED. Contains the Client ID of the client receiving the assertion as an audience value. Other audience values MAY also be present. REQUIRED. The time at which the End-User was authenticated, expressed in number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time. See for details regarding date/times in general and UTC in particular. auth_time MAY be a time earlier than when the ID Token was issued, as defined by iat. REQUIRED. The time at which the ID Token was issued, expressed in number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time. See for details regarding date/times in general and UTC in particular. REQUIRED. The time at which the ID Token expires, expressed in number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time. See for details regarding date/times in general and UTC in particular. Note that expires_in refers to the access token lifespan whereas exp refers to the ID Token lifespan. OPTIONAL. Authentication Context Class Reference. String specifying an Authentication Context Class Reference value that identifies the Authentication Context Class that the authentication performed satisfied. The value "0" indicates the End-User authentication did not meet the requirements of ISO/IEC 29115 level 1. Authentication using a long-lived browser cookie, for instance, is one example where the use of "level 0" is appropriate. An absolute URI or an RFC 6711 registered name SHOULD be used as the acr value. Parties using this claim will need to agree upon the meanings of the values used, which may be context-specific. The acr value is a case sensitive string. 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 defined Authentication Method Reference values: Password authentication, either by user or service if client_secret is used. 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. One time password. Multiple factor authentication was used. When this is used the other authentication methods will also be included. A federated authentication assertion (e.g. JWT or SAML) was used. OPTIONAL. The authentication assurance level as described by (see also ). 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 token lifetimes. [[ NOTE: This is data about the user, not about the authentication. Therefore, this should probably be accessed as a protected resource using the access token, rather than included as a claim here. ]] A non-normative example successful response with an ID Token follows (with line breaks within lines for readability):

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. eyJpc3MiOiJodHRwczovL3NlcnZlci5leGFtcGxlLmNvbSIsInN1YiI6IjVkZWRjYz hiLTczNWMtNDA1Zi1lMDI5ZiIsImF1ZCI6InM2QmhkUmtxdDMiLCJhdXRoX3RpbWUi OjEzNjc5NTYwOTYsImlhdCI6MTM2Nzk1NjA5OCwiZXhwIjoxMzY4MDQyNDk2LCJhbH YiOiIyIiwiZXhhbXBsZV9leHRlbnNpb25fcGFyYW1ldGVyIjoiZXhhbXBsZV92YWx1 ZSJ9." }

As per the JWT specification, the encoded ID Token is separated into parts by the "." character. The first part (eyJhbGciOiJub25lIn0) contains the signature algorithm and in this case decodes as: {"alg":"none"}

The claim set is then decoded as: { "iss":"https://server.example.com", "sub":"5dedcc8b-735c-405f-e029f", "aud":"s6BhdRkqt3", "auth_time":1367956096, "iat":1367956098, "exp":1368042496, "alv":"2", "example_extension_parameter":"example_value" } If the ID Token contains the claim alv and its value is higher than "2", the ID Token MUST be signed (have a signature alg value other than none) and its signature MUST be validated. All claims defined above MUST be understood before proceeding. Additional claims/parameters that are not understood MAY be ignored. The client MUST verify that the auth_time value is not future dated and exp is not a date currently in the past.