idnits 2.17.1 draft-wdenniss-oauth-device-posture-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 : ---------------------------------------------------------------------------- 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 (November 13, 2017) is 2327 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 473, 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 KM. McGuinness 5 Expires: May 17, 2018 Okta 6 J. Bradley 7 Yubico 8 November 13, 2017 10 OAuth 2.0 Device Posture Signals 11 draft-wdenniss-oauth-device-posture-01 13 Abstract 15 Enterprise and security focused OAuth providers typically want 16 additional signals to confirm user presence when users return to 17 previously authorized apps. Rather than requiring a full 18 reauthentication, or require enrollment in a mobile device management 19 solution, some authorization servers may be willing to accept device 20 posture signals from the app, like the fact that device has a lock 21 screen, as confirmation of user presence. This document details how 22 OAuth native app clients can communicate device posture signals to 23 OAuth providers. 25 Status of This Memo 27 This Internet-Draft is submitted in full conformance with the 28 provisions of BCP 78 and BCP 79. 30 Internet-Drafts are working documents of the Internet Engineering 31 Task Force (IETF). Note that other groups may also distribute 32 working documents as Internet-Drafts. The list of current Internet- 33 Drafts is at https://datatracker.ietf.org/drafts/current/. 35 Internet-Drafts are draft documents valid for a maximum of six months 36 and may be updated, replaced, or obsoleted by other documents at any 37 time. It is inappropriate to use Internet-Drafts as reference 38 material or to cite them other than as "work in progress." 40 This Internet-Draft will expire on May 17, 2018. 42 Copyright Notice 44 Copyright (c) 2017 IETF Trust and the persons identified as the 45 document authors. All rights reserved. 47 This document is subject to BCP 78 and the IETF Trust's Legal 48 Provisions Relating to IETF Documents 49 (https://trustee.ietf.org/license-info) in effect on the date of 50 publication of this document. Please review these documents 51 carefully, as they describe your rights and restrictions with respect 52 to this document. Code Components extracted from this document must 53 include Simplified BSD License text as described in Section 4.e of 54 the Trust Legal Provisions and are provided without warranty as 55 described in the Simplified BSD License. 57 Table of Contents 59 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 60 2. Notational Conventions . . . . . . . . . . . . . . . . . . . 3 61 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 62 4. Device Posture Signal Dictionary . . . . . . . . . . . . . . 3 63 5. Authorization Request Device Posture Hint . . . . . . . . . . 5 64 6. Token Endpoint Device Posture Enforcement . . . . . . . . . . 5 65 7. Security Considerations . . . . . . . . . . . . . . . . . . . 6 66 7.1. Device Posture Scope . . . . . . . . . . . . . . . . . . 6 67 7.2. Spoofed Devices . . . . . . . . . . . . . . . . . . . . . 6 68 7.3. App Trustworthiness . . . . . . . . . . . . . . . . . . . 6 69 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 70 8.1. OAuth Parameters Registration . . . . . . . . . . . . . . 7 71 8.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 7 72 8.2. OAuth Extensions Error Registration . . . . . . . . . . . 7 73 8.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 7 74 8.3. Device Posture Keys Registry . . . . . . . . . . . . . . 7 75 8.3.1. Registration Template . . . . . . . . . . . . . . . . 8 76 8.3.2. Initial Registry Contents . . . . . . . . . . . . . . 9 77 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 10 78 9.1. Normative References . . . . . . . . . . . . . . . . . . 10 79 9.2. Informative References . . . . . . . . . . . . . . . . . 11 80 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 11 81 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 11 83 1. Introduction 85 Users who follow strong security practices on their devices - such as 86 configuring screen locks, and not enabling admin privileges (commonly 87 known as "rooting" or "jailbreaking") - shouldn't need to 88 reauthenticate frequently to the individual apps on their device. 90 This specification details how apps can send device posture signals 91 to the OAuth Token Endpoint, enabling it to enforce device policy 92 compliance, and avoid the need for reauthentication in some cases. 94 It is designed to provide a mechanism for honest apps to communicate 95 device posture. By itself it doesn't protect against malicious 96 users, dishonest apps, or compromised devices, but the signal format 97 described could carry signals that do. 99 2. Notational Conventions 101 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 102 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 103 "OPTIONAL" in this document are to be interpreted as described in Key 104 words for use in RFCs to Indicate Requirement Levels [RFC2119]. If 105 these words are used without being spelled in uppercase then they are 106 to be interpreted with their normal natural language meanings. 108 3. Terminology 110 In addition to the terms defined in referenced specifications, this 111 document uses the following terms: 113 MDM 114 Mobile Device Management. 116 EMM 117 Enterprise Mobility Management. 119 4. Device Posture Signal Dictionary 121 The device posture is a dictionary of signals asserted by the app 122 about the device. The structure is send as an added parameter in 123 several places during the OAuth flow, as documented in the subsequent 124 sections. 126 All device posture keys are OPTIONAL and MUST only be set when the 127 attribute can be obtained by the app. The standard attribute keys 128 are as follows: 130 screen_lock 131 Boolean. True if the device has a screen lock, such as a pin, 132 pattern biometric, etc. 134 root_privileges 135 Boolean. True if user apps can access root device privileges. 136 For mobile operating systems, known as "jailbreaking" on iOS and 137 "rooting" on Android. 139 full_disk_encryption 140 Boolean. True if data stored on the device is fully encrypted at 141 rest. 143 device_id 144 String. A unique identifier for the device. 146 device_os 147 String. The name of the operating system running on the device 148 such as "iOS" or "Android". 150 device_os_version 151 String. The current version of the operating system. 153 device_vendor 154 String. The vendor of the device such as "Apple" or "Google". 156 device_model 157 String. The model of the device such as "iPhone X" or "Pixel 2". 159 device_attestation 160 Dictionary. An attestation from the operating system, containing 161 a signed-statement about the device and/or the app. The format is 162 a dictionary, the specifics of which depends on the operating 163 system. 165 app_id 166 String. The platform-specific identifier (URI) for the 167 application. For Android, the format of the URI is android:apk- 168 key-hash:. For iOS, the format of URI 169 is ios:bundle-id:. 171 app_managed 172 Boolean. True if the app is managed by a MDM/EMM system. 174 An example device posture dictionary: 176 { 177 "screen_lock": true, 178 "root_privileges": false, 179 "full_disk_encryption": true, 180 "device_id": "6bdde1e8-0667-40f9-9993-16aa52ee6b38", 181 "device_os": "iOS", 182 "device_os_version": "11.1", 183 "device_vendor": "Apple", 184 "device_model": "iPhone X", 185 "app_id": "ios:bundle-id:com.example.myapp", 186 "app_managed": false 187 } 189 5. Authorization Request Device Posture Hint 191 Clients MAY send the device posture signal dictionary to the 192 authorization server in the authorization request. These signals, 193 except for those that are signed and bound to the device are 194 susceptible to client-side modification by end-users. While 195 untrusted, such signals can still be used as hints by the 196 authorization server to present a better user experience, like 197 informing the user they need a lock screen. 199 Error encountered during authorization can be displayed to the user 200 in the browser making this a more user friendly way to instruct the 201 user on how to move their device into conformance. The token 202 endpoint (on which errors are less user-friendly as there's no user 203 agent), can then enforce the restrictions per Section 6. 205 The following parameters are added to the OAuth 2.0 Authorization 206 Request or the OpenID Connect Authorization Request: 208 device_posture_hint 209 JSON String. URL-encoded JSON dictionary, contains the Device 210 Posture Signals defined in Section 4. 212 A AS receving device_posture_hint may pass the value on to upstream 213 OpenID Connect IDP using the same paramater to enable the 214 Authentication Server to make policy decisions. 216 6. Token Endpoint Device Posture Enforcement 218 Clients that follow this specification MUST send the device posture 219 signals on every request to the token endpoint. 221 Token Endpoints SHOULD verify that the posture conforms to their 222 requirements and act accordingly. 224 The following parameters are added to all requests to the Token 225 Endpoint: 227 device_posture 228 JSON String. URL-encoded JSON dictionary, contains the Device 229 Posture Signals defined in Section 4. 231 The app MUST obtain fresh device posture information before every 232 request to the Token Endpoint, and MUST NOT include stale information 233 (rather, it should drop any signals it cannot freshly obtain). 235 For token refresh requests, where the device posture has been 236 previously communicated, if an attribute is missing, the Token 237 Endpoint may choose to use the previous value, based on it's own 238 policy and freshness requirements. 240 If the policy does not meet requirements, the Token Endpoint SHOULD 241 return the following error code: 243 device_posture_invalid 244 Error indicating that the device posture does not meet 245 requirements. The error description SHOULD contain details on why 246 this is is the case. 248 7. Security Considerations 250 7.1. Device Posture Scope 252 This specification is designed to help authorization servers enforce 253 security policy (like requiring a lock screen) on end-users. The 254 intent is to enforce restrictions on honest users, to force them to 255 follow security practices set out by the authorization server. By 256 itself, it offers no protection against malicious users, dishonest 257 apps, or compromised devices. 259 Combined with other technologies like device-based attestations and 260 token binding may enable such protection, and this specification 261 could be used to transmit secure signals, but that topic is out of 262 scope for this specification. 264 7.2. Spoofed Devices 266 It is possible to at a device level completely spoof the device 267 posture. Even statements signed by the operating system are 268 vulnerable to spoofing, as it's possible a statement from the real 269 device can be replayed on a spoofed device, unless such statements 270 include a binding to the device itself. Per Section 7.1, this topic 271 is out of scope for this specification. 273 7.3. App Trustworthiness 275 This specification is designed to allow trusted apps to report device 276 posture to the authorization server to help the server enforce 277 security policy on end-users. It does not by itself force apps to be 278 honest, or genuine. Genuine apps (i.e. apps not lying about their 279 client ID) might be dishonest about the device posture, and apps that 280 are normally honest, could be spoofed, unless anti-spoofing 281 countermeasures that are out of scope of this specification are 282 employed. 284 8. IANA Considerations 286 8.1. OAuth Parameters Registration 288 This specification registers the following value in the IANA "OAuth 289 Parameters" registry [IANA.OAuth.Parameters] established by 290 [RFC6749]. 292 8.1.1. Registry Contents 294 o Parameter name: device_posture_hint 295 o Parameter usage location: authorization request 296 o Change controller: IESG 297 o Specification document(s): Section 5 of [[ this specification ]] 299 o Parameter name: device_posture 300 o Parameter usage location: token request 301 o Change controller: IESG 302 o Specification document(s): Section 6 of [[ this specification ]] 304 8.2. OAuth Extensions Error Registration 306 This specification registers the following error in the IANA "OAuth 307 Extensions Error Registry" [IANA.OAuth.Parameters] established by 308 [RFC6749]. 310 8.2.1. Registry Contents 312 o Error name: device_posture_invalid 313 o Error usage location: authorization response, token error response 314 o Related protocol extension: resource parameter 315 o Change controller: IESG 316 o Specification document(s): Section 6 of [[ this specification ]] 318 8.3. Device Posture Keys Registry 320 This specification establishes the IANA "Device Posture Keys" 321 registry for Device Posture Dictionary keys. The registry records 322 the Device Posture key and a reference to the specification that 323 defines it. This specification registers the Device Posture keys 324 defined in Section 4. 326 Keys are registered on an Expert Review [RFC5226] basis after a 327 three-week review period on the oauth-reg-review@ietf.org mailing 328 list, on the advice of one or more Designated Experts. 330 Registration requests sent to the mailing list for review should use 331 an appropriate subject (e.g., "Request to register Device Posture 332 Key: screen_lock"). 334 Within the review period, the Designated Experts will either approve 335 or deny the registration request, communicating this decision to the 336 review list and IANA. Denials should include an explanation and, if 337 applicable, suggestions as to how to make the request successful. 338 Registration requests that are undetermined for a period longer than 339 21 days can be brought to the IESG's attention (using the 340 iesg@ietf.org mailing list) for resolution. 342 Criteria that should be applied by the Designated Experts includes 343 determining whether the proposed registration duplicates existing 344 functionality, whether it is likely to be of general applicability or 345 whether it is useful only for a single application, whether the value 346 is actually being used, and whether the registration description is 347 clear. 349 IANA must only accept registry updates from the Designated Experts 350 and should direct all requests for registration to the review mailing 351 list. 353 It is suggested that the same Designated Experts evaluate these 354 registration requests as those who evaluate registration requests for 355 the IANA "OAuth Parameters" registry [IANA.OAuth.Parameters]. 357 8.3.1. Registration Template 359 Device Posture Signal Key: 360 The key name requested (e.g., "screen_lock"). Names may not match 361 other registered names in a case-insensitive manner unless the 362 Designated Experts state that there is a compelling reason to 363 allow an exception. 364 Device Posture Signal Key Description: 365 Brief description of the device posture signal (e.g., "Screen lock 366 active"). 367 Change Controller: 368 For Standards Track RFCs, state "IESG". For others, give the name 369 of the responsible party. Other details (e.g., postal address, 370 email address, home page URI) may also be included. 371 Specification Document(s): 372 Reference to the document or documents that specify the parameter, 373 preferably including URIs that can be used to retrieve copies of 374 the documents. An indication of the relevant sections may also be 375 included but is not required. 377 8.3.2. Initial Registry Contents 379 o Device Posture Signal Key: "screen_lock" 380 o Device Posture Signal Key Description: Boolean. 'true' when the 381 device has a screen lock enabled. 382 o Change Controller: IESG 383 o Specification Document(s): Section 4 of [[ this specification ]] 385 o Device Posture Signal Key: "root_privileges" 386 o Device Posture Signal Key Description: Boolean. True if user apps 387 can access root device privileges. 388 o Change Controller: IESG 389 o Specification Document(s): Section 4 of [[ this specification ]] 391 o Device Posture Signal Key: "full_disk_encryption" 392 o Device Posture Signal Key Description: Boolean. True if data 393 stored on the device is fully encrypted at rest. 394 o Change Controller: IESG 395 o Specification Document(s): Section 4 of [[ this specification ]] 397 o Device Posture Signal Key: "device_id" 398 o Device Posture Signal Key Description: String. A unique 399 identifier for the device. 400 o Change Controller: IESG 401 o Specification Document(s): Section 4 of [[ this specification ]] 403 o Device Posture Signal Key: "device_os" 404 o Device Posture Signal Key Description: String. The name of the 405 operating system running on the device such as "iOS" or "Android". 406 o Change Controller: IESG 407 o Specification Document(s): Section 4 of [[ this specification ]] 409 o Device Posture Signal Key: "device_os_version" 410 o Device Posture Signal Key Description: String. The current 411 version of the operating system. 412 o Change Controller: IESG 413 o Specification Document(s): Section 4 of [[ this specification ]] 415 o Device Posture Signal Key: "device_vendor" 416 o Device Posture Signal Key Description: String. The vendor of the 417 device such as "Apple or "Google". 418 o Change Controller: IESG 419 o Specification Document(s): Section 4 of [[ this specification ]] 421 o Device Posture Signal Key: "device_model" 422 o Device Posture Signal Key Description: String. The model of the 423 device such as "iPhone X" or "Pixel 2" 424 o Change Controller: IESG 425 o Specification Document(s): Section 4 of [[ this specification ]] 427 o Device Posture Signal Key: "device_attestation" 428 o Device Posture Signal Key Description: Dictionary. An attestation 429 from the operating system, containing a signed-statement about the 430 device and/or the app. 431 o Change Controller: IESG 432 o Specification Document(s): Section 4 of [[ this specification ]] 434 o Device Posture Signal Key: "app_id" 435 o Device Posture Signal Key Description: String. The platform- 436 specific identifier (URI) for the application. For Android, the 437 format of the URI is android:apk-key-hash:. For iOS, the format of URI is ios:bundle-id:. 440 o Change Controller: IESG 441 o Specification Document(s): Section 4 of [[ this specification ]] 443 o Device Posture Signal Key: "app_managed" 444 o Device Posture Signal Key Description: Boolean. True if the app 445 is managed by a MDM/EMM system. 446 o Change Controller: IESG 447 o Specification Document(s): Section 4 of [[ this specification ]] 449 9. References 451 9.1. Normative References 453 [IANA.OAuth.Parameters] 454 IANA, "OAuth Parameters", 455 . 457 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 458 Requirement Levels", BCP 14, RFC 2119, 459 DOI 10.17487/RFC2119, March 1997, 460 . 462 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 463 IANA Considerations Section in RFCs", RFC 5226, 464 DOI 10.17487/RFC5226, May 2008, 465 . 467 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 468 RFC 6749, DOI 10.17487/RFC6749, October 2012, 469 . 471 9.2. Informative References 473 [RFC6819] Lodderstedt, T., Ed., McGloin, M., and P. Hunt, "OAuth 2.0 474 Threat Model and Security Considerations", RFC 6819, 475 DOI 10.17487/RFC6819, January 2013, 476 . 478 Appendix A. Acknowledgements 480 The following individuals contributed ideas, feedback, and wording 481 that shaped and formed the final specification: 483 Eric Sachs, John Bradley, and Andy Zmolek. 485 Authors' Addresses 487 William Denniss 488 Google 489 1600 Amphitheatre Pkwy 490 Mountain View, CA 94043 491 USA 493 Phone: +1 650-253-0000 494 Email: wdenniss@google.com 495 URI: http://google.com/ 497 Karl McGuinness 498 Okta 499 301 Brannan St. 500 San Francisco, CA 94107 501 USA 503 Email: kmcguinness@okta.com 504 URI: https://www.okta.com/ 506 John Bradley 507 Yubico 508 530 Lytton Ave, Suite 301 509 Palo Alto, CA 94301 510 USA 512 Phone: +1 202-630-5272 513 Email: ietf@ve7jtb.com 514 URI: https://www.thread-safe.com/