SCIM Profile for Security Event Tokens

1.2. Notational Conventions

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.3. Definitions

This specification uses definitions from the following specifications:¶

• Security Event Tokens [RFC8417], and¶
• System for Cross-Domain Identity Management Protocol [RFC7644].¶

Additionally, the following terms are defined:¶

Attributes and Claims

The JWT specification [RFC7519] upon which SET is based uses the term "claims" to refer to attributes in a JSON token. SCIM in contrast uses the term "attributes" to refer to JSON attributes. For the purposes of this draft, the terms "attributes" and "claims" are equivalent.¶

CP

Abbreviation for "Co-ordinated Provisioning" as defined in Appendix A.2. In these relationships an Event Publisher and Receiver typically exchange resource change events without exchanging change data. For a receiver to know the value of the data, the Event Receiver usually has to call back to the Event Publisher domain to receive a new copy of data (e.g. Using a SCIM GET request).¶

DBR

Abbreviation for "Domain Based Replication" as defined in Appendix A.1. In this mode because there is an administrative relationship spanning multiple operational domains, data shared in Events typically includes all of the change data. This eliminates the need for a call back (e.g. a SCIM GET request), to retrieve raw data.¶

Event Feed

This describes the notion that a feed MAY be individualized per client. A service provider MAY offer to allow Event Receiver's to "subscribe" to specific event types or events about specific resources. If no option is offered, it is assumed the client will receive all events about all resources.¶

Event Receiver

A service that receives events for the purpose of subsequent action (e.g. such as replication), co-ordination of workflow, or signalling. In the case of SET Push Transfer [RFC8935], the Event Receiver is an HTTP Service Endpoint that receives requests. In the case of SET Poll-Based Transfer [RFC8936], the receiver is an HTTP client that initiates HTTP request to an Event Publisher endpoint.¶

Event Publisher

A system that issues SETs based on a change that has occurred at a SCIM Service Provider. For example, events MAY originate from a SCIM Create, Modify, or Delete per [RFC7644] request. A SCIM Service Provider MAY be an Event Publisher or an independent service that aggregates events into Event Receiver feeds. As described above, when using [RFC8935], the Event Publisher is an HTTP Client that initiates HTTP POST requests to a defined Event Receiver endpoint. When using [RFC8936], the Event Publisher provides an HTTP endpoint which a receiver MAY use to "poll" for Security Events.¶

RS

Abbreviation for "Risk Signals" as defined in Appendix A.3.¶

SCIM Client

An HTTP client that initiates SCIM Protocol [RFC7644] requests and receives responses.¶

SCIM Service Provider

An HTTP server that implements SCIM Protocol [RFC7644] and SCIM Schema [RFC7643].¶

SET

Abbreviation for "Security Event Token" as defined in [RFC8417]¶

2.1. Identifying the Subject of an Event

SCIM Events SHALL use the "sub_id" claim defined by Subject Identifiers for Security Event Tokens [SUBID] specification to identify the subject of events. Since it is possible to issue a SCIM SET Event with multiple events, the sub_id claim MUST NOT be contained within an Event payload. A SET with multiple event URI's SHALL indicate that the events originate from the same transaction or resource state change. Finally, to distinguish SET Events from JWT tokens, the JWT "sub" claim MUST NOT be used.¶

{
     "iss": "issuer.example.com",
     "iat": 1508184845,
     "aud": "aud.example.com",
     "sub_id": {
        "format": "scim",
        "uri": "/Users/2b2f880af6674ac284bae9381673d462",
        "externalId": "alice@example.com"
     },
     "events": {
       ...
     }
}

The top-level claim "sub_id" contains a sub-claim "format" whose value is set to scim to indicate the other attributes present are SCIM attributes. The following sub_id attributes are defined:¶

uri

The SCIM relative path for the resource which usually consists of the resource type endpoint plus the resource id. For example /Users/2b2f880af6674ac284bae9381673d462. This attributes MUST be provided in a SCIM Event sub_id claim. Note the relative path is the path component after the SCIM Service Provider Base URI as defined in Section 1.3 [RFC7644]. In cases where the Event Receiver is unable to match a URI, the Event Receiver MAY issue a call-back to a previously agreedn SCIM Service Provider Base URI plus the relative uri value and perform a SCIM GET request per Section 3.4.1 [RFC7644].¶

externalId

If known, the externalId value of the SCIM Resource that MAY be used by a receiver to identify the corresponding resource in the Event Receiver's domain.¶

id

The SCIM Id attribute MAY be used for backwards compatibility reasons in addition to the uri claim.¶

emails,username, ...

A SCIM attribute which is uniquely identifiable (e.g. username, emails). Used in situtations where the normal SCIM identifiers ( id and externalId) are insufficient to identfy a common resource between an Event Publisher and Event Receiver.¶

2.2. Common Event Attributes

The following attributes are available for all events defined. Some attributes are defined as SET/JWT claims, while others are "Event Payload" claims as defined in Section 1.2 [RFC8417].¶

txn

For the purposes of SCIM, this SET defined "top-level" claim identifies a unique transaction originating at a SCIM Service Provider and/or its underlying data repository or database. The claim is used to detect duplicate transactions that may have been received (e.g. in the case of a re-transmitted or recovered event). If not provided, the SET jti claim MAY be used. Where txn identifies uniqueness within a SCIM Service Provider, multiple SETs may be issued each with distinct JTI's stemming from a common originating transaction with identical txn values.¶

data

Defined in SCIM Bulk Operations, Section 3.7 [RFC7644], thie payload attribute contains the equivalent SCIM command processed by the SCIM Service provider. For example, after processing a SCIM Create operation, the data contained includes the final representation of the created entity by the SCIM Service Provider including the assigned id value.¶

attributes

This payload attribute contains an array of attributes that were added, revised, or removed. For example:
"attributes": ["username","emails"]¶

Only one of data or attributes claims SHALL be provided depending on the event definition.¶

This specifications defines a new URI prefix urn:ietf:params:event:SCIM which is used as the prefix for the following defined SCIM Events.¶

2.3. SCIM Feed Events

This section defines events related to notices about which resources are being added or removed from an event feed. These events are used in Co-operative Provisioning scenarios where only a sub-set of entities are shared across an Event Feed. The URI prefix for these events is: urn:ietf:params:event:SCIM:feed¶

{
  "jti": "6164f3bbf6ff41a88dc94f18cb0620e8",
  "txn": "b7b953f11cc6489bbfb87834747cc4c1",
  "sub_id": {
    "format": "scim",
    "uri": "/Users/2b2f880af6674ac284bae9381673d462",
    "externalId": "jdoe"
  },
  "events":{
    "urn:ietf:params:event:SCIM:feed:add": {}
  },
  "iat": 1458505044,
  "iss":"https://scim.example.com",
  "aud":[
   "https://scim.example.com/Feeds/98d52461fa5bbc879593b7754"
  ]
}

{
  "jti": "6164f3bbf6ff41a88dc94f18cb0620e8",
  "sub_id": {
    "format": "scim",
    "uri": "/Users/2b2f880af6674ac284bae9381673d462"
    "externalId": "jdoe",
  },
  "events":{
    "urn:ietf:params:event:SCIM:feed:remove": {}
  },
  "iat": 1458505044,
  "iss":"https://scim.example.com",
  "aud":[
   "https://scim.example.com/Feeds/98d52461fa5bbc879593b7754"
  ]
}

2.4. SCIM Provisioning Events

This section defines provisioning events that have occurred within a SCIM Service Provider. These events are used in both Domain Based Replication (DBR) and Co-operative Provisioning (CP) mode. The URI prefix for these events is: urn:ietf:params:event:SCIM:prov¶

{
  "jti": "4d3559ec67504aaba65d40b0363faad8",

  "iat": 1458496404,
  "iss":"https://scim.example.com",
  "aud":[
    "https://scim.example.com/Feeds/98d52461fa5bbc879593b7754",
    "https://scim.example.com/Feeds/5d7604516b1d08641d7676ee7"
  ],
  "sub_id": {
    "format": "scim",
    "uri": "/Users/44f6142df96bd6ab61e7521d9",
     "externalId":"jdoe"
  }
  "events":{
    "urn:ietf:params:event:SCIM:prov:create":{
      "data":{
        "schemas":[ "urn:ietf:params:scim:schemas:core:2.0:User"],
        "emails":[
          {"type":"work","value":"jdoe@example.com"}
        ],
        "userName":"jdoe",
        "name":{
          "givenName":"John",
          "familyName":"Doe"
        }
      }
    }
  }
}

{
  "jti": "4d3559ec67504aaba65d40b0363faad8",
  "iat": 1458496404,
  "iss":"https://scim.example.com",
  "aud":[
    "https://scim.example.com/Feeds/98d52461fa5bbc879593b7754",
    "https://scim.example.com/Feeds/5d7604516b1d08641d7676ee7"
  ],
  "sub_id": {
    "format": "scim",
    "uri": "/Users/44f6142df96bd6ab61e7521d9",
    "externalId": "jdoe"
  },
  "events": {
    "urn:ietf:params:event:SCIM:prov:create": {
      "attributes": [
        "id",
        "name",
        "userName",
        "password",
        "emails"
      ]
    }
  }
}

{
  "jti": "6164f3bbf6ff41a88dc94f18cb0620e8",
  "sub_id": {
    "format": "scim",
    "uri": "/Groups/176f397ec4c44b94b2cfcb759780b8c2",
    "externalId": "crmUsers"
  },
  "events":{
    "urn:ietf:params:event:SCIM:prov:patch": {
      "version": "a330bc54f0671c9",
      "data": {
        "schemas":
      ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
        "Operations":[{
          "op":"add",
          "path":"members",
          "value":[{
             "display": "Babs Jensen",
             "$ref": "/Users/2819c223...413861904646",
             "value": "2819c223-7f76-453a-919d-413861904646"
          }]
        }]
      }
    }
  },
  "iat": 1458505044,
  "iss":"https://scim.example.com",
  "aud":[
   "https://scim.example.com/Feeds/98d52461fa5bbc879593b7754"
  ]
}

{
  "jti": "6164f3bbf6ff41a88dc94f18cb0620e8",
  "sub_id": {
    "format": "scim",
    "uri": "/Groups/176f397ec4c44b94b2cfcb759780b8c2",
    "externalId": "crmUsers"
  },
  "events":{
    "urn:ietf:params:event:SCIM:prov:patch": {
      "attributes": ["members"],
      "version": "a330bc54f0671c9"
    }
  },
  "iat": 1458505044,
  "iss":"https://scim.example.com",
  "aud":[
   "https://scim.example.com/Feeds/98d52461fa5bbc879593b7754"
  ]
}

{
  "jti": "6164f3bbf6ff41a88dc94f18cb0620e8",
  "sub_id": {
    "format": "scim",
    "uri": "/Users/2819c223-7f76-453a-919d-413861904646"
  },
  "events":{
    "urn:ietf:params:event:SCIM:prov:put": {
      "version": "a330bc54f0671c9",
      "data": {
        "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],
        "userName":"jdoe",
        "externalId":"jdoe",
        "name":{
           "formatted":"Mr. Jon Jack Doe III",
           "familyName":"Doe",
           "givenName":"Jon",
           "middleName":"Jack"
        },
        "roles":[],
        "emails":[
          {"value":"jdoe@example.com"},
          {"value":"anon@jdoe.org"}
        ]
      }
    }
  },
  "iat": 1458505044,
  "iss":"https://scim.example.com",
  "aud":[
   "https://scim.example.com/Feeds/98d52461fa5bbc879593b7754"
  ]
}

{
  "jti": "6164f3bbf6ff41a88dc94f18cb0620e8",
  "sub_id": {
    "format": "scim",
    "uri": "/Users/2819c223-7f76-453a-919d-413861904646"
  },
  "events":{
    "urn:ietf:params:event:SCIM:prov:put": {
      "version": "a330bc54f0671c9",
      "attributes": ["userName","externalId","name","roles","emails"]
    }
  },
  "iat": 1458505044,
  "iss":"https://scim.example.com",
  "aud":[
   "https://scim.example.com/Feeds/98d52461fa5bbc879593b7754"
  ]
}

{
  "jti": "6164f3bbf6ff41a88dc94f18cb0620e8",
  "sub_id": {
    "format": "scim",
    "uri": "/Users/2b2f880af6674ac284bae9381673d462",
    "externalId": "jDoe"
  },
  "events":{
    "urn:ietf:params:event:SCIM:prov:delete": {}
  },
  "iat": 1458505044,
  "iss":"https://scim.example.com",
  "aud":[
   "https://scim.example.com/Feeds/98d52461fa5bbc879593b7754"
  ]
}

{
  "jti": "6164f3bbf6ff41a88dc94f18cb0620e8",
  "sub_id": {
    "format": "scim",
    "uri": "/Users/2b2f880af6674ac284bae9381673d462"
  },
  "events":{
    "urn:ietf:params:event:SCIM:prov:activate": {}
  },
  "iat": 1458505044,
  "iss":"https://scim.example.com",
  "aud":[
   "https://scim.example.com/Feeds/98d52461fa5bbc879593b7754"
  ]
}

2.5. SCIM Signals Events

This section defines security signal events that have occured within a SCIM Service Provider.The URI prefix for these events is: urn:ietf:params:event:SCIM:signal¶

{
  "jti": "3d0c3cf797584bd193bd0fb1bd4e7d30",
  "sub_id": {
    "format": "scim",
    "uri": "/Users/44f6142df96bd6ab61e7521d9"
  },
  "events":{
    "urn:ietf:params:event:SCIM:sig:authMethod": {}
  },
  "iat": 1458496025,
  "iss": "https://scim.example.com"
}

{
  "jti": "3d0c3cf797584bd193bd0fb1bd4e7d30",
  "sub_id": {
    "format": "scim",
    "uri": "/Users/44f6142df96bd6ab61e7521d9"
  },
  "events": {
    "urn:ietf:params:event:SCIM:sig:pwdReset": {}
  },
  "iat": 1458496025,
  "iss": "https://scim.example.com",
  "aud":[
    "https://jhub.example.com/Feeds/98d52461fa5bbc879593b7754",
    "https://jhub.example.com/Feeds/5d7604516b1d08641d7676ee7"
  ]
}

2.6. Miscellaneous Events

This section defines events related miscellaneous events such as Asynchronous Request complettion that have occured within a SCIM Service Provider. The URI prefix for these events is: urn:ietf:params:event:SCIM:misc¶

{
  "jti": "6164f3bbf6ff41a88dc94f18cb0620e8",
  "sub_id": {
    "format": "scim",
    "uri": "/Users/b7c14771-226c-4d05-8860-134711653041"
  },
  "txn": "7880fc68a2f0428ebbb5a906e5aeae53",
  "events":{
    "urn:ietf:params:event:SCIM:misc:asyncResp": {
        "method": "PUT",
        "version": "W\/\"huJj29dMNgu3WXPD\"",
        "status": "200"
    }
  },
  "iat": 1458505044,
  "iss":"https://scim.example.com",
  "aud":[
   "https://scim.example.com/Feeds/98d52461fa5bbc879593b7754"
  ]
}

3.1. Security Event Token Signing and Encryption

This specification uses Security Event Tokens as the message format for SCIM Events. As SETs are based on JWT tokens [RFC7519], they can be transmitted unsecurity, signed, or encrypted. For more information see the JWT Cookbook specification [RFC7520] for examples. The decision on whether to use JWS and JWE depends on operational considerations. For each SCIM Feed relationship, it is up to deployers to decide on signing, encryption and algorithm requirements. Deployers SHOULD be aware that too much emphasis on turning on every possible encryption feature may cause operational performance to suffer. Deployers MUST weigh the security trade-offs of up-to-date SCIM services, vs. the potential information loss of an event.¶

Unsecured

Per Section 6 [RFC7519], tokens MAY be generated with {"alg":"none"}. This mode speeds up processing and is best used in DBR scenarios. Unencrypted tokens MUST be transferred over authenticated TLS layer encryption and SHOULD only be used in a restricted network environment.¶

Signed

JWS ([RFC7515]) signed SETs are useful when it is important to be able to verify the issuer of a SET as valid. In addition, some systems MAY wish to validate the authenticity of the event in a review process which may occur at a later date. While the content can be validated as originating from the correct issuer and is unmodified, the message contents remain unsecure. Signed SETs MUST be transferred over encrypted transport.¶

Encrypted

JWE ([RFC7516]) are encrypted SETs and are useful when the transport mechanism is not fully securable (e.g. messages carried by a third party). The use of JWEs ensures only the designated receiver can read the event and provides mutual authentication within the SET mesage itself.¶

3.2. Point-to-Point Delivery Over HTTP

Security Event Tokens MAY be delivered using push-based HTTP delivery [RFC8935], or pull-based HTTP Polling [RFC8936]. Both of these protocols define a method of transfer and acknowledgement to prevent loss-of-information and to provide re-transmission and recover. The method of transfer is best decided by considering the following advantages and disadvantages in a production scenario:¶

Push-based delivery has the following advantages:¶

• Message transfer is instant (when compared to using a common Event Publisher acting as a relay), and in high event frequency scenarios, HTTP connections can be kept open.¶
• Scales well when an SCIM Event Publisher has thousands of event receivers and TCP resources may be limited.¶
• Does not require events to be routed to a single publisher node. SCIM Events may be issued by SCIM Service Provider nodes where the transaction occurred.¶
• SCIM Events only need to be retained until they have been delivered to designated receivers.¶

Push-delivery has the following disadvantages:¶

• A SCIM Event Publisher system needs authorization credentials enabling it to access the HTTP SCIM Event delivery endpoint.¶
• When synchronizing business data that is behind protected firewalls, a virtual network or other firewall policy may be required to allow external network based SCIM providers to deliver SCIM Events to internally hosted systems.¶

Delivery by HTTP Polling has the following advantages:¶

• It is possible for a SCIM Event Receiver to use the same SCIM credentials it uses when access the normal SCIM Service Provider service defined by [RFC7644].¶
• Systems behind protected network boundaries can reach externally hosted systems without requiring special firewall or network configuration.¶
• Instantaneous transfer can be used using HTTP Long-polling as described Section 2.1 of [RFC8936].¶

Polling-based delivery has the following disadvantages:¶

• Long-polling requires the use of persistent connections for which TCP resources may be limited. HTTP Long-polling is best used in scenarios when there are relatively few Event Receivers.¶
• The SCIM Event Publisher MUST retain events for the Event Receiver until delivered.¶

A.1. Domain Based Replication

The objective of "Domain Based Replication" events (DBR) is to synchronize resource changes between SCIM service providers in a common administrative domain. In this mode, complete information about changes for resources are shared between replicas for immediate processing.¶

From a security perspective, it is assumed that servers sharing DBR events are secured by a common access policy and all servers are required to be up-to-date. From a Privacy Perspective, because all servers are in the same administrative domain, the primary objective is to keep individual service provider nodes or cluster synchronized.¶

A.2. Co-ordinated Provisioning

In "Co-ordinated Provisioning" (CP), SCIM resource change events perform the function of change notification without the need to provide raw data. In any Event Publisher and Receiver relationship, the set of SCIM resources (e.g. Users) that are linked or co-ordinated is managed within the context of a an event feed and which MAY be a subset of the total set of resources on either side. For example, an event feed could be limited to users who have consented to the sharing of information between domains. To support capability, "feed" specific events are defined to indicate the addition and removal of SCIM resources from a feed. For example, when a user consents to the sharing of information between domains, events about the User MAY be added to the feed between the Event Publisher and Receiver.¶

In CP mode, the receiver of an event must call back to the originating SCIM Service Provider (e.g. using a SCIM GET request) to reconcile the newly changed resource in order to obtain the changes.¶

Co-ordinated provisioning has the following benefits:¶

• Differences in schema (e.g. attributes) between domains. For example, a receiving domain may only be interested or only be allowed access to a few attributes (e.g. role based access data) to enable access to an application.¶
• Different Event Receivers MAY have differing needs access to information and thus be assigned varying access rights. Minimal information events combined with call-backs for data allows data filtering to be applied.¶
• Receivers can take independent action. For example deciding which attributes or resource lifecycle changes to accept. For example, in the case of a conflict, a receiver can prioritize one domain source over another.¶
• A receiver MAY throttle or buffer changes rather than act immediately on a notification. For example, for a frequently changing resource, the receiver MAY choose to make scheduled SCIM GET for resources that have been marked "dirty" by events received in the last scheduled cycle.¶

A disadvantage of the CP approach is that it may be considered costly in the sense that each event received might trigger a call back to the event issuer. This cost should be weighed against the cost producing filtered information in each event for each receiver. Further a receiver is not required to make a call-back on every provisioning event.¶

It is assumed that an underlying relationship between domains exists that permits the exchange of personal information and credentials. For example the decision to perform SCIM provisioning operations at the SCIM Service Provider issuing change events, was previously authorized and appropriate confidentiality and privacy agreements have been met in cross-domain scenarios. Examples of this might be services for hire by an employer or a specific consent from an end-user as part of a online authorization where individual consent was obtained.¶

When sharing information between parties, CP Events minimize the information shared in each message requiring the Security Event Receiver to call back to the event publisher to retrieve more information if required. In this way, the Event Publisher is able to regular access to information through normal SCIM protocol access restrictions.¶

A.3. Risk Signals

The sharing of risk signals (RS) is used for the purpose of co-ordinating account change events between a SCIM Service Provider and another related security service. For example, when a password or other authentication factor has changed, a receiving security system can choose to terminate current User sessions to force a re-authentication against the modified User resource.¶

These signals MAY also include those described in the OpenID Shared Signals Working Group Specifications [SSWG].¶

These events are intended for receivers where there is a prior relationship on behalf of the users described in the SCIM Service Provider. The intent of sharing information about security events is for the purpose of securing a user account and ensuring privacy.¶

A.4. Async Requests

A SCIM provisioning client MAY wish to request "asynchronous" processing using the "Prefer Header for HTTP", Section 4.1 [RFC7240]. In this mode, a normal SCIM protocol POST, PUT, PATCH, or DELETE request is made, and the HTTP Header Prefer is included with the value respond-async. When a SCIM Client signals respond-async, the SCIM server response changes to HTTP Status 202 Accepted as defined in [RFC7231]. The Location header returned is the final resource location and no payload is present. Following acceptance of an asynchronous request, a notification of completion can be issued using the Async Event Notification per Section 2.6.1. The location returned SHALL correspond to the sub claim in the future Async Event SET message.¶