D. McAdams Amazon October 7, 2020 FastFed Enterprise SCIM Profile 1.0 - draft 03 fastfed-scim-1_0 Abstract This specification defines the requirements to implement the FastFed Profile for SCIM 2.0 Enterprise provisioning. This profile supports continual provisioning, update, and deprovisioning of end-users between the Identity Provider and Application Provider. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1.1. Requirements Notation and Conventions . . . . . . . . . . 2 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 2. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 3 2.1. Roles and Responsibilities . . . . . . . . . . . . . . . 3 2.2. Client Authentication . . . . . . . . . . . . . . . . . . 3 3. Protocol Extensions . . . . . . . . . . . . . . . . . . . . . 3 3.1. FastFed Metadata . . . . . . . . . . . . . . . . . . . . 4 3.1.1. Provisioning Profile URN . . . . . . . . . . . . . . 4 3.1.2. Application Metadata . . . . . . . . . . . . . . . . 4 3.2. FastFed Handshake . . . . . . . . . . . . . . . . . . . . 6 3.2.1. FastFed Registration Request . . . . . . . . . . . . 7 3.2.1.1. Usage of the OAuth-2.0 JWT Profile . . . . . . . 8 3.2.2. FastFed Registration Response . . . . . . . . . . . . 9 3.2.2.1. Usage of the OAuth-2.0 JWT Profile . . . . . . . 10 4. Interoperability Requirements . . . . . . . . . . . . . . . . 10 4.1. General Requirements . . . . . . . . . . . . . . . . . . 11 4.2. User Provisioning . . . . . . . . . . . . . . . . . . . . 11 4.2.1. Create User . . . . . . . . . . . . . . . . . . . . . 12 4.2.2. Update User . . . . . . . . . . . . . . . . . . . . . 12 4.2.3. Deactivate or Reactivate User . . . . . . . . . . . . 13 4.2.4. Delete User . . . . . . . . . . . . . . . . . . . . . 14 4.2.5. Get User By Id . . . . . . . . . . . . . . . . . . . 15 4.2.6. List Users By Alternate Identifier . . . . . . . . . 16 4.3. Group Provisioning . . . . . . . . . . . . . . . . . . . 17 4.3.1. Create Group . . . . . . . . . . . . . . . . . . . . 18 4.3.2. Update Group Metadata . . . . . . . . . . . . . . . . 18 4.3.3. Deactivate Group . . . . . . . . . . . . . . . . . . 19 4.3.4. Delete Group . . . . . . . . . . . . . . . . . . . . 20 4.3.5. Get Group By Id . . . . . . . . . . . . . . . . . . . 20 4.3.6. List Groups By Alternate Identifier . . . . . . . . . 21 McAdams Expires April 10, 2021 [Page 1] FastFed Enterprise SCIM Profile 1.0 October 2020 4.3.7. Add or Remove Group Members . . . . . . . . . . . . . 22 4.4. Metadata Endpoints . . . . . . . . . . . . . . . . . . . 24 4.4.1. ResourceTypes . . . . . . . . . . . . . . . . . . . . 24 4.4.2. ServiceProviderConfig . . . . . . . . . . . . . . . . 24 4.4.3. Schemas . . . . . . . . . . . . . . . . . . . . . . . 25 5. Example Usage of the OAuth 2.0 JWT Profile . . . . . . . . . 25 5.1. Identity Provider Shares Public Key . . . . . . . . 25 5.2. Application Provider Shares SCIM and OAuth Endpoints . . 26 5.3. Identity Provider Acquires an OAuth Access Token . . . . 26 5.4. Identity Provider Uses the OAuth Access Token . . . . . . 27 6. Security Considerations . . . . . . . . . . . . . . . . . . . 28 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 28 8. Normative References . . . . . . . . . . . . . . . . . . . . 28 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 29 Appendix B. Notices . . . . . . . . . . . . . . . . . . . . . . 29 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 30 1. Introduction This specification defines the functionality which a provider must implement to satisfy the FastFed Profile for SCIM 2.0 Enterprise provisioning. It consists of the following extensions to the FastFed Core [FastFed.Core] specification: o Additional metadata in the FastFed Handshake Flows to exchange SCIM provisioning information and authentication credentials. o An interoperability profile describing the subset of the SCIM specifications which must be implemented. 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 specification, 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 specification, values to be taken literally are indicated by the use of "this fixed-width font". McAdams Expires April 10, 2021 [Page 2] FastFed Enterprise SCIM Profile 1.0 October 2020 1.2. Terminology This FastFed Profile uses the terminology defined in Section 1.2 of the FastFed Core [FastFed.Core] specification. The terms ""SCIM"", ""SCIM client"", and ""SCIM service"" refer to the terminology defined in RFC 7644 [RFC7644]. 2. Overview 2.1. Roles and Responsibilities In this profile, the Identity Provider plays the role of a SCIM client, pushing user and group information to the Application Provider who hosts the SCIM service. The result is to maintain a copy of user and group information in the Application by communicating, via calls the to the SCIM APIs, the creation, update, and deletion of these records. To perform these responsibilities, this specification defines the subset of SCIM capabilities that each party must implement to fulfill the FastFed interoperability requirements. 2.2. Client Authentication SCIM [RFC7644] does not prescribe a mechanism for client authentication. However, for interoperability purposes, it is necessary for Providers to agree on an authentication method. To fill the gap, this specification prescribes an OAuth 2.0 authentication profile for SCIM services, while also leaving extension points available for alternative authentication methods. As described in Section 6 of the FastFed Core [FastFed.Core] specification, the use of asymmetric key pairs is preferred over long-lived shared secrets. As a result, this profile uses RFC 7523 [RFC7523] which defines a mechanism to exchange a signed JWT for an OAuth 2.0 access token. An end-to-end example of SCIM client authentication via RFC 7523 [RFC7523] is provided in Section 5. 3. Protocol Extensions McAdams Expires April 10, 2021 [Page 3] FastFed Enterprise SCIM Profile 1.0 October 2020 3.1. FastFed Metadata 3.1.1. Provisioning Profile URN This specification extends the FastFed Core [FastFed.Core] metadata (Section 3.3.1) with the following value for "provisioning_profiles": urn:ietf:params:fastfed:1.0:provisioning:scim:2.0:enterprise A Provi der who includes this URN in their list of capabilities MUST comply with the requirements described in this specification. The following is a non-normative example of Provider Metadata showing the usage of the value: { "application_provider": { "capabilities": { "provisioning_profiles": ["urn:ietf:params:fastfed:1.0:provisioning:scim:2.0:enterprise"], ... } 3.1.2. Application Metadata This specification extends the Application Provider Metadata defined in Section 3.3.9 of FastFed Core [FastFed.Core] with an additional member having the name: ""urn:ietf:params:fastfed:1.0:provisioning:scim:2.0:enterprise"". The value of the element is a structure containing the following members: desired_attributes REQUIRED. A structure specifying the attributes to be provisioned, as described in Section 3.3.5 of FastFed Core [FastFed.Core]. When using this profile, the Application Provider MUST include the following SCIM Core User attribute in the list of "required_user_attributes": * "externalId" * "userName" * "active" If the Application Provider supports Group provisioning, it MUST: McAdams Expires April 10, 2021 [Page 4] FastFed Enterprise SCIM Profile 1.0 October 2020 * Include the SCIM Core Group attributes "displayName" and "externalId" in the list of "required_group_attributes". * Include the SCIM Core Group attribute "members" in the list of "optional_group_attributes". As a reference, "members" is optional is because it is acceptable to create an empty group, or to remove all members from an existing group. For example, see Section 4.3.3. If the Application Provider does not support Group provisioning, it MUST omit the following from the desired attributes: * "required_group_attributes" * "optional_group_attributes" can_support_nested_groups OPTIONAL. Boolean value indicating whether the Application Provider supports provisioning of nested Group memberships. The default value is "false". See Section 4.3.7 for details on Group membership provisioning. max_group_membership_changes OPTIONAL. Number indicating the maximum number of Group membership changes that can be included in a single PATCH request. The minimum value is 100. The maximum value is 1000. The default value is 100. See Section 4.3.7 for details on Group membership provisioning. The following is a non-normative example of Application Provider Metadata with the profile extensions: { "application_provider": { "entity_id": "https://tenant-67890.app.example.com/" "provider_domain": "example.com", "provider_contact_information": { "organization": "Example Inc.", "phone": "+1-800-555-5555", "email": "support@example.com" }, "display_settings": { "display_name": "Example Application Provider", "logo_uri": "https://app.example.com/images/logo.png", "icon_uri": "https://app.example.com/images/icon.png", "license": "https://openid.net/intellectual-property/licenses/fastfed/1.0/" } "capabilities": { "provisioning_profiles": [ "urn:ietf:params:fastfed:1.0:provisioning:scim:2.0:enterprise" McAdams Expires April 10, 2021 [Page 5] FastFed Enterprise SCIM Profile 1.0 October 2020 ], "schema_grammars": [ "urn:ietf:params:fastfed:1.0:schemas:scim:2.0" ], "signing_algorithms": [ "ES512", "RS256" ] }, "fastfed_handshake_register_uri": "https://tenant-67890.app.example.com/fastfed/register", "urn:ietf:params:fastfed:1.0:provisioning:scim:2.0:enterprise": { "can_support_nested_groups": true, "max_group_membership_changes": 1000, "desired_attributes": { "urn:ietf:params:fastfed:1.0:schemas:scim:2.0": { "required_user_attributes": [ "externalId", "userName", "active" ], "optional_user_attributes": [ "displayName", "emails[primary eq true]" ], "required_group_attributes": [ "displayName", "externalId" ], "optional_group_attributes": [ "members" ] } } } } 3.2. FastFed Handshake When using this SCIM provisioning profile, the FastFed Identity Provider and Application Provider have various responsibilities to comply with the protocol. The Identity Provider fulfills the role of a SCIM Client. It has a responsibility to provision user information into the Application Provider as described in Section 4. McAdams Expires April 10, 2021 [Page 6] FastFed Enterprise SCIM Profile 1.0 October 2020 The Application Provider fulfills the role of a SCIM Service. It has a responsibility to host a SCIM Endpoint and handle provisioning messages from the Identity Provider as described in described in Section 4 This specification extends the FastFed Core [FastFed.Core] handshake messages with the additional attributes necessary for each party to fulfill their respective obligations under SCIM. 3.2.1. FastFed Registration Request This specification extends the contents of the FastFed Registration Request (Section 7.2.3.1 of FastFed Core [FastFed.Core]) with an additional member sharing the same name as the profile: ""urn:ietf:params:fastfed:1.0:provisioning:scim:2.0:enterprise"". The value of the element is a structure with the following members: provider_contact_information REQUIRED. A structure containing the contact information for the provisioning provider, as defined in Section 3.3.3 of FastFed Core [FastFed.Core]. The "provider_contact_information" MAY be the same party who hosted the FastFed Handshake (as defined in the Identity Provider FastFed Metadata). Alternatively, SCIM provisioning may be delegated to a distinct sub-system which authenticates with its own identity and key materials. By specifying protocol-specific "provider_contact_information" for SCIM provisioning, both scenarios are supported. provider_authentication_methods REQUIRED. A list of supported authentication methods for client authentication to the SCIM service, along with any additional metadata specified by each method. Providers SHOULD support the JWT Profile for OAuth-2.0 (defined in Section 3.2.1.1) and MAY support additional methods. The following is a non-normative example of the contents of a registration request message: McAdams Expires April 10, 2021 [Page 7] FastFed Enterprise SCIM Profile 1.0 October 2020 { "iss": "https://tenant-12345.idp.example.com", "aud": "https://tenant-67890.app.example.com", "exp": 1234567890, "provisioning_profiles": [ "urn:ietf:params:fastfed:1.0:provisioning:scim:2.0:enterprise" ], "urn:ietf:params:fastfed:1.0:provisioning:scim:2.0:enterprise": { "provider_contact_information": { "organization": "Example Inc.", "phone": "+1-800-555-5555", "email": "support@example.com" }, "provider_authentication_methods_supported": [ {...protocol-specific values...} ] } } 3.2.1.1. Usage of the OAuth-2.0 JWT Profile Support for this authentication method is indicated by including an additional member in the "provider_authentication_methods" with the name: ""urn:ietf:params:fastfed:1.0:provider_authentication:oauth:2.0:jwt_p rofile"" The value of the element is a structure with the following members: jwks_uri REQUIRED. URL of the SCIM client's JSON Web Key Set [JWK] [RFC7517] containing the signing key(s) used by the Provider. If the same entity hosts both the FastFed Handshake and performs SCIM provisioning, then the same "jwks_uri" MAY be used for both purposes. Alternatively, if SCIM provisioning is delegated to a distinct sub-system which authenticates with its own key materials, then a different key set can be used. By specifying a protocol-specific "jwks_uri" for SCIM provisioning, both scenarios are supported. The following is a non-normative example of the contents of a registration request message containing this authentication method: McAdams Expires April 10, 2021 [Page 8] FastFed Enterprise SCIM Profile 1.0 October 2020 { "iss": "https://tenant-12345.idp.example.com", "aud": "https://tenant-67890.app.example.com", "exp": 1234567890, "provisioning_profiles": [ "urn:ietf:params:fastfed:1.0:provisioning:scim:2.0:enterprise" ], "urn:ietf:params:fastfed:1.0:provisioning:scim:2.0:enterprise": { "provider_contact_information": { "organization": "Example Inc.", "phone": "+1-800-555-5555", "email": "support@example.com" }, "provider_authentication_methods_supported": [ { "urn:ietf:params:fastfed:1.0:provider_authentication:oauth:2.0:jwt_profile": { "jwks_uri": "https://provisioning.example.com/keys" } } ] } } 3.2.2. FastFed Registration Response This specification extends the contents of the FastFed Registration Response (Section 7.2.3.3 of FastFed Core [FastFed.Core]) with an additional member sharing the same name as the profile: ""urn:ietf:params:fastfed:1.0:provisioning:scim:2.0:enterprise"" The value of the element is a structure with the following members: scim_service_uri REQUIRED. Contains the URL of the Application Provider's SCIM Endpoint. provider_authentication_method REQUIRED. Contains the URN of the chosen authentication method, selected by the Application Provider from amongst the set of compatible methods shared by both the Identity Provider and the Application Provider. The following is a non-normative example of the contents of a registration response message: McAdams Expires April 10, 2021 [Page 9] FastFed Enterprise SCIM Profile 1.0 October 2020 { "urn:ietf:params:fastfed:1.0:provisioning:scim:2.0:enterprise": { "scim_service_uri": "https://tenant-56789.app.example.com/scim", "provider_authentication_method": ..., } } 3.2.2.1. Usage of the OAuth-2.0 JWT Profile The selection of this authentication method is indicated by setting the value of "provider_authentication_method" to be: ""urn:ietf:params:fastfed:1.0:provider_authentication:oauth:2.0:jwt_p rofile"" In addition, a member with the same name as this URN is included in the response. The value of the element is a structure with the following members: token_endpoint REQUIRED. Contains the URL of the Application Provider's OAuth 2.0 token endpoint. scope REQUIRED. Contains the OAuth scope parameter to be provided to the OAuth 2.0 token endpoint when requesting an access token. The OAuth scope MUST authorize the SCIM client to perform all provisioning activities specified by this profile. The following is a non-normative example of the contents of a registration response message using the OAuth 2.0 JWT Profile: { "urn:ietf:params:fastfed:1.0:provisioning:scim:2.0:enterprise": { "scim_service_uri": "https://tenant-56789.app.example.com/scim", "provider_authentication_method": "urn:ietf:params:fastfed:1.0:provider_authentication:oauth:2.0:jwt_profile", "urn:ietf:params:fastfed:1.0:provider_authentication:oauth:2.0:jwt_profile": { "token_endpoint": "https://tenant-56789.app.example.com/oauth", "scope": "scim" } } } See Section 5 for an end-to-end example of authenticating via the OAuth 2.0 JWT profile. 4. Interoperability Requirements Each identity standard defines a set of optional features to enable usage in a wide variety of circumstances. McAdams Expires April 10, 2021 [Page 10] FastFed Enterprise SCIM Profile 1.0 October 2020 However, a consequence of the flexibility is that two Providers may find themselves incompatible despite sharing the same protocols. To deliver the simplified experience that is the goal of FastFed, it is important that two FastFed-enabled Providers have confidence that they can interoperate when sharing the same protocols. The following sections describe the subset of the SCIM Protocol specifications that Providers MUST implement to be FastFed Compatible for this profile. Providers MAY support additional functionality, but MUST NOT require the additional functionality when configuring federation with another Provider using the FastFed specifications. 4.1. General Requirements The Identity Provider MUST: o Implement the required functionality of a SCIM Client as defined in RFC 7643 [RFC7643] and RFC 7644 [RFC7644]. o Authenticate to the SCIM endpoint using the method negotiated during the FastFed registration exchange. (Section 3.2.1 and Section 3.2.2). The Application Provider MUST: o Implement the required functionality of a SCIM Service Provider as defined in RFC 7643 [RFC7643] and RFC 7644 [RFC7644]. o Authenticate the client using the method negotiated during the FastFed registration exchange. (Section 3.2.1 and Section 3.2.2). The "groups" attribute on the User resource is not used in this FastFed Profile. Any SCIM operation containing a User resource in the contents MUST NOT include the "groups" attribute on the User entity. 4.2. User Provisioning Application Providers MUST support all the User provisioning operations defined in this section. Identity Providers SHOULD replicate User information to the Application Provider within 60 minutes of the User being created or updated, and MAY use any combination of the operations to accomplish the User provisioning. McAdams Expires April 10, 2021 [Page 11] FastFed Enterprise SCIM Profile 1.0 October 2020 4.2.1. Create User User creation is performed via the SCIM operation: "PUT /Users" If multiple values are provided for the User attributes ""emails"", ""phoneNumbers"", or ""addresses"", then the Identity Provider MUST specify one value in the list as ""primary=true"". If only a single value is provided, the Application Provider MAY treat the single value as the primary if not explicitly labeled as such. The following is a non-normative example of creating a User: POST /Users HTTP/1.1 Host: example.com Accept: application/scim+json Content-Type: application/scim+json Authorization: Bearer h480djs93hd8 Content-Length: ... { "schemas":[ "urn:ietf:params:scim:schemas:core:2.0:User", "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User" ], "externalId": "98d78581-dd0d-4361-ab61-9511c6e5f035", "userName":"bjensen", "name":{ "formatted":"Ms. Barbara J Jensen III", "familyName":"Jensen", "givenName":"Barbara" } "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": { "costCenter":"12345", "manager":{"value": "0cca76a8-090a-4944-8e61-e7791e619d48"} } } 4.2.2. Update User User updates are performed via the SCIM operation: "PATCH /Users/{id}" The following is a non-normative example of updating a User: McAdams Expires April 10, 2021 [Page 12] FastFed Enterprise SCIM Profile 1.0 October 2020 PATCH /Users/{id} HTTP/1.1 Host: example.com Accept: application/scim+json Content-Type: application/scim+json Authorization: Bearer h480djs93hd8 Content-Length: ... { "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], "Operations": [ { "op": "replace" "path": "name.formatted" "value": "Babs Jensen" }, { "op": "replace" "path": "addresses[type eq \"work\"].streetAddress" "value": "1010 Broadway Ave" }, ] } 4.2.3. Deactivate or Reactivate User Changes to the user activation status are performed via the SCIM operation: "PATCH /Users/{id}" The Identity Provider SHOULD propagate user deactivation events to the Application Provider within 5 minutes of the user being deactivated. The Application Provider SHOULD respond to user deactivation events by revoking the ability for the user to continue accessing the Application, including the revocation of currently active sessions. The revocation mechanism is an implementation detail outside the scope of this specification. Revocation SHOULD occur within 5 minutes of receiving the deactivation. The Application Provider MUST allow reactivation of a deactivated user. The following is a non-normative example of deactivating a User: McAdams Expires April 10, 2021 [Page 13] FastFed Enterprise SCIM Profile 1.0 October 2020 PATCH /Users/{id} HTTP/1.1 Host: example.com Accept: application/scim+json Content-Type: application/scim+json Authorization: Bearer h480djs93hd8 Content-Length: ... { "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], "Operations": [{ "op": "replace" "path": "active" "value": false }] } The following is a non-normative example of reactivating a User: PATCH /Users/{id} HTTP/1.1 Host: example.com Accept: application/scim+json Content-Type: application/scim+json Authorization: Bearer h480djs93hd8 Content-Length: ... { "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], "Operations": [{ "op": "replace" "path": "active" "value": true }] } 4.2.4. Delete User User deletions are performed via the SCIM operation: "DELETE /Users/{id}" Identity Providers SHOULD delete users when they have reason to believe the User will not be reactivated in the future. This may occur, for example, when a userName is recycled and given to a new actor, necessitating removal of the prior record. After a user is deleted, Application Providers MUST allow the creation of a new user with the same userName. The following is a non-normative example of deleting a User: McAdams Expires April 10, 2021 [Page 14] FastFed Enterprise SCIM Profile 1.0 October 2020 DELETE /Users/{id} Host: example.com Authorization: Bearer h480djs93hd8 4.2.5. Get User By Id User lookups by id are performed via the SCIM operation: "GET /Users/{id}" The following is a non-normative example of retrieving a User by id: GET /Users/{id} Host: example.com Accept: application/scim+json Authorization: Bearer h480djs93hd8 HTTP/1.1 200 OK Content-Type: application/scim+json { "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"], "meta":{ "resourceType":"User", "created":"2011-08-01T18:29:49.793Z", "lastModified":"2011-08-01T18:29:49.793Z", "version":"W\/\"f250dd84f0671c3\"" }, "id":"2819c223-7f76-453a-919d-413861904646", "externalId": "98d78581-dd0d-4361-ab61-9511c6e5f035", "userName":"bjensen", "name":{ "formatted":"Ms. Barbara J Jensen III", "familyName":"Jensen", "givenName":"Barbara" }, "emails":[ { "value":"bjensen@example.com", "type":"work" "primary":true } ] } McAdams Expires April 10, 2021 [Page 15] FastFed Enterprise SCIM Profile 1.0 October 2020 4.2.6. List Users By Alternate Identifier User lookups by alternate identifier are performed via the SCIM operation: "GET /Users?filter={filterExpression}" Application Providers MUST support the following filter expressions: o "userName eq {userName}" o "externalId eq {externalId}" o "emails[value eq {email}]" The following is a non-normative example of retrieving Users by username: GET /Users?filter=userName+eq+bjensen Host: example.com Accept: application/scim+json Authorization: Bearer h480djs93hd8 McAdams Expires April 10, 2021 [Page 16] FastFed Enterprise SCIM Profile 1.0 October 2020 HTTP/1.1 200 OK Content-Type: application/scim+json { "schemas":["urn:ietf:params:scim:api:messages:2.0:ListResponse"], "totalResults":1, "Resources":[ { "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"], "meta":{ "resourceType":"User", "created":"2011-08-01T18:29:49.793Z", "lastModified":"2011-08-01T18:29:49.793Z", "version":"W\/\"f250dd84f0671c3\"" }, "id":"2819c223-7f76-453a-919d-413861904646", "externalId": "98d78581-dd0d-4361-ab61-9511c6e5f035", "userName":"bjensen", "name":{ "formatted":"Ms. Barbara J Jensen III", "familyName":"Jensen", "givenName":"Barbara" }, "emails":[ { "value":"bjensen@example.com", "type":"work" } ] } ] } 4.3. Group Provisioning Application Providers MAY support Group Provisioning. Support is indicated by including values for "required_group_attributes" and "optional_group_attributes" in the desired attributes, as specified in Section 3.1.2. In addition, the Application Provider must include Groups as a supported resource type in the response from the SCIM /ResourceTypes endpoint, as defined in Section 4 of the SCIM Protocol [RFC7644]. If the Application Provider supports Groups, it MUST implement all the Group provisioning operations defined in this section. McAdams Expires April 10, 2021 [Page 17] FastFed Enterprise SCIM Profile 1.0 October 2020 If an Identity Provider holds information about Groups, then it MUST implement provisioning of the Group information to Applications who support it. Before initiating Group provisioning, the Identity Provider MUST query the Application Provider's SCIM /ResourceTypes endpoint to confirm Groups are supported by the Application. As a reference to implementors, this check can occur when the FastFed Handshake completes, on-or-after Section 7.2.4.4 of the FastFed Core [FastFed.Core] specification. If both the Identity Provider and the Application Provider support Group provisioning, the Identity Provider SHOULD replicate Group information to the Application Provider within 60 minutes of the Group being created or updated. Identity Providers MAY use any combination of the operations to perform Group provisioning. 4.3.1. Create Group Group creation is performed via the SCIM operation: "POST /Groups " The Identity Provider MUST NOT include a value for the "members" attribute. See Section 4.3.7 for information on Group membership changes. The following is a non-normative example of creating a Group: POST /Groups HTTP/1.1 Host: example.com Accept: application/scim+json Content-Type: application/scim+json Authorization: Bearer h480djs93hd8 Content-Length: ... { "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"], "externalId": "e5a41517-bcd6-4b8b-8590-487ae996de44", "displayName": "ExampleGroup" } 4.3.2. Update Group Metadata Group updates are performed via the SCIM operation: "PATCH " The Identity Provider MUST NOT update the "members" attribute of a Group in the same PATCH request that updates other Group attributes. See Section 4.3.7 for information on Group membership changes. McAdams Expires April 10, 2021 [Page 18] FastFed Enterprise SCIM Profile 1.0 October 2020 The following is a non-normative example of updating a Group: PATCH /Groups/{id} HTTP/1.1 Host: example.com Accept: application/scim+json Content-Type: application/scim+json Authorization: Bearer h480djs93hd8 Content-Length: ... { "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], "Operations": [ { "op": "replace", "path": "externalId", "value": "{newExternalId}" }, { "op": "replace", "path": "displayName", "value": "{newDisplayName}" } ] } 4.3.3. Deactivate Group Unlike User resources, SCIM does not define a mechanism to softly deactivate a Group prior to permanent deletion. However, experience has demonstrated that jumping straight to permanent deletion can have undesired repercussions for user entitlements in an Application that are based on group membership. If the Group deletion was in error, it cannot be easily undone. The end-users have lost access and the entitlements inside the Application must be re-established from scratch under a new group id. To provide increased safety, and simulate an undo window, it is RECOMMENDED that Identity Providers first remove all group members, wait a period of time, and then permanently delete the group when comfortable with the action. The wait period is an implementation detail. Identity Providers MAY also allow the empty group to exist for a longer duration and delete only when necessary, such as when a new group is being created with a recycled name that requires cleanup of the prior record. McAdams Expires April 10, 2021 [Page 19] FastFed Enterprise SCIM Profile 1.0 October 2020 To allow this behavior, Application Providers MUST support removing all Group members via the SCIM operation "PATCH Groups/{id}" with an "Operation" element containing the following contents: o The "op" attribute set to ""remove"". o The "path" attribute set to ""members"". o The "value" attribute unspecified. The following is a non-normative example of removing all Group members: PATCH /Groups/{id} HTTP/1.1 Host: example.com Accept: application/scim+json Content-Type: application/scim+json Authorization: Bearer h480djs93hd8 Content-Length: ... { "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], "Operations": [{ "op": "remove" "path": "members" }] } 4.3.4. Delete Group Group deletions are performed via the SCIM operation: "DELETE Group/{id}" The following is a non-normative example of deleting a Group: DELETE /Groups/{id} HTTP/1.1 Host: example.com Accept: application/scim+json Content-Type: application/scim+json Authorization: Bearer h480djs93hd8 4.3.5. Get Group By Id Group lookups by id are performed via the SCIM operation: "GET /Group/{id}?excludedAttributes=members" The following is a non-normative example of retrieving a Group by id: McAdams Expires April 10, 2021 [Page 20] FastFed Enterprise SCIM Profile 1.0 October 2020 GET /Groups/{id}?excludedAttributes=members Host: example.com Accept: application/scim+json Authorization: Bearer h480djs93hd8 HTTP/1.1 200 OK Content-Type: application/scim+json { "schemas":["urn:ietf:params:scim:schemas:core:2.0:Group"], "meta":{ "resourceType":"Group", "created":"2011-08-01T18:29:49.793Z", "lastModified":"2011-08-01T18:29:49.793Z", "version":"W\/\"f250dd84f0671c3\"" }, "id":"d637f86b-9171-4b2b-9fa8-15d552604e6f", "externalId": "530eb5eb-0ccf-4312-85d8-db1423a10b2a", "displayName":"ExampleGroup" } 4.3.6. List Groups By Alternate Identifier Group lookups by alternate identifier are performed via the SCIM operation: "GET /Groups?filter={filterExpression}&excludedAttributes=members" Application Providers MUST support the following filter expressions: o "displayName eq {displayName}" The following is a non-normative example of retrieving Groups by displayName: GET /Groups?filter=displayName+eq+ExampleGroup&excludedAttributes=members Host: example.com Accept: application/scim+json Authorization: Bearer h480djs93hd8 McAdams Expires April 10, 2021 [Page 21] FastFed Enterprise SCIM Profile 1.0 October 2020 HTTP/1.1 200 OK Content-Type: application/scim+json { "schemas":["urn:ietf:params:scim:api:messages:2.0:ListResponse"], "totalResults":1, "Resources":[ { "schemas":["urn:ietf:params:scim:schemas:core:2.0:Group"], "meta":{ "resourceType":"Group", "created":"2011-08-01T18:29:49.793Z", "lastModified":"2011-08-01T18:29:49.793Z", "version":"W\/\"f250dd84f0671c3\"" }, "id":"d637f86b-9171-4b2b-9fa8-15d552604e6f", "externalId": "530eb5eb-0ccf-4312-85d8-db1423a10b2a", "displayName":"ExampleGroup" } ] } 4.3.7. Add or Remove Group Members Members are added or removed from Groups via the SCIM operation: "PATCH /Groups/{id}" For each "Operation" in the PATCH: o The "op" attribute MUST contain either ""add"" or ""remove"". o When the "op" is ""add"": * The "path" attribute MUST be ""members"". * The "value" attribute MUST be an array of Group "member" elements, as defined in Section 4.2 of the SCIM Core Schema [RFC7643]. Each member MUST contain a "value" subattribute with the "id" of the resource being added to the group. o When the "op" is ""remove"": * The "path" attribute MUST be either: + ""members"" (to remove all members) + ""members[value eq \"{id}\"]"" (to remove a single member) McAdams Expires April 10, 2021 [Page 22] FastFed Enterprise SCIM Profile 1.0 October 2020 * The "value" attribute MUST be unspecified. The number of membership changes in a PATCH request MUST NOT exceed the value of "max_group_membership_changes", as defined in Section 3.1.2. The number of changes is determined by counting the total members being added/removed, summed across all operations in the PATCH. The truncation of all members in the group via the "remove" operation on the "members" attribute is counted as one change, and if included, MUST be the first operation in the PATCH. If the Application Provider supports nested groups, as indicated by the attribute "can_support_nested_groups" defined in Section 3.1.2, the resource being added to the Group members MAY be either a User or Group. Alternatively, if the Application Provider does not support nested groups, the resource type MUST be a User. If an Administrator seeks to provision a nested group to an Application Provider that does not support nested groups, the handling of this scenario is an implementation detail outside the scope of the specification. As a reference to implementors, the Identity Provider can consider signaling an error to the Administrator, or flattening the nested group memberships into a single array for provisioning. The same resource "id" MUST NOT appear more than once in a single PATCH request. For example, a resource should not be added and removed in a single PATCH, or added multiple times. If any membership change in the PATCH results in an error, the Application Provider SHOULD stop processing and return the error response. If the Identity Provider receives an error response from the PATCH request, it SHOULD assume that none of the changes in the PATCH were committed and retry as appropriate. If the Application Provider receives a PATCH request to add a resource to a group to which the resource already belongs, or remove a resource from a group from which it doesn't belong, the Application Provider MUST behave idempotently and return a successful response. The following is a non-normative example of adding and removing members of a Group: McAdams Expires April 10, 2021 [Page 23] FastFed Enterprise SCIM Profile 1.0 October 2020 PATCH /Groups/{id} HTTP/1.1 Host: example.com Accept: application/scim+json Content-Type: application/scim+json Authorization: Bearer h480djs93hd8 Content-Length: ... { "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], "Operations": [ { "op": "remove", "path": "members[value eq \"{user_id_1}\"]", }, { "op": "remove", "path": "members[value eq \"{user_id_2}\"]", }, { "op": "add", "path": "members", "value": [ {"value": "{user_id_3}"}, {"value": "{user_id_4}"} ] } ] } 4.4. Metadata Endpoints 4.4.1. ResourceTypes Application Providers MUST host a /ResourceTypes endpoint, as defined in Section 4 of RFC 7644 [RFC7644]. The supported ResourceTypes MUST include Users. It MAY include Groups. 4.4.2. ServiceProviderConfig Application Providers MUST host a /ServiceProviderConfig endpoint to describe the operations they support, as defined in Section 4 of RFC 7644 [RFC7644]. The operations MUST include, at minimum, the set of SCIM capabilities required for compatibility with this FastFed Profile. McAdams Expires April 10, 2021 [Page 24] FastFed Enterprise SCIM Profile 1.0 October 2020 Additional capabilities MAY be supported, but are not required for FastFed compatibility. 4.4.3. Schemas Application Providers MUST host a /Schemas endpoint to describe the supported schemas, as defined in Section 4 of RFC 7644 [RFC7644]. There MUST exist a schema definition for every attribute listed in the "desired_attributes", as described in Section 3.1.2. 5. Example Usage of the OAuth 2.0 JWT Profile The following end-to-end example illustrates the message flows when using the authentication method ""urn:ietf:params:fastfed:1.0:provide r_authentication:oauth:2.0:jwt_profile"". This method enables a SCIM client to invoke a SCIM service using OAuth access tokens derived from public/private key pairs. 5.1. Identity Provider Shares Public Key As a first-step, the Identity Provider shares a public key with the Application Provider in the form of a JSON Web key Set [JWK] [RFC7517]. This occurs during the FastFed Handshake (see "jwks_uri", below) and is described in Section 3.2.1 of this specification. { "iss": "https://tenant-12345.idp.example.com", "aud": "https://tenant-67890.app.example.com", "exp": 1234567890, "provisioning_profiles": [ "urn:ietf:params:fastfed:1.0:provisioning:scim:2.0:enterprise" ], "urn:ietf:params:fastfed:1.0:provisioning:scim:2.0:enterprise": { "provider_contact_information": { "organization": "Example Inc.", "phone": "+1-800-555-5555", "email": "support@example.com" }, "provider_authentication_methods": { "urn:ietf:params:fastfed:1.0:provider_authentication:oauth:2.0:jwt_profile": { "jwks_uri": "https://provisioning.example.com/keys" } } } } McAdams Expires April 10, 2021 [Page 25] FastFed Enterprise SCIM Profile 1.0 October 2020 Upon receiving this information, the Application Provider may internally perform an OAuth client registration in order to capture the provider's contact information and "jwks_uri", and authorize the Provider to perform SCIM provisioning activities. This is an implementation detail. FastFed does not require the exchange of an OAuth clientID. 5.2. Application Provider Shares SCIM and OAuth Endpoints Subsequently in the FastFed Handshake, the Application Provider returns SCIM and OAuth metadata back to the Identity Provider. This is described in Section 3.2.2 of this specification. { "urn:ietf:params:fastfed:1.0:provisioning:scim:2.0:enterprise": { "scim_service_uri": "https://tenant-56789.app.example.com/scim", "provider_authentication_method": "urn:ietf:params:fastfed:1.0:provider_authentication:oauth:2.0:jwt_profile", "urn:ietf:params:fastfed:1.0:provider_authentication:oauth:2.0:jwt_profile": { "token_endpoint": "https://tenant-56789.app.example.com/oauth", "scope": "scim" } } } 5.3. Identity Provider Acquires an OAuth Access Token After the FastFed Handshake is complete and the Identity Provider is ready to begin calling the SCIM endpoint, it must first acquire an OAuth "access_token". This will be used to authenticate to the SCIM endpoint. The "access_token" is acquired by using the JWT Authorization Grant Type. This grant type is defined in RFC 7523 [RFC7523], and its usage within FastFed is specified in Section 6.6 of the FastFed Core [FastFed.Core] specification. In essence, the Identity Provider sends a signed JWT to the OAuth endpoint hosted by the Application Provider. If the JWT is valid and is signed by an authorized party, an OAuth access_token is returned. This is illustrated in the following steps. First, a JWT is constructed with the following contents: { "iss": "https://tenant-12345.idp.example.com", "aud": "https://tenant-56789.app.example.com", "exp": 1234567890, } McAdams Expires April 10, 2021 [Page 26] FastFed Enterprise SCIM Profile 1.0 October 2020 Next, a request is made to the OAuth token endpoint, using the signed and serialized JWT as the value of the "assertion". { POST /oauth HTTP/1.1 Host: tenant-56789.app.example.com Content-Type: application/x-www-form-urlencoded grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer &assertion=eyJhbGciOiJFUzI1NiIsImtpZCI6IjE2In0. eyJpc3Mi[...omitted for brevity...]. J9l-ZhwP[...omitted for brevity...] } In response, an OAuth token is returned: HTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8 Cache-Control: no-store Pragma: no-cache { "access_token":"2YotnFZFEjr1zCsicMWpAA", "token_type":"Bearer", "expires_in":3600 } 5.4. Identity Provider Uses the OAuth Access Token Finally, the token can be used to authenticate to the SCIM endpoint: POST scim/Users HTTP/1.1 Host: tenant-56789.app.example.com Accept: application/scim+json Content-Type: application/scim+json Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA Content-Length: ... { "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"], "userName":"bjensen", "externalId":"bjensen", "name":{ "formatted":"Ms. Barbara J Jensen III", "familyName":"Jensen", "givenName":"Barbara" } } McAdams Expires April 10, 2021 [Page 27] FastFed Enterprise SCIM Profile 1.0 October 2020 When the access token expires, the SCIM service returns an HTTP 401 response code. The JWT Authorization Grant flow may then be re- executed to acquire a new access token. 6. Security Considerations For SCIM security considerations, see RFC 7643 [RFC7643] and RFC 7644 [RFC7644]. For FastFed security considerations, see Section 8 of FastFed Core [FastFed.Core]. 7. IANA Considerations Pending 8. Normative References [FastFed.Core] McAdams, K., "FastFed Core 1.0", October 2020, . [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517, DOI 10.17487/RFC7517, May 2015, . [RFC7523] Jones, M., Campbell, B., and C. Mortimore, "JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants", RFC 7523, DOI 10.17487/RFC7523, 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, . McAdams Expires April 10, 2021 [Page 28] FastFed Enterprise SCIM Profile 1.0 October 2020 Appendix A. Acknowledgements The OpenID Community would like to thank the following people for their contributions to this specification: Brian Campbell (bcampbell@pingidentity.com), Ping Identity Zhen Chien Chia (chiazhenchien@outlook.com), Microsoft Pamela Dingle (pamela.dingle@microsoft.com), Microsoft Matt Domsch (matt.domsch@sailpoint.com), SailPoint Wesley Dunnington (wesleydunnington@pingidentity.com), Ping Identity Erik Gustavson (erikgustavson@google.com), Google Dick Hardt (dick.hardt@gmail.com), Independent Romain Lenglet (rlenglet@google.com), Google Karl McGuinness (kmcguinness@okta.com), Okta Chuck Mortimore (cmortimore@salesforce.com), Salesforce Brian Rose (brian.rose@sailpoint.com), SailPoint Appendix B. Notices Copyright (c) 2020 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 McAdams Expires April 10, 2021 [Page 29] FastFed Enterprise SCIM Profile 1.0 October 2020 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. Author's Address Darin K. McAdams Amazon Email: darinm@amazon.com McAdams Expires April 10, 2021 [Page 30]