idnits 2.17.1 draft-yu-oauth-token-translation-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (November 30, 2014) is 3434 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Unused Reference: 'I-D.ietf-jose-json-web-algorithms' is defined on line 226, but no explicit reference was found in the text == Unused Reference: 'I-D.ietf-jose-json-web-encryption' is defined on line 230, but no explicit reference was found in the text == Unused Reference: 'I-D.ietf-jose-json-web-key' is defined on line 235, but no explicit reference was found in the text == Unused Reference: 'I-D.ietf-jose-json-web-signature' is defined on line 239, but no explicit reference was found in the text == Unused Reference: 'I-D.ietf-oauth-json-web-token' is defined on line 244, but no explicit reference was found in the text == Unused Reference: 'RFC1964' is defined on line 249, but no explicit reference was found in the text == Unused Reference: 'RFC3961' is defined on line 255, but no explicit reference was found in the text == Unused Reference: 'RFC4120' is defined on line 258, but no explicit reference was found in the text == Outdated reference: A later version (-40) exists of draft-ietf-jose-json-web-algorithms-31 == Outdated reference: A later version (-40) exists of draft-ietf-jose-json-web-encryption-31 == Outdated reference: A later version (-41) exists of draft-ietf-jose-json-web-key-31 == Outdated reference: A later version (-41) exists of draft-ietf-jose-json-web-signature-31 == Outdated reference: A later version (-32) exists of draft-ietf-oauth-json-web-token-25 Summary: 1 error (**), 0 flaws (~~), 14 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group T. Yu 3 Internet-Draft MIT-KIT 4 Intended status: Standards Track November 30, 2014 5 Expires: June 3, 2015 7 A Kerberos Token Translation Service for OAuth 8 draft-yu-oauth-token-translation-01 10 Abstract 12 This document describes a Token Translation Service that allows a 13 site to use an existing Kerberos infrastructure to provide 14 authentication in an OAuth 2.0 web service environment. 16 Status of This Memo 18 This Internet-Draft is submitted in full conformance with the 19 provisions of BCP 78 and BCP 79. 21 Internet-Drafts are working documents of the Internet Engineering 22 Task Force (IETF). Note that other groups may also distribute 23 working documents as Internet-Drafts. The list of current Internet- 24 Drafts is at http://datatracker.ietf.org/drafts/current/. 26 Internet-Drafts are draft documents valid for a maximum of six months 27 and may be updated, replaced, or obsoleted by other documents at any 28 time. It is inappropriate to use Internet-Drafts as reference 29 material or to cite them other than as "work in progress." 31 This Internet-Draft will expire on June 3, 2015. 33 Copyright Notice 35 Copyright (c) 2014 IETF Trust and the persons identified as the 36 document authors. All rights reserved. 38 This document is subject to BCP 78 and the IETF Trust's Legal 39 Provisions Relating to IETF Documents 40 (http://trustee.ietf.org/license-info) in effect on the date of 41 publication of this document. Please review these documents 42 carefully, as they describe your rights and restrictions with respect 43 to this document. Code Components extracted from this document must 44 include Simplified BSD License text as described in Section 4.e of 45 the Trust Legal Provisions and are provided without warranty as 46 described in the Simplified BSD License. 48 Table of Contents 50 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 51 2. Requirements Language . . . . . . . . . . . . . . . . . . . . 2 52 3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 2 53 4. Claim Translation . . . . . . . . . . . . . . . . . . . . . . 3 54 4.1. Principal Names . . . . . . . . . . . . . . . . . . . . . 3 55 4.2. Timestamps . . . . . . . . . . . . . . . . . . . . . . . 4 56 4.3. Addresses . . . . . . . . . . . . . . . . . . . . . . . . 4 57 4.4. Authorization Data . . . . . . . . . . . . . . . . . . . 4 58 4.5. Example . . . . . . . . . . . . . . . . . . . . . . . . . 4 59 5. Key Management . . . . . . . . . . . . . . . . . . . . . . . 5 60 6. Security Considerations . . . . . . . . . . . . . . . . . . . 5 61 7. Normative References . . . . . . . . . . . . . . . . . . . . 5 62 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 6 64 1. Introduction 66 An OAuth 2.0 client and an OAuth 2.0 authorization server could be 67 registered within the same Kerberos realm, or be registered in 68 Kerberos realms that share a cross-realm key. The following is a 69 description of how a site could leverage an existing Kerberos 70 infrastructure to provide authentication in an OAuth 2.0 web service 71 environment. 73 The Token Translation Service (TTS) allows an OAuth client to submit 74 a Kerberos service ticket and receive an OAuth Proof-of-Possession 75 token for the authorization server in return. The TTS can be 76 integrated into the Kerberos KDC, or it can be a standalone service 77 that has a copy of the Kerberos long-term service key of the OAuth 78 authorization server. The latter scenario has better security 79 properties because it uses the least amount of privilege required for 80 providing the service. 82 2. Requirements Language 84 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 85 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 86 document are to be interpreted as described in RFC 2119 [RFC2119]. 88 3. Overview 90 The client submits a request to the TTS that contains the Kerberos 91 ticket. The client need not be able to decode the Kerberos ticket 92 itself; as long as it somehow obtains a copy of the session key from 93 within the ticket, it can use the resulting OAuth Proof-of-Possession 94 token without having any knowledge of Kerberos encodings. 96 Example request 98 POST /tts HTTP/1.1 99 Host: www.example.com 100 Content-Type: application/x-www-form-urlencoded 102 ticket=YX8wfaADAgEFoQ0bC0VYQU1QTEUuQ09N... 104 Example reply 106 HTTP/1.1 200 OK 107 Content-Type: application/jwt 109 eyJhbGciOiJub25lIn0.... 111 The client can use the resulting Proof-of-Possession token to contact 112 the OAuth Authorization Server to receive tokens to access Resource 113 Servers. This can involve using the OAuth Authorization Server to 114 gain further Proof-of-Possession tokens for resource servers as 115 described in draft-bradley-oauth-pop-key-distribution. 116 Alternatively, the TTS could provide OAuth Access Tokens that are 117 Proof-of-Possession tokens, and the client could use them to access 118 the OAuth Resource Server directly using a protocol such as described 119 in draft-ietf-oauth-signed-http-request. 121 4. Claim Translation 123 [ This section specifies a mapping between fields of a Kerberos 124 ticket and JWT claims . Related protocols could use this mapping to 125 translate JWT claims into Kerberos ticket fields or vice versa. ] 127 4.1. Principal Names 129 Kerberos principal names have some amount of structure, so they will 130 generally need to be "flattened" to a single string encoding for use 131 in JWT claims. For translating Kerberos principal names into JWT 132 claims, the TTS SHOULD use the procedure in RFC 1964 section 2.1.3 133 ("Exported Name Object Form for Kerberos V5 Mechanism"). The TTS MAY 134 provide alternative, possibly site-configured, mappings from 135 principal names into JWT claims. 137 The TTS SHOULD translate the Kerberos client principal name (the 138 cname and crealm fields of the ticket) to the JWT "sub" (subject) 139 claim. The TTS SHOULD translate the Kerberos server principal name 140 (the sname and realm fields of the ticket) to the JWT "aud" 141 (audience) claim. The TTS SHOULD translate the principal name of the 142 Ticket Granting Service (TGS) for the client's realm to the JWT "iss" 143 (issuer) claim. 145 4.2. Timestamps 147 The ticket authtime is translated to the JWT "iat" claim. The ticket 148 starttime is translated to the JWT "nbf" claim. The ticket endtime 149 is translated to the JWT "exp" claim. There is no JWT claim 150 corresponding to the ticket renew-till timestamp, so a new one would 151 need to be registered if this attribute is to be translated. 153 4.3. Addresses 155 Embedding IP addresses in Kerberos tickets is largely obsolescent, so 156 the JWT won't contain them. The TTS SHOULD refuse to translate 157 Kerberos tickets that contain IP addresses in the caddr field. 159 4.4. Authorization Data 161 Translations for Kerberos authorization data will need to be 162 configured on the TTS if needed, because there is no general way to 163 translate Kerberos authorization data into a form that is useful to 164 an OAuth Authorization Server. Additional specifications can define 165 procedures for translating a given Kerberos authorization data type 166 to JWT format. 168 4.5. Example 170 For example, a Kerberos ticket with client name (cname) "someuser" 171 and client realm (crealm) "EXAMPLE.COM", service name (sname) "HTTP/ 172 as.example.com" and realm "EXAMPLE.COM", authtime of 20010101000000Z 173 and endtime of 20010101100000Z, would result in a JWT containing the 174 following fields: 176 { 177 "iss": "krbtgt/EXAMPLE.COM@EXAMPLE.COM", 178 "sub": "someuser@EXAMPLE.COM", 179 "aud": "HTTP/as.example.com@EXAMPLE.COM", 180 "exp": 978343200, 181 "iat": 978307200, 182 "cnf": { 183 "jwk": { 184 "kty": "oct", 185 "k": "AADerb7vyv4", 186 "alg": "A128GCM" 187 } 188 } 189 } 191 5. Key Management 193 The RFC 3961 pseudo-random function (PRF) for a given Kerberos 194 enctype will be used to produce any symmetric keys to be used with 195 JWE or JWS in conjunction with the resulting JWT. The input octet 196 string for the PRF for this purpose will be "tts.jwt." with the JWK 197 encryption algorithm name appended. At least the Kerberos session 198 key will be translated in this way. If the JWT is encrypted using 199 JWE, the symmetric key for that will also be derived from the long- 200 term Kerberos key for the service in this way. 202 Typically, the TTS produces a JWT that is a JWE token, so the 203 contents of the JWT are encrypted. Alternatively, the TTS could 204 produce a plaintext JWS token, but in that case the JWK for the "cnf" 205 claim MUST be protected using a key wrap algorithm. 207 6. Security Considerations 209 The Token Translation Service SHOULD be implemented as a standalone 210 service that has access to the relevant individual Kerberos service 211 principal key, rather than integrated into the Kerberos KDC. This 212 allows the TTS to operate at the lowest privilege level required for 213 its task, and prevents a compromise of the TTS from affecting parts 214 of the Kerberos infrastructure that do not depend on it. 216 The service principal name of a Kerberos ticket is not 217 cryptographically protected, because it is only used to locate a 218 decryption key. In Kerberos, services are presumed to have unique, 219 strongly random keys. If an OAuth server depends on having the "aud" 220 claim correctly reflect the service principal, the TTS MUST ensure 221 that the service key is unique and is correctly associated with the 222 principal name in the "aud" claim. 224 7. Normative References 226 [I-D.ietf-jose-json-web-algorithms] 227 Jones, M., "JSON Web Algorithms (JWA)", draft-ietf-jose- 228 json-web-algorithms-31 (work in progress), July 2014. 230 [I-D.ietf-jose-json-web-encryption] 231 Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", 232 draft-ietf-jose-json-web-encryption-31 (work in progress), 233 July 2014. 235 [I-D.ietf-jose-json-web-key] 236 Jones, M., "JSON Web Key (JWK)", draft-ietf-jose-json-web- 237 key-31 (work in progress), July 2014. 239 [I-D.ietf-jose-json-web-signature] 240 Jones, M., Bradley, J., and N. Sakimura, "JSON Web 241 Signature (JWS)", draft-ietf-jose-json-web-signature-31 242 (work in progress), July 2014. 244 [I-D.ietf-oauth-json-web-token] 245 Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 246 (JWT)", draft-ietf-oauth-json-web-token-25 (work in 247 progress), July 2014. 249 [RFC1964] Linn, J., "The Kerberos Version 5 GSS-API Mechanism", RFC 250 1964, June 1996. 252 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 253 Requirement Levels", BCP 14, RFC 2119, March 1997. 255 [RFC3961] Raeburn, K., "Encryption and Checksum Specifications for 256 Kerberos 5", RFC 3961, February 2005. 258 [RFC4120] Neuman, C., Yu, T., Hartman, S., and K. Raeburn, "The 259 Kerberos Network Authentication Service (V5)", RFC 4120, 260 July 2005. 262 Author's Address 264 Tom Yu 265 MIT Consortium for Kerberos and Internet Trust 267 Email: tlyu@mit.edu