TOC 
Network Working GroupN. Sakimura
Internet-DraftNRI
Intended status: ExperimentalJ. Bradley
Expires: October 21, 2011Protiviti Government Services
 M. Jones
 Microsoft
 B. de Madeiros
 Google
 C. Mortimore
 Salesforce
 E. Jay
 MGI1
 April 19, 2011


OpenID Connect Session Management 1.0 - draft 00
draft-openid-connect-session-0_0.xml

Abstract

This document describes how to manage sessions for OpenID Connect.

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 (Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” March 1997.) [RFC2119].

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 October 21, 2011.

Copyright Notice

Copyright (c) 2011 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
2.  Terminology
3.  Session Management
    3.1.  ID Token
    3.2.  Session Management Endpoints
        3.2.1.  User Authorization
        3.2.2.  Session Refresh
        3.2.3.  Check Session
        3.2.4.  End Session
    3.3.  Error Responses
    3.4.  Session Management Flows
    3.5.  Session Synchronization
4.  Other Items for Consideration
5.  IANA Considerations
6.  Security Considerations
7.  Acknowledgements
8.  Normative References
§  Authors' Addresses




 TOC 

1.  Introduction

Sessions are used to keep track of infomation and interactions for users across multiple pages. This creates a sense of continuity, customization, and a more pleasant experience for the users. Visitors to a OpenID relying party site accessing protected resources will be asked for authentication and authorization. Upon user authorization, the user will be granted access to the requested resources. The site may perform other background tasks for the user using the same authenticated session. This allows the user to have a simplified experiene without being asked for authorization each time and may even allow the user to go off-line while the tasks are being performed. This specification describes how OpenID Connect sessions can be created, used, and terminaed.



 TOC 

2.  Terminology

Client
An application obtaining authorization and making protected resource requests.
End-user
A human resource owner.
OpenID Provider (OP)
Authorization Servers that are able to support OpenID Connect Messages.
Relying Party (RP)
Client and Resource Servers.
End-User Authorization Endpoint
The Authorization Server's endpoint capable of authenticating the End-User and obtaining authorization.
Client Identifier
An unique identifier that the client uses to identify itself to the OP.
Token Endpoint
The Authorization Server's HTTP endpoint capable of issuing tokens.
OP Endpoints
End-User Authentication, Authorization, and Token Endpoint.
RP Endpoints
The endpoint to which the OP responses are returned through redirect.
UserInfo Endpoint
A protected resource that when presented with a token by the client returns authorized information about the current user.
Identifier
An Identifier is either a "http" or "https" URI, (commonly referred to as a "URL" within this document), or an account URI. This document defines various kinds of Identifiers, designed for use in different contexts.
ID Token
A JWS signed claim that attest to the identity of the user, intended audience, and the issuer of the claim. The signed claim uses compact serialization.
Get ID Token Endpoint
The endpoint where an ID Token is retrieved.


 TOC 

3.  Session Management



 TOC 

3.1.  ID Token

An ID Token is a JWS signed claim that attests to the following:

issuer
The issuer of the claim
client_id
The identifier of the client initiating the request.
audience
The identifier or client_id of the intended recipient of the response.
id
The identifier of the user.
exp
The expiration time of the token after which it is no longer valid. It is the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the desired date/time. See RFC 3339 (Klyne, G., Ed. and C. Newman, “Date and Time on the Internet: Timestamps,” July 2002.) [RFC3339] for more information.

The ID Token may contain other claims. The ID Token can be used as a session cookie to access session information from an authenticated session or to pass a session to other applications.



 TOC 

3.2.  Session Management Endpoints

To manage a session, the client sends a request to the session management endpoints at the authorization server. The session management endpoints at the authorization server are:

User Authorization
Initiates user authorization and retrieves access token and ID Token.
Session Refresh
Refreshes an expired ID Token
Check Session
Get a plain text JSON structure from a ID Token
End Session
Ends a session

The sequences for session management are as follows:



 TOC 

3.2.1.  User Authorization

The user sends an authorization request to the OpenID user authorization endpoint. This is a OpenID authorization request. After user authorization, the server returns an access token and an ID Token, the latter of which may be used as a session cookie.

The following is a non-normative authorization request:

Request:

GET /authorize?scope=openid&response_type=token
&openid.type=http%3A%2F%2Fopenid.net%2Fspecs%2Fcc%2F1.0%2F%23req
&client_id=s6BhdRkqt3&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb HTTP/1.1
Host: server.example.com

...
   Authorization server displays UI for login
   ...
   User performs successful login and authorization
...


Response:

HTTP/1.1 302 Found
Location: http://client.example.com/cb?access_token=FJQbwq9&expires_in=3600&id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiIsImtpZCI6ImNsaWVudC5leGFtcGxlLmNvbSJ9.eyJpc3N1ZXIiOiJodHRwOlwvXC9zZXJ2ZXIuZXhhbXBsZS5jb20iLCJjbGllbnRfaWQiOiJjbGllbnQuZXhhbXBsZS5jb20iLCJhdWRpZW5jZSI6ImNsaWVudC5leGFtcGxlLmNvbSIsImlkIjoidXNlcl8yMzQyMzQiLCJleHAiOjEzMDM4NTI3MzJ9.Vdj-sU3xxwHRd9rF6gjBTw3YMm1BqmT43fGDCpa96jo


 TOC 

3.2.2.  Session Refresh

To refresh a ID Token session that has expired, the client sends a request to the Refresh Session endpoint with an ID Token. A new ID Token is returned in JWS signed format.

Request Parameters:

id_token
REQUIRED. A previously issued ID Token from a session request
state
REQUIRED. An opaque value used by the Client to maintain state between the request and callback. If provided, the Authorization Server MUST include this value when redirecting the user-agent back to the Client. Clients are strongly advised to use this variable to relate the request and response.
redirect_uri
REQUIRED. An absolute URI to which the authorization server will redirect the user-agent to with the new ID Token.

Response:

The response is a HTTP 302 redirect to the specified redirect_uri in the request with a new ID Token.

id_token
A new ID Token

The following is a non-normative session refresh request:

Request:

GET /op/refresh_token?id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiIsImtpZCI6ImNsaWVudC5leGFtcGxlLmNvbSJ9.eyJpc3N1ZXIiOiJodHRwOlwvXC9zZXJ2ZXIuZXhhbXBsZS5jb20iLCJjbGllbnRfaWQiOiJjbGllbnQuZXhhbXBsZS5jb20iLCJhdWRpZW5jZSI6ImNsaWVudC5leGFtcGxlLmNvbSIsImlkIjoidXNlcl8yMzQyMzQiLCJleHAiOjEzMDM4NTI3MzJ9.Vdj-sU3xxwHRd9rF6gjBTw3YMm1BqmT43fGDCpa96jo
&state=bar&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fidtoken_cb
Host: server.example.com

Response:

HTTP/1.1 302 OK
Location: http://client.example.com/idtoken_cb?id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiIsImtpZCI6ImNsaWVudC5leGFtcGxlLmNvbSJ9.eyJpc3N1ZXIiOiJodHRwOlwvXC9zZXJ2ZXIuZXhhbXBsZS5jb20iLCJjbGllbnRfaWQiOiJjbGllbnQuZXhhbXBsZS5jb20iLCJhdWRpZW5jZSI6ImNsaWVudC5leGFtcGxlLmNvbSIsImlkIjoidXNlcl8yMzQyMzQiLCJleHAiOjEzMDM4NTI4ODB9.aJwagC6501Da-zK-X8Az9B-Y625aSEfxVuBpFEDjOxQ&state=bar&expires_in=3600



 TOC 

3.2.3.  Check Session

For clients that are not capable of dealing with JWS signed ID Tokens, they can send the ID Token to the Check Session endpoint. It will validate the ID Token and return a plain text JSON structure of the ID Token.

Request Parameters:

id_token
REQUIRED. A previously issued ID Token from a session request

Response:

The response is a HTTP 200 response code with the content-type header set to "application/json". The response body is a plain text JSON structure of the base64url decoded payload of the signed ID Token.

The following is a non-normative example of a check session request:

Request:
POST /op/check_id_token?id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiIsImtpZCI6ImNsaWVudC5leGFtcGxlLmNvbSJ9.eyJpc3N1ZXIiOiJodHRwOlwvXC9zZXJ2ZXIuZXhhbXBsZS5jb20iLCJjbGllbnRfaWQiOiJjbGllbnQuZXhhbXBsZS5jb20iLCJhdWRpZW5jZSI6ImNsaWVudC5leGFtcGxlLmNvbSIsImlkIjoidXNlcl8yMzQyMzQiLCJleHAiOjEzMDM4NTI4ODB9.aJwagC6501Da-zK-X8Az9B-Y625aSEfxVuBpFEDjOxQ

Response:
HTTP/1.1 200 OK
Content-Type: application/json

{
  "issuer":"http://server.example.com",
  "client_id","http://client.example.com",
  "audience", "http://client.example.com",
  "id":"user_328723",
  "exp":1303852880,
}




 TOC 

3.2.4.  End Session

Send a ID Token to the End Session endpoint to terminate a session. Upon receiving the request, the authorization server performs the logout flow for the user and then redirects the user-agent to the specified redirect_uri.

Request Parameters:

id_token
REQUIRED. A previously issued ID Token from a session request
state
REQUIRED. An opaque value used by the Client to maintain state between the request and callback. If provided, the Authorization Server MUST include this value when redirecting the user-agent back to the Client. Clients are strongly advised to use this variable to relate the request and response.
redirect_uri
REQUIRED. An absolute URI to which the authorization server will redirect the user-agent to with the new ID Token.

Response:

The response is a HTTP 302 redirect response to the redirect_uri specified in the request.

The following is a non-normative session refresh request:

Request:

GET /op/end_session?id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiIsImtpZCI6ImNsaWVudC5leGFtcGxlLmNvbSJ9.eyJpc3N1ZXIiOiJodHRwOlwvXC9zZXJ2ZXIuZXhhbXBsZS5jb20iLCJjbGllbnRfaWQiOiJjbGllbnQuZXhhbXBsZS5jb20iLCJhdWRpZW5jZSI6ImNsaWVudC5leGFtcGxlLmNvbSIsImlkIjoidXNlcl8yMzQyMzQiLCJleHAiOjEzMDM4NTI4ODB9.aJwagC6501Da-zK-X8Az9B-Y625aSEfxVuBpFEDjOxQ&state=bar&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fendtoken_cb
Host: server.example.com

...
   Authorizion server performs logout flow
...

Response:

HTTP/1.1 302 OK
Location: http://client.example.com/endtoken_cb?state=bar



 TOC 

3.3.  Error Responses

In cases of error, the authorization server returns a HTTP 400 status code with the error descriptions in the response body. The response media-type is set as "application/json" and the response body contains the error descriptions in a JSON structure.

error
REQUIRED. A single error code which can be the following:
invalid_access_token - The access token is invalid.
invalid_id_token - The ID Token is invalid.
invalid_signature - The signature of the ID Token is invalid.
error_description
OPTIONAL. A text description which describes the error in more detail.


 TOC 

3.4.  Session Management Flows

There following various ways that session management can be used:

User-agent
This flow is suitable for use by web browsers. Session management is used exactly as described above.
Web Server
This flow is suitable for use by a web server. The server obtains an ID Token together with an access token at the access token endpoint in exchange for an authorization code or refresh token.
Native Application
This flow is used by native applications. It is similar to the web server flow except that the audience for the ID Token may be a fourth party such as a client servlet. The audience for the ID token should be explicitly specified in the authorization request using a "login" parameter.
Native Application - Browser Load
This is suitable for native applications that want to start an authenticated browser session for the same user. The native application starts the browser with the client servlet location and an ID Token as a parameter. The client servlet immediately requests a new ID Token at the Refresh Session Endpoint.


 TOC 

3.5.  Session Synchronization

If the client obtains an ID Token either by (a) receiving it together with the access_token in the end-user authorization response; or (b) redeeming an authorization code; or (c) by renewing an existing id_token, then the resulting ID Token is synchronized with the user's session at the authorization server. If the ID Token is obtained as a result of using a refresh token, then this ID Token is not bound to a session because the accompanying access token is used by a web server or native application and the user may have gone off-line after giving authorization.



 TOC 

4.  Other Items for Consideration



 TOC 

5.  IANA Considerations

This document makes no request of IANA.

Note to RFC Editor: this section may be removed on publication as an RFC.



 TOC 

6.  Security Considerations



 TOC 

7.  Acknowledgements



 TOC 

8. Normative References

[JWS] Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, “JSON Web Signatures,” March 2011.
[JWT] Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, “JSON Web Token,” March 2011.
[OpenID.2.0] specs@openid.net, “OpenID Authentication 2.0,” 2007 (TXT, HTML).
[OpenID.AB] Sakimura, N., Ed., Bradley, J., de Madeiros, B., Ito, R., and M. Jones, “OpenID Connect Artifact Binding 1.0,” January 2011.
[OpenID.CC] Recordon, D., Sakimura, N., Bradley, J., de Madeiros, B., and M. Jones, “OpenID Connect Connect Core 1.0,” January 2011.
[RFC2119] Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” BCP 14, RFC 2119, March 1997 (TXT, HTML, XML).
[RFC3339] Klyne, G., Ed. and C. Newman, “Date and Time on the Internet: Timestamps,” RFC 3339, July 2002 (TXT, HTML, XML).
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, “Uniform Resource Identifier (URI): Generic Syntax,” STD 66, RFC 3986, January 2005 (TXT, HTML, XML).
[RFC4627] Crockford, D., “The application/json Media Type for JavaScript Object Notation (JSON),” RFC 4627, July 2006 (TXT).
[SWD] Jones, M., Ed. and Y. Goland, “Simple Web Discovery,” October 2010.
[XRI_Syntax_2.0] Reed, D. and D. McAlpin, “Extensible Resource Identifier (XRI) Syntax V2.0,” November 2005 (HTML, PDF).


 TOC 

Authors' Addresses

  Nat Sakimura
  Nomura Research Institute, Ltd.
Email:  n-sakimura@nri.co.jp
  
  John Bradley
  Protiviti Government Services
Email:  jbradley@mac.com
  
  Mike Jones
  Microsoft Corporation
Email:  Michael.Jones@microsoft.com
  
  Breno de Madeiros
  Google
Email:  breno@google.com
  
  Chuck Mortimore
  Salesforce
Email:  cmortimore@salesforce.com
  
  Edmund Jay
  MGI1
Email:  ejay@mgi1.com