Draft P. Hunt Oracle C. Mortimore Salesforce June 15, 2016 OpenID Connect Profile for SCIM Services Abstract SCIM (RFC7644) is an IETF protocol that enables HTTP clients to retrieve and manage cross-domain identities. OpenID Connect 1.0 is a simple identity layer on top of the OAuth 2.0 protocol which offers access to profile information through a UserInfo endpoint. This specification defines how OpenID Connect relying parties may discover availability of and register for, and access, SCIM services as part of an OpenID Provider (OP) services. Hunt & Mortimore [Page 1] OpenID Connect SCIM Profile June 2016 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1. Requirements Notation and Conventions . . . . . . . . . . 3 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 2. Metadata and Claim Defintions . . . . . . . . . . . . . . . . 5 2.1. Discovery Metadata . . . . . . . . . . . . . . . . . . . . 5 2.2. Dynamic Registration Metadata . . . . . . . . . . . . . . 5 2.3. ID Token Claims . . . . . . . . . . . . . . . . . . . . . 5 3. Using SCIM . . . . . . . . . . . . . . . . . . . . . . . . . . 6 4. Security Considerations . . . . . . . . . . . . . . . . . . . 8 5. Privacy Considerations . . . . . . . . . . . . . . . . . . . . 9 5.1. Personally Identifiable Information . . . . . . . . . . . 9 5.2. Data Access Monitoring . . . . . . . . . . . . . . . . . . 9 5.3. Correlation . . . . . . . . . . . . . . . . . . . . . . . 9 5.4. Offline Access . . . . . . . . . . . . . . . . . . . . . . 9 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 6.1. JSON Web Token Claims Registration . . . . . . . . . . . . 11 6.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 11 7. Normative References . . . . . . . . . . . . . . . . . . . . . 12 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 14 Appendix B. Notices . . . . . . . . . . . . . . . . . . . . . . . 15 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 16 Hunt & Mortimore [Page 2] OpenID Connect SCIM Profile June 2016 1. Introduction SCIM [RFC7644] is an IETF protocol that enables HTTP clients to retrieve and manage cross-domain identities. OpenID Connect 1.0 is a simple identity layer on top of the OAuth 2.0 [RFC6749] protocol which offers access to profile information through a UserInfo endpoint (see Section 5.3 [OpenID.Core]). This specification defines how OpenID Connect relying parties may discover availability of and register for, and access, SCIM services as part of an OpenID Provider services. This specification defines the following metadata: o Discovery metadata indicating the avilability of a SCIM protocol base endpoint. o Dynamic registration metadata that is used to indicate a clients intent to use the SCIM protocol and its associated endpoint. o An additional ID Token claim which specifies the SCIM resource endpoint and identifier associated with the authenticate subject. In addition to the above metadata attributes and claims, the specification will also show how a client MAY access the SCIM endpoint. 1.1. Requirements Notation and Conventions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [RFC2119]. In the .txt version of this document, values are quoted to indicate that they are to be taken literally. When using these values in protocol messages, the quotes MUST NOT be used as part of the value. In the HTML version of this document, values to be taken literally are indicated by the use of "this fixed-width font". 1.2. Terminology This specification uses the terms "Access Token", "Authorization Code", "Authorization Endpoint", "Authorization Grant", "Authorization Server", "Client", "Client Authentication", "Client Identifier", "Client Secret", "Grant Type", "Protected Resource", "Redirection URI", "Refresh Token", "Resource Owner", "Resource Server", "Response Type", and "Token Endpoint" defined by OAuth 2.0 [RFC6749], the terms "JSON Web Token (JWT)" and "Nested JWT" defined Hunt & Mortimore [Page 3] OpenID Connect SCIM Profile June 2016 by JSON Web Token (JWT) [RFC7519], SCIM Protocol [RFC7644], OpenID Connect Core 1.0 [OpenID.Core]. OpenID Discovery 1.0 [OpenID.Discovery], and the terms defined by OpenID Connect Dynamic Client Registration 1.0 [OpenID.Registration]. This specification uses the OpenID term "relying party" to refer to what is defined as a "client" in SCIM protocol (see Section 1.2 [RFC7643]). Hunt & Mortimore [Page 4] OpenID Connect SCIM Profile June 2016 2. Metadata and Claim Defintions 2.1. Discovery Metadata This specification extends the OpenID Connect Discovery metadata Section 3 [OpenID.Discovery] and defines the following: scim_endpoint RECOMMENDED. The base URI of the OP's designated SCIM service provider. The base URI is as defined in Section 1.3 [RFC7644]. This URI when appended with a path of "/Me" points to the subject authenticated by the OP. Further, SCIM clients MAY discover SCIM configuration metadata by using this URI to query endpoints such as "/ServiceProviderConfig" (see Section 3.2 [RFC7644]). 2.2. Dynamic Registration Metadata This specification extends the OpenID Connect Dynamic Registration draft (see Section 2 [OpenID.Registration]), and defines the following metadata: scim_profile RECOMMENDED. Boolean value. When the value is "true", it indicates that the client will use SCIM Protocol [RFC7644] to accessuser information. 2.3. ID Token Claims This specification extends the claims in OpenID Connect Core Section 5 [OpenID.Core] and defines the following: scim_id An identifier whose value corresponds to the "id" attribute as defined in Section 3.1 [RFC7643] that is associated with the authenticated subject ("sub"). scim_location An URI whose value corresponds to the "meta.location" attribute as defined in Section 3.1 [RFC7643] and that is associated with the authenticated subject ("sub"). If this value differs from the discovered "scim_endpoint", the client MUST use the ID Token claim "scim_location" value. Hunt & Mortimore [Page 5] OpenID Connect SCIM Profile June 2016 3. Using SCIM When using SCIM, the relying party MAY use all the protocol features of SCIM and act as a SCIM client. A relying party MAY query SCIM configuration endpoints such as: _/ServiceProviderConfig_ _/ResourceTypes_ _/Schemas_ The OpenID Connect profile for SCIM provides two ways for a relying party to construct a SCIM URI for the authenticated subject: o The relying party MAY use the previously discovered "scim_endpoint" plus the path "/Me" as a URI alias (see Section 3.11 of [RFC7644]). Or, o The relying party MAY use the URI returned in the "scim_resource" ID_Token claim provided. When accessing the SCIM endpoint, the relying party SHOULD use the access token issued in the response from the OP as its authorization to access the SCIM endpoint as per section 2 of OAuth 2.0 Bearer Token Usage [RFC6750]. OpenID Connect relying parties MAY use "scope" values to request authorization as per Section 5.4 [OpenID.Core]. The values used in OpenID Connect SHALL be ignored for the purpose of authorizing access to SCIM. These include: o openid o profile o email o address o phone These scopes SHALL continue to be used as defined by OpenID Connect Core. For example, as a list of claims to be included in the ID_Token. OpenID Connect Providers offering SCIM profile services MAY support SCIM specific scopes not defined in this specification. OpenID Hunt & Mortimore [Page 6] OpenID Connect SCIM Profile June 2016 Connect Providers MAY also use registration data to determine the appropriate scope of authorization for the purpose of access to the SCIM endpoint. Hunt & Mortimore [Page 7] OpenID Connect SCIM Profile June 2016 4. Security Considerations This specification references the security considerations defined in Section 10 of OAuth 2.0 [RFC6749], and Section 5 of OAuth 2.0 Bearer Token Usage [RFC6750]. Furthermore, the OAuth 2.0 Threat Model and Security Considerations [RFC6819] specification provides an extensive list of threats and controls that apply to this specification as well, given that it is based upon OAuth 2.0. ISO/IEC 29115 [ISO29115] also provides threats and controls that implementers need to take into account. Implementers are highly advised to read these references in detail and apply the countermeasures described therein. Hunt & Mortimore [Page 8] OpenID Connect SCIM Profile June 2016 5. Privacy Considerations 5.1. Personally Identifiable Information The SCIM service providers typically contain Personally Identifiable Information (PII). As such, End-User consent for the release of the information for the specified purpose should be obtained at or prior to the authorization time in accordance with relevant regulations. The purpose of use is typically registered in association with the "redirect_uris". Only necessary UserInfo data should be stored at the Client and the Client SHOULD associate the received data with the purpose of use statement. 5.2. Data Access Monitoring The SCIM Resource Server SHOULD make End-Users' resource access logs available to them so that they can monitor who accessed their data. 5.3. Correlation To protect the End-User from a possible correlation among Clients, the use of a Pairwise Pseudonymous Identifier (PPID) as the "sub" (subject) SHOULD be considered. 5.4. Offline Access Offline access enables access to Claims when the user is not present, posing greater privacy risk than the Claims transfer when the user is present. Therefore, it is prudent to obtain explicit consent for offline access to resources. This specification mandates the use of the "prompt" parameter to obtain consent unless it is already known that the request complies with the conditions for processing the request in each jurisdiction. When an Access Token is returned via the User Agent using the Implicit Flow or Hybrid Flow, there is a greater risk of it being exposed to an attacker, who could later use it to access the UserInfo endpoint. If the Access Token does not enable offline access and the server can differentiate whether the Client request has been made offline or online, the risk will be substantially reduced. Therefore, this specification mandates ignoring the offline access request when the Access Token is transmitted through the User Agent. Note that differentiating between online and offline access from the server can be difficult especially for native clients. The server may well have to rely on heuristics. Also, the risk of exposure for the Access Token delivered through the User Agent for the Response Hunt & Mortimore [Page 9] OpenID Connect SCIM Profile June 2016 Types of "code token" and "token" is the same. Thus, the implementations should be prepared to detect whether the Access Token was issued through the User Agent or directly from the Token Endpoint and deny offline access if the token was issued through the User Agent. Note that although these provisions require an explicit consent dialogue through the "prompt" parameter, the mere fact that the user pressed an "accept" button etc., might not constitute a valid consent. Developers should be aware that for the act of consent to be valid, typically, the impact of the terms have to be understood by the End-User, the consent must be freely given and not forced (i.e., other options have to be available), and the terms must fair and equitable. In general, it is advisable for the service to follow the required privacy principles in each jurisdiction and rely on other conditions for processing the request than simply explicit consent, as online self-service "explicit consent" often does not form a valid consent in some jurisdictions. Hunt & Mortimore [Page 10] OpenID Connect SCIM Profile June 2016 6. IANA Considerations 6.1. JSON Web Token Claims Registration This specification registers the Claims defined in Section 2.3 in the IANA JSON Web Token Claims registry defined in [RFC7519]. 6.1.1. Registry Contents o Claim Name: "scim_id" o Claim Description: SCIM Identifier o Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net o Specification Document(s): Section 2.3 of this document o Claim Name: "scim_location" o Claim Description: SCIM Resource Location o Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net o Specification Document(s): Section 2.3 of this document Hunt & Mortimore [Page 11] OpenID Connect SCIM Profile June 2016 7. Normative References [ISO29115] International Organization for Standardization, "ISO/IEC 29115:2013 -- Information technology - Security techniques - Entity authentication assurance framework", ISO/ IEC 29115, March 2013. [OpenID.Core] Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and C. Mortimore, "OpenID Connect Core 1.0", November 2014. [OpenID.Discovery] Sakimura, N., Bradley, J., Jones, M., and E. Jay, "OpenID Connect Discovery 1.0", November 2014. [OpenID.Registration] Sakimura, N., Bradley, J., and M. Jones, "OpenID Connect Dynamic Client Registration 1.0", November 2014. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ RFC2119, March 1997, . [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2616, DOI 10.17487/ RFC2616, June 1999, . [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, DOI 10.17487/RFC3986, January 2005, . [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security (TLS) Protocol Version 1.2", RFC 5246, DOI 10.17487/ RFC5246, August 2008, . [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and Verification of Domain-Based Application Service Identity within Internet Public Key Infrastructure Using X.509 (PKIX) Certificates in the Context of Transport Layer Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March 2011, . Hunt & Mortimore [Page 12] OpenID Connect SCIM Profile June 2016 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", RFC 6749, DOI 10.17487/RFC6749, October 2012, . [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization Framework: Bearer Token Usage", RFC 6750, DOI 10.17487/ RFC6750, October 2012, . [RFC6819] Lodderstedt, T., Ed., McGloin, M., and P. Hunt, "OAuth 2.0 Threat Model and Security Considerations", RFC 6819, DOI 10.17487/RFC6819, January 2013, . [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, . [RFC7643] Hunt, P., Ed., Grizzle, K., Wahlstroem, E., and C. Mortimore, "System for Cross-domain Identity Management: Core Schema", RFC 7643, DOI 10.17487/RFC7643, September 2015, . [RFC7644] Hunt, P., Ed., Grizzle, K., Ansari, M., Wahlstroem, E., and C. Mortimore, "System for Cross-domain Identity Management: Protocol", RFC 7644, DOI 10.17487/RFC7644, September 2015, . Hunt & Mortimore [Page 13] OpenID Connect SCIM Profile June 2016 Appendix A. Acknowledgements Hunt & Mortimore [Page 14] OpenID Connect SCIM Profile June 2016 Appendix B. Notices Copyright (c) 2016 The OpenID Foundation. The OpenID Foundation (OIDF) grants to any Contributor, developer, implementer, or other interested party a non-exclusive, royalty free, worldwide copyright license to reproduce, prepare derivative works from, distribute, perform and display, this Implementers Draft or Final Specification solely for the purposes of (i) developing specifications, and (ii) implementing Implementers Drafts and Final Specifications based on such documents, provided that attribution be made to the OIDF as the source of the material, but that such attribution does not indicate an endorsement by the OIDF. The technology described in this specification was made available from contributions from various sources, including members of the OpenID Foundation and others. Although the OpenID Foundation has taken steps to help ensure that the technology is available for distribution, it takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this specification or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any independent effort to identify any such rights. The OpenID Foundation and the contributors to this specification make no (and hereby expressly disclaim any) warranties (express, implied, or otherwise), including implied warranties of merchantability, non- infringement, fitness for a particular purpose, or title, related to this specification, and the entire risk as to implementing this specification is assumed by the implementer. The OpenID Intellectual Property Rights policy requires contributors to offer a patent promise not to assert certain patent claims against other contributors and against implementers. The OpenID Foundation invites any interested party to bring to its attention any copyrights, patents, patent applications, or other proprietary rights that may cover technology that may be required to practice this specification. Hunt & Mortimore [Page 15] OpenID Connect SCIM Profile June 2016 Authors' Addresses Phil Hunt Oracle Corporation Email: phil.hunt@oracle.com URI: http://twitter.com/independentid Chuck Mortimore Salesforce Email: cmortimore@salesforce.com URI: https://twitter.com/cmort Hunt & Mortimore [Page 16]