Sentinel Service API

The Sentinel Service API defines RESTful services that consumers may utilize when integrating with the Sentinel system.

Data Model

The following describes, at a high level, the data model of entities supported by the Sentinel platform.

Audit Event Data Model

Audit events are events used to track when a user has caused an action within a system. An audit event is uniquely identified by a minimum of three attributes (and, consequently, requires, at minimum, these attributes):

• Event Key: An identifier of an event that, when namespaced within the pool of events emitted by your system, uniquely identifies the type of action performed.
• Event Time: The date and time at which an event occurred.
• Outcome: The outcome of the event; typically, the event will be successful unless there was an error on the part of the user that would cause an expected failure (for example, if a user enters an incorrect password, then such a login event would be audited as a failure)

The following are optional fields that you can supply to describe your audit event:

• Tenant: An identifier of the tenant on whose behalf an action was taken; as an example, if a user in a Millennium multi-tenant performs an audited action in the Millennium system, the event would have a tenant identifying the Millennium tenant on whose behalf the action was taken within the Millennium system.
• User: An identifier of the user who caused the action to occur. Preferablly, this is a globally unique identifier, such as an OpenID identifier, but it does not necessarily have to be such.

Additionally, every event can contain a number of key-multivalue pairs of attributes describing additional properties of the attribute, themselves, are not necessarily part of the core data model, but help describe the context around an audited event.

Provided Attributes

The Sentinel platform, itself, provides a number of attributes that further describe details of your event.

System and System & Tenant Names

By default, all events received have a SYSTEM attribute added that contains the authenticated identifier of the system that submitted an event.

Additionally, if available, the SYSTEM:NAME and TENANT:NAME meta attributes are added to events, each of which containing a more human-readable descriptor of the system and/or tenant (if such information is available at time of processing the event).

Person Details

If the Sentinel platform, upon receipt of an event, sees a user identifier for which it can retrieve details, it will add the following meta attributes for that attribute:

• <attribute name>:EMAILS: a list of any known e-mail addresses for the user at time of data ingestion
• <attribute name>:FAMILY_NAME: the family name of the user (if known)
• <attribute name>:GIVEN_NAME: the given name of the user (if known)
• <attribute name>:USERNAME: the username of the user (if known)

The following identifiers are supported for this kind of expansion:

• CernerCare OpenID
• Associate OpenID
• Millennia OpenID
• Identity Federation URN

Registration Data Model

Registrations describe information about the events that will be emitted by your system. Each registration describes each event your system will emit, as well as all possible attributes that could be emitted on that attribute. Bear in mind that your events do not have to always have all registered attributes present when you emit that event; your registrations are only to describe all possible attributes that can be present on an event.

At minimum, a registration is uniquely identified (and, implicitly, requires, at minimum, all of these attributes):

• Event Key: The identifier of the event; this matches the same constraints and purpose as the event key in the audit event data model.
• Description: The description of the event - the event it identifies as an audited action.

All registrations are versioned in Sentinel to help tie audited events to the registrations that describe them at the time of emittance.

Optionally, for an individual event, you can submit descriptions (the data elements described further below) for the following attributes:

• Tenant
• User

You can also submit descriptions for any and all possible attributes that may be emitted along with your events.

Attribute Definitions

For tenant, user, and arbitrary attributes associated with your events, you can describe the following about these audit event attributes:

• Description: The textual description of what data in the attribute represents.
• Type: The type of data that can be contained in the attribute (described below).
• Cardinality: The cardinality of the data; this indicates if it should be expected to be a single value or multiple values in the attribute.

Attribute Types

The following types are available to describe data within an attribute:

• Simple: This is a catch-all type; it can be data of any type and is not treated specially.
• OpenID: This attribute will contain OpenID identifiers.
• System Key: This will be a system key distributed from the CernerCentral System Accounts management ecosystem.
• IP Address: This will contain IP addresses.
• E-mail: This contains e-mail addresses.
• Time: This is a date and time, expressed as milliseconds since the Unix epoch.
• URL: This attribute will contain URLs.
• User Input: This attribute contains input captured from a user.
• Numeric: This attribute contains numeric data.

Endpoints

The following endpoints are available:

• /events: The endpoint used to receive audit events emitted by a system.
• /registrations: The endpoint used to receive descriptive metadata about audit events emitted by a system.