[Docs] [txt|pdf|xml|html] [Tracker] [Email] [Nits]

Versions: 00

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

Abstract

   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.

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

   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.




Wahl                    Expires December 23, 2019               [Page 1]


Internet-Draft     SCIM Profile for Relying Party Apps         June 2019


Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
     1.1.  Requirements Language . . . . . . . . . . . . . . . . . .   4
   2.  General Considerations  . . . . . . . . . . . . . . . . . . .   4
     2.1.  Endpoints and Payload . . . . . . . . . . . . . . . . . .   4
     2.2.  Authentication and Authorization  . . . . . . . . . . . .   5
     2.3.  SCIM Servers With Multiple Identity Providers and
           Multiple tenants  . . . . . . . . . . . . . . . . . . . .   5
     2.4.  Case Sensitivity in Payloads  . . . . . . . . . . . . . .   6
     2.5.  Overlapping and Throttling Requests . . . . . . . . . . .   6
     2.6.  Bulk Operations and Service Provider Configuration  . . .   7
     2.7.  Error Results . . . . . . . . . . . . . . . . . . . . . .   7
     2.8.  Non-Requirements  . . . . . . . . . . . . . . . . . . . .   7
   3.  Minimum Schema and Schema Discovery . . . . . . . . . . . . .   7
     3.1.  Additional Considerations for the ID Attribute  . . . . .   9
     3.2.  Additional Considerations ExternalId Attribute  . . . . .   9
     3.3.  Resources for Schema Discovery  . . . . . . . . . . . . .  10
   4.  Operations on Users . . . . . . . . . . . . . . . . . . . . .  12
     4.1.  When a User Account is added in the Identity Provider . .  12
       4.1.1.  Optionally locating a User by ExternalId  . . . . . .  12
       4.1.2.  Creating a User with POST . . . . . . . . . . . . . .  13
     4.2.  When a User Account's Attributes Change . . . . . . . . .  14
       4.2.1.  Retrieving a User by ID . . . . . . . . . . . . . . .  15
       4.2.2.  Modifying a User with PATCH . . . . . . . . . . . . .  16
       4.2.3.  Indicating User Sign In Blocked . . . . . . . . . . .  18
     4.3.  When the User's Account is to be Removed  . . . . . . . .  19
       4.3.1.  Removing a User with DELETE . . . . . . . . . . . . .  19
     4.4.  User Account Retrieval from the Relying Party . . . . . .  20
       4.4.1.  Retrieving Multiple Users in a Single Request . . . .  20
   5.  Security Considerations . . . . . . . . . . . . . . . . . . .  20
   6.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .  21
   7.  References  . . . . . . . . . . . . . . . . . . . . . . . . .  21
     7.1.  Normative References  . . . . . . . . . . . . . . . . . .  21
     7.2.  Informative References  . . . . . . . . . . . . . . . . .  22
   Author's Address  . . . . . . . . . . . . . . . . . . . . . . . .  22

1.  Introduction

   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 [OPENID.OIDC].  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



Wahl                    Expires December 23, 2019               [Page 2]


Internet-Draft     SCIM Profile for Relying Party Apps         June 2019


   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 [RFC7644] 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
   [RFC7643] 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:

   o  A replying party application has a database of user resources with
      attributes of those users relevant to that application.  It also
      trusts one or more identity providers to authenticate users on its
      behalf and provide claims about that user.  It also copies the
      values from some of those claims from those identity providers
      into its database.

   o  An identity provider has its own distinct database of user
      resources.  That database is the source of its claims which it
      provides to a relying party application.  Normally this is done
      through a sign-in flow using a protocol such as SAML or Open ID
      Connect.

   o  The identity provider also wishes to keep the relying party
      application up to date, even when no user is signing in to that
      replying party, and so uses SCIM to send changes to the
      application.

   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



Wahl                    Expires December 23, 2019               [Page 3]


Internet-Draft     SCIM Profile for Relying Party Apps         June 2019


   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.

1.1.  Requirements Language

   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 [RFC2119].

2.  General Considerations

   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.

2.1.  Endpoints and Payload

   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 [RFC7644]).  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 [RFC3629] encoding, in the Content-Type "application/
   scim+json".

   These are to be sent via HTTPS using TLS, RFC 8446 [RFC8446].





Wahl                    Expires December 23, 2019               [Page 4]


Internet-Draft     SCIM Profile for Relying Party Apps         June 2019


2.2.  Authentication and Authorization

   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 [RFC6750].  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.

2.3.  SCIM Servers With Multiple Identity Providers and Multiple tenants

   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.



Wahl                    Expires December 23, 2019               [Page 5]


Internet-Draft     SCIM Profile for Relying Party Apps         June 2019


   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.

2.4.  Case Sensitivity in Payloads

   As defined in RFC 7644 [RFC7644], 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.

2.5.  Overlapping and Throttling Requests

   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 [RFC6585], to subsequent
   requests.  A SCIM client which receives status code 429 SHOULD wait
   before retrying that request.





Wahl                    Expires December 23, 2019               [Page 6]


Internet-Draft     SCIM Profile for Relying Party Apps         June 2019


2.6.  Bulk Operations and Service Provider Configuration

   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 [RFC7644].  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.

2.7.  Error Results

   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 [RFC7644] and RFC 6585 [RFC6585].

2.8.  Non-Requirements

   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.

   o  HTTP cookies for authentication, or authentication not related to
      OAuth (from RFC 7644 [RFC7644] section 2)

   o  sorting, paging or queries via POST (from RFC 7644 [RFC7644]
      sections 3.4.2 and 3.4.3)

   o  updates via PUT (from RFC 7644 [RFC7644] sections 3.5.1)

   o  the Me URI fragment (from RFC 7644 [RFC7644] sections 3.11)

   o  eTags (from RFC 7644 [RFC7644] sections 3.14)

   o  anonymous requests (from RFC 7644 [RFC7644] sections 7.6)

3.  Minimum Schema and Schema Discovery

   SCIM defines a user schema in RFC 7643 [RFC7643].  A SCIM server
   implementing this profile need not implement the full set of




Wahl                    Expires December 23, 2019               [Page 7]


Internet-Draft     SCIM Profile for Relying Party Apps         June 2019


   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
   [RFC7643], 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 [RFC7643].

   From these schemas,

   o  A SCIM server MUST provide the attribute "ID" for all users.

   o  A SCIM server that supports a client creating users SHOULD support
      the attribute "userName" being supplied by a SCIM client when
      creating a user, or when the client is modifying a user.

   o  A SCIM server SHOULD support the attribute "active", as it allows
      a SCIM client to temporarily de-activate a user.

   o  A SCIM server SHOULD support the attribute "displayName", with
      values of at least 128 characters in length, being included when a
      user resource is created and subsequently changed.

   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,

   o  That SCIM server SHOULD support the multi-valued attribute
      "emails", for a client providing one value.

   o  That SCIM server MAY support a client providing more than one
      value.  As there is no way to indicate this at present, a SCIM
      client SHOULD NOT require a SCIM server to support multiple
      values.

   o  That SCIM server SHOULD support each value of "emails" having sub-
      attributes "primary", "type" and "value", and SHOULD support sub-
      attribute "type" having a value of "work".

   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,

   o  A SCIM server MAY support the attribute "externalId", with values
      of at least 64 characters in length.



Wahl                    Expires December 23, 2019               [Page 8]


Internet-Draft     SCIM Profile for Relying Party Apps         June 2019


   o  A SCIM server MAY support the complex multi-valued attributes
      "addresses" and "phoneNumbers", for a client providing one value
      of each, and MAY support a client providing more than one value of
      each attribute.

   o  A SCIM server MAY support the complex attribute "manager".

   o  A SCIM server MAY support the complex attribute "name", and if it
      does, SHOULD support the sub-attributes "formatted", "familyName",
      "givenName", "middleName", "honorificPrefix" and
      "honorificSuffix".

   o  A SCIM server MAY support the attributes "title" and
      "preferredLanguage".

   o  A SCIM server MAY support the attribute "department" in the
      enterprise 2.0 user schema.

3.1.  Additional Considerations for the ID Attribute

   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 [RFC4122] 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.

3.2.  Additional Considerations ExternalId Attribute

   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 [RFC4122] would be a better




Wahl                    Expires December 23, 2019               [Page 9]


Internet-Draft     SCIM Profile for Relying Party Apps         June 2019


   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.

3.3.  Resources for Schema Discovery

   A SCIM server SHOULD support schema discovery through the "Schemas"
   and "ResourceTypes" endpoint URIs, as described in section 4 RFC 7644
   [RFC7644], 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",



Wahl                    Expires December 23, 2019              [Page 10]


Internet-Draft     SCIM Profile for Relying Party Apps         June 2019


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







Wahl                    Expires December 23, 2019              [Page 11]


Internet-Draft     SCIM Profile for Relying Party Apps         June 2019


4.  Operations on Users

4.1.  When a User Account is added in the Identity Provider

   When a user account is added in the identity provider, then

   o  The identity provider's SCIM client MAY query a SCIM server to
      locate the user by externalId.  This step is OPTIONAL and a SCIM
      client MAY omit it.  A SCIM server is not required to support
      querying by externalId, and if it does not, SHOULD return an error
      for a filter on the "Users" endpoint with the externalId
      attribute.

   o  If the user does already not exist in that SCIM server, or the
      client did not query for it, then the identity provider's SCIM
      client MAY send a POST to create the user in that SCIM server.

4.1.1.  Optionally locating a User by ExternalId

   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 [RFC7644].  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":[]
      }





Wahl                    Expires December 23, 2019              [Page 12]


Internet-Draft     SCIM Profile for Relying Party Apps         June 2019


   Otherwise, if there is a matching entry, then the query response is a
   successful response with one result resource.

4.1.2.  Creating a User with POST

   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.





Wahl                    Expires December 23, 2019              [Page 13]


Internet-Draft     SCIM Profile for Relying Party Apps         June 2019


   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.

4.2.  When a User Account's Attributes Change

   When inside of an identity provider, one or more of a user's
   attributes, such as display name, changes to a new value, then

      The identity provider's SCIM client MAY query a SCIM server with a
      GET to retrieve the user's current attributes, as known to that
      server.  This step is OPTIONAL and a SCIM client MAY omit it.

      The identity provider's SCIM client MAY send a PATCH to update the
      user in a SCIM server.













Wahl                    Expires December 23, 2019              [Page 14]


Internet-Draft     SCIM Profile for Relying Party Apps         June 2019


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

4.2.1.  Retrieving a User by ID

   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.




















Wahl                    Expires December 23, 2019              [Page 15]


Internet-Draft     SCIM Profile for Relying Party Apps         June 2019


      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.

4.2.2.  Modifying a User with PATCH

   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
   [RFC7644].

   o  A SCIM server SHOULD support the "replace" operation for the
      "userName" attribute.



Wahl                    Expires December 23, 2019              [Page 16]


Internet-Draft     SCIM Profile for Relying Party Apps         June 2019


   o  A SCIM server SHOULD support the "add", "remove" and "replace"
      operations for the attributes "active" and "displayName".  A SCIM
      client MUST only send the "add" operation for one of these
      attributes if it has not previously set or retrieved that value
      for that attribute, and MUST only send the "remove" operation for
      one of these attributes if it has previously set or retrieved a
      value for that attribute.

   o  If a SCIM server supports storing email addresses, then that SCIM
      server SHOULD support the "add", "remove" and "replace" operations
      for attribute "emails", and SHOULD support "replace" changing just
      the value sub-attribute.

   o  A SCIM server MAY support operations on other attributes within
      the PATCH.

   o  A SCIM client MUST NOT assume the response contains any or all of
      the user attributes, as that SCIM server MAY choose to not return
      the entire user resource and all its attributes in the response.


      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.




Wahl                    Expires December 23, 2019              [Page 17]


Internet-Draft     SCIM Profile for Relying Party Apps         June 2019


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



4.2.3.  Indicating User Sign In Blocked

   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.


















Wahl                    Expires December 23, 2019              [Page 18]


Internet-Draft     SCIM Profile for Relying Party Apps         June 2019


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



4.3.  When the User's Account is to be Removed

   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.

4.3.1.  Removing a User with DELETE

   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.






Wahl                    Expires December 23, 2019              [Page 19]


Internet-Draft     SCIM Profile for Relying Party Apps         June 2019


4.4.  User Account Retrieval from the Relying Party

   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.

4.4.1.  Retrieving Multiple Users in a Single Request

   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":[{
       ...
      }]
      }



5.  Security Considerations

   The security requirements of sections 7.1, 7.2, 7.3, 7.4, 7.5, 7.7
   and 7.8 of RFC 7644 [RFC7644] apply to implementations of this
   profile.  A SCIM server following this protocol SHOULD NOT support




Wahl                    Expires December 23, 2019              [Page 20]


Internet-Draft     SCIM Profile for Relying Party Apps         June 2019


   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.

6.  IANA Considerations

   There are no IANA considerations in this document.

7.  References

7.1.  Normative References

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119,
              DOI 10.17487/RFC2119, March 1997,
              <https://www.rfc-editor.org/info/rfc2119>.

   [RFC3629]  Yergeau, F., "UTF-8, a transformation format of ISO
              10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November
              2003, <https://www.rfc-editor.org/info/rfc3629>.

   [RFC6585]  Nottingham, M. and R. Fielding, "Additional HTTP Status
              Codes", RFC 6585, DOI 10.17487/RFC6585, April 2012,
              <https://www.rfc-editor.org/info/rfc6585>.

   [RFC6750]  Jones, M. and D. Hardt, "The OAuth 2.0 Authorization
              Framework: Bearer Token Usage", RFC 6750,
              DOI 10.17487/RFC6750, October 2012,
              <https://www.rfc-editor.org/info/rfc6750>.

   [RFC7643]  Hunt, P., Ed., Grizzle, K., Wahlstroem, E., and C.
              Mortimore, "System for Cross-domain Identity Management:
              Core Schema", RFC 7643, DOI 10.17487/RFC7643, September
              2015, <https://www.rfc-editor.org/info/rfc7643>.

   [RFC7644]  Hunt, P., Ed., Grizzle, K., Ansari, M., Wahlstroem, E.,
              and C. Mortimore, "System for Cross-domain Identity
              Management: Protocol", RFC 7644, DOI 10.17487/RFC7644,
              September 2015, <https://www.rfc-editor.org/info/rfc7644>.






Wahl                    Expires December 23, 2019              [Page 21]


Internet-Draft     SCIM Profile for Relying Party Apps         June 2019


   [RFC8446]  Rescorla, E., "The Transport Layer Security (TLS) Protocol
              Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018,
              <https://www.rfc-editor.org/info/rfc8446>.

7.2.  Informative References

   [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,
              <https://openid.net/specs/openid-connect-core-1_0.html>.

   [RFC4122]  Leach, P., Mealling, M., and R. Salz, "A Universally
              Unique IDentifier (UUID) URN Namespace", RFC 4122,
              DOI 10.17487/RFC4122, July 2005,
              <https://www.rfc-editor.org/info/rfc4122>.

Author's Address

   Mark Wahl (editor)
   Microsoft Corporation
   1 Microsoft Way
   Redmond, WA  98052
   US

   Email: mwahl@microsoft.com

























Wahl                    Expires December 23, 2019              [Page 22]


Html markup produced by rfcmarkup 1.129c, available from https://tools.ietf.org/tools/rfcmarkup/