| D. McAdams | |
| Amazon | |
| October 7, 2020 |
FastFed Enterprise SCIM Profile 1.0 - draft 03
fastfed-scim-1_0
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.
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 specification:
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.
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.
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.
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.
This specification extends the FastFed Core metadata (Section 3.3.1) with the following value for provisioning_profiles:
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"],
...
}
This specification extends the Application Provider Metadata defined in Section 3.3.9 of 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:
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:
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"
],
"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"
]
}
}
}
}
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.
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:enterprise".
The value of the element is a structure with the following members:
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,
"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...}
]
}
}
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:
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,
"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"
}
}
]
}
}
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:enterprise"
The value of the element is a structure with the following members:
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:enterprise": {
"scim_service_uri": "https://tenant-56789.app.example.com/scim",
"provider_authentication_method": ...,
}
}
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:
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.
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.
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.
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.
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"}
}
}
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"
},
]
}
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
}]
}
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
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
}
]
}
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"
}
]
}
]
}
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.
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 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.
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"
}
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}"
}
]
}
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"
}]
}
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
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"
}
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:
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"
}
]
}
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}"}
]
}
]
}
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.
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.
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.
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.
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,
"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"
}
}
}
}
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.
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"
}
}
}
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
}
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.
For SCIM security considerations, see RFC 7643 and RFC 7644.
For FastFed security considerations, see Section 8 of FastFed Core.
Pending
| [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., 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. |
The OpenID Community would like to thank the following people for their contributions to this specification:
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.