idnits 2.17.1 draft-wdenniss-oauth-device-posture-00.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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (March 11, 2017) is 2597 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: 'RFC6819' is defined on line 364, but no explicit reference was found in the text ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) Summary: 1 error (**), 0 flaws (~~), 2 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 OAuth Working Group W. Denniss 3 Internet-Draft Google 4 Intended status: Standards Track March 11, 2017 5 Expires: September 12, 2017 7 OAuth 2.0 Device Posture Signals 8 draft-wdenniss-oauth-device-posture-00 10 Abstract 12 Enterprise and security focused OAuth providers typically want 13 additional signals to confirm user presence when users return to 14 previously authorized apps. Rather than requiring a full 15 reauthentication, or require enrollment in a mobile device management 16 solution, some authorization servers may be willing to accept device 17 posture signals from the app, like the fact that device has a lock 18 screen, as confirmation of user presence. This document details how 19 OAuth native app clients can communicate device posture signals to 20 OAuth providers. 22 Status of This Memo 24 This Internet-Draft is submitted in full conformance with the 25 provisions of BCP 78 and BCP 79. 27 Internet-Drafts are working documents of the Internet Engineering 28 Task Force (IETF). Note that other groups may also distribute 29 working documents as Internet-Drafts. The list of current Internet- 30 Drafts is at http://datatracker.ietf.org/drafts/current/. 32 Internet-Drafts are draft documents valid for a maximum of six months 33 and may be updated, replaced, or obsoleted by other documents at any 34 time. It is inappropriate to use Internet-Drafts as reference 35 material or to cite them other than as "work in progress." 37 This Internet-Draft will expire on September 12, 2017. 39 Copyright Notice 41 Copyright (c) 2017 IETF Trust and the persons identified as the 42 document authors. All rights reserved. 44 This document is subject to BCP 78 and the IETF Trust's Legal 45 Provisions Relating to IETF Documents 46 (http://trustee.ietf.org/license-info) in effect on the date of 47 publication of this document. Please review these documents 48 carefully, as they describe your rights and restrictions with respect 49 to this document. Code Components extracted from this document must 50 include Simplified BSD License text as described in Section 4.e of 51 the Trust Legal Provisions and are provided without warranty as 52 described in the Simplified BSD License. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 57 2. Notational Conventions . . . . . . . . . . . . . . . . . . . 3 58 3. Device Posture Signal Dictionary . . . . . . . . . . . . . . 3 59 4. Authorization Request Device Posture Hint . . . . . . . . . . 3 60 5. Token Endpoint Device Posture Enforcement . . . . . . . . . . 4 61 6. Security Considerations . . . . . . . . . . . . . . . . . . . 5 62 6.1. Device Posture Scope . . . . . . . . . . . . . . . . . . 5 63 6.2. Spoofed Devices . . . . . . . . . . . . . . . . . . . . . 5 64 6.3. App Trustworthiness . . . . . . . . . . . . . . . . . . . 5 65 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 5 66 7.1. OAuth Parameters Registration . . . . . . . . . . . . . . 5 67 7.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 6 68 7.2. OAuth Extensions Error Registration . . . . . . . . . . . 6 69 7.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 6 70 7.3. Device Posture Keys Registry . . . . . . . . . . . . . . 6 71 7.3.1. Registration Template . . . . . . . . . . . . . . . . 7 72 7.3.2. Initial Registry Contents . . . . . . . . . . . . . . 7 73 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 8 74 8.1. Normative References . . . . . . . . . . . . . . . . . . 8 75 8.2. Informative References . . . . . . . . . . . . . . . . . 8 76 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 8 77 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 9 79 1. Introduction 81 Users who follow strong security practices on their devices - such as 82 configuring screen locks, and not enabling admin privileges (commonly 83 known as "rooting" or "jailbreaking") - shouldn't need to 84 reauthenticate frequently to the individual apps on their device. 86 This specification details how apps can send device posture signals 87 to the OAuth Token Endpoint, enabling it to enforce device policy 88 compliance, and avoid the need for reauthentication in some cases. 90 It is designed to provide a mechanism for honest apps to communicate 91 device posture. By itself it doesn't protect against malicious 92 users, dishonest apps, or compromised devices, but the signal format 93 described could carry signals that do. 95 2. Notational Conventions 97 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 98 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 99 "OPTIONAL" in this document are to be interpreted as described in Key 100 words for use in RFCs to Indicate Requirement Levels [RFC2119]. If 101 these words are used without being spelled in uppercase then they are 102 to be interpreted with their normal natural language meanings. 104 3. Device Posture Signal Dictionary 106 The device posture is a dictionary of signals asserted by the app 107 about the device. The structure is send as an added parameter in 108 several places during the OAuth flow, as documented in the subsequent 109 sections. 111 All device posture keys are OPTIONAL and MUST only be set when the 112 attribute can be obtained by the app. The standard attribute keys 113 are as follows: 115 screen_lock 116 Boolean. True if the user has a screen lock, such as a pin, 117 pattern biometric, etc. 118 root_privileges 119 Boolean. True if user apps can access root device privileges. 120 For mobile operating systems, known as "jailbreaking" on iOS and 121 "rooting" on Android. 122 device_attestation 123 Dictionary. An attestation from the operating system, containing 124 a signed-statement about the device and/or the app. The format is 125 a dictionary, the specifics of which depends on the operating 126 system. 128 An example device posture dictionary: 130 { 131 "screen_lock": true, 132 "root_privileges": false 133 } 135 4. Authorization Request Device Posture Hint 137 Clients MAY send the device posture signal dictionary to the 138 authorization server in the authorization request. These signals, 139 except for those that are signed and bound to the device are 140 susceptible to client-side modification by end-users. While 141 untrusted, such signals can still be used as hints by the 142 authorization server to present a better user experience, like 143 informing the user they need a lock screen. 145 Error encountered during authorization can be displayed to the user 146 in the browser making this a more user friendly way to instruct the 147 user on how to move their device into conformance. The token 148 endpoint (on which errors are less user-friendly as there's no user 149 agent), can then enforce the restrictions per Section 5. 151 The following parameters are added to the OAuth 2.0 Authorization 152 Request: 154 device_posture_hint 155 JSON String. URL-encoded JSON dictionary, contains the Device 156 Posture Signals defined in Section 3. 158 5. Token Endpoint Device Posture Enforcement 160 Clients that follow this specification MUST send the device posture 161 signals on every request to the token endpoint. 163 Token Endpoints SHOULD verify that the posture conforms to their 164 requirements and act accordingly. 166 The following parameters are added to all requests to the Token 167 Endpoint: 169 device_posture 170 JSON String. URL-encoded JSON dictionary, contains the Device 171 Posture Signals defined in Section 3. 173 The app MUST obtain fresh device posture information before every 174 request to the Token Endpoint, and MUST NOT include stale information 175 (rather, it should drop any signals it cannot freshly obtain). 177 For token refresh requests, where the device posture has been 178 previously communicated, if an attribute is missing, the Token 179 Endpoint may choose to use the previous value, based on it's own 180 policy and freshness requirements. 182 If the policy does not meet requirements, the Token Endpoint SHOULD 183 return the following error code: 185 device_posture_invalid 186 Error indicating that the device posture does not meet 187 requirements. The error description SHOULD contain details on why 188 this is is the case. 190 6. Security Considerations 192 6.1. Device Posture Scope 194 This specification is designed to help authorization servers enforce 195 security policy (like requiring a lock screen) on end-users. The 196 intent is to enforce restrictions on honest users, to force them to 197 follow security practices set out by the authorization server. By 198 itself, it offers no protection against malicious users, dishonest 199 apps, or compromised devices. 201 Combined with other technologies like device-based attestations and 202 token binding may enable such protection, and this specification 203 could be used to transmit secure signals, but that topic is out of 204 scope for this specification. 206 6.2. Spoofed Devices 208 It is possible to at a device level completely spoof the device 209 posture. Even statements signed by the operating system are 210 vulnerable to spoofing, as it's possible a statement from the real 211 device can be replayed on a spoofed device, unless such statements 212 include a binding to the device itself. Per Section 6.1, this topic 213 is out of scope for this specification. 215 6.3. App Trustworthiness 217 This specification is designed to allow trusted apps to report device 218 posture to the authorization server to help the server enforce 219 security policy on end-users. It does not by itself force apps to be 220 honest, or genuine. Genuine apps (i.e. apps not lying about their 221 client ID) might be dishonest about the device posture, and apps that 222 are normally honest, could be spoofed, unless anti-spoofing 223 countermeasures that are out of scope of this specification are 224 employed. 226 7. IANA Considerations 228 7.1. OAuth Parameters Registration 230 This specification registers the following value in the IANA "OAuth 231 Parameters" registry [IANA.OAuth.Parameters] established by 232 [RFC6749]. 234 7.1.1. Registry Contents 236 o Parameter name: device_posture_hint 237 o Parameter usage location: authorization request 238 o Change controller: IESG 239 o Specification document(s): Section 4 of [[ this specification ]] 241 o Parameter name: device_posture 242 o Parameter usage location: token request 243 o Change controller: IESG 244 o Specification document(s): Section 5 of [[ this specification ]] 246 7.2. OAuth Extensions Error Registration 248 This specification registers the following error in the IANA "OAuth 249 Extensions Error Registry" [IANA.OAuth.Parameters] established by 250 [RFC6749]. 252 7.2.1. Registry Contents 254 o Error name: device_posture_invalid 255 o Error usage location: authorization response, token error response 256 o Related protocol extension: resource parameter 257 o Change controller: IESG 258 o Specification document(s): Section 5 of [[ this specification ]] 260 7.3. Device Posture Keys Registry 262 This specification establishes the IANA "Device Posture Keys" 263 registry for Device Posture Dictionary keys. The registry records 264 the Device Posture key and a reference to the specification that 265 defines it. This specification registers the Device Posture keys 266 defined in Section 3. 268 Keys are registered on an Expert Review [RFC5226] basis after a 269 three-week review period on the oauth-reg-review@ietf.org mailing 270 list, on the advice of one or more Designated Experts. 272 Registration requests sent to the mailing list for review should use 273 an appropriate subject (e.g., "Request to register Device Posture 274 Key: screen_lock"). 276 Within the review period, the Designated Experts will either approve 277 or deny the registration request, communicating this decision to the 278 review list and IANA. Denials should include an explanation and, if 279 applicable, suggestions as to how to make the request successful. 280 Registration requests that are undetermined for a period longer than 281 21 days can be brought to the IESG's attention (using the 282 iesg@ietf.org mailing list) for resolution. 284 Criteria that should be applied by the Designated Experts includes 285 determining whether the proposed registration duplicates existing 286 functionality, whether it is likely to be of general applicability or 287 whether it is useful only for a single application, whether the value 288 is actually being used, and whether the registration description is 289 clear. 291 IANA must only accept registry updates from the Designated Experts 292 and should direct all requests for registration to the review mailing 293 list. 295 It is suggested that the same Designated Experts evaluate these 296 registration requests as those who evaluate registration requests for 297 the IANA "OAuth Parameters" registry [IANA.OAuth.Parameters]. 299 7.3.1. Registration Template 301 Device Posture Signal Key: 302 The key name requested (e.g., "screen_lock"). Names may not match 303 other registered names in a case-insensitive manner unless the 304 Designated Experts state that there is a compelling reason to 305 allow an exception. 306 Device Posture Signal Key Description: 307 Brief description of the device posture signal (e.g., "Screen lock 308 active"). 309 Change Controller: 310 For Standards Track RFCs, state "IESG". For others, give the name 311 of the responsible party. Other details (e.g., postal address, 312 email address, home page URI) may also be included. 313 Specification Document(s): 314 Reference to the document or documents that specify the parameter, 315 preferably including URIs that can be used to retrieve copies of 316 the documents. An indication of the relevant sections may also be 317 included but is not required. 319 7.3.2. Initial Registry Contents 321 o Device Posture Signal Key: "screen_lock" 322 o Device Posture Signal Key Description: Boolean. 'true' when the 323 device has a screen lock enabled. 324 o Change Controller: IESG 325 o Specification Document(s): Section 3 of [[ this specification ]] 327 o Device Posture Signal Key: "root_privileges" 328 o Device Posture Signal Key Description: Boolean. True if user apps 329 can access root device privileges. 330 o Change Controller: IESG 331 o Specification Document(s): Section 3 of [[ this specification ]] 333 o Device Posture Signal Key: "device_attestation" 334 o Device Posture Signal Key Description: Dictionary. An attestation 335 from the operating system, containing a signed-statement about the 336 device and/or the app. 337 o Change Controller: IESG 338 o Specification Document(s): Section 3 of [[ this specification ]] 340 8. References 342 8.1. Normative References 344 [IANA.OAuth.Parameters] 345 IANA, "OAuth Parameters", 346 . 348 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 349 Requirement Levels", BCP 14, RFC 2119, 350 DOI 10.17487/RFC2119, March 1997, 351 . 353 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 354 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 355 DOI 10.17487/RFC5226, May 2008, 356 . 358 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 359 RFC 6749, DOI 10.17487/RFC6749, October 2012, 360 . 362 8.2. Informative References 364 [RFC6819] Lodderstedt, T., Ed., McGloin, M., and P. Hunt, "OAuth 2.0 365 Threat Model and Security Considerations", RFC 6819, 366 DOI 10.17487/RFC6819, January 2013, 367 . 369 Appendix A. Acknowledgements 371 The following individuals contributed ideas, feedback, and wording 372 that shaped and formed the final specification: 374 Eric Sachs, John Bradley, and Andy Zmolek. 376 Author's Address 378 William Denniss 379 Google 380 1600 Amphitheatre Pkwy 381 Mountain View, CA 94043 382 USA 384 Phone: +1 650-253-0000 385 Email: wdenniss@google.com 386 URI: http://google.com/