Notifications

An integral part of the overall integration architechture around Cerebrum is the message broker. Cerebrum publishes messages to a broker whenever a resource is modified.

Message broker

The message broker is implemented using RabbitMQ, and uses the AMQP-0.9.1 protocol to communicate with message producers and consumers.

For more details consult the the RabbitMQ AMQP v0.9.1 tutorial and the official AMQP v0.9.1 specification.

Messages from Cerebrum is available at:

Message subscriptions are available through Brom:

  1. Create an application in Brom
  2. Apply for subscription from the system-production-cerebrum notification source.

Message format

The message payload (body) is represented in JSON, encoded in JWT (RFC7519) using the SCIM Event Extension of the SCIM Protocol (RFC7644).

Example:

{
    "jti": "c311850c-e6e1-38c4-b253-3e28afcc9cf0",
    "iss": "cerebrum-example",
    "iat": 1523949064,
    "resourceType": "accounts",
    "sub": "https://example.org/cerebrum/v1/accounts/alice",
    "aud": [],
    "eventUris": ["urn:ietf:params:event:SCIM:password"],
    "urn:ietf:params:event:SCIM:password": {
        "attributes": [
            "password"
        ]
    }
}

Message fields

jti

UUID4 identifier — every message gets assigned a unique jti value. This value can be used to index or trace messages.

Example: "c1726be7-3812-4162-8ccd-ce2c580864d4"

iss

Issuer — every message from Cerebrum is assigned an issuer value to indicate which tenant the message was produced at: cerebrum-<tenant>

Example: "cerebrum-uio"

iat

Unix timestamp - shows when the message was issued.

Example: 1724249401

nbf

Unix timestamp - shows when the message is valid. This field is not always present. Messages with an nbf value should not be processed before the specified time.

Example: 1724249401

resourceType

Shows which object type the message relates to.

Possible values are:

sub

Identifier for the modified subject. The value is also an URL to the subject resource.

Example: "https://example.org/cerebrum/v1/accounts/alice"

aud

Audience - special interest field to indicate system scope for the affected subject. Certain systems can use this field to filter out messages for irrelevant subjects.

A list of possible values and descriptions can be fetched from the API (/cerebrum/v1/contexts/).

Example: ["active-directory", "ldap"]

eventUris

Lists the changes that are represented in this message. In the current implementation, a message will only carry one eventUri. Possible eventUris are:

Example: ["urn:ietf:params:event:SCIM:password"]

Some eventUris will add extra information in a <eventUri> object. This object may contain two values:

Example: {"attributes": ["password"]}

Routing keys

Each message is published with a routing key that matches its resource type and event type.

The format is no.uio.cerebrum.scim.<resource-type>.<event-type>, where resource-type matches the resourceType field, and event-type is the last part of the message eventUri.

Examples:

Examples: Account events

Typically, an account that has just been created isn't really of interest outside of Cerebrum internals. An account without any contexts (audience) are generally not considered active. However, immediately after creation, the account will usually be given a context, and modified with some basic account information.

You typically want to listen for account modification before provisioning accounts in other systems:

Routing keys:

Example message with routing key no.uio.cerebrum.scim.accounts.modify:

{
  "jti": "15b88e1c-f83d-464a-8e0b-9f88428ef00c",
  "iss": "cerebrum-uio",
  "iat": 899085600,
  "resourceType": "accounts",
  "sub": "https://gw-uio.intark.uh-it.no/cerebrum/v1/accounts/bob",
  "aud": ["AD_account", "NIS_user@uio"],
  "eventUris": ["urn:ietf:params:event:SCIM:modify"],
  "urn:ietf:params:event:SCIM:modify": {
    "attributes": ["accountType"]
  }
}

Furthermore, accounts are usually not deleted. Whether an account should exist or not in external systems should be decided by examining the resource and looking at the subject expire_date value.

Examples: Group events

Group create events are published with the routing key no.uio.cerebrum.scim.groups.create:

{
  "jti": "f0b34abd-b89d-44d0-9af7-049bb3a17433", 
  "iss": "cerebrum-example", 
  "iat": 899085600,
  "resourceType": "groups", 
  "sub": "https://example.org/cerebrum/v1/groups/acme", 
  "aud": [], 
  "eventUris": ["urn:ietf:params:event:SCIM:create"], 
  "iat": 1601559718, 
  "urn:ietf:params:event:SCIM:create": {
    "attributes": ["description"]
  }
}

When members are added to a group, a message is published with the routing key no.uio.cerebrum.scim.groups.add:

{
  "jti": "a603c0d5-2d05-447f-92c3-63f469dbebf4",
  "iss": "cerebrum-example",
  "iat": 899085600,
  "resourceType": "groups",
  "sub": "https://example.org/cerebrum/v1/groups/acme",
  "aud": [],
  "eventUris": ["urn:ietf:params:event:SCIM:add"],
  "urn:ietf:params:event:SCIM:add": {
    "attributes": ["member"],
    "object": ["https://example.org/cerebrum/v1/accounts/bob"]
  }
}

As with accounts, groups are first soft deleted by setting an expire date. Just as with accounts, you should monitor the routing key for no.uio.cerebrum.scim.groups.modify, look up the resource, and remove any groups that are expired (expire_date).

Groups that are expired will get permanently deleted after a while with a no.uio.cerebrum.scim.groups.delete message.