| Network Working Group | P. Hunt, Ed. |
| Internet-Draft | Oracle |
| Intended status: Standards Track | M. Ansari |
| Expires: January 3, 2018 | Cisco |
| July 2, 2017 |
SCIM Use Cases for SECEVENTS
draft-hunt-secevent-usecases-00
This specification defines the SCIM use cases for the SECEVENTs working group.
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 January 3, 2018.
Copyright (c) 2017 IETF Trust and the persons identified as the document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. 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.
SCIM is a system intended for provisioning identities (such as enterprise users or consumers) and other objects across security domains to a cloud based service providers. SCIM defines an extensible JSON [RFC7643] document format and profiles HTTP protocol [RFC7644]. In practice, SCIM service providers are applications supporting pre-provisioning support, or may be a service provider directory upon which applications are integrated.
This document defines the operational requirements SCIM deployers have for the use of triggers, as defined in the SCIM Use Cases specification [RFC7642], and used in the form of security events and the requirements for management based on SCIM architectural assumptions.
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 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.
This specification assumes terminology defined in the Security Event Token specification[I-D.ietf-secevent-token] .
This specification assumes terminology defined in the SCIM specifications, specifically [RFC7643] and [RFC7644]
This specification defines the following terms:
The SCIM Core Schema specification [RFC7643] is a profile of JSON [RFC7159] that defines attribute types, mutability, data formats, composites, and multi-value attributes as well as SCIM Service Provider feature and schema discovery metadata. As core schema defines standard resource types: Users and Groups which are common to most service providers. Each resource type establishes a common set of attribute definitions that can be mapped to SAML [saml-core-2.0] and to OpenID Connect [openid-connect-core] as well as application specific attributes. The core schema specification provides an extension mechanism which has been popular in:
The SCIM Protocol specification [RFC7644] describes a RESTful profile of HTTP [RFC7231] that defines create, read, update and delete life-cycle for resources. The processing rules follow Jon Postel's "Robustness Principle" (see Section 2.10) which help avoid many of the failings of previous XML based approaches. In particular the use of robust RESTful JSON helped ensure client and server ability to deal with inter-domain differences in schema, data, and implementation avoiding a lot of per implementation/deployment custom connector approaches.
SCIM clients use HTTP requests to SCIM service providers as follows to:
The SCIM Protocol defines capabilities for:
Some other relevant information:
SCIM's need for Security Events arises from a requirement for triggers identified in the SCIM Use Case specification [RFC7642]. Clients and service providers that operate across security domains have independent resource management that causes co-ordination and governance challenges between domains. The use of triggers is intended to alert clients (e.g. enterprises) of state changes within service providers that may be of interest to SCIM clients that may need to be co-ordinated or reconciled across domains.
As a general example, a change to a resource that occurs within a cloud software as a service (SaaS) provider generates an Event to be sent to a registered recipient via an Event Stream. Upon receipt of the event, the receiver performs a SCIM GET to obtain additional information and then decide if a local update or other action is required.
In the original SCIM identity event proposals, "Control Plane" functionality was accomplished by SCIM. SCIM protocol was proposed to configure and provision "streams" that deliver events via other protocols or profiles. The SCIM proposal allowed Event Receivers to check for delivery problems by retrieving Stream "resources" (which contain the stream configuration attributes) of which "status" is an attribute that could be used to report operational state of a stream. Updates to Stream resource enable Event Recipients to do things like rotate credentials, or suspend streams. To initiate a verification to test a stream is functional, the Receiver or an authorized administrator can modify the Stream resource to "request" a verify by changing the value of "status" to "verify". In SCIM the subjects in a stream can be identified by a number of methods:
The SCIM WG in re-using SCIM as the control plane had assumed the following is already defined (and any alternative proposal would have to support):
The SCIM WG discussed that transmission (now called data-plane or stream) can have much simpler semantics and error conditions and thus did not need to profile JSON beyond simple SET transfer (no need for attribute types, filters, etc). The SCIM WG also anticipated some varied requirements for delivery that include:
When defining filtered Streams, SCIM has to consider some special cases when the contents of a Stream is based upon a filter (query) to define which affected resources are included. For example, if the contents of a Stream is defined as Events related to resources where emails.value sw "A" and a resource is deleted, then the deleted resource won't match the filter anymore but notification may still need to be sent.
Network relationships for connections are typically:
An enterprise directory is typically (but not always) legacy-LDAP. In the cloud, a directory is simply any shared centralized profile store (e.g. Google Dir, Azure Directory/OpenGraph, SCIM Directory, etc). Important: While for many organizations LDAP remains the center of administrative control, it is important to note that cloud directories and applications hold significantly more PII than enterprise directories. This creates a challenge for enterprise organizations to ensure proper governance and management of data given that a lot of cloud data is independently managed and updated.
As with an enterprise directory, a cloud directory is often shared by multiple applications. Cloud directories not only contain entitlement information but now also contain CRM data, contact, credentials, personalization and localization data, social network data, etc (the list goes on). While some cloud providers centralize others are tenancy structured with different directory endpoints per tenancy (e.g. Oracle).
As described above, because data, particularly PII, is being independently managed across multiple domains, there is a need to generate change signals (events) from cloud based directories and applications back to the enterprise. This was originally identified in the SCIM Use Cases (see Section 2.2.1).
The following use cases are expressed in terms of the direction of flow of events. In typical SCIM cases, there is only 1-way event exchange. Typical usage of events is to act as a “trigger” (see [RFC7642]) to let a receiver know that an event has occurred in the transmitter's domain that may require action on the part of the receiver. Events can be simple resource changed events, to higher level account status and change events (e.g. account or password reset). While many events are similar to OpenID RISC proposed events, a major distinction is that SCIM events are often triggered by user, administrative, or workflow provisioning action rather than a risk analytical engine (e.g. that might detect suspicious activity).
Pre-conditions:
+----------------+--------+
| SCIM | SCIM |
|Service Provider| Events |
| | Stream |
+--------^-------+--------+
SCIM| |Events via
Commands| |HTTP POST
| |
| |
| |
| |
+-+----------v-+
| SCIM Client |
| Provisioning |
| Controller |
+--------------+
Figure 1: SCIM Provisioining with PUSH Triggers
In Figure 1, the SCIM client initiates RESTful SCIM commands to a SCIM service provider. In addition to provisioning security objects such as Users and Groups, the client also uses SCIM to provision Event Streams in order to receive Events to an endpoint the provisioning controller requests. The service provider MUST be able to POST to the client's domain. Usually this means the client is able to have a public HTTP endpoint available to receive SET events.
Stream Creation Flow:
To create a Stream, the Event Receiver (or an administrator) uses their SCIM access credential to access the SCIM endpoint and creates a Stream resource configuration:
POST /Streams
Host: scim.bighost.com
Authorization: Bearer h480djs93hd8
{ "receiverId":"<client-id>",
"method":"webCallBack",
"receiverUri":"https://set.example.com/events/",
"aud":"<client-id>",
"type":"SCIM",
"receiverJwkUri":"<receiver's public key url>",
"authorization":"<btoken|BasicAuth>"
}
Figure 2: Stream Creation Operation
Note: If the Transmitter does not have an HTTP credential to send events, the receiver should include one in its registration POST request or negotiate one out-of-band.
In the stream configuration there is likely a definition as to what types of events (event families) and which subjects constitute the feed. In SCIM this will likely be a group of objects, or filter condition such as “roles” eq ”CRM_Users”. This is likely based on the relationship between parties that determines which entities are provisioned between domains.
Upon successful creation of the Stream, the SCIM Event Transmitter Responds with:
HTTP/1.1 201 Created
Location: https://events.bighost.com/Streams/2819c223-7f76-453a
{ "receiverId":"<client-id>",
"method":"webCallBack",
"receiverUri":"https://set.example.com/events/",
"aud":"<client-id>",
"type":"SCIM",
"receiverJwkUri":"<receiver's public key url>",
"authorization":"<btoken|BasicAuth>”,
”status”:”on"
}
Note that in the above figure, the Location URI is the fixed reference to the Stream for as long as it exists. Administrative users and Event Receiver entities MAY use the location to check status or update configuration as needed.
Figure 3: Stream Creation Response
[[TBD, the event receiver, needs to issue the event transmitter a credential in order for it to issue HTTP POSTs to the Event Receivers callback endpoint. In some cases there may be an existing OpenID Connect relationship but in most cases this not expected - especially in directory-to-directory synchronization scenarios.]]
Stream Verification:
During the initial stream creation request and at any point the transmitter deems appropriate (e.g. as a ping), the transmitter verifies configuration by sending a verification event to the receiver that demonstrates the receiver:
Conversely an Event Receiver should be able to initiate a verification request and may provide a confirmation challenge and nonce to verify the relationship from the Event Receiver's perspective.
Delivery:
Delivery is accomplished by doing a simple HTTP POST to the registered endpoint of the receiver. The payload of the POST is application/jwt and contains a single JWT (which is actually a SET).
Before responding with a 2xx success message, the receiver should ensure it was able to read and validate the SET. If the transmitter receives a 2xx response, the transmitter may assume the event was successfully delivered.
A set of Status 400 error conditions are defined which the receiver can use to indicate various JWT validation conditions.
Pre-conditions:
+----------------+--------+
| SCIM | SCIM |
|Service Provider| Events |
| | |
+--------^-------+--^-----+
SCIM| |Events via
Commands| |HTTP GET Long Poll
| |& POST Acks
Firewall | |
+---------------------------------------+
| |
+-+----------+-+
| SCIM Client |
| Provisioning |
| Controller |
+--------------+
Figure 4: Event Delivery with Firewall
In Figure 4, the SCIM client initiates RESTful SCIM commands to a SCIM service provider. In addition to provisioning security objects such as Users and Groups, the client also uses SCIM to provision Event Streams in order to receive Events to an endpoint the provisioning controller requests. In this case, the SCIM Client "polls" for events using HTTP GET. The client MAY request immediate response based on a timed schedule, or the client MAY use HTTP Long Polling to wait for SETs as they become available.
Stream Creation Flow:
The Event Receiver uses their SCIM credential to access the SCIM service provider endpoint to create a Stream resource by performing a POST
POST /Streams
Host: scim.bighost.com
Authorization: Bearer h480djs93hd8
{ "receiverId":"<client-id>",
"method”:"POLLING”,
"aud":"<client-id>",
"type":"SCIM",
"receiverJwkUri":"<receiver's public key url>"
}
Figure 5: Create Polling Stream
It is assumed, but may not always be true. that the POLLING receiver can simply use their SCIM credential to perform HTTP GETs to the polling endpoint. Additional parameters will likely need to be defined to control polling rate, number of events in a message, etc.
Note, in the stream configuration there is likely a definition as to what types of events (event families) and which subjects constitute the feed. In SCIM this will likely be a group of objects, or filter condition such as “roles” eq ”CRM_Users”. This is likely based on the relationship between parties that determines which entities are provisioned between domains.
Upon successful creation of the stream, the transmitter responds to the receiver with:
HTTP/1.1 201 Created
Location: https://events.bighost.com/Streams/2819c223-7f76-453a
{ "receiverId":"<client-id>",
"method”:"POLLING",
"receiverUri":"https://set.bighost.com/Events/2819c223-7f76-453a",
"aud":"<client-id>",
"type":"SCIM",
"receiverJwkUri":"<receiver's public key url>”,
”status”:”on"
}
Figure 6: Polling Stream Creation Response
In the above response, the transmitter indicates to the receiver where to poll for events by setting a value for “receiverUri”. This endpoint does not need to be SCIM compliant and can be a generic (e.g. shared by all polliers) endpoint such as https://events.bighost.com.
Stream Verification:
Same requirements are for Scenario 1 (see Section 4.1).
Delivery:
Delivery is accomplished by having the Event Receiver initiate an HTTP request that causes a response such as:
{
"sets":{
"4d3559ec67504aaba65d40b0363faad8":
"eyJhbGciOiJub25lIn0
.
e3sgIAogICJqdGkiOiAiNGQzNTU5ZWM2NzUwNGFhYmE2NWQ0MGIwMzYzZmFhZDgiLAog
ICJpYXQiOiAxNDU4NDk2NDA0LAogICJpc3MiOiAiaHR0cHM6Ly9zY2ltLmV4YW1wbGUu
Y29tIiwgIAogICJhdWQiOiBbCiAgICJodHRwczovL3NjaW0uZXhhbXBsZS5jb20vRmVl
ZHMvOThkNTI0NjFmYTViYmM4Nzk1OTNiNzc1NCIsCiAgICJodHRwczovL3NjaW0uZXhh
bXBsZS5jb20vRmVlZHMvNWQ3NjA0NTE2YjFkMDg2NDFkNzY3NmVlNyIKICBdLCAgCiAg
CiAgImV2ZW50cyI6IHsKICAgICJ1cm46aWV0ZjpwYXJhbXM6c2NpbTpldmVudDpjcmVh
dGUiOiB7CiAgICAgICJyZWYiOgogICAgICAgICJodHRwczovL3NjaW0uZXhhbXBsZS5j
b20vVXNlcnMvNDRmNjE0MmRmOTZiZDZhYjYxZTc1MjFkOSIsCiAgICAgICJhdHRyaWJ1
dGVzIjpbImlkIiwgIm5hbWUiLCAidXNlck5hbWUiLCAicGFzc3dvcmQiLCAiZW1haWxz
Il0KICAgIH0KICB9Cn0",
"<nextJti>":"<nextJwt>"
},
"since":1458496025
}
Figure 7: Example Polling Response
In the above JSON object is a JSON attribute “sets” whose value is a JSON object that contains a set of JSON attributes that correspond to each event’s JTI value. the value for each attribute is the actual encoded SET.
In addition to the “sets” attribute, a “since” attribute indicates the timestamp of either the last event previously transmitted or potentially oldest event in the current payload (To be discussed).
In order to acknowledge receipt, the receiver must successfully parse each message and respond by doing an HTTP POST back to the events endpoint using something along the lines of the following JSON structure:
{
"ack":[
“39e48e70e9f84d90b5fdbf2fbd826219”,
“8e1ed13b871547ffa332f7027a0fdd91”,
“0a02c62529e34541a8b3c5c7941fa545”
]
"setErrs":{
"3d0c3cf797584bd193bd0fb1bd4e7d30":{
"err":"dup",
"description":"SET already received. Ignored."
}
}
}
Figure 8: Poll Acknowledgement Response
In the payload above the receiver indicates which SET event JTIs have been accepted, and which SETs had errors using “accepts” and “setErrs”.
It is expected that because most errors are due to JWT crypto configuration errors, that most responses will tend to be all errors or all accepts.
If a transmitter receives what it deems an unrecoverable error, or a receiver fails to poll for events, the transmitter can set the stream state to “failed” with an appropriate error indicator.
This scenario is a hybrid of scenario 1 and 2. The scenario uses mobile message delivery services (APNS, GMS, SMS) to deliver events. Typically a stream has only one subject in its feed. The events are used to notify client applications about changes to entitlements, or other configuration (e.g. new tenancy endpoints)that might be useful to user experience.
As in the polling method in Scenario 2, to acknowledge events, the mobile app will need to use the POST (as defined in Scenario 2) to acknowledge SET delivery. To be discussed, this might not be necessary if assured delivery is not required.
None as this is a use case document to describe considerations.
None as this is a use case document to describe considerations.
There are no IANA considerations.
| [RFC2119] | Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997. |
| [RFC3986] | Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, DOI 10.17487/RFC3986, January 2005. |
The editors would like to thanks the members of the SCIM WG which began discussions of provisioning events starting with: draft-hunt-scim-notify-00 in 2015.
The editor would like to thank the participants in the the SECEVENTS working group for their support of this specification.
Draft 00 - PH - Initial draft