Identity Event Subscription ProtocolOracle Corporationphil.hunt@yahoo.comCiscomorteza.ansari@cisco.comInternet-Draft
This specification defines a registry to define methods to distribute
identity events to subscribers. It includes a definition for publishers
to use HTTP POST to push events to clients via web callback, and a method
for subscribers to use HTTP GET to retrieve events in a feed queue.
Many service providers have a requirement to co-ordinate state
of entities and services between each other. Each service provider
often tracks different information about entities and thus positive
update commands such as HTTP POST or PATCH may not be possible as this
would introduce complex error and signal requirements. In contrast,
when one service provider notifies another of an event, the subscriber
is free to take local action as it has access to the relevant local
state information.
This specification defines a set of capabilities that can be used
by publishers to distribute identity event tokens (see )
to subscribers. This specification defines a registry
for profiling existing messaging protocols that may be used for
event delivery by a particular subscriber. The specification also
defines two methods HTTP POST and GET to deliver events.
An Identity feed provider may be directly integrated into a source
service that generates events, or it may be a separate service entity
that off-loads event distribution from the event generator to act
as its publisher. For the purposes of this specification, while event
distribution may be handled separately, this specification will
consider the definition of those exchanges out of scope.
This specification addresses event delivery only. It is assumed that
there are other protocols or administrative methods for providing event
feeds catalogs and subscription management.
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
. These keywords are capitalized when used to
unambiguously specify requirements of the protocol or application
features and behavior that affect the inter-operability 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
.
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.
The following definitions are specific to Identity Event
publishing:
The feed provider publishes
events to be distributed to registered subscribers.
An event is an identify 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.
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 feed provider to subscribe
to events associated with a feed.
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. Examples of possible delivery
mechanisms include:
Registered Callback - The feed provider will deliver
events by using HTTP POST to a registered endpoint.
Polling - The subscriber will periodically poll the
feed provider for one or more events by performing an HTTP
GET to a specified URI (mailbox endpoint).
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.
A Subscriber registers to receive event
notifications from a feed provider.
When an event occurs, the feed provider constructs a JWT based
Identity Event token that describes the
event. The feed provider determines the
feeds that the event should be published to, and determines
which subscribers are effected. The process by which events are
categorized and selected for subscribers is out of scope of this
specification.
When an event is available for a subscriber, the feed provider
attempts to deliver the event based on the subscribers registered
delivery mechanism. For example,
The subscriber provided a web-callback endpoint, the
publisher uses an HTTP/1.1 POST to the endpoint to deliver the
event to the registered subscriber;
For subscribers electing to poll for events, the feed
publisher retains the events for a period of time or until the
registered subscriber retrieves all pending events via HTTP/1.1 GET to the
subscriber's assigned retrieval endpoint by the feed publisher; or,
The subscriber elected to use an alternate delivery method
(e.g. WebPUSH, Apple APNS, Google GMS), delivery is facilitated
via the registered delivery profile for that method.
After an event is delivered to all subscribers, feed providers
will not typically maintain event records or histories. As such,
published events SHOULD be self-validating (e.g. signed).
If delivery to any particular subscriber has been delayed for
an extended period of time, the feed provider MAY suspend the
subscription and even stop maintaining outstanding events for
the subscriber at its discretion and available resources. See subscription
state in .
Upon receiving an event token (or tokens in the case of multiple
events), the subscriber reads the token and validates it. Based
on the content of the token, the subscriber decides what if
any action it needs to take in response to the event. For example,
in response to a SCIM event indicating
a changed resource, the subscriber might perform a SCIM GET request (see
Section 3.4
) to the affected resource URI in order to confidentially obtain
the current state of the affected resource. The receiver of the
event then determines what action, if any, needs to be taken within
the subscriber's domain.
The action a receiver takes may be substantially different than
merely copying the action of the publisher. A single publisher event
MAY trigger multiple receiver actions. For example, upon receiving notification that
a user resource has been added to a group, the receiver may first determine
that the user does not exist in the subscriber's domain. The receiver
translates the event into two actions. Retrieve the user (e.g. using
SCIM GET) and then provisions the user locally. After enabling
the user, the receiver then enables the user for the application
associated with membership in the publisher's group.
An event feed is service that provides a series of events made
available that a
client (known as the "subscriber") MAY subscribe to. A subscription
contains the information about a particular client and their subscription
to a particular feedUri. The subscription
metadata describes the client that has subscribed, the current
delivery status indicating whether all events are delivered, pending,
or whether delivery has failed. Subscription metadata also describes the
method of event delivery and any associated configuration information (see
).
A feed 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:
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.
A feed might be defined by an endpoint
where any event relating to a resource within an endpoint is
delivered to a subscriber. This type of feed is likely to have
many
notifications as the number of resources in an endpoint grows (e.g.
a SCIM "/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.
A feed might define a collection of
resources based on a filter that describes 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.
For example, all resources within a
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]
How feeds are defined or implemented is out of the scope of this
specification. The above are examples about how feeds might be
defined.
A feed description consists of the following singular
attributes:
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. This is a
required attribute.
An attribute of type
String
that is a
unique URI identifying the feed. This attribute characteristic
mutability
is
immutable
and SHALL NOT change once assigned. This is a required
attribute.
A
String
attribute that describes the purpose of the feed in human
readable form. This is an optional attribute.
A
Reference
attribute that is one of the following canonical values:
Indicates that the feed is for
events related to a specific resource. In such cases,
the value of the attribute
filter
is set to a specific
resource URI or
/Me
.
Indicates that the feed is for all
events that occur for resources within a specific endpoint.
In such cases,
filter
is set to
an endpoint container for a group of resources (e.g.
/Users
).
Indicates that events for a feed
will be selected based on events relating to the set of
resources described by a filter. The value of the attribute
filter
is a SCIM filter that
describes a condition that selects a set of resources that
match before or after a resource state change.
Indicates that events for a feed
will be based on events relating to the set of resources
listed in a SCIM Group. The value of the attribute
filter
is a URI that
corresponds to a SCIM Group containing a set of members
to be monitored.
hangText="publisher">Indicates a group whose definition
is specific to the service provider publisher.The value of the
attribute
filter
if used, is defined
by the service provider.[[SHOULD THERE BE AN EXTENSION POINT?]]
A String value containing a SCIM
filter (see Section 3.4.2.2
),
a resource, or a SCIM endpoint URI. The contents of the value is
indicated by the feed
type
attribute.
The following multi-valued attributes are defined:
One or more String values that contain
the Event URIs supported[[TBD]]. By default, all available events
MAY be published.
One or more URIs representing the methods of
delivery
supported by the feed. By default, all delivery modes are supported.
A subscription represents an agreement to deliver events from a
specified feed of events from a feed provider to an individual subscriber
entity. The method of delivery and the parameters for delivery are
specified a set of parameters called subscription metadata (see ).
A subscription is defined by the following metadata:
A string value containing the URI
for a feed supported by the feed provider. It describes the
content of the feed and MAY also be a resolvable URI where the
feed meta data may be returned as a JSON object. REQUIRED.A REQUIRED single-valued string
which is a URI with a prefix of urn:ietf:params:event:delivery.
The following are defined in :The feed provider delivers events
using HTTP POST to a specified callback URI.The subscriber will poll for events
using HTTP GET.A URI representing the unique
identifier for a single subscriber of a feed. It MAY also
be an actual event polling endpoint which the subscriber MAY
use to receive such as with deliveryUri
method of urn:ietf:params:event:delivery:HTTP:poll.
AN OPTIONAL JSON Web Key (see
) that will be used
to sign published events. If present, the subscriber can
authenticate events relayed from the feed provider.An OPTIONAL subscriber
provided public JSON Web Key (see )
that may be used by the feed provider to encrypt event messages
for the subscriber.An optional value which indicates
the current status of a subscription:on - the default setting
indicates the feed provider 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
feed provider is temporarily suspending delivery to
subscriber. While in paused
events SHOULD be retained and delivered when state
returns to on.off - indicates that the
subscription is no longer passing events. While in off mode,
the subscription metadata is maintained, but new events are ignored
and not processed or retained.fail - Indicates that the
feed provider 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. Unlike paused
status, a failed subscription is no longer receiving events
nor are they retained by the feed provider.An OPTIONAL number indicating the
maximum number of attempts to deliver an event. A value of '0'
indicates there is no maximum. Upon reaching the maximum, the
subscription subStatus is set
to failed [[or "paused"?]].An OPTIONAL number indicating
the maximum amount of time an event MAY wait before delivery.
Upon reaching the maximum, the
subscription subStatus is set
to failed [[or "paused"?]]. An OPTIONAL
integer that represents the minimum interval in seconds between deliveries. A value of '0'
indicates delivery should happen immediately. When delivery is
a polling method (e.g. HTTP GET), it is the expected time between subscriber attempts.
When in push mode (e.g. HTTP POST), it is the interval the server
will wait before sending a new event or events.In order to avoid ongoing communication issues and to minimize
requirements for feed providers to maintain events indefinitely,
a verification process is used to confirm that the requested event
distribution endpoints are correct and that events may be
successfully delivered. When a subscription is created or modified, the feed
provider SHALL set the subscription state (subStatus)
to verify and send a test event message to the subscriber. If the event is
delivered successfully, the subscription state MAY be turned to
on. If however verification fails due
to a hard failure, or the client fails to retrieve the event within
a [reasonable?] period, the subscription status SHALL be set to
fail.When using the WebCallback mode, or any other
'push'-style communication scheme, the verification process
serves to verify that the identified endpoint consents to receiving
events and is valid. This prevents a notification server from
flooding an endpoint which did not actually request an event
subscription.To confirm a subscription, the feed provider SHALL send a
verification event to the subscriber using the registered
deliveryUri mechanism. The event contains
the following attributes:Set with a value of
urn:ietf:params:event:event:verify.Set to the URI of the feed publisher (see
).MUST be set to a value that matches the
subscription feedUri requested.A String value that the
subscriber SHALL echo back in its response. See deliveryUri
method profile for usage details.A 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 including
confirmation of keys.
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).For clients that use a subscription mode (e.g.
urn:ietf:params:scimnotify:api:messages:2.0:poll) that pick up events from a
subscription endpoint, the client MAY confirm the subscription
by simply reading the event using an HTTP GET at the endpoint specified by
the attribute subUri in the subscription. Once the
confirmation event has been retrieved, the service provider MAY mark the
subscription as confirmed.Each event delivery method SHALL have the following information:The deliveryUri URI value
for the delivery method and a description of the method.The procedure
that the configuration for a subscription is confirmed causing the
subscription status to be set to on.A description of an event delivery
message and how to locate the event token(s) as well as any additional
signaling parameters.The protocol procedure for a delivery
request (push or poll), and the expected successful response.A description of the failure
conditions that might occur and the impact on the subscriptions
operational status (subStatus) if any.A description of
any special considerations when passing multiple events in a single
delivery.[[is this needed?]]This method allows a feed provider to use HTTP POST to deliver
events to a registered web callback URL. The deliveryUri
value for this method is urn:ietf:params:event:delivery:HTTP:webCallback.Depending on the settings for the subscription metadata, this
delivery method is capable of delivering multiple signed events
in a single delivery.The content-type for this method is application/json
and consists of a JSON object containing the following attributes:A multi-valued String with each value containing
an identity event token (). Each value
MAY represent an unsigned, signed, or encrypted token. At least one
value MUST be present in a delivery request. An integer representing the number of events
present in the message. REQUIRED.An boolean indicating more deliveries
are pending. The default value is false.An optional multi-valued set of JSON objects containing events
that could not be accepted or failed. Used in a delivery response, a subscriber MAY return
an event that failed to validate or was unparseable.See .To deliver an event, the publisher generates an event delivery message
and uses HTTP POST to the registered endpoint.In response, if the event token is validated, the server SHALL
indicate successful submission by responding with: or to indicate errors it MAY respond with Since the normal operation of the Feed Provider is to forward
events to registered subscribers, the Feed Provider 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.[[TO BE COMPLETED]]This method allows a subscriber to use HTTP GET to poll for
events to the subUri provided to the subscriber by the publisher.
The deliveryUrivalue for this method
is urn:ietf:params:event:delivery:HTTP:poll.Depending on the settings for the subscription metadata, this
delivery method is capable of delivering multiple signed events
in a single delivery poll request.The delivery message is the same as .Subscription verification is described in .To deliver an event, the publisher places the event in a queue/buffer
associated with the client subscription that will be requested at some
future time by the subscriber using the URI specified in subUri.To pick up any events, the subscriber issues an HTTP GET to the URI
provided by the event publisher in subUri.In response to the HTTP GET request, the feed publisher responds with
a body that corresponds to the event delivery message format (see ).[[TO BE DISCUSSED: Should the subscriber be able to request
events based on an event id (e.g. since), by date, etc. How does
a client know it got them all? Should we use ETags to signal
whether there are new events?]][[TO BE DISCUSSED: The polling mode provides no way for a subscriber to indicate
parsing validation errors directly in response to a delivery. When
errors occur, subscriber administrators must re-confirm the subscription
configuration.]][[TO BE COMPLETED]]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]TODO: Registration for Notification MechanismsTODO: Registration of Event TypesIdentity Event Token (work in progress)Oracle CorporationSCIM Event Extensions (work in progress)Oracle CorporationThe editor would like to thank the participants in the the SCIM
working group for their support of this specification.Draft 00 - PH - First Draft