D. McAdams
Amazon
March 9, 2020

FastFed Basic SCIM Profile 1.0 - draft 02
fastfed-scim-1_0

Abstract

This specification defines the requirements to implement the FastFed Profile for SCIM 2.0 Basic provisioning. This profile supports continual provisioning, update, and deprovisioning of end-users between the Identity Provider and Application Provider.


Table of Contents

1. Introduction

This specification defines the functionality which a provider must implement to satisfy the FastFed Profile for SCIM 2.0 Basic provisioning.

It consists of the following extensions to the FastFed Core specification:

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.

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.

1.2. Terminology

This FastFed Profile uses the terminology defined in Section 1.2 of the FastFed Core specification.

The terms "SCIM", "SCIM client", and "SCIM service" refer to the terminology defined in RFC 7644.

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 specification, the use of asymmetric key pairs is preferred over long-lived shared secrets. As a result, this profile uses RFC 7523 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 is provided in Section 5.

3. Protocol Extensions

3.1. FastFed Metadata

3.1.1. Provisioning Profile URN

This specification extends the FastFed Core metadata (Section 3.3.1) with the following value for provisioning_profiles:

urn:ietf:params:fastfed:1.0:provisioning:scim:2.0:basic
A Provider 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:basic"],
   ...
 }

3.1.2. Application Metadata

This specification extends the Application Provider Metadata defined in Section 3.3.8 of FastFed Core with an additional member having the name:

"urn:ietf:params:fastfed:1.0:provisioning:scim:2.0:basic".

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.

When using this profile, the Application Provider MUST include the following SCIM Core User attribute in the list of required_user_attributes:

If the Application Provider supports Group provisioning, it MUST:

If the Application Provider does not support Group provisioning, it MUST omit the following from the desired 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:basic"
       ],
       "schema_grammars": [
         "urn:ietf:params:fastfed:1:0:schemas:scim:2.0"
       ],
       "signing_alg_values_supported": [
         "ES512",
         "RS256"
       ]
     },
     "fastfed_handshake_register_uri": "https://tenant-67890.app.example.com/fastfed/register",

     "urn:ietf:params:fastfed:1.0:provisioning:scim:2.0:basic": {
       "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.

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 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) with an additional member sharing the same name as the profile:

"urn:ietf:params:fastfed:1.0:provisioning:scim:2.0:basic".

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.

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:

 {
   "iss": "https://tenant-12345.idp.example.com",
   "aud": "https://tenant-67890.app.example.com",
   "exp": 1234567890,
   "schema_grammar": "urn:ietf:params:fastfed:1:0:schemas:scim:2.0",
   "provisioning_profiles": [
     "urn:ietf:params:fastfed:1.0:provisioning:scim:2.0:basic"
   ],
   "urn:ietf:params:fastfed:1.0:provisioning:scim:2.0:basic": {
     "provider_contact_information": {
       "organization": "Example Inc.",
       "phone": "+1-800-555-5555",
       "email": "support@example.com"
     },
     "provider_authentication_methods": {
        ...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_profile"

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] 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:

 {
   "iss": "https://tenant-12345.idp.example.com",
   "aud": "https://tenant-67890.app.example.com",
   "exp": 1234567890,
   "schema_grammar": "urn:ietf:params:fastfed:1:0:schemas:scim:2.0",
   "provisioning_profiles": [
     "urn:ietf:params:fastfed:1.0:provisioning:scim:2.0:basic"
   ],
   "urn:ietf:params:fastfed:1.0:provisioning:scim:2.0:basic": {
     "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"
       }
     }
   }
 }

3.2.2. FastFed Registration Response

This specification extends the contents of the FastFed Registration Response (Section 7.2.3.3 of FastFed Core) with an additional member sharing the same name as the profile:

"urn:ietf:params:fastfed:1.0:provisioning:scim:2.0:basic"

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:

 {
   "urn:ietf:params:fastfed:1.0:provisioning:scim:2.0:basic": {
     "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_profile"

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:basic": {
     "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.

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:

The Application Provider MUST:

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.

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:

 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:

 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:

 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
     }
   ]   
 }

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:

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
 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.

The Identity Provider MUST query the Application Provider's SCIM /ResourceTypes endpoint to determine if Groups are supported. 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 specification.

If the Application Provider supports 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.

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.

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:

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:

 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

User lookups by alternate identifier are performed via the SCIM operation: GET /Groups?filter={filterExpression}&excludedAttributes=members

Application Providers MUST support the following filter expressions:

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
 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:

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:

 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.

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.

The operations MUST include, at minimum, the set of SCIM capabilities required for compatibility with this FastFed Profile.

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.

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:provider_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]. 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,
   "schema_grammar": "urn:ietf:params:fastfed:1:0:schemas:scim:2.0",
   "provisioning_profiles": [
     "urn:ietf:params:fastfed:1.0:provisioning:scim:2.0:basic"
   ],
   "urn:ietf:params:fastfed:1.0:provisioning:scim:2.0:basic": {
     "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"
       }
     }
   }
 }

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:basic": {
     "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, and its usage within FastFed is specified in Section 6.6 of the 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,            
 }

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"
     }
   }

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 and RFC 7644.

For FastFed security considerations, see Section 8 of FastFed Core.

7. IANA Considerations

Pending

8. Normative References

[FastFed.Core] McAdams, K., "FastFed Core 1.0", March 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., 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., Grizzle, K., Ansari, M., Wahlstroem, E. and C. Mortimore, "System for Cross-domain Identity Management: Protocol", RFC 7644, DOI 10.17487/RFC7644, September 2015.

Appendix A. Acknowledgements

The OpenID Community would like to thank the following people for their contributions to this specification:

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 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