draft-wahl-scim-jit-profile-00:
SCIM Profile For Enhancing Just-In-Time Provisioning
Author(s): Mark Wahl
This document specifies a profile of the System for Cross-Domain Identity Management Protocol (SCIM) for use by servers which rely upon just-in-time provisioning patterns in a protocol (such as SAML) to create user accounts, and need an additional...
Network Working Group M. Wahl
Internet Draft Microsoft
Intended status: Proposed Standard February 18, 2013
Expires: August 2013
SCIM Profile For Enhancing Just-In-Time Provisioning
draft-wahl-scim-jit-profile-00.txt
Status of this Memo
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), its areas, and its working groups. Note that
other groups may also distribute working documents as Internet-
Drafts.
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."
The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt
The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html
This Internet-Draft will expire on August 18, 2013.
Copyright Notice
Copyright (c) 2013 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
(http://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.
Wahl Expires August 18, 2013 [Page 1]
Internet-Draft SCIM Profile for use with JIT February 2013
Abstract
This document specifies a profile of the System for Cross-Domain
Identity Management Protocol (SCIM) for use by servers which rely
upon just-in-time provisioning patterns in a protocol (such as SAML)
to create user accounts, and need an additional channel to be
notified of changes to user accounts.
Table of Contents
1. Introduction...................................................2
1.1. Conventions used in this document.........................4
2. Events in the SCIM client database.............................4
2.1. User is added to the SCIM client database.................4
2.2. User's username changes...................................4
2.3. User's display name changes...............................4
2.4. User's account is disabled................................5
2.5. User's account is re-enabled..............................5
2.6. User's account is purged..................................6
3. SCIM interaction profiles......................................6
3.1. Locating a user by their user name........................6
3.2. Modifying a user..........................................7
3.3. Deleting a user...........................................8
4. Schema Profile.................................................8
5. Security Considerations........................................9
6. IANA Considerations............................................9
7. References.....................................................9
7.1. Normative References......................................9
7.2. Informative References....................................9
1. Introduction
The SCIM protocol [1] is an application-level, REST protocol for
provisioning and managing identity data on the web. SCIM can be
leveraged for numerous use cases, including transfer of attributes to
a relying party web site (see [4] section 3.6).
This profile of SCIM illustrates the interactions between a SCIM
client and a SCIM server, in the following scenario:
o The SCIM client has an associated database (SCIM client database)
of user records, and that SCIM client database is leveraged by an
identity provider for user authentication.
Wahl Expires August 18, 2013 [Page 2]
Internet-Draft SCIM Profile for use with JIT February 2013
o The SCIM server has a different associated database (SCIM server
database) of user records, and that SCIM server database is
leveraged by a service provider (an application).
o The service provider trusts the identity provider to authenticate
users, and a user's username and other attributes as stored in the
SCIM client database are transferred (using a federation or
authentication protocol such as SAML -- not SCIM) from the
identity provider to the service provider each time a user
accesses the service provider.
o When the service provider receives a user identity from the
identity provider in the federation/authentication protocol, and
the service provider cannot find a user record with matching
username in the SCIM server database, then the service provider
creates a new record in the SCIM server database.
o An identity management system associated with the SCIM client
database makes changes to users in the SCIM client database, for
instance to de-activate a user, or change the user's display
names. These changes are of interest to the service provider.
This profile enables the SCIM client to notify the SCIM server of
changes to users in the SCIM client database, so that the SCIM server
can make corresponding changes in the SCIM server database, which are
then available to the service provider. For example, if the identity
provider deletes a user, this deletion event can be transferred to
the service provider via SCIM, so that the service provider can clean
up any data associated with a user who won't be accessing that
service provider again. Or if the user changes their username, then
this can be made known to the service provider, so that subsequent
requests by that user will be associated to the same account in the
SCIM server database.
This profile is not intended to be a comprehensive replication
protocol; instead, it provides basic consistency for user records for
in two domain's databases, for all users who choose to access the
service provider. This profile also explicitly does not create users
via SCIM, which is assumed to occur out of band from SCIM, such as
through a "just in time" operation in a federation protocol such as
SAML [5]. This profile also does not cover establishing common index
keys of usernames between a SCIM client and a SCIM server. Finally,
management of other object types besides users, and additional
attributes beyond basic user status and name, is outside the scope of
this profile.
Wahl Expires August 18, 2013 [Page 3]
Internet-Draft SCIM Profile for use with JIT February 2013
1.1. Conventions used in this document
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 [2].
2. Events in the SCIM Client Database
A SCIM client will, either upon specific change in the SCIM client
database, or at intervals, provide one or more changes to the SCIM
server.
2.1. User is added to the SCIM client database
The SCIM client does not notify the SCIM server of this event. (In
this profile, user creation is assumed to occur out of band from
SCIM, such as through a "just in time" operation in a federation
protocol such as SAML [5].)
2.2. User's username changes
When a user's username changes in the SCIM client database, then the
SCIM client will perform the following procedure.
o The SCIM client will attempt to locate the user in the SCIM server
using the old username, as described in section 3.1 of this
document.
o If the user could not be located (no matching record is returned
from the GET request), then the procedure ends.
o Otherwise, if the user's record was found in the SCIM server, then
the SCIM client will send a patch, as described in section 3.2 of
this document, to set the value of the username attribute to the
new username.
o If the SCIM server returns a 400-series error indication from the
patch, then the SCIM client SHOULD NOT retry the operation.
2.3. User's display name changes
When a user's display name changes in the SCIM client database, then
the SCIM client will perform the following procedure.
o The SCIM client will attempt to locate the user in the SCIM server
using the user's username, as described in section 3.1 of this
document.
Wahl Expires August 18, 2013 [Page 4]
Internet-Draft SCIM Profile for use with JIT February 2013
o If the user could not be located (no matching record is returned
from the GET request), then the procedure ends.
o Otherwise, if the user's record was found in the SCIM server, then
the SCIM client will send a patch, as described in section 3.2 of
this document, to set the value of the displayName attribute, and
OPTIONALLY the value of the name attribute, to the new name.
o If the SCIM server returns a 400-series error indication from the
patch, then the SCIM client SHOULD NOT retry the operation.
2.4. User's account is disabled
When a user's account is disabled in the SCIM client database, then
the SCIM client will perform the following procedure.
o The SCIM client will attempt to locate the user in the SCIM server
using the user's username, as described in section 3.1 of this
document.
o If the user could not be located (no matching record is returned
from the GET request), then the procedure ends.
o If the user's record was found in the SCIM server, and the GET
returned the "active" attribute type in that record and that
attribute had the value false, then the procedure ends.
o Otherwise, then the SCIM client will send a patch, as described in
section 3.2 of this document, to set the value of the active
attribute to false.
o If the SCIM server returns a 400-series error indication from the
patch, then the SCIM client SHOULD NOT retry the operation.
2.5. User's account is re-enabled
When a user's account is re-enabled in the SCIM client database after
having previously been disabled, then the SCIM client will perform
the following procedure.
o The SCIM client will attempt to locate the user in the SCIM server
using the user's username, as described in section 3.1 of this
document.
o If the user could not be located (no matching record is returned
from the GET request), then the procedure ends.
Wahl Expires August 18, 2013 [Page 5]
Internet-Draft SCIM Profile for use with JIT February 2013
o If the user's record was found in the SCIM server, and the GET
returned the "active" attribute type in that record and that
attribute had the value true, then the procedure ends.
o Otherwise, then the SCIM client will send a patch, as described in
section 3.2 of this document, to set the value of the active
attribute to true.
o If the SCIM server returns a 400-series error indication from the
patch, then the SCIM client SHOULD NOT retry the operation.
2.6. User's account is purged
When a user's account is purged in the SCIM client, then the SCIM
client will perform the following procedure.
o The SCIM client will attempt to locate the user in the SCIM server
using the user's username, as described in section 3.1 of this
document.
o If the user could not be located (no matching record is returned
from the GET request), then the procedure ends.
o Otherwise, then the SCIM client will send a delete, as described
in section 3.3 of this document.
o If the SCIM server returns a 400-series error indication from the
delete, then the SCIM client SHOULD NOT retry the operation.
3. SCIM Interaction Profile
3.1. Locating a user by their user name
In order to modify or delete a user record in a SCIM server, the SCIM
client needs to first discover the id of that record as stored in the
SCIM server. This is done by searching for the userName attribute,
which is defined in section 6.1 of the SCIM Core Schema [3].
The client can issue a SCIM query request for the namespace ending
with /Users with a query parameter of a filter for userName matching
the user name. For example (lines wrapped for clarity):
Wahl Expires August 18, 2013 [Page 6]
Internet-Draft SCIM Profile for use with JIT February 2013
GET /TBD/scimbase/Users?filter=username%20eq%20%22matt@example.co
m%22 HTTP/1.1
Host: example.com
Accept: application/json
Authorization: Bearer deadbeef
If found, the server will respond with a HTTP 200 message containing
a single result resource, with one or more attributes:
HTTP/1.1 200 OK
Content-Type: application/json
{
"totalResults":1,
"schemas":["urn:scim:schemas:core:1.0"],
"Resources":[
{
"id":"2819c223-7f76-453a-919d-413861904646,
...
"userName":"matt@example.com"
}
]
}
If not found, the SCIM server will respond with a HTTP 200 message
containing zero result resources.
3.2. Modifying a user
For this interaction, the SCIM client needs the id of the user. If
it does not already have it, it can obtain the id of the user as
described in section 3.1.
If the SCIM client can locate the user record, then the client can
modify the attributes of the user in the SCIM server by issuing a
POST with an override to PATCH. The body of the message will be a
JSON structure with a "schemas" key, and one or more keys. For
example (lines wrapped for clarity)
Wahl Expires August 18, 2013 [Page 7]
Internet-Draft SCIM Profile for use with JIT February 2013
POST /TBD/scimbase/Users/acbf3ae7-8463-4692-b4fd-9b4da3f908ce
HTTP/1.1
Host: example.com
Accept: application/json
Content-Type: application/json
Authorization: Bearer deadbeef
X-HTTP-Method-Override: PATCH
Content-Length: 72
{
"schemas": ["urn:scim:schemas:core:1.0"],
"displayName": "Babs Jensen"
}
3.3. Deleting a user
For this interaction, the SCIM client needs the id of the user. If
it does not already have it, it can obtain the id of the user as
described in section 3.1.
If the SCIM client can locate the user record, then the client can
request deletion of user in the server by issuing a POST with an
override to DELETE. For example (lines wrapped for clarity)
POST /TBD/scimbase/Users/acbf3ae7-8463-4692-b4fd-9b4da3f908ce
HTTP/1.1
Host: example.com
Authorization: Bearer deadbeef
X-HTTP-Method-Override: DELETE
If the user cannot be found, the server will return error code 404.
4. Schema Profile
A server that implements this profile is REQUIRED to recognize and
store in its database the "username" attribute of the SCIM User
Schema. (This attribute is described in section 6 of the SCIM Schema
[3].)
The SCIM server MUST recognize and SHOULD store the "displayName",
"active" and "name" (with components "givenName" and "familyName")
attributes of the SCIM User Schema. If the SCIM server does not store
one or more of those attributes, then any changes to them requested
by the SCIM client SHOULD be silently discarded.
Wahl Expires August 18, 2013 [Page 8]
Internet-Draft SCIM Profile for use with JIT February 2013
The SCIM server MUST recognize the "schemas" attribute of the SCIM
Core Schema (in section 5 of the SCIM Schema [3]), but the value is
not modified by the SCIM client in this profile.
The password attribute is not used in this profile.
5. Security Considerations
As described in the SCIM protocol security considerations [1], the
SCIM interactions are to be protected using TLS.
Note that for each of the interactions in section 3, the SCIM client
will need an OAuth bearer token. Such tokens are normally short-lived
(hours). How the SCIM client locates an OAuth endpoint to obtain this
token is currently outside the scope of this document.
6. IANA Considerations
There are no IANA considerations in this document.
7. References
7.1. Normative References
[1] Drake, T., Mortimore, C., Ansari, M., Grizzle, K., Wahlstroem,
E., "System for Cross-Domain Identity Management:Protocol",
draft-ietf-scim-api-00, August 2012.
[2] Bradner, S., "Key words for use in RFCs to Indicate Requirement
Levels", BCP 14, RFC 2119, March 1997.
[3] Mortimore, C., Harding, P., Madsen, P., Drake, T., "System for
Cross-Domain Identity Management:Core Schema", draft-ietf-scim-
core-schema-00, August 2012.
7.2. Informative References
[4] Hunt, P., Khasnabish, B., Nadalin, A., Zeltsan, Z., Li, K.,
"SCIM Use Cases", draft-zeltsan-scim-use-cases-01, February
2013.
[5] Cantor, S., Kemp, J., Philpott, R., Maler, E., "Assertions and
Protocols for the OASIS Security Assertion Markup Language
(SAML) V2.0", http://docs.oasis-
open.org/security/saml/v2.0/saml-core-2.0-os.pdf , March 2005.
Wahl Expires August 18, 2013 [Page 9]
Internet-Draft SCIM Profile for use with JIT February 2013
Authors' Addresses
Mark Wahl
Microsoft Corporation
1 Microsoft Way
Redmond WA 98052 USA
Email: mark.wahl@microsoft.com
Wahl Expires August 18, 2013 [Page 10]
