FastFed Enterprise SCIM Profile
1.0 - draft 03Amazondarinm@amazon.comFastFed Working Group
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:
Additional metadata in the FastFed Handshake Flows to exchange SCIM
provisioning information and authentication credentials.
An interoperability profile describing the subset of the SCIM
specifications which must be implemented.
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 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
.
This specification extends the FastFed
Core metadata (Section 3.3.1) with the following value
for provisioning_profiles:
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:
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:
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:
externalIduserNameactive
If the Application Provider supports Group provisioning, it MUST:
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
.
If the Application Provider does not support Group provisioning, it
MUST omit the following from the desired attributes:
required_group_attributesoptional_group_attributes
OPTIONAL. Boolean value indicating whether the Application Provider supports
provisioning of nested Group memberships. The default value
is false. See
for details on Group membership provisioning.
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
for details on Group membership provisioning.
The following is a non-normative example of Application Provider Metadata with
the profile extensions:
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
.
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
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:
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.
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
) and MAY
support additional methods.
The following is a non-normative example of the contents of a
registration request message:
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:
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:
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:
REQUIRED. Contains the URL of the Application Provider's
SCIM Endpoint.
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:
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:
REQUIRED. Contains the URL of the Application Provider's
OAuth 2.0 token endpoint.
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:
See 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:
Implement the required functionality of a SCIM Client as
defined in RFC 7643
and RFC 7644.
Authenticate to the SCIM endpoint using the method negotiated
during the FastFed registration exchange.
( and
).
The Application Provider MUST:
Implement the required functionality of a SCIM Service
Provider as defined in RFC 7643
and RFC 7644.
Authenticate the client using the method negotiated
during the FastFed registration exchange.
( and
).
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:
User updates are performed via the SCIM operation:
PATCH /Users/{id}
The following is a non-normative example of updating a 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:
The following is a non-normative example of reactivating a 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:
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:
User lookups by alternate identifier are performed via the SCIM operation:
GET /Users?filter={filterExpression}
Application Providers MUST support the following filter expressions:
userName eq {userName}externalId eq {externalId}emails[value eq {email}]
The following is a non-normative example of retrieving Users by username:
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
. 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 .
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
for information on Group membership changes.
The following is a non-normative example of creating a Group:
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
for information on Group membership changes.
The following is a non-normative example of updating a 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 op attribute set to
"remove".
The path attribute set to
"members".
The value attribute
unspecified.
The following is a non-normative example of removing all Group
members:
Group deletions are performed via the SCIM operation:
DELETE Group/{id}
The following is a non-normative example of deleting a Group:
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:
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:
displayName eq {displayName}
The following is a non-normative example of retrieving Groups by
displayName:
Members are added or removed from Groups via the SCIM operation:
PATCH /Groups/{id}
For each Operation in the PATCH:
The op attribute MUST
contain either "add"
or "remove".
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 . Each member
MUST contain a
value subattribute with
the id of the resource being added to
the group.
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)
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 . 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 , 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:
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 .
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 of
this specification.
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 of
this specification.
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:
Next, a request is made to the OAuth token endpoint, using the signed
and serialized JWT as the value of
the assertion.
In response, an OAuth token is returned:
Finally, the token can be used to authenticate to the SCIM endpoint:
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 1.0Amazon
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
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.