A Kerberos Token Translation Service for OAuth
draft-yu-oauth-token-translation-01

Abstract

This document describes a Token Translation Service that allows a site to use an existing Kerberos infrastructure to provide authentication in an OAuth 2.0 web service environment.

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 June 3, 2015.

Copyright Notice

Copyright (c) 2014 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. Requirements Language
• 3. Overview
• 4. Claim Translation
• 4.1. Principal Names
• 4.2. Timestamps
• 4.3. Addresses
• 4.4. Authorization Data
• 4.5. Example
• 5. Key Management
• 6. Security Considerations
• 7. Normative References
• Author's Address

1. Introduction

An OAuth 2.0 client and an OAuth 2.0 authorization server could be registered within the same Kerberos realm, or be registered in Kerberos realms that share a cross-realm key. The following is a description of how a site could leverage an existing Kerberos infrastructure to provide authentication in an OAuth 2.0 web service environment.

The Token Translation Service (TTS) allows an OAuth client to submit a Kerberos service ticket and receive an OAuth Proof-of-Possession token for the authorization server in return. The TTS can be integrated into the Kerberos KDC, or it can be a standalone service that has a copy of the Kerberos long-term service key of the OAuth authorization server. The latter scenario has better security properties because it uses the least amount of privilege required for providing the service.

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

3. Overview

The client submits a request to the TTS that contains the Kerberos ticket. The client need not be able to decode the Kerberos ticket itself; as long as it somehow obtains a copy of the session key from within the ticket, it can use the resulting OAuth Proof-of-Possession token without having any knowledge of Kerberos encodings.

Example request

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

  ticket=YX8wfaADAgEFoQ0bC0VYQU1QTEUuQ09N...

        

Example reply

  HTTP/1.1 200 OK
  Content-Type: application/jwt

  eyJhbGciOiJub25lIn0....

        

The client can use the resulting Proof-of-Possession token to contact the OAuth Authorization Server to receive tokens to access Resource Servers. This can involve using the OAuth Authorization Server to gain further Proof-of-Possession tokens for resource servers as described in draft-bradley-oauth-pop-key-distribution. Alternatively, the TTS could provide OAuth Access Tokens that are Proof-of-Possession tokens, and the client could use them to access the OAuth Resource Server directly using a protocol such as described in draft-ietf-oauth-signed-http-request.

4. Claim Translation

[ This section specifies a mapping between fields of a Kerberos ticket and JWT claims . Related protocols could use this mapping to translate JWT claims into Kerberos ticket fields or vice versa. ]

4.1. Principal Names

Kerberos principal names have some amount of structure, so they will generally need to be "flattened" to a single string encoding for use in JWT claims. For translating Kerberos principal names into JWT claims, the TTS SHOULD use the procedure in RFC 1964 section 2.1.3 ("Exported Name Object Form for Kerberos V5 Mechanism"). The TTS MAY provide alternative, possibly site-configured, mappings from principal names into JWT claims.

The TTS SHOULD translate the Kerberos client principal name (the cname and crealm fields of the ticket) to the JWT "sub" (subject) claim. The TTS SHOULD translate the Kerberos server principal name (the sname and realm fields of the ticket) to the JWT "aud" (audience) claim. The TTS SHOULD translate the principal name of the Ticket Granting Service (TGS) for the client's realm to the JWT "iss" (issuer) claim.

4.2. Timestamps

The ticket authtime is translated to the JWT "iat" claim. The ticket starttime is translated to the JWT "nbf" claim. The ticket endtime is translated to the JWT "exp" claim. There is no JWT claim corresponding to the ticket renew-till timestamp, so a new one would need to be registered if this attribute is to be translated.

4.3. Addresses

Embedding IP addresses in Kerberos tickets is largely obsolescent, so the JWT won't contain them. The TTS SHOULD refuse to translate Kerberos tickets that contain IP addresses in the caddr field.

4.4. Authorization Data

Translations for Kerberos authorization data will need to be configured on the TTS if needed, because there is no general way to translate Kerberos authorization data into a form that is useful to an OAuth Authorization Server. Additional specifications can define procedures for translating a given Kerberos authorization data type to JWT format.

4.5. Example

For example, a Kerberos ticket with client name (cname) "someuser" and client realm (crealm) "EXAMPLE.COM", service name (sname) "HTTP/as.example.com" and realm "EXAMPLE.COM", authtime of 20010101000000Z and endtime of 20010101100000Z, would result in a JWT containing the following fields:

   {
     "iss": "krbtgt/EXAMPLE.COM@EXAMPLE.COM",
     "sub": "someuser@EXAMPLE.COM",
     "aud": "HTTP/as.example.com@EXAMPLE.COM",
     "exp": 978343200,
     "iat": 978307200,
     "cnf": {
       "jwk": {
          "kty": "oct",
           "k": "AADerb7vyv4",
           "alg": "A128GCM"
       }
     }
   }

5. Key Management

The RFC 3961 pseudo-random function (PRF) for a given Kerberos enctype will be used to produce any symmetric keys to be used with JWE or JWS in conjunction with the resulting JWT. The input octet string for the PRF for this purpose will be "tts.jwt." with the JWK encryption algorithm name appended. At least the Kerberos session key will be translated in this way. If the JWT is encrypted using JWE, the symmetric key for that will also be derived from the long-term Kerberos key for the service in this way.

Typically, the TTS produces a JWT that is a JWE token, so the contents of the JWT are encrypted. Alternatively, the TTS could produce a plaintext JWS token, but in that case the JWK for the "cnf" claim MUST be protected using a key wrap algorithm.

6. Security Considerations

The Token Translation Service SHOULD be implemented as a standalone service that has access to the relevant individual Kerberos service principal key, rather than integrated into the Kerberos KDC. This allows the TTS to operate at the lowest privilege level required for its task, and prevents a compromise of the TTS from affecting parts of the Kerberos infrastructure that do not depend on it.

The service principal name of a Kerberos ticket is not cryptographically protected, because it is only used to locate a decryption key. In Kerberos, services are presumed to have unique, strongly random keys. If an OAuth server depends on having the "aud" claim correctly reflect the service principal, the TTS MUST ensure that the service key is unique and is correctly associated with the principal name in the "aud" claim.

7. Normative References

Author's Address