Internet DRAFT - draft-hunt-scim-notify
draft-hunt-scim-notify
Network Working Group P. Hunt, Ed.
Internet-Draft Oracle
Intended status: Standards Track M. Ansari
Expires: September 9, 2015 Cisco
I. Glazer
Salesforce
March 8, 2015
SCIM Event Notification
draft-hunt-scim-notify-00
Abstract
The System for Cross-Domain Identity Management (SCIM) specification
is an HTTP based protocol that makes managing identities in multi-
domain scenarios easier to support through a standardized HTTP
service.
In a SCIM environment, changes to resources may be requested by
multiple parties. As time goes by an interested subscriber may wish
to be informed about resource state changes that are occurring at the
SCIM service provider. This specification defines a hub notification
service that can be used to publish and distribute events to
interested registered subscribers.
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 http://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 September 9, 2015.
Copyright Notice
Copyright (c) 2015 IETF Trust and the persons identified as the
document authors. All rights reserved.
Hunt, et al. Expires September 9, 2015 [Page 1]
Internet-Draft draft-hunt-scim-notify March 2015
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. 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.
Table of Contents
1. Introduction and Overview . . . . . . . . . . . . . . . . . . 3
1.1. Notational Conventions . . . . . . . . . . . . . . . . . 4
1.2. Definitions . . . . . . . . . . . . . . . . . . . . . . . 5
2. Notification Process . . . . . . . . . . . . . . . . . . . . 6
3. SCIM Events . . . . . . . . . . . . . . . . . . . . . . . . . 7
3.1. Event Types . . . . . . . . . . . . . . . . . . . . . . . 7
3.2. Event Metadata . . . . . . . . . . . . . . . . . . . . . 8
3.3. Event Message . . . . . . . . . . . . . . . . . . . . . . 9
4. Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . 11
4.1. SCIM Server Resource Link Headers . . . . . . . . . . . . 11
4.2. Feeds Endpoint . . . . . . . . . . . . . . . . . . . . . 12
5. SCIM Feeds . . . . . . . . . . . . . . . . . . . . . . . . . 12
5.1. Feed Discovery . . . . . . . . . . . . . . . . . . . . . 13
6. Notification Hub . . . . . . . . . . . . . . . . . . . . . . 13
6.1. Subscriber Services . . . . . . . . . . . . . . . . . . . 13
6.1.1. Subscription Metadata . . . . . . . . . . . . . . . . 14
6.1.2. Request Subscription . . . . . . . . . . . . . . . . 15
6.1.3. Subscription Verification . . . . . . . . . . . . . . 17
6.1.4. Cancel A Subscription . . . . . . . . . . . . . . . . 19
6.2. Publisher Services . . . . . . . . . . . . . . . . . . . 19
6.2.1. Feed Registration . . . . . . . . . . . . . . . . . . 19
6.2.2. Feed Definition Operations . . . . . . . . . . . . . 23
6.2.3. Event POSTing . . . . . . . . . . . . . . . . . . . . 23
6.2.4. Polling for Publisher Events . . . . . . . . . . . . 25
6.3. Event Delivery . . . . . . . . . . . . . . . . . . . . . 25
6.3.1. Web Callback . . . . . . . . . . . . . . . . . . . . 26
6.3.2. Polling . . . . . . . . . . . . . . . . . . . . . . . 26
6.3.3. Push Notification Extensions . . . . . . . . . . . . 26
7. Security Considerations . . . . . . . . . . . . . . . . . . . 26
8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 26
8.1. SCIM Event Notification Mechanism Registry . . . . . . . 26
8.2. SCIM Event Type Registry . . . . . . . . . . . . . . . . 26
9. References . . . . . . . . . . . . . . . . . . . . . . . . . 26
9.1. Normative References . . . . . . . . . . . . . . . . . . 26
9.2. Informative References . . . . . . . . . . . . . . . . . 27
Appendix A. Contributors . . . . . . . . . . . . . . . . . . . . 27
Hunt, et al. Expires September 9, 2015 [Page 2]
Internet-Draft draft-hunt-scim-notify March 2015
Appendix B. Acknowledgments . . . . . . . . . . . . . . . . . . 27
Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 27
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 28
1. Introduction and Overview
The System for Cross-Domain Identity Management (SCIM) specification
is an HTTP based protocol that makes managing identities in multi-
domain scenarios easier to support through a standardized HTTP
service.
In a SCIM environment, changes to resources may be requested by
multiple parties. As time goes by an interested subscriber may wish
to be informed about resource state changes that are occurring at the
SCIM service provider. This specification defines a hub notification
service that can be used to publish and distribute events to
interested registered subscribers. This specification's design is
inspired by [pubsubhubbub], but is significantly adapted to use JSON
and JWT tokens.
The goal of this specification is to avoid alternative approaches
such as ATOM feeds or LDAP changelogs that require historical change
history be maintained. These techniques not only causes scalability
issues, but may also provide security risks over time because of the
difficulties in filtering history and data for specific subscribers
based on their authorized access to information.
This specification defines a Notification Hub which receives events
from a SCIM Service Provider. The role of the notification hub is to
offload the SCIM Service provider by taking care of:
o Re-publishing events to appropriate Feeds where the event is a
match.
o Distributing events to registered subscribers using their
registered notification mechanism.
o Persisting events as necessary until all registered subscribers
have received the event.
Hunt, et al. Expires September 9, 2015 [Page 3]
Internet-Draft draft-hunt-scim-notify March 2015
The following diagram shows a typical Notification Hub and its
service relationships with SCIM Service Providers and registered
notification Subscribers.
+----------------+
| SCIM |
|Service Provider|
| "Publisher" |
+-------+--------+
|
|
+-------v--------+
| Notification |
| "Hub" |
+------+---------+
| | |
| | |
| v v
+-----v------+
| Feed |+
|"Subscriber"||+
| |||
+------------+||
+------------+|
+------------+
Figure 1: Notification Relationships
The specification supports two layers of authentication. The base
layer uses normal HTTP Authentication techniques that may include TLS
mutual-authentication and OAuth access token authorizations. The
second layer involves the exchange of JWT keys that may be used to
authenticate messages and encrypt content for registered subscribers.
For a feed subscriber, this specification makes it possible to
receive update or change-of-state notifications that may be of
interest. By providing state change event notifications, a large
cross-section of subscribers can be developed to support use cases
such as: work-flow co-ordination, overall enterprise identity
governance co-ordination, and cross-domain replication. [DISCUSS:
should we elaborate on this?]
1.1. Notational Conventions
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 [RFC2119]. These
keywords are capitalized when used to unambiguously specify
Hunt, et al. Expires September 9, 2015 [Page 4]
Internet-Draft draft-hunt-scim-notify March 2015
requirements of the protocol or application features and behavior
that affect the interoperability and security of implementations.
When these words are not capitalized, they are meant in their
natural-language sense.
For purposes of readability examples are not URL encoded.
Implementers MUST percent encode URLs as described in Section 2.1 of
[RFC3986].
Throughout this documents all figures MAY contain spaces and extra
line-wrapping for readability and space limitations. Similarly, some
URI's contained within examples, have been shortened for space and
readability reasons.
1.2. Definitions
SCIM Service Provider The SCIM service provider as defined in SCIM
core schema. A SCIM service provider publishes events to be
distributed by a trusted Notification Hub.
Notification Hub A service provider in the same domain as the SCIM
Service Provider. Because the "hub" manages individual
subscribers, the "hub" must have access to all event message
content so that it may encrypt it for specific subscribers when
required.
Event An event is a SCIM change event that is to be distributed to
one or more registered subscribers. An event is encapsulated as a
JWT token and MAY be signed or encrypted using JWS/JWE for
authentication and confidentiality reasons.
Feed A feed is a URI that describes the set of resources and events
under which events may be issued. An interested client registers
with the Notification Hub to subscribe to events associated with a
feed.
Notification Mechanism A URI that describes the chosen event
notification mechanism. When subscribing to a feed, a client may
choose a specific mechanism by which it wishes to receive
notification events. [This specification will define a delivery
extension point.] Examples of possible delivery mechanisms
include:
* Registered Callback - The Notification Hub will deliver events
by using HTTP POST to a registered endpoint.
Hunt, et al. Expires September 9, 2015 [Page 5]
Internet-Draft draft-hunt-scim-notify March 2015
* Polling - The subscriber will periodically poll the
notification hub for one or more events by performing an HTTP
GET to a specified URI (mailbox endpoint).
* WebPush - An HTTP/2 based method for delivering real-time
events. https://tools.ietf.org/wg/webpush/
* Platform/Mobile Notification Services (e.g. Apple Push
Notification Service, Google Cloud Messaging, and Windows
Notification Services). Future profiles that support delivery
of SCIM events vis platform specific messaging services.
Subscriber A Subscriber registers to receive event notifications
from a Notification Hub on behalf of a SCIM Service Provider.
2. Notification Process
When a resource has changed, a SCIM Service Provider constructs a JWT
that describes the event. The service provider MAY include the
affected feedURIs for the Notification Hub to process. The SCIM
service provider publishes the event to the Notification Hub using
either an HTTP POST, or will hold the event (along with other events)
until the notification retrieves pending events via an HTTP GET.
After an event is delivered to the Notification Hub, the service
provider has no further obligation to maintain or distribute the
event. The service provider MAY subsequently receive requests from
subscribers for more information about the current state of a
resource using a normal SCIM GET request.
An event is a set of attributes combined together in a JWT token. An
event typically includes:
o Affected resource URI
o A list of attributes modified
o An event type (patch, create, delete)
o Optional attribute values for affected attributes. Note: JWT MUST
be a JWE if raw data is included.
An event describes what state change has occurred at a publishing
service provider resource. An event should not be interpreted as a
command to change by the subscriber.
Upon receiving an event, the notification hub, categorizes the event
and determine which feeds should be notified of the event. For each
feed, the notification hub delivers the events to any registered
Hunt, et al. Expires September 9, 2015 [Page 6]
Internet-Draft draft-hunt-scim-notify March 2015
clients. If the event contains raw attribute values, the
notification hub encrypts the JWT so that only the registered
subscriber(s) may receive the event. To deliver the event, the
notification hub uses the registered notification mechanism requested
by the subscriber.
Upon receiving an event (or events for polling subscribers), the
subscriber reads the JWT or JWE token and validates it if signed (a
JWS). Based on the content of the JWT, the subscriber decides what
if any action it needs to take in response to the event from the SCIM
Service Provider. The subscriber MAY perform a SCIM GET request to
the affected resource URI in order to confidentially obtain the
current state of the affected resource.
3. SCIM Events
A SCIM Event notifies a subscriber of a possible change in state of a
resource contained within a specified feed. The event specifies the
URI of an affected resource and the type of event that has occurred.
The event message may also contain additional metadata describing the
attributes that may have been modified, and/or values representing
the final state of the affected attribute(s).
3.1. Event Types
This specification defines 8 events. Additional event types may be
defined using the Event Type IANA registration process described in
Section 8.2.
ADD
The specified resource URI was added to the feed. An add does not
necessarily indicate a resource is new or has been recently
created, but rather that it has been added to a feed. For
example, an existing user has had a new role (e.g. CRM_User)
added to their profile which has caused their resource to join a
feed.
CREATE
The new resource URI has been created at the service provider and
has been added to the feed. When a CREATE event is sent, a
corresponding ADD event is not issued. For example, a new user
was created via HTTP POST, whose attribute profile met the
criteria of a current feed.
ACTIVATE
The specified resource (e.g. User) has been activated or is
otherwise available for use. [TODO: this seems to be a higher
Hunt, et al. Expires September 9, 2015 [Page 7]
Internet-Draft draft-hunt-scim-notify March 2015
level concept that may consist of multiple attributes changing -
How to differentiate between activate and MODIFY events]
MODIFY
The specified resource has been updated (e.g. one or more
attributes has changed).
DEACTIVATE
The specified resource (e.g. User) has been deactivated. [TODO:
Is there a corresponding MODIFY event?]
DELETE The specified resource has been deleted from the service
provider and is also removed from the feed. When a DELETE is
sent, a corresponding REMOVE is not issued.
REMOVE
The specified resource has been removed from the feed. Removal
does not indicate that the resource was deleted or otherwise
deactivated.
PASSWORD
The specified resource (e.g. User) has changed its password. If
secure exchange is possible with the subscriber, the event may
also include the raw password update text. A PASSWORD event MUST
be transmitted in encrypted form (see Section 3.3).
CONFIRMATION A special event that is used during Polling Feed
Registrations and Web Callback URI subscriptions to confirm
successful configuration of an event feed. The contents of a
CONFIRMATION event SHALL be defined by the registration process
documented in following sections [TODO add reference]
3.2. Event Metadata
The following are attributes that may be included in an event
message:
schemas A multi-valued String attribute that contains the value
"urn:ietf:params:scim:schemas:notify:2.0:Event".
feedUris A multivalued String containing the URIs of the feeds the
event is associated with. The notification hub may filter these
values to be only those values relevant to a particular
subscriber. In doing so, the notification hub is not obligated to
deliver repeated events to the same subscriber. [DISCUSS: Is this
problematic if the subscriber is using multiple endpoints?]
publisherUri
Hunt, et al. Expires September 9, 2015 [Page 8]
Internet-Draft draft-hunt-scim-notify March 2015
A single valued string containing the URI of the SCIM Service
Provider publishing the event. Typically this is the SCIM Service
Provider's root endpoint.
resourceUris
A multi-valued string that contains the URIs of one or more
affected resources in the event. For each resource URI included,
the event must be identical.
type
A single-valued string that contains the type of event as
described in Section 3.1 or defined in the event extension
registry in Section 8.2.
attributes
A multi-valued list of affected SCIM attributes. Each attribute
listed may be a fully-qualified attribute name or an attribute
"path" as defined in Figure 7 of Section 3.3.2 of
[I-D.ietf-scim-api]
values
A JSON object structure containing the affected attributes and
their associated values. If the "values" attribute is supplied,
the event message MUST be encrypted. Service providers SHOULD
take care to ensure that eligible subscribers are able to see
attribute values. Alternatively, subscribers MAY use the
resourceURIs to retrieve the final attribute values. When doing
so, the SCIM service provider can then assess the subscribers
right to obtain the actual attribute values.
For a password change event, the clear text password attribute
value MAY be included in the values attribute. "PASSWORD" event.
3.3. Event Message
Hunt, et al. Expires September 9, 2015 [Page 9]
Internet-Draft draft-hunt-scim-notify March 2015
An event message is a JSON structure consisting of the attributes
described in the Event Metadata section above. The following is a
non-normative example event that has been modified for readability:
{
"schemas":["urn:ietf:params:scim:schemas:notify:2.0:Event"],
"publisherUri":"https://scim.example.com",
"feedUris":[
"https://jhub.example.com/Feeds/98d52461fa5bbc879593b7754",
"https://jhub.example.com/Feeds/5d7604516b1d08641d7676ee7"
],
"resourceUris":[
"https://scim.example.com/Users/44f6142df96bd6ab61e7521d9"
],
"type":"CREATE",
"attributes":["id","name","userName","password","emails"],
"values":{
"emails":[
{"type":"work","value":"jdoe@example.com"}
],
"password":"not4u2no",
"userName":"jdoe",
"id":"44f6142df96bd6ab61e7521d9",
"name":{
"givenName":"John",
"familyName":"Doe"
}
}
}
Figure 2: Example Event JSON Data
When transmitted, the above JSON body must be converted into a JWT as
per [I-D.ietf-oauth-json-web-token]. In this example, because the
event contains attribute values, the token MUST be encrypted per JWE
(see [I-D.ietf-jose-json-web-encryption]) before transmission.
The following is an example of a SCIM Event expressed in an unsecured
JWT token. The JWT header of:
{"alg":"none"}
Base64url encoding of the octets of the UTF-8 representation of the
header yields:
eyJhbGciOiJub25lIn0
Hunt, et al. Expires September 9, 2015 [Page 10]
Internet-Draft draft-hunt-scim-notify March 2015
The example JSON Event Data is encoded as follows:
eyJwdWJsaXNoZXJVcmkiOiJodHRwczovL3NjaW0uZXhhbXBsZS5jb20iLCJmZWV
kVXJpcyI6WyJodHRwczovL2podWIuZXhhbXBsZS5jb20vRmVlZHMvOThkNTI0Nj
FmYTViYmM4Nzk1OTNiNzc1NCIsImh0dHBzOi8vamh1Yi5leGFtcGxlLmNvbS9GZ
WVkcy81ZDc2MDQ1MTZiMWQwODY0MWQ3Njc2ZWU3Il0sInJlc291cmNlVXJpcyI6
WyJodHRwczovL3NjaW0uZXhhbXBsZS5jb20vVXNlcnMvNDRmNjE0MmRmOTZiZDZ
hYjYxZTc1MjFkOSJdLCJldmVudFR5cGVzIjpbIkNSRUFURSJdLCJhdHRyaWJ1dG
VzIjpbImlkIiwibmFtZSIsInVzZXJOYW1lIiwicGFzc3dvcmQiLCJlbWFpbHMiX
SwidmFsdWVzIjp7ImVtYWlscyI6W3sidHlwZSI6IndvcmsiLCJ2YWx1ZSI6Impk
b2VAZXhhbXBsZS5jb20ifV0sInBhc3N3b3JkIjoibm90NHUybm8iLCJ1c2VyTmF
tZSI6Impkb2UiLCJpZCI6IjQ0ZjYxNDJkZjk2YmQ2YWI2MWU3NTIxZDkiLCJuYW
1lIjp7ImdpdmVuTmFtZSI6IkpvaG4iLCJmYW1pbHlOYW1lIjoiRG9lIn19fQ
The encoded JWS signature is the empty string. Concatenating the
parts yields:
eyJhbGciOiJub25lIn0
.
eyJwdWJsaXNoZXJVcmkiOiJodHRwczovL3NjaW0uZXhhbXBsZS5jb20iLCJmZWV
kVXJpcyI6WyJodHRwczovL2podWIuZXhhbXBsZS5jb20vRmVlZHMvOThkNTI0Nj
FmYTViYmM4Nzk1OTNiNzc1NCIsImh0dHBzOi8vamh1Yi5leGFtcGxlLmNvbS9GZ
WVkcy81ZDc2MDQ1MTZiMWQwODY0MWQ3Njc2ZWU3Il0sInJlc291cmNlVXJpcyI6
WyJodHRwczovL3NjaW0uZXhhbXBsZS5jb20vVXNlcnMvNDRmNjE0MmRmOTZiZDZ
hYjYxZTc1MjFkOSJdLCJldmVudFR5cGVzIjpbIkNSRUFURSJdLCJhdHRyaWJ1dG
VzIjpbImlkIiwibmFtZSIsInVzZXJOYW1lIiwicGFzc3dvcmQiLCJlbWFpbHMiX
SwidmFsdWVzIjp7ImVtYWlscyI6W3sidHlwZSI6IndvcmsiLCJ2YWx1ZSI6Impk
b2VAZXhhbXBsZS5jb20ifV0sInBhc3N3b3JkIjoibm90NHUybm8iLCJ1c2VyTmF
tZSI6Impkb2UiLCJpZCI6IjQ0ZjYxNDJkZjk2YmQ2YWI2MWU3NTIxZDkiLCJuYW
1lIjp7ImdpdmVuTmFtZSI6IkpvaG4iLCJmYW1pbHlOYW1lIjoiRG9lIn19fQ
.
Figure 3: Example Unsecured Event Token
To create and or validate a signed or encrypted event token follow
the instructions in section 7 of [I-D.ietf-oauth-json-web-token].
4. Discovery
4.1. SCIM Server Resource Link Headers
A SCIM Service Provider MAY provide resource link headers per
[RFC5988] for the purpose of feed and endpoint discovery. When
querying a SCIM Service Provider, the following resource link headers
are defined:
rel=notifyHub
Hunt, et al. Expires September 9, 2015 [Page 11]
Internet-Draft draft-hunt-scim-notify March 2015
The URI provided is the base URI for a SCIM Notification Hub and
its associated HTTP services.
rel=oauth
The URI provides is for an OAuth authorization endpoint that will
authorize access to a SCIM feed. When requesting authorization,
clients should request an OAuth scope of "notifyHub". This allows
the client to register and request access to specific feeds. [TBD
is this needed?]
rel=scimfeed
The URI provided is for a SCIM Feed for the current resource. The
feed URI might be specific to the current resource, or for a
larger set of resources (e.g. /Users). There may be more than one
feed for any particular resource or set of resources.
4.2. Feeds Endpoint
A service provider may publish a set of Feed resources that each
describe an available feed at a "/Feeds" endpoint. [TODO: Define the
schema and resource type configuration for a feed based on SCIM Feed
definitions in the next section]
5. SCIM Feeds
A SCIM Service Provider may define feeds based on a number of
criteria. This specification does not specify or limit the basis for
which a service provider defines a feed or how feed URIs should be
specified. Some possible methods for defining feeds include:
By Resource
Each resource might have its own event notification feed. For
example, a User's mobile application may require notification of
changes or rights defined in a SCIM User resource associated with
the mobile user.
By Endpoint
A feed might be defined by an endpoint where any event relating to
a resource within an endpoint is transmitted to subscriber. This
type of feed is likely to have many notifications as the number of
resources in an endpoint grows (e.g. /Users). Typically only
privileged partners would be allowed to use this type of feed.
For example an enterprise wishes to be notified of all events to
any of its Users assuming all Users within the endpoint are
related to the subscribing enterprise.
By Filter
Hunt, et al. Expires September 9, 2015 [Page 12]
Internet-Draft draft-hunt-scim-notify March 2015
A feed might define a collection of resources based on a SCIM
search filter. Based on a set of matching criteria a resource may
be included in a feed. Note that this type of feed may require
extra processing by the service provider to determine if any
particular resource event matches the filter criteria. It may
also be difficult for the service provider to notify subscribers
of Feed additions and deletions as these will occur dynamically
based on the filter.
By Group
A designated SCIM Group could be used to define the resources
within a particular feed. [TODO define a FEED Group extensions
that define the attributes and events included within a particular
Feed Group]
5.1. Feed Discovery
[TBD] May be discovered by resource link headers, or by querying for
SCIM Feed Groups [TBD].
6. Notification Hub
The notification hub is usually deployed as a separate but trusted
server (in the same security domain) in relation to a SCIM Service
Provider. A single server MAY support both SCIM services and the API
described in the notification hub. The notification hub's API
follows the SCIM API specification unless indicated otherwise. The
notification hub provides 2 core services:
o A set of publisher endpoints that allows SCIM Service Providers to
define feeds and to post SCIM Events.
o A set of subscriber endpoints that allows subscription clients to
subscribe to feeds and to receive events.
6.1. Subscriber Services
Subscribers MAY manage their subscriptions using the notification
hub's "/Subscriptions" endpoint. With the exception of the PATCH
operation (which is not used), endpoints within the notification hub
follow the same message format and API guidelines as per the SCIM API
specification (see [I-D.ietf-scim-api]). The subscriptions endpoint
supports HTTP GET, POST, PUT, and DELETE to manage the full life
cycle of a subscription.
Hunt, et al. Expires September 9, 2015 [Page 13]
Internet-Draft draft-hunt-scim-notify March 2015
6.1.1. Subscription Metadata
The following attributes are used to define a feed subscription by a
subscription client.
feedUri
A string value containing the URI for a feed supported by the
notification hub. REQUIRED.
mode
A REQUIRED single-valued string which is a URI with one of the
following values:
"urn:ietf:params:scimnotify:api:messages:2.0:webCallback" - The
notification hub will pass SCIM Events using HTTP POST to the
callback URI specified in the attribute "eventUri".
"urn:ietf:params:scimnotify:api:messages:2.0:poll" - The
subscriber will poll for SCIM Events using HTTP GET at the URI
specified in the attribute "eventUri"
eventUri
When "mode" is set to
"urn:ietf:params:scimnotify:api:messages:2.0:poll", "eventUri"
specifies the endpoint where the subscriber will retrieve pending
events. When set to
"urn:ietf:params:scimnotify:api:messages:2.0:webCallback", it
contains the URI where the notification hub will POST events.
feedJwk
AN OPTIONAL JSON Web Key (see [I-D.ietf-jose-json-web-key]) that
will be used to sign published events. If present, the subscriber
can authenticate events relayed from the notification hub.
confidentialJwk
The subscriber may provide a public JSON Web Key (see
[I-D.ietf-jose-json-web-key]) that may be used by the notification
hub to encrypt event messages for the subscriber.
pollInterval
The optional period in seconds between event polls when the
subscriber plans to poll for events from the notification hub.
The interval is used by the hub to determine if a subscriber is
offline or has otherwise failed over a number of intervals. The
hub MAY then change the state of the feed and/or perform some out-
of-band administrative alert.
state
Hunt, et al. Expires September 9, 2015 [Page 14]
Internet-Draft draft-hunt-scim-notify March 2015
An optional value which indicates the current state of the feed
which is:
"on" - the default setting indicates the notification hub
processing events and will pass them to the subscriber.
"verify" - the subscription is pending verification. While in
"verify", published events SHALL NOT be stored or delivered to
the subscriber.
"paused" - indicates the notification hub is temporarily
suspending delivery to subscriber. While in "paused" events
MAY be posted and will be delivered when state returns to "on".
"off" - indicates that the subscription is no longer passing
events. While in off mode, the subscription is maintained, but
new events are ignored and not processed.
"fail" - Indicates that the notification hub was unable to
deliver events to the subscriber for an extended period of
time, or due to a call failure to the registered web call back
URI.
6.1.2. Request Subscription
To request a subscription, a client performs a SCIM POST to the
/Subscriptions endpoint with a HTTP Body consisting of a JSON object
based on the attributes described in Section 6.1.1. The request MUST
include the "schemas" attribute with a value of:
"urn:ietf:params:scim:schemas:notify:2.0:Subscription".
Hunt, et al. Expires September 9, 2015 [Page 15]
Internet-Draft draft-hunt-scim-notify March 2015
The following is a non-normative example subscription creation
request.
POST /Subscriptions HTTP/1.1
Host: notify.example.com
Accept: application/scim+json
Content-Type: application/scim+json
Authorization: Bearer h480djs93hd8
Content-Length: ...
{
"schemas":
["urn:ietf:params:scim:schemas:notify:2.0:Subscription"],
"feedUri":"https://example.com/v2/Feeds/548b7c3f77c8bab33a4fef40",
"mode":"urn:ietf:params:scimnotify:api:messages:2.0:webCallback",
"eventUri":"https://subscriber.com/Events",
"state":"verify",
"feedJwk":{
"kty":"EC",
"crv":"P-256",
"x":"f83OJ3D2xF1Bg8vub9tLe1gHMzV76e8Tus9uPHvRVEU",
"y":"x_FEzRu9m36HLN_tue659LNpXW6pCyStikYjKIWI5a0",
"kid":"Public key for Example.com SCIM Publisher"
}
}
Figure 4: Example Subscription Creation Request
Hunt, et al. Expires September 9, 2015 [Page 16]
Internet-Draft draft-hunt-scim-notify March 2015
In response to a successful subscription creation request, the server
responds with HTTP Status 200 and a representation of the completed
subscription. The following is a non-normative example response that
has been formatted for display purposes:
HTTP/1.1 201 Created
Content-Type: application/scim+json
Location:
https://example.com/v2/Subscriptions/548b7c3f77c8bab33a4fef40
{
"schemas":
["urn:ietf:params:scim:schemas:notify:2.0:Subscription"],
"feedUri":"https://example.com/v2/Feeds/548b7c3f77c8bab33a4fef40",
"mode":"urn:ietf:params:scimnotify:api:messages:2.0:webCallback",
"eventUri":"https://subscriber.com/Events",
"feedJwk":{
"kty":"EC",
"crv":"P-256",
"x":"f83OJ3D2xF1Bg8vub9tLe1gHMzV76e8Tus9uPHvRVEU",
"y":"x_FEzRu9m36HLN_tue659LNpXW6pCyStikYjKIWI5a0",
"kid":"Public key for Example.com SCIM Publisher"
}
}
Upon receiving a successful subscription response, the subscribing
client SHOULD check the subscription "state". If set to "verify",
the client needs to complete the subscription verification process in
the following section.
6.1.3. Subscription Verification
In order to avoid ongoing communication issues and to minimize
requirements for notification hubs to maintain events indefinitely, a
verification process is used to confirm that the requested event
distribution endpoints are correct and that an event may be
successfully delivered.
When using the WebCallback mode, or any other "push"-style
communication scheme, the verification process also serves to verify
that the identified endpoint consents to receiving events. This
prevents a notification server from flooding an endpoint which did
not actually request an event subscription.
To confirm a subscription, the notification hub SHALL POST (or
otherwise send) an event to the endpoint identified by eventUri or as
specified by the registered push extension. The event contains the
following attributes:
Hunt, et al. Expires September 9, 2015 [Page 17]
Internet-Draft draft-hunt-scim-notify March 2015
type Set to the value of "CONFIRMATION"
publisherUri Set to the URI used to identify the notification hub.
feedUris MUST be set to a value that matches the subscription
"feedUri" requested.
confirmChallenge A random String value that the subscriber SHALL
echo back in its response.
expires A SCIM DateTime value that indicates the time the
verification request will expire. Once expired, the server will
set the subscription state to "fail".
If a confidential JWK was supplied, then the event SHOULD be
encrypted with the provided key. Successful parsing of the message
confirms that both the endpoint is valid and the subscribers ability
to parse the message.
A non-normative JSON representation of an event to be sent to a
subscriber as a subscription confirmation. Note the event is not yet
encoded as a JWT token.
{
"schemas":["urn:ietf:params:scim:schemas:notify:2.0:Event"],
"publisherUri":"https://scim.example.com",
"feedUris":[
"https://notify.example.com/Feeds/98d52461fa5bbc879593b7754"
],
"type":"CONFIRMATION",
"confirmChallenge":"ca2179f4-8936-479a-a76d-5486e2baacd7",
"expires":""
}
Hunt, et al. Expires September 9, 2015 [Page 18]
Internet-Draft draft-hunt-scim-notify March 2015
Upon receiving a subscription confirmation request, a consenting
client responds with a confirmation that includes the original
"confirmChallenge" value. A non-normative example of the response
is:
HTTP/1.1 200 OK
Content-Type: application/scim+json
{
"schemas":["urn:ietf:params:scim:schemas:notify:2.0:Confirm"],
"challengeResponse":"ca2179f4-8936-479a-a76d-5486e2baacd7"
}
}
As per the above figure, upon receiving and parsing a confirmation
event, the subscriber MUST respond by returning a JSON structure that
includes the attribute "challengeResponse" with a matching value to
"confirmChallenge" that was sent in the event. The response is not
formatted as an event token but rather a JSON object with schemas set
to "urn:ietf:params:scim:schemas:notify:2.0:Confirm". If the
subscriber returns a non-matching value or an HTTP status other than
a 200 series response, the subscription "state" SHALL be set to
"fail". A declining subscriber MAY simply respond with any 400
series HTTP error (e.g. 404).
6.1.4. Cancel A Subscription
To cancel a subscription, the subscriber MAY perform a SCIM DELETE
against the resource URI for the subscription. In the event the
subscriber wants to temporarily suspend the subscription, it may
modify the "state" attribute to a value of "off".
6.2. Publisher Services
With the exception of the PATCH operation (which is not used), the
endpoints within the Notification Hub follow the same message format
and API guidelines as per the SCIM API specification (see
[I-D.ietf-scim-api]). Feed Registration supports HTTP GET, POST,
PUT, and DELETE to manage the full life cycle of a Feed.
6.2.1. Feed Registration
To register a feed, a SCIM Service Provider makes a call to the
Notify Hub's registration endpoint ("<Notification_base>/Feeds") by
performing an HTTP POST containing a JSON structure based on the
parameters defined in the following section. In response, the server
will return a feed location and an optional public key which the
publisher may use to encrypt posted events to the Notification Hub.
Hunt, et al. Expires September 9, 2015 [Page 19]
Internet-Draft draft-hunt-scim-notify March 2015
In the registration request, the "schemas" attribute MUST be included
in the registration request and be set to:
"urn:ietf:params:scim:schemas:notify:2.0:Feed". The following is a
non-normative example of a request to create a new SCIM Feed. Note
that additional spacing has been introduced for clarity.
POST /Feeds HTTP/1.1
Host: notify.example.com
Accept: application/scim+json
Content-Type: application/scim+json
Authorization: Bearer h480djs93hd8
Content-Length: ...
{
"schemas":["urn:ietf:params:scim:schemas:notify:2.0:Feed"],
"feedName":"bjensen",
"feedDescription":"Feed for changes related to bjensen",
"feedData":{
"$ref":
"https://example.com/v2/Users/453a-919d-413861904646"
}
"mode":"post",
"publisherJwk":{
"kty":"EC",
"crv":"P-256",
"x":"f83OJ3D2xF1Bg8vub9tLe1gHMzV76e8Tus9uPHvRVEU",
"y":"x_FEzRu9m36HLN_tue659LNpXW6pCyStikYjKIWI5a0",
"kid":"Public key for Example.com SCIM Publisher"
}
}
Figure 5: Example Feed Creation Request
In response to a successful registration request, the Notification
Hub SHALL respond with the location of the created feed in the HTTP
Location header, and the HTTP body SHALL contain a JSON structure
with the accepted registration parameters and MAY include in its
response, the following additional parameter:
confidentialJwk
In its response, the Notification Hub may provide a public JSON
Web Key (see [I-D.ietf-jose-json-web-key]) that may be used by the
client to encrypt event messages for the notification hub. The
key might be the notification hub's general public key, or it may
be generated per registered feed. Accordingly, registering SCIM
Service Providers should assume that each key returned MAY be
specific to the corresponding registered feed.
Hunt, et al. Expires September 9, 2015 [Page 20]
Internet-Draft draft-hunt-scim-notify March 2015
HTTP/1.1 201 Created
Content-Type: application/scim+json
Location:
https://example.com/v2/Feeds/548b7c3f77c8bab33a4fef40
ETag: 9d1c124149f522472e7a511c85b3a31b
{
"schemas":["urn:ietf:params:scim:schemas:notify:2.0:Feed"],
"id":"548b7c3f77c8bab33a4fef40",
"feedName":"bjensen",
"feedDescription":"Feed for changes related to bjensen",
"feedData":{
"type":"resource",
"$ref":
"https://example.com/v2/Users/453a-919d-413861904646"
}
"mode":"post",
"state":"on",
"publisherJwk":{
"kty":"EC",
"crv":"P-256",
"x":"f83OJ3D2xF1Bg8vub9tLe1gHMzV76e8Tus9uPHvRVEU",
"y":"x_FEzRu9m36HLN_tue659LNpXW6pCyStikYjKIWI5a0",
"kid":"Public key for Example.com SCIM Publisher"
}
"confidentialJwk":{
...<feed public crypto key>...
}
}
Figure 6: Example Feed Creation Response
6.2.1.1. Feed Request Parameters
To create a feed, the following parameters are used by the SCIM
Service Provider to register a feed:
feedName
A required string value containing a name for the feed. May be
used in administrative user interfaces to assist subscribers in
feed selection. The value MUST be unique within a given
administrative domain.
feedDescription
An optional string value containing text that describes the
content of the feed. May be used in administrative user
interfaces to assist subscribers in feed selection.
Hunt, et al. Expires September 9, 2015 [Page 21]
Internet-Draft draft-hunt-scim-notify March 2015
feedData
A single-valued complex attribute which contains feed information.
$ref A SCIM Reference attribute that contains a URI as defined by
"feedType".
mode
A single-valued string which is one of the following values:
"post" - The publisher will pass SCIM Events using the HTTP
POST option.
"poll" - The notification hub will poll for SCIM Events using
HTTP GET at the specified URI ("feedPollUri").
The choice of "mode" is largely an internal decision based on the
respective implementation architecture of the hub and its
corresponding service providers that are publishing feeds. For
many service providers with high rates of change, it may be
limiting to store events for pick-up by a hub or subscriber (who
is "polling"). In many cases service providers will normally
prefer to simply POST events as generated to the hub so that they
do not have to worry about persistence, etc. [TODO: is this a
case for WebPUSH?]
feedPollUri
When "mode" is set to "poll", "feedPollUri" specifies the endpoint
where the Notification hub will retrieve pending updates from the
publishing SCIM Service Provider.
publisherJwk
The publishers optional JSON Web Key (see
[I-D.ietf-jose-json-web-key]) that will be used to publish events.
By registering a key, the Notification hub can authenticate events
from SCIM Service Provider.
pollInterval
The optional period in seconds between event polls when the
Notification Hub is set to poll for events from the SCIM Service
Provider.
state
An optional value which indicates the current state of the feed
which is:
"on" - the default setting indicates the notification hub is
receiving events and will forward them to current feed
Hunt, et al. Expires September 9, 2015 [Page 22]
Internet-Draft draft-hunt-scim-notify March 2015
subscribers. If no subscribers exist or all subscribers have
been notified, the events are deleted.
"pending" - indicates the notification hub is temporarily
suspending delivery to subscribers. While in "pending" events
may be posted and will be held for delivery by the hub until
state returns to "on" (when events are subsequently delivered)
or "fail".
"off" - indicates an administrator or publisher has requested
the feed to stop delivery. While in off mode, the subscribers
are maintained, but new events shall be ignored.
"fail" - usually used in connection with "polling" feeds.
Indicates that the notification hub has been unable to retrieve
events from the service provider for an extended period of
time, or due to a call failure to the registered polling call
back URI. [TODO: discuss whether a hub should continue to
queue events in failed mode]
6.2.2. Feed Definition Operations
As with any SCIM resource, a notification Feed MAY be:
o Queried by using a SCIM HTTP GET request. In particular,
subscribers may perform a GET to the "/Feeds" endpoint to discover
available feeds.
o Updated by using a SCIM PUT request.
o Deleted using a SCIM DELETE request. Upon receiving a delete
request, all corresponding notification subscriptions SHALL also
be deleted. For this reason, instead of deletion, setting feed
status to "off" is recommended.
6.2.3. Event POSTing
To create an event, a SCIM Event Publisher, simply performs an HTTP
POST "/Events" appended to the Feed location URI. The body of the
request includes a JSON object with the following attributes:
schemas A multi-valued string containing the value "
A non-normative example is as follows:
Hunt, et al. Expires September 9, 2015 [Page 23]
Internet-Draft draft-hunt-scim-notify March 2015
POST /Feeds/548b7c3f77c8bab33a4fef40/Events HTTP/1.1
Host: notify.example.com
Accept: application/scim+json
Content-Type: application/scim+json
Content-Length: ...
{
"schemas":["urn:ietf:params:scim:schemas:notify:2.0:Feed"]
"eventToken":
"eyJhbGciOiJub25lIn0
.
eyJwdWJsaXNoZXJVcmkiOiJodHRwczovL3NjaW0uZXhhbXBsZS5jb20iLCJmZWV
kVXJpcyI6WyJodHRwczovL2podWIuZXhhbXBsZS5jb20vRmVlZHMvOThkNTI0Nj
FmYTViYmM4Nzk1OTNiNzc1NCIsImh0dHBzOi8vamh1Yi5leGFtcGxlLmNvbS9GZ
WVkcy81ZDc2MDQ1MTZiMWQwODY0MWQ3Njc2ZWU3Il0sInJlc291cmNlVXJpcyI6
WyJodHRwczovL3NjaW0uZXhhbXBsZS5jb20vVXNlcnMvNDRmNjE0MmRmOTZiZDZ
hYjYxZTc1MjFkOSJdLCJldmVudFR5cGVzIjpbIkNSRUFURSJdLCJhdHRyaWJ1dG
VzIjpbImlkIiwibmFtZSIsInVzZXJOYW1lIiwicGFzc3dvcmQiLCJlbWFpbHMiX
SwidmFsdWVzIjp7ImVtYWlscyI6W3sidHlwZSI6IndvcmsiLCJ2YWx1ZSI6Impk
b2VAZXhhbXBsZS5jb20ifV0sInBhc3N3b3JkIjoibm90NHUybm8iLCJ1c2VyTmF
tZSI6Impkb2UiLCJpZCI6IjQ0ZjYxNDJkZjk2YmQ2YWI2MWU3NTIxZDkiLCJuYW
1lIjp7ImdpdmVuTmFtZSI6IkpvaG4iLCJmYW1pbHlOYW1lIjoiRG9lIn19fQ
."
}
In response, if the event token is validated, the server SHALL
indicate successful submission by responding with:
HTTP/1.1 204 No Content
Since the normal operation of the notification hub is to forward
events to registered subscribers, the Notification Hub is not
obligated to inform the publisher of a permanent event URI that was
created. Servers MAY allow HTTP clients to check for undelivered
events by performing a GET against the same endpoint as the Event
submission endpoint described above.
[TODO: Describe the error conditions and responses]
A SCIM Event Publisher MAY publish an event of type "CONFIRMATION" to
the provided publication endpoint to confirm successful
configuration. "CONFIRMATION" events SHALL NOT be passed on to
subscribers.
Hunt, et al. Expires September 9, 2015 [Page 24]
Internet-Draft draft-hunt-scim-notify March 2015
6.2.4. Polling for Publisher Events
When a publisher registers a feed with a "mode" of "poll", the
notification hub SHALL confirm configuration by performing an HTTP
GET to the "feedPollUri" provided by the publisher during
registration of the feed. On the first GET, the notification server
should receive an event of type "CONFIRMATION". The confirmation
event should contain an event with the "resourceUris" attribute set
to a value that corresponds to the URI of the feed registration.
In its response to the notification polling for events by performing
an HTTP Get to the "feedPollUri", the server shall construct a JSON
message, with a schemas attribute consisting of the value:
"urn:ietf:params:scim:api:messages:2.0:EventList" and a multivalued
attribute of "eventTokens" containing one or more event tokens. The
following non-normative example has been modified for brevity and
readability:
HTTP/1.1 200 OK
Content-Type: application/scim+json
Location: https://example.com/FeedPoll/548b7c3f77c8bab33a4fef40
{
"schemas":["urn:ietf:params:scim:api:messages:2.0:EventList"],
"eventTokens":[
"eyJhbGciOiJub25lIn0
.
eyJwdWJsaXNoZXJVcmkiOiJodHRwczovL3NjaW0uZXhhbXBsZS5jb20iLCJmZWV
kVXJpcyI6WyJodHRwczovL2podWIuZXhhbXBsZS5jb20vRmVlZHMvOThkNTI0Nj
FmYTViYmM4Nzk1OTNiNzc1NCIsImh0dHBzOi8vamh1Yi5leGFtcGxlLmNvbS9GZ
WVkcy81ZDc2MDQ1MTZiMWQwODY0MWQ3Njc2ZWU3Il0sInJlc291cmNlVXJpcyI6
WyJodHRwczovL3NjaW0uZXhhbXBsZS5jb20vVXNlcnMvNDRmNjE0MmRmOTZiZDZ
hYjYxZTc1MjFkOSJdLCJldmVudFR5cGVzIjpbIkNSRUFURSJdLCJhdHRyaWJ1dG
VzIjpbImlkIiwibmFtZSIsInVzZXJOYW1lIiwicGFzc3dvcmQiLCJlbWFpbHMiX
SwidmFsdWVzIjp7ImVtYWlscyI6W3sidHlwZSI6IndvcmsiLCJ2YWx1ZSI6Impk
b2VAZXhhbXBsZS5jb20ifV0sInBhc3N3b3JkIjoibm90NHUybm8iLCJ1c2VyTmF
tZSI6Impkb2UiLCJpZCI6IjQ0ZjYxNDJkZjk2YmQ2YWI2MWU3NTIxZDkiLCJuYW
1lIjp7ImdpdmVuTmFtZSI6IkpvaG4iLCJmYW1pbHlOYW1lIjoiRG9lIn19fQ
."]
}
6.3. Event Delivery
[TODO: Detail the event delivery extension point and define the
following 3 methods]
Hunt, et al. Expires September 9, 2015 [Page 25]
Internet-Draft draft-hunt-scim-notify March 2015
6.3.1. Web Callback
6.3.2. Polling
6.3.3. Push Notification Extensions
7. Security Considerations
The synchronizing of User passwords between administrative domains is
to be handled with great care. From a security perspective the re-
use of passwords across service providers is to be highly
discouraged. However, in the enterprise user experience, if the
perception of the user is that service providers from multiple
domains are part of a single corporate application environment, then
password synchronization MAY be appropriate as part of an overall
identity management and governance mechanism.
[TO BE COMPLETED]
8. IANA Considerations
8.1. SCIM Event Notification Mechanism Registry
TODO: Registration for Notification Mechanisms
8.2. SCIM Event Type Registry
TODO: Registration of Event Types
9. References
9.1. Normative References
[I-D.ietf-oauth-json-web-token]
Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token
(JWT)", draft-ietf-oauth-json-web-token-32 (work in
progress), December 2014.
[I-D.ietf-scim-api]
Hunt, P., Grizzle, K., Ansari, M., Wahlstroem, E., and C.
Mortimore, "System for Cross-Domain Identity Management:
Protocol", draft-ietf-scim-api-15 (work in progress),
February 2015.
Hunt, et al. Expires September 9, 2015 [Page 26]
Internet-Draft draft-hunt-scim-notify March 2015
[I-D.ietf-scim-core-schema]
Hunt, P., Grizzle, K., Wahlstroem, E., and C. Mortimore,
"System for Cross-Domain Identity Management: Core
Schema", draft-ietf-scim-core-schema-17 (work in
progress), March 2015.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66, RFC
3986, January 2005.
[RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010.
9.2. Informative References
[I-D.ietf-jose-json-web-encryption]
Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)",
draft-ietf-jose-json-web-encryption-40 (work in progress),
January 2015.
[I-D.ietf-jose-json-web-key]
Jones, M., "JSON Web Key (JWK)", draft-ietf-jose-json-web-
key-41 (work in progress), January 2015.
[I-D.ietf-jose-json-web-signature]
Jones, M., Bradley, J., and N. Sakimura, "JSON Web
Signature (JWS)", draft-ietf-jose-json-web-signature-41
(work in progress), January 2015.
[pubsubhubbub]
Google, Inc, Google, Inc, Six Apart Ltd, and Notifixious
Inc., "PubSubHubbub Core 0.4 -- Working Draft", .
Appendix A. Contributors
Appendix B. Acknowledgments
The editor would like to thank the participants in the the SCIM
working group for their support of this specification.
Appendix C. Change Log
Draft 00 - PH - First Draft
Hunt, et al. Expires September 9, 2015 [Page 27]
Internet-Draft draft-hunt-scim-notify March 2015
Authors' Addresses
Phil Hunt (editor)
Oracle Corporation
Email: phil.hunt@yahoo.com
Morteza Ansari
Cisco
Email: morteza.ansari@cisco.com
Ian Glazer
Salesforce.com
Email: iglazer@salesforce.com
Hunt, et al. Expires September 9, 2015 [Page 28]
