| Internet Engineering Task Force | M. Wahl, Ed. |
| Internet-Draft | Microsoft Corporation |
| Intended status: Standards Track | June 21, 2019 |
| Expires: December 23, 2019 |
SCIM Profile for Provisioning Users Into Relying Party Applications
draft-wahl-scim-profile-00
This document specifies a profile of the System for Cross-Domain Identity Management Protocol (SCIM). This profile defines how an identity provider, acting as a SCIM client, can notify a relying party application of changes to user accounts.
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."
This Internet-Draft will expire on December 23, 2019.
Copyright (c) 2019 IETF Trust and the persons identified as the document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.
Relying party applications implement single-sign on protocols, such as SAML or OpenID Connect, for user authentication from an identity provider, and often store one or more attributes about each of user identities from those identity providers. The term relying party is defined in OpenID Connect. The single sign in flows between an identity provider and a relying party often allow the identity provider to include one or more attributes about a user signing in, such as their name, at the time of the sign in event. However, those attributes might also change, and those changes be relevant, to a relying party application, even when no user is signing in. For example, if an identity provider deletes a user, then the relying party application would never see a subsequent sign in event from that user.
The SCIM protocol RFC 7644 is an application-level, REST protocol for provisioning and managing identity data on the web. SCIM can be leveraged for many use cases, including transfer of attributes about users to a relying party application (see RFC 7643 section 3). This profile describes how SCIM can be used between an identity provider and a relying party application, so the identity provider can notify a relying party application acting as a SCIM server of changes to user accounts, out of band from the normal sign-in flow of those users. . This profile defines the interactions between an identity provider as the initiator, a SCIM client, and a replying party application, as the SCIM server, in the following scenario:
Based on this profile, the identity provider acts as a SCIM client and sends the changes via the SCIM protocol to the application acting as a SCIM server. The relying party application represents each user account in its database which is visible to the identity provider, as a SCIM User resource. This enables the relying party application to have a more up-to-date copy of users with its identity provider, than if it was only being updated when a user signs in.
For example, if the identity provider deletes a user, this deletion event can be transferred to the relying party application via SCIM, so that the application also cleans up any data associated with that user -- who won't be accessing that application in future. Or, for another example, if the user changes their name in the identity provider, then this change can be sent to the application, so that the user's name is displayed correctly within the application to other users.
This profile is not intended to be a comprehensive or bidirectional replication protocol; instead, it provides basic consistency for user resources sent from an identity provider to a relying party, necessary for a user to be able to sign into the relying party. Management of other resource types besides users is outside the scope of this profile.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.
A SCIM client in an identity provider will, either upon specific changes in its database (e.g., when there is a new user), or at intervals, send queries and changes to the relying party application's SCIM server. This section covers the basic requirements for a SCIM client and server implementation. The sections following this one cover the schema requirements, the pattern of operations in this profile, and security considerations.
A SCIM client and server MUST support HTTPS. A SCIM client and SCIM server MUST have previously agreed on the HTTPS URI for the SCIM server's "Users" endpoint, below the Base URI (Base URI is defined in section 1.3 of RFC 7644). Additionally, the client and server MAY have also previously agreed on the HTTPS URIs for the SCIM server's "ResourceTypes" and "Schemas" endpoints. These URI MAY contain the string "v2", for example "https://api.example.com/scim/tenant/example.org/v2/Users" might be a base endpoint for Users in a particular application.
A SCIM client implementing this profile MUST use JSON-structured request bodies and expect JSON-structured responses using the UTF-8 RFC 3629 encoding, in the Content-Type "application/scim+json".
These are to be sent via HTTPS using TLS, RFC 8446.
This profile is intended for service-to-service communication: a SCIM client is not acting under the context of an individual person, it is operating on behalf of the identity provider.
A SCIM client and a SCIM server SHOULD support one or more authentication mechanisms to authenticate a SCIM client to a SCIM server. One mechanism SHOULD be bearer tokens.
If a SCIM client supports bearer tokens, then the client SHOULD include the token in the Authorization header of each request, as described in section 2.1 of RFC 6750. This profile does not cover establishing common authentication keys, which is assumed to occur out of band.
A SCIM server does not need to support operations by un-authenticated clients. A SCIM server MUST only permit a client to query, create, update and delete one or more User resources, after the token is validated.
If a SCIM server supports multiple tenants, then the operations defined in this profile are relative to a single tenant. If a SCIM server is part of an application which is affiliated with multiple independent identity providers, and the operator of that SCIM server permits each tenant to choose its identity providers, then that SCIM server MUST ensure that the operations performed by one SCIM client on behalf of one tenant do not affect another tenant.
A SCIM server SHOULD give each SCIM client a distinct identity and authorization information.
A SCIM server SHOULD ensure that within a single tenant, or within the application if the application is not multi-tenanted, each SCIM client's updates do not affect those of other SCIM clients.
There are several ways for a SCIM server to achieve that. For example, a SCIM server might have each tenant or each SCIM client use a unique User endpoint.
For example, if the application had tenants example.com and example.org, and identity providers A and B, and tenant example.com used identity providers A and B but tenant example.org only allowed identity provider B, then identity provider A would be instructed to use endpoints /example.com/Users and /example.org/Users, and identity provider B would be instructed to use endpoint /example.org/Users.
Or, in another approach, a SCIM server MAY record which SCIM client identity created each user resource, and only permit user resources to be queried, updated or deleted by the same client.
As defined in RFC 7644, attribute names and attribute operators used in filters are case insensitive.
An implementation of this protocol SHOULD treat all other ABNF US-ASCII strings as case insensitive. For example, in the following PATCH body
{
"schemas":
["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"Operations":[{
"op":"remove",
"path":"emails[type eq \"work\"]"
}]
}
The case of these strings "schemas", "Operations", "op", "remove" and "path" are not significant.
Most attribute values are case insensitive when matching, however the values of the "id" attribute and the "externalID" attribute are case sensitive.
A SCIM client MAY send multiple requests to a SCIM server, and need not wait for one a response prior to sending another requests, with one exception. A SCIM client SHOULD NOT send another PATCH request for a particular User resource, if there was a PATCH request sent for that same resource in the last 60 seconds for which the client did not receive a response. A SCIM server need not process multiple operations in the order they were sent by the client.
A SCIM server MAY throttle clients who send too many simultaneous requests or too many requests in a short time interval, by returning status code 429, as defined in RFC 6585, to subsequent requests. A SCIM client which receives status code 429 SHOULD wait before retrying that request.
A SCIM server MAY support bulk operations, and if it does SHOULD support querying the service provider configuration. A SCIM server is not required to support bulk operations or the service provider configuration, and a server which does not support them SHOULD return either an error or an empty result for a query for the ServiceProviderConfig.
A SCIM client MAY query a SCIM server to determine if it supports bulk operations, by sending a GET for ServiceProviderConfig, as described in section 4 RFC 7644. If a SCIM server returns an error to this query, then a SCIM client SHOULD assume that SCIM server does not support bulk operations, and send subsequent requests not using bulk operations.
If a SCIM server implementing this profile encounters an error when processing a request from a client, it SHOULD transmit the error in the HTTP status code of the response, as described in section 3.2 of RFC 7644 and RFC 6585.
A SCIM server implementing this profile MAY implement these or other features, but a SCIM client SHOULD NOT assume they are supported unless it has determined otherwise.
SCIM defines a user schema in RFC 7643. A SCIM server implementing this profile need not implement the full set of attributes of that schema, since those attributes are not necessarily relevant to the application.
A SCIM server that supports a client creating users MUST recognize the User resource schema, as described in section 4.1 of RFC 7643, but does not need to support all of the attributes.
A SCIM server SHOULD recognize the Enterprise User schema extension as described in section 4.3 of RFC 7643.
From these schemas,
A SCIM server SHOULD NOT require any additional attributes besides userName to be supplied by a SCIM client when creating a user.
If email addresses are relevant to a SCIM server application,
For other attributes, if they are relevant to the application, and can be supplied by the identity provider, then that application's SCIM server MAY support storing them. In particular,
A SCIM server SHOULD construct a value for the "ID" attribute which is unique across all users which that SCIM server has in its database, and is likely to have in the future. In addition, the value SHOULD NOT include any characters which would require escaping if they were included in a HTTPS URI, and be limited to 64 US-ASCII characters in length. For example, a universally unique identifier as described in RFC 4122 would be a better choice for an id value than an email address or person's display name.
A SCIM server SHOULD NOT change the value of the "ID" attribute once it has been assigned to a User. Each subsequent GET of that user SHOULD return the same value.
A SCIM client MUST NOT assign any semantics to the value of the "ID" attribute which is receives from a SCIM server, other than it is unique in that server.
A SCIM client MAY construct a value for the "externalId" attribute for its users. If it does, the values of that attribute SHOULD be unique across all users which the identity provider has in its database, and is likely to have in the future. In addition, the value SHOULD NOT include any characters which would require escaping if they were to be included in a HTTPS URI, and be limited to 64 US-ASCII characters in length. For example, a universally unique identifier as described in RFC 4122 would be a better choice for an externalId value than an email address or person's display name.
A SCIM server need not support the "externalId" attribute. If it does, it SHOULD NOT assign any semantics to the value of the "externalId" attributes.
A SCIM server SHOULD support schema discovery through the "Schemas" and "ResourceTypes" endpoint URIs, as described in section 4 RFC 7644, that specifies the attributes of the "User" resource type which it supports.
A SCIM server that supports more than the minimum attributes of this profile SHOULD publish through schema discovery any additional attributes which it permits an identity provider to send.
A SCIM client MAY query a SCIM server to determine its schema, by querying either of those collections with GET requests. If that SCIM server returns an error to either query, then the SCIM client SHOULD assume that SCIM server only supports the attributes "userName", "ID", "active", "displayName" and "emails".
A SCIM server MUST ignore any additional resource types or attributes in the returned schema which it does not understand.
For example, if "https://example.com/Schemas" was the endpoint for "Schemas", and an authorized SCIM client sent
GET /Schemas HTTP/1.1 Authorization: Bearer h480djs93hd8
then a SCIM server might return
HTTP/1.1 200 OK
Content-Type: application/scim+json
Content-Length: ...
{
"schemas":["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
"totalResults": 1,
"Resources":[
{
"id":"urn:ietf:params:scim:schemas:core:2.0:User",
"name":"User",
"description":"User Account",
"attributes":[
{
"name":"userName",
"type":"string",
"multiValued":false,
"required":true,
"caseExact":false,
"mutability":"readWrite",
"returned":"default",
"uniqueness":"server"
},
{
"name":"displayName",
"type":"string",
"multiValued":false,
"required":false,
"caseExact":false,
"mutability":"readWrite",
"returned":"default",
"uniqueness":"none"
},
{
"name":"active",
"type":"boolean",
"multiValued":false,
"required":false,
"mutability":"readWrite",
"returned":"default"
},
...
]
},
"meta":{
"resourceType":"Schema"
}
}
]
}
When a user account is added in the identity provider, then
If a SCIM server supports the "externalId" attribute, a SCIM client MAY query a user by filtering for a value of the "externalId" attribute. A SCIM server that implements this profile and supports the "externalId" attribute SHOULD support filtering, as described in section 3.4.2.22 of RFC 7644. That SCIM server MAY support filtering by an equality match of the "externalId" attribute.
GET /Users?filter=externalId%20eq%201-2 HTTP/1.1 Authorization: Bearer h480djs93hd8
A SCIM client MAY query a SCIM server for a value of "externalId". If the SCIM server supports this query and the attribute value is not present on any current User in that SCIM server, the query response is a successful response with 0 result resources.
HTTP/1.1 200 OK
Content-Type: application/scim+json
Content-Length: ...
{
"schemas":["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
"totalResults": 0,
"Resources":[]
}
Otherwise, if there is a matching entry, then the query response is a successful response with one result resource.
To create a user, a SCIM client sends a POST request to the SCIM server's "Users" endpoint. The order of fields in the request for the attributes and metadata is not significant.
For example, if a SCIM client has determined a SCIM server supports the attributes "email", "name" and "department", the SCIM client would send
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"],
"active":true,
"displayName":"Babs Jensen",
"emails":[{"primary":true","type":"work",
"value":"babs@example.com"}],
"meta":{"resourceType":"User"},
"userName":"bjensen@example.com",
"name":{
"formatted":"Ms. Barbara J Jensen III",
"familyName":"Jensen",
"givenName":"Barbara"
},
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User":{
"department":"Retail"
}
}
In addition to the attributes, a SCIM server MAY supply, and a SCIM server SHOULD permit, the POST payload to contain the "schemas" and "meta" fields. A SCIM client MUST NOT send the "id" attribute in the POST request.
If the creation was successful, then that server SHOULD return HTTP status code 201 with a representation of the User resource. The returned resource SHOULD have an "id" attribute. The returned resource MAY contain some of the attributes supplied by that SCIM client, but some attributes might not be returned if they were not stored by that server, or if that server chooses not to return them. The returned resource MAY have additional attributes generated by that server.
HTTP/1.1 201 Created
Content-Type: application/scim+json
Content-Length: ...
{
"schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],
"id":"48af03ac28ad4fb88478"
}
If a user resource earlier existed but had been deleted, then a POST request for a new User resource with the same userName, externalId or other attributes as the previously deleted resource SHOULD NOT fail due to attribute conflict. If it does fail due to an attribute conflict, that server SHOULD return status code 409.
When inside of an identity provider, one or more of a user's attributes, such as display name, changes to a new value, then
If a SCIM client chooses to perform the query prior to the PATCH, then the sequence of operations would resemble
+--------+ +--------+ | | | | | |--(1) GET Request with id of user->| | | | | | | |<-(2) GET Response of that user----| | | | | | | IDP | | RP | | | | | | |--(3) PATCH Request for that user->| | | | | | | |<-(4) PATCH Response---------------| | | | | | +--------+ +--------+
A SCIM client MAY query a SCIM server for a user created earlier, by constructing an URI from the "Users" endpoint and the value of the "id" attribute returned by that server in an earlier POST response. For example,
GET /Users/6ba7b810-9dad-11d1-80b4-00c04fd430c8 HTTP/1.1 Authorization: Bearer h480djs93hd8
If that user still exists in that SCIM server, that SCIM server would return it.
HTTP/1.1 200 OK
Content-Type: application/scim+json
{
"schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],
"id":"5d48a0a8e9f04aa38008",
"externalId":"58342554-38d6-4ec8-948c-50044d0a33fd",
"meta": {
"resourceType":"User"
},
"userName":"bjensen@example.com",
"name": {
"formatted":"givenName familyName",
"familyName":"familyName",
"givenName":"givenName",
},
"active": true,
"emails":[{
"value":"bjensen@example.com",
"type":"work",
"primary": true
}]
}
A SCIM client MAY use the returned user resource to determine if a change it intends to send has already been made to a user.
If the user no longer exists, a SCIM server SHOULD return a 404 error.
If a SCIM client expected that the user was present, but received a 404 error, then that SCIM client MAY attempt to re-create a replacement user with a POST operation, it cannot PATCH a deleted user. Note that the new user SHOULD have a different "ID" attribute value.
A SCIM client sends a PATCH operation to change one or more attributes of the user. A SCIM server implementing this profile SHOULD support PATCH, as described in section 3.5 of RFC 7644.
PATCH /Users/6ba7b810-9dad-11d1-80b4-00c04fd430c8 HTTP/1.1
Host: example.com
Accept: application/scim+json
Content-Type: application/scim+json
Authorization: Bearer h480djs93hd8
{
"schemas":
["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"Operations":[{
"op":"replace",
"value":{
"emails":[
{
"value":"bjensen@example.com",
"type":"work",
"primary":true
}
]
}]
}
A SCIM client MAY include multiple operations for different attributes in a single PATCH.
PATCH /Users/6ba7b810-9dad-11d1-80b4-00c04fd430c8 HTTP/1.1
Host: example.com
Accept: application/scim+json
Content-Type: application/scim+json
Authorization: Bearer h480djs93hd8
{
"schemas":
["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"Operations":[
{
"op":"Replace",
"path":"emails[type eq \"work\"].value",
"value":"bjensen@example.com"
},
{
"op":"Replace",
"path":"name.familyName",
"value":"Jensen"
}
]
}
An identity provider MAY wish to indicate that a user is unable to sign in, and so is temporarily unable to access the application. A SCIM client would send a change of the "active" attribute to the value false to indicate the user will be unable to sign in. Later, if the user is made able to sign in, that SCIM client would send a new request to change the value of the "active" attribute of true.
PATCH /Users/6ba7b810-9dad-11d1-80b4-00c04fd430c8 HTTP/1.1
Host: example.com
Accept: application/scim+json
Content-Type: application/scim+json
Authorization: Bearer h480djs93hd8
{
"schemas":
["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"Operations":[{
"op":"replace",
"value":{
"active":false
}]
}
The identity provider MAY wish to indicate to the application that a user will never be signing in again. As there is no undo, this SHOULD only be done when the user account has been purged, e.g., if the user account has been soft-deleted in the identity provider but might be restored, the "active" attribute SHOULD be used instead of a delete to indicate the user's undoable change of status.
A SCIM client MAY delete a user it had created earlier, using the DELETE operation.
DELETE /Users/6ba7b810-9dad-11d1-80b4-00c04fd430c8 HTTP/1.1 Host: example.com Authorization: Bearer h480djs93hd8
If the delete was successful, a SCIM server SHOULD return status code 200.
A SCIM server MAY return an error 404 if the user was already deleted, and SHOULD return a different error if the delete could not be performed.
At intervals, a SCIM client MAY wish to query a SCIM server to ensure that SCIM server's copy of the user resources matches those expected by that SCIM client. For example, the identity provider might wish to reconcile with the application so that it can determine if one or more changes are needed. This can be done by either querying for each individual user with a GET operation, or retrieving multiple users in a single request.
Querying for an individual user was shown in the earlier section, Retrieving a User by ID.
A SCIM client MAY request to retrieve all users visible to it, by sending a GET request for the "Users" endpoint.
GET /Users HTTP/1.1 Authorization: Bearer h480djs93hd8
That SCIM server SHOULD either return the result, return the result in multiple pages, or reject the request if the response would be too large to return.
HTTP/1.1 200 OK
Content-Type: application/scim+json
Content-Length: ...
{
"schemas":["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
"totalResults": 1,
"Resources":[{
...
}]
}
The security requirements of sections 7.1, 7.2, 7.3, 7.4, 7.5, 7.7 and 7.8 of RFC 7644 apply to implementations of this profile. A SCIM server following this protocol SHOULD NOT support anonymous requests, so section 7.6 of that RFC would not be applicable.
If a SCIM server in an application is affiliated with multiple independent identity providers, then multiple SCIM clients could be making changes and querying the same SCIM server. The application security model will take into consideration whether user resources created from one identity provider are intended be visible to a client acting on behalf of a different identity provider.
There are no IANA considerations in this document.
| [OPENID.OIDC] | Sakimura, N., Bradley, J., Jones, M., de Medeiros, B. and C. Mortimore, "OpenID Connect Core 1.0 incorporating errata set 1", November 2014. |
| [RFC4122] | Leach, P., Mealling, M. and R. Salz, "A Universally Unique IDentifier (UUID) URN Namespace", RFC 4122, DOI 10.17487/RFC4122, July 2005. |