Your suggested change has been received. Thank you.

close

Suggest A Change

https://thales.na.market.dpondemand.io/docs/dpod/services/kmo….

Thales Logo

All

  • All
back

IDAAS core

Event store

search

Event store

The OneWelcome Identity Platform generates an event and associated attributes for every activity, such as adding a user. The events are divided into categories and uniquely identified in the event store. Event categories share event attributes, so events can be filtered by event attribute values, such as userId or IP address.

In addition, you can use the OneWelcome Identity Platform event API to retrieve events by category, time span, time stamp, IDs, and many other criteria. You can also include events generated by other applications and pushed via the Event API into the OneWelcome Identity Platform event store.

Event categories

The event store is a component of the OneWelcome Identity Platform identity and access core. It tracks the following two categories of events:

  • Public events (Domain events) record state changes, such as a user signed in (UserSignedInEvent) or created an account (UserCreatedEvent). These events contain metadata such as IdentityProvider ID and destination.

  • Log events provide an audit trail of technical activities. These events contain metadata such as date/time, trigger/agent/user, and IP address.

All events follow the high-level structure shown in this JSON example:

{
  "metadata": {
    ...
  },
  "payload": {
   ...
  }
}

Event attributes

The following table describes OneWelcome Identity Platform event attributes.

Event attribute name Description Example of content/values
device Browser characteristics
event - category Functional group - CREDENTIAL_VERIFICATION
- AUTHENTICATION
- ACCESS
- LIFECYCLE
- CREDENTIAL_MANAGEMENT
- COMMUNICATION
- PROFILE
- CONSENT_MANAGEMENT
- PRIVACY
event - type Short name for the event type
event - typeid Event identifier used for filtering See Event types.
timestamp Date and time of the event
userDataBeforeEvent A JSON representation of the user before the event
userid Identifier generated by OneWelcome Identity Platform when user is created

Event types

The following tables describe OneWelcome Identity Platform event types.

Access events

Event Type Name Event Type ID Event Description
Access granted (SAML, OAuth OIDC) 201 A Service Provider (or Relying application) delegated authentication and/or authorization towards OneWelcome Identity Platform through SAML, OAuth or OpenID Connect and OneWelcome Identity Platform granted the access.
Access denied 202 A Service Provider (or Relying application) delegated authentication and/or authorization towards OneWelcome Identity Platform through SAML, OAuth or OpenID Connect but OneWelcome Identity Platform denied the access.
Access token renewal 203 After access was granted through OAuth, the access token was refreshed. This typically applies to mobile applications.
Access withdrawal (SLO SAML) 204 Single logout has been requested.
Token introspection 205 Validation of an OAuth/OIDC token was executed.

Authentication events

Event type name Event type ID Event description
Login 101 A user logged in successfully with either:
-username and password
-a 2FA authentication flow including OTP-SMS
Login failure 102 A user failed to login.
Log off 103 A user logged off.
Social Login with IDP 105 A user successfully did a federated login (e.g. Facebook login).
Click on Authenticating link 106 A user authenticated himself by clicking on a link that was sent to him via a trusted communication channel. This event is generated when a user is resetting his forgotten password and clicks on the link in the password reset email that was sent to his primary email address.
Click on identifying link 107 A user click on identifying link.
Emailed OTP validation 109 Generated whenever OneWelcome Identity Platform verifies an OTP that was sent to a user's verified email address.
User not found 111 User does not exist.

Authorization group events

Event Type Name Event Type ID Event Description
User added to a group 1001 A user was added to a group.
User removed from a group 1002 A user was removed from a group.
Group created 1050 A group was created.
Group deleted 1051 A group was deleted.

Communication events

Event Type Name Event Type ID Event Description
Activation email sent 501 An email was sent to an INACTIVE user as part of the account registration and/or activation process. The email contains a link to proceed with the account activation.
Verification email sent 502 An email was sent to an ACTIVE account to validate a (new) email address.
Password reset email sent 503 An email was sent containing a password reset link.
Sms verification 506 Sms verification code.
OTP SMS sent 507 Indicates a login code has been sent per SMS text message to the user's verified phone number.
Email account is deleted 509 An email was sent to confirm to the end user that his identity and associated personal information will be deleted.
OTP email verification sent 510 This event indicates a code has been sent per email message to verify a user's email address.
OTP email sent 511 This event indicates a login code has been sent per email text message to the user's verified email address.
Event Type Name Event Type ID Event Description
Consent of Legal document 801 The user gave his consent to a legal document such as Privacy Policy or Terms of Service. This typically happens during a registration process.
Document consent withdrawn 802 The end-user revoked his consent to a document, such as Privacy Policy or Terms of Service.
Attribute consent given 805 The user gave his consent to use some of his personal data to be used for a certain processing purpose. This consent was given in accordance with the GDPR privacy regulation. The consent was given by an affirmative act.
Attribute consent revoked 806 The user withdrew his consent for some of his personal data to be used for a certain processing purpose.

Credential management events

Event Type Name Event Type ID Event Description
Set password 401 A new value for the user’s password was set during registration or via SCIM API.
Username was set 402 A new value for the identity's userName is set.
Password reset requested 403 A password reset process was initiated for a forgotten password.
Password reset 404 A new value for the identity's password was set as the result of a password reset process (forgotten password).
Primary Email is set 405 The user's primary email address value was set.
Password was changed 406 The end user changed their password via Self-Service (Credential API).
Password change failed 407 An attempt to change the user's password failed.
Request to change primary email 408 Request to change primary email.
Change primary email 409 Primary email is changed.
Primary phone number is set 410 The user's primary phone number value was set or changed.
Request to change primary phone number 411 Request to change primary phone number.
Change primary phone number 412 Primary phone number is changed.
User enrol success 413 OneWelcome Identity Platform mobile Identity user enrolled with with success.
User enrol failed 414 OneWelcome Identity Platform mobile identity enrollment failed.
Enrol QR code generation success 415 OneWelcome Identity Platform mobile identity enrollment QR code generation successful.
Enrol QR code generation failed 416 OneWelcome Identity Platform mobile identity enrollment QR code generation failed.
Push confirmation success 419 OneWelcome Identity Platform mobile identity push confirmation successful.
Social Account is linked 420 A social account was linked to an identity within OneWelcome Identity Platform so it can be used for delegated authentication.
Social Account is unlinked 421 A social account was unlinked to an identity.
Link failed 422 Social account linking failed.
Unlink failed 423 Social account unlinking failed.
Identity link activated success 424 Identity link activated with success.
Identity link activated failed 425 Identity link activated failed.
Push confirmation timeout 426 OneWelcome Identity Platform mobile identity push confirmation timeout.
Get devices success 427 OneWelcome Identity Platform mobile identity get devices successful.
Get devices failed 428 OneWelcome Identity Platform mobile identity get devices failed.
Delete device success 429 OneWelcome Identity Platform mobile identity delete device successful.
Delete device failed 430 OneWelcome Identity Platform mobile identity delete device failed.
Push device notification success 437 OneWelcome Identity Platform mobile identity push device notification successful.
Push device notification failed 438 OneWelcome Identity Platform mobile identity push device notification failed.
Admin enrol QR code generation success 441 OneWelcome Identity Platform mobile identity enrollment QR code generation by admin successful.
Admin enrol QR code generation failed 442 OneWelcome Identity Platform mobile identity enrollment QR code generation by admin failed.
Admin push device notification success 445 OneWelcome Identity Platform mobile identity push device notification by admin successful.
Admin push device notification failed 446 OneWelcome Identity Platform mobile identity push device notification by admin failed.
Admin get devices success 447 OneWelcome Identity Platform mobile identity get devices by admin successful.
Admin get devices failed 448 OneWelcome Identity Platform mobile identity get devices by admin failed.
Admin delete device success 451 Identity Platform mobile identity delete device by admin successful.
Admin delete device failed 452 OneWelcome Identity Platform mobile identity delete device by admin failed.
QR code enrollment timeout 455 OneWelcome Identity Platform mobile identity get devices by admin failed.
QR code login timeout 456 OneWelcome Identity Platform mobile identity QR code login timeout.
Request change primary email failed 457 Request to change primary email failed.
Push notification declined 458 OneWelcome Identity Platform mobile identity push notification declined.
Invitation send 460 Invitation has been sent successfully.
Invitation accepted 461 Invitation has been accepted.
Invitation rejected 462 The invitation has been rejected.
Invitation expired 463 The invitation has expired.
Link invitation data to account 464 The invitation data has successfully linked to user account.
Failed to link invitation data to user account 465 The invitation data wasn't linked to user account.

Credential verification events

Event type name Event type ID Event description
Password validation 151 A password that is entered is validated against the hashed password that is stored for user's identity.
SMS OTP validation 152 A One Time Password (OTP) that is entered by the end user is validated against the OTP that was sent to him via SMS/ text message.
Delegated authentication 153 User authentication was delegated to an external IDP (identity provider) and a positive response was received from that IDP.
TOTP validation 154 Time based one time password validation.
Validation authentication link 155 The user clicked on a link that contains a token and the validity of that token was verified.
SMS OTP validation failed 157 One Time Password (OTP) that is entered by the end user fails being validated against the OTP that was sent to him via SMS/ text message.
Password validation failed 161 A password that is entered fails being validated against the hashed password that is stored for user's identity.
Login QR code success 162 OneWelcome Identity Platform mobile identity login with QR code successful.
Login QR code failed 163 OneWelcome Identity Platform mobile identity login with QR code failed. User does not exist in system.
Login with push notification failed 164 OneWelcome Identity Platform mobile identity login with push notification failed. User does not exist in system.
Create session failed 165 OneWelcome Identity Platform mobile identity create session failed.
Create session success 166 OneWelcome Identity Platform mobile identity create session success.
QR code validation failed 167 OneWelcome Identity Platform mobile identity QR code validation for login with second factor failed.
Push notification validation failed 168 OneWelcome Identity Platform mobile identity push notification validation for login with second factor failed.
Emailed OTP validation failed 169 Generated whenever OneWelcome Identity Platform verifies an OTP that was sent to a user's verified email address and the OTP was not correct.

Identity lifecycle events

Event Type Name Event Type ID Event Description
Create account 301 A new identity is created within OneWelcome Identity Platform.
Hard delete account 302 Hard delete account.
Activation 311 The state of an identity is changed from INACTIVE to ACTIVE.
Soft delete 303 The state of an identity is changed to GRACE. This occurs when a ServiceDesk user deletes an identity.
Account restored 304 A soft deleted account is restored from GRACE to its previous state.
Status change: blocked 305 The account status changed into BLOCKED.
Account unblocked 306 The state of the user changed from BLOCKED to ACTIVE after last block was removed. The block information that is included in the event is the (last) block that was removed.
Block added 307 An additional block was added to an account that was already BLOCKED. CHECK, This may actually be generated for any block that is added; 1st one or 2nd one.
Block requested/removed 308 One of the block reasons that caused the identity to be BLOCKED was removed. After this event the state of the identity may be ACTIVE or may still be BLOCKED because a different block reason still exists.
Account temporarily blocked 313 Account is temporarily blocked after a failed login attempt.
State changed 314 The account state has changed.

Privacy events

Event Type Name Event Type ID Event Description
User data viewed 901 The user's profile data was (possibly) viewed through OneWelcome's ServiceDesk application.

Profile management events

Event Type Name Event Type ID Event Description
Attribute added 601 Attribute value added.
Attribute verified 602 OneWelcome Identity Platform features tracking Attribute Value Metadata including accuracy metadata. When an attribute value is verified and the accuracy information is updated this event is generated.
Update account 603 User profile updated.
Attribute value was retrieved 605 The attribute value was retrieved.
User looked-up 650 The user was looked-up in an external identity store.

Event examples

This section shows the sequence of events for typical configurations of the following use cases:

Social registration

When a registration process doesn't include any optional data, the sequence of events is typically as follows:

  • LIFECYCLE: Create Identity
  • CREDENTIAL MANAGEMENT: social account linked
  • CREDENTIAL MANAGEMENT: primary email is set
  • CONSENT: Post document consent (ToS)
  • CONSENT: Post document consent (PP)

Email-based registration

When a user registers by using their email address, the sequence of events is typically as follows:

  • LIFECYCLE: Create Identity
  • COMMUNICATION: Email sent
  • PROFILE: attribute verified
  • CREDENTIAL MANAGEMENT: primary email is set
  • CREDENTIAL MANAGEMENT: Set password
  • LIFECYCLE: identity activated
  • CONSENT: Post document consent (ToS)
  • CONSENT: Post document consent (PP)

Password reset

When a user requests a password reset, the sequence of events is typically as follows:

  • CREDENTIAL MANAGEMENT: password reset requested
  • COMMUNICATION: password reset email sent
  • AUTHENTICATION: user clicks on link
  • CREDENTIAL MANAGEMENT: password reset

Detailed event examples

Events are always associated with users, the userID (UUID), and the identifying attributes unique to the event, as outlined in the Business Object Model scheme.

Login with username and password (AUTHENTICATION 101)

{
    "device" : {
        "browserDetailVersion" : "69.0.3497",
        "name" : "Other",
        "os" : "Mac OS X",
        "userAgent" : "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/69.0.3497.100 Safari/537.36",
        "browser" : "Chrome",
        "browserVersion" : "69.0"
    },
    "identifyingField" : "USERID",
    "identifyingValue" : "sdadmin",
    "timestamp" : "2018-09-25T18:57:09.352Z",
    "event" : {
        "category" : "AUTHENTICATION",
        "eventType" : "LoginSuccessEvent",
        "type" : "Login",
        "typeId" : "101"
    },
    "userId" : "43d4a519fd964cad82645083c83f9a98",
    "segment" : "sd",
    "location" : {
            "ip" : "172.18.0.1"
     },
    "authenticationFlow" : "USERNAME_AND_PASSWORD"
}

Logoff (AUTHENTICATION 103)

{
    "device" : {
        "browserDetailVersion" : "69.0.3497",
        "name" : "Other",
        "os" : "Mac OS X",
        "userAgent" : "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/69.0.3497.100 Safari/537.36",
        "browser" : "Chrome",
        "browserVersion" : "69.0"
    },
    "timestamp" : "2018-09-26T05:47:40.844Z",
    "event" : {
        "category" : "AUTHENTICATION",
        "eventType" : "LogOffEvent",
        "type" : "Logoff",
        "typeId" : "103"
    },
    "userId" : "98127d312d484a86a18e37b0ca404bb4",
    "segment" : "ongo",
    "location" : {
        "ip" : "172.18.0.1",
    }
}

User data viewed (PRIVACY 901)

{
  "userId": "3b3bf20a2e464c44824b43ab56a47f5c",
  "timestamp": "2018-02-08T15:48:29.516Z",
  "segment": "ongo/bikes",
  "event": {
    "category": "PRIVACY",
    "typeId": "901",
    "type": "User data viewed",
    "eventType": "UserDateViewedEvent"
  },
  "clientName": "sd",
  "employeeResourceId": "5a377494075648679e37a02a86992e84",
  "employeeFormattedName": "test.onewelcome",
  "userDataBeforeEvent": {
    "emails": [
      {
        "type": "other",
        "value": "wcarnava1@yopmail.com",
        "primary": true
      }
    ],
    "urn:scim:schemas:extension:iwelcome:1+0": {
      "segment": "ongo/bikes",
      "state": "ACTIVE",
      "birthDate": "26/01/1981"
    },
    "meta": {
      "created": "2017-11-13T09:56:30.402Z",
      "lastModified": "2017-11-16T11:47:07.725Z",
      "version": "W/1041344808",
      "location": "https://test.onewelcome.nl/api/scim1.1/v1/Users/3b3bf20a2e464c44824b43ab56a47f5c"
    },
    "schemas": [
      "urn:scim:schemas:core:1.0",
      "urn:scim:schemas:extension:iwelcome:1.0",
      "urn:scim:schemas:extension:iwelcomeattributemetadata:1.0"
    ]
    },
    "name": {
      "familyName": "Carnaval",
      "givenName": "W",
      "formatted": "W Carnaval"
    },
    "active": true,
    "id": "3b3bf20a2e464c44824b43ab56a47f5c",
    "userName": "wcarnava1"
  }

Email address verification (COMMUNICATION-501)

{
  "userId": "b989bbf85eb14785a86e81fc73eb5104",
  "timestamp": "2018-02-09T08:54:59.465Z",
  "segment": "bikes",
  "event": {
    "category": "COMMUNICATION",
    "typeId": "501",
    "type": "Email address verification.",
    "eventType": "ActivationEmailSentEvent"
  }
}

Account created (LIFECYCLE-301)

In this user creation example, the event metadata includes device fingerprinting, geolocation, and IP address.

{
  "userId": "b989bbf85eb14785a86e81fc73eb5104",
  "timestamp": "2018-02-09T08:54:59.275Z",
  "segment": "ongo/bikes",
  "event": {
    "category": "LIFECYCLE",
    "typeId": "301",
    "type": "create account",
    "eventType": "CreateAccountEvent"
  },
  "device": {
    "name": "Spider",
    "os": "Other",
    "browser": "Java",
    "browserVersion": "8.0",
    "browserDetailVersion": "8.0.151",
    "userAgent": "Java/1.8.0_151"
  },
  "location": {
    "ip": "192.168.1.21"
  },
  "clientName": "ums",
  "dateTime": "2018-02-09T08:54:59.275Z",
  "host": "https://test.onewelcome.nl/workflowapi/",
  "userDataAfterEvent": {
    "urn:scim:schemas:core:1+0:emails": [
      {
        "type": "other",
        "value": "test.user9001@yopmail.com",
        "primary": true
      }
    ],
    "urn:scim:schemas:extension:iwelcome:1+0:state": "INACTIVE",
    "urn:scim:schemas:core:1+0:schemas": [
      "urn:scim:schemas:core:1.0",
      "urn:scim:schemas:extension:iwelcome:1.0",
      "urn:scim:schemas:extension:iwelcomeattributemetadata:1.0",
      "urn:scim:schemas:extension:iwelcomeattributevaluemetadata:1.0"
    ],
    "urn:scim:schemas:core:1+0:id": "b989bbf85eb14785a86e81fc73eb5104",
    "urn:scim:schemas:core:1+0:userName": "TEST009001",
    "urn:scim:schemas:extension:iwelcome:1+0:segment": "ongo/bikes",
    "urn:scim:schemas:core:1+0:name": {
      "familyName": "Testnovember",
      "givenName": "ABC",
      "middleName": null,
      "formatted": "ABC Testnovember"
    },
    "urn:scim:schemas:extension:iwelcome:1+0:birthDate": "02/02/1980"
  }
}

Block event (unblock via ServiceDesk)

{
          "dateTime" : "2018-09-27T15:38:30.197Z",
          "block" : {
            "date" : "2018-09-27T15:38:18.281Z",
            "reason" : "System generated reason",
            "userid" : "b15027b304514cc5ba89f15af745afa4"
          },
          "uuid" : "ccd788af41be41ee9bc6e201b9c2c07b",
          "@version" : "1",
    "timestamp" : "2018-09-27T15:38:30.204Z",
    "eventType" : "UnblockUserAuditEvent",
    "source" : "UnblockEvent"
}

Activation email sent (COMMUNICATION-501)

{
  "userId": "b989bbf85eb14785a86e81fc73eb5104",
  "timestamp": "2018-02-09T08:54:59.465Z",
  "segment": "ongo/bikes",
  "event": {
    "category": "COMMUNICATION",
    "typeId": "501",
    "type": "Email address verification.",
    "eventType": "ActivationEmailSentEvent"
  },
  "device": {
    "name": "Other",
    "os": "Other",
    "browser": "Other",
    "userAgent": "okhttp/3.8.1"
  },
  "location": {
    "ip": "192.168.1.22"
  }
}

Approval of Terms of Service

In this example, category=consent and typeId=801.

{
   "userId": "b989bbf85eb14785a86e81fc73eb5104",
   "timestamp": "2018-02-09T08:59:40.364Z",
   "segment": "ongo/bikes",
   "event": {
     "category": "CONSENT",
     "typeId": "801",
     "type": "Approval terms of service",
     "eventType": "ApprovalTermsOfServiceEvent"
   },
   "device": {
     "name": "Other",
     "os": "Mac OS X",
     "browser": "Firefox",
     "browserVersion": "58.0",
     "browserDetailVersion": "58.0",
     "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.13; rv:58.0) Gecko/20100101 Firefox/58.0"
   },
   "document": {
     "name": "Ongo Terms of Service",
     "version": "3.1",
     "versionDate": "2017-06-01"
   },
   "location": {
     "ip": "77.165.59.121"
   }
}

User added to a group (AUTHORISATION 1001)

{
  "event_type_id": "1001",
  "event_type_details": {
    "category": "AUTHORISATION",
    "name": "User added to a group"
  },
  "user": {
    "id": "98127d312d484a86a18e37b0ca404bb4",
    "external_id": "ongo-customer-id-0123456789",
    "segment": "ongo-bikes"
  },
  "authenticated_user": {
    "id": "5a377494075648679e37a02a86992e84",
    "segment": "employees"
  },
  "client_application": {
    "client_id": "s6BhdRkqt3",
    "client_name": "DUMS"
  },
  "group": {
    "id": "f480b020-61f5-478b-aa75-ec0c8b0dbba3",
    "display_name": "Office365 users"
  }
}

Public events

Public events have a strictly defined payload taxonomy and version. See Public event payload for the list of public events and their payload structure. When breaking changes are made, the payload version of an event will be changed accordingly.

The metadata of a public event has the following fields:

Metadata field Value format Example value Presence Description
agent String d725e807-de02-4f70-a271-040e15b62eee Optional The identifier of the user / machine that this event can be linked to
aggregateId String 0b7897ac-3c8f-4067-b23b-d262fc2bffb0 Required The identifier of the aggregate that triggered this event. The concept of aggregates is used to parallelise processing of events.
category String public Required The event category, either log or public. Always "public" for public events
eventId UUID 3b307680-2f7f-4186-8495-17d4cb82955b Required A Unique identifier for an event
hostIp String
IPv4 or IPv6		 127.0.0.1 Optional The IP address of the client from which this event originated. This would normally be the IP address of the end-user / machine that generated an event
metadataVersion String
<major>.<minor>		 1.0 Required The metadata version of this event
occurredTime ISO 8601 2022-07-13T18:59:43.596191+02:00 Required OffsetDateTime. This is an immutable representation of a date-time with an offset from UTC/Greenwich in the ISO-8601 calendar system
payloadVersion String
<major>.<minor>		 1.0 Required The payload version of this event
producerId String test-app Required The service that produced this event
producerInstanceId String test-app Required The service that produced this event
producerVersion String d921970 Optional The app version of the producer that created this event
tenantId UUID 50a7dbf5-ce45-4f57-ab9a-554c23510a01 Required The identifier of the tenant that generated this event
tags Array of predefined values [ "EXPORTABLE" ] Optional An array of strings that represent the tags for the current event. Allowed values for public events:
EXPORTABLE - the event is meant to be exportable outside of the OneWelcome Identity Platform
traceId String 84e85059-0416-4e4b-85f9-eba03100c7de Optional A correlation identifier that can be used to trace events originating from the same transaction / request
type String UserSigedInEvent Required The event type, will always end with "event"

Example public event:

{
  "metadata": {
    "type": "UserSignedInEvent",
    "category": "public",
    "eventId": "3b307680-2f7f-4186-8495-17d4cb82955b",
    "aggregateId": "d725e807-de02-4f70-a271-040e15b62eee",
    "payloadVersion": "1.0",
    "metadataVersion": "1.0",
    "producerId": "testInstance",
    "producerInstanceId": "testInstance-1",
    "occurredTime": "2022-07-13T18:59:43.596191+02:00",
    "tenantId": "50a7dbf5-ce45-4f57-ab9a-554c23510a01",
    "tags": [
      "EXPORTABLE"
    ],
    "producerVersion": "d921970",
    "hostIp": "127.0.0.1",
    "traceId": "84e85059-0416-4e4b-85f9-eba03100c7de",
    "agent": "d725e807-de02-4f70-a271-040e15b62eee"
  },
  "payload": {
    "userId": "d725e807-de02-4f70-a271-040e15b62eee",
    "identityProviderId": "test-identity-provider",
    "date": "2022-07-13T18:59:43.596191+02:00",
    "destination": "test-service-provider"
  }
}

Log events

A log event largely follows the same format as a public event. It has metadata that depicts the event type, category and other fields. The most important difference compared to a public event is that the payload in a log event is optional. In addition, the payload is not versioned and does not follow a strictly defined contract. It is mostly used to provide debug information.

The metadata of a log event contains the following fields:

Metadata field Value format Example value Presence Description
agent String d725e807-de02-4f70-a271-040e15b62eee Optional The identifier of the user / machine that this event can be linked to
description String A user signed in Required Description that gives additional information about an event.
category String log Required The event category, either log or public. Always "log" for log events
eventId UUID 3b307680-2f7f-4186-8495-17d4cb82955b Required A Unique identifier for an event
hostIp String
IPv4 or IPv6		 127.0.0.1 Optional The IP address of the client from which this event originated. Typically, the IP address of the end-user / machine that generated the event
metadataVersion String
.		 1.0 Required The metadata version of this event
occurredTime ISO 8601 2022-07-13T18:59:43.596191+02:00 Required OffsetDateTime. This is an immutable representation of a date-time with an offset from UTC/Greenwich in the ISO-8601 calendar system
producerId String test-app Required The service that produced this event
producerInstanceId String test-app Required The service that produced this event
producerVersion String d921970 Optional The app version of the producer that created this event
tenantId UUID 50a7dbf5-ce45-4f57-ab9a-554c23510a01 Required The identifier of the tenant that generated this event
tags Array of predefined values [ "ERROR", "EXPORTABLE" ] Optional An array of strings that represent the tags for the current event. Allowed values for log events:
EXPORTABLE - the event is meant to be exportable outside of the OneWelcome Identity Platform
ERROR - an event that is part of a non-happy flow
USER_FACING_FUNCTION - an event that is part of business function observable by the user (this excludes strictly technical events)
traceId String 84e85059-0416-4e4b-85f9-eba03100c7de Optional A correlation identifier that can be used to trace events originating from the same transaction / request
type String UserSigedInEvent Required The event type, will always end with "event"

Example log event

{
  "metadata": {
    "type": "UserSignedInEvent",
    "description": "A user signed in"
    "category": "log",
    "eventId": "3b307680-2f7f-4186-8495-17d4cb82955b",
    "metadataVersion": "1.0",
    "producerId": "oneex-test-app-1",
    "producerInstanceId": "e0d42d60-a0b1-406e-8b55-b49bde0fe532",
    "occurredTime": "2022-05-02T12:34:50.747866+02:00",
    "tenantId": "50a7dbf5-ce45-4f57-ab9a-554c23510a01",
    "tags": [],
    "producerVersion": "abcdef",
    "agent": "An Agent",
    "userAgent": "userAgent",
    "hostIp": "127.0.0.1",
    "traceId": "84e85059-0416-4e4b-85f9-eba03100c7de"
  },
  "payload": {}
}

Event publishing options

Every tenant can be individually configured to publish log and public events to either Amazon Kinesis Data Streams or an S3 bucket.

Examples

Clients Public events Log events Notes
Single tenant Amazon Kinesis Data Streams S3 bucket
Single tenant Amazon Kinesis Data Streams Amazon Kinesis Data Streams Configure separate data streams for each event category.
Single tenant S3 bucket S3 bucket Configure separate folders for public and log events.
Multiple tenants Amazon Kinesis Data Streams Amazon Kinesis Data Streams The tenant ID distinguishes the events for each tenant.

Amazon Kinesis Data Streams

OneWelcome Identity Platform events are wrapped in a JSON object containing an array of events and stored in the data field of an Amazon Kinesis Data Streams record. The structure of the record is described in AWS documentation.

Example of an Amazon Kinesis Data Streams record

{
  "events": [
    {
      "metadata": {
        "type": "BEvent",
        "eventId": "73724fb9-ad9b-493e-be98-4aed7a2a6c69",
        "aggregateId": "0b7897ac-3c8f-4067-b23b-d262fc2bffb0",
        "payloadVersion": "1.0",
        "metadataVersion": "1.0",
        "producerId": "oneex-test-app-1",
        "producerInstanceId": "e0d42d60-a0b1-406e-8b55-b49bde0fe532",
        "occurredTime": "2022-05-02T12:34:50.747346+02:00",
        "tenantId": "50a7dbf5-ce45-4f57-ab9a-554c23510a01",
        "tags": [],
        "producerVersion": "local",
        "agent": "An Agent",
        "userAgent": "userAgent",
        "hostIp": "127.0.0.1",
        "traceId": "de943d73-2f71-4f95-bb31-6762ea236aa9"
      },
      "payload": {
        "testProducerInstanceId": "2022-05-02T12:34:42.802332+02:00_e0d4",
        "testProducerEventCounter": 2,
        "testProducerOperationCounter": 2
      }
    },
    {
      "metadata": {
        "type": "BEvent",
        "eventId": "3b307680-2f7f-4186-8495-17d4cb82955b",
        "aggregateId": "0b7897ac-3c8f-4067-b23b-d262fc2bffb0",
        "payloadVersion": "1.0",
        "metadataVersion": "1.0",
        "producerId": "oneex-test-app-1",
        "producerInstanceId": "e0d42d60-a0b1-406e-8b55-b49bde0fe532",
        "occurredTime": "2022-05-02T12:34:50.747866+02:00",
        "tenantId": "50a7dbf5-ce45-4f57-ab9a-554c23510a01",
        "tags": [],
        "producerVersion": "local",
        "agent": "An Agent",
        "userAgent": "userAgent",
        "hostIp": "127.0.0.1",
        "traceId": "84e85059-0416-4e4b-85f9-eba03100c7de"
      },
      "payload": {
        "testProducerInstanceId": "2022-05-02T12:34:42.802332+02:00_e0d4",
        "testProducerEventCounter": 3,
        "testProducerOperationCounter": 2
      }
    }
  ]
}

Thales recommends that you follow the AWS documentation about how to use data from Amazon Kinesis Data Streams.

Configuring Amazon Kinesis Data Streams

To enable OneWelcome Identity Platform to push events to Amazon Kinesis Data Streams:

  1. Create a data stream. KMS encryption is optional, but recommended, see step 5 for instructions. We recommend On demand scaling, so capacity doesn’t have to be managed.

  2. Create an IAM policy (IAM / Policies / Create policy / JSON).
    Use the contents specified in the following code block. Replace the placeholders $aws-region, $aws-account-no, and $your-stream-name to resources created and known by you.

    {
  "Version": "2012-10-17",
  "Statement": [
      {
          "Sid": "Put records role",
          "Effect": "Allow",
          "Action": [
            "kinesis:PutRecord",
            "kinesis:PutRecords"
          ],
          # CHANGE $aws-region, $aws-region and $aws-account-no into meaningful values!
          "Resource": "arn:aws:kinesis:$aws-region:$aws-account-no:stream/$your-stream-name"
      }
  ]
}

  3. Create an IAM Role with trust policy (IAM / Roles / Create role / Custom trust policy).
    The contents are specified in the code block below. 185813010098 is the OneWelcome Identity Platform AWS account. The Condition block in this trust policy is optional but recommended. If you provide a token (a random string), it will be presented every time OneWelcome Identity Platform assumes this role to prevent unauthorized access attempts (confused deputy problem).

    {
  "Version": "2012-10-17",
  "Statement": {
      "Effect": "Allow",
      "Principal": {
          "AWS": "arn:aws:iam::185813010098:root"
      },
      "Action": "sts:AssumeRole",
      # OPTIONAL
      "Condition": {
          "StringEquals": {
              "sts:ExternalId": "some-arbitrary-token"
          }
      }
  }
}

  4. Attach the policy from point 2 to role from point 3.

  5. [Optional] Using a KMS key for record encryption. The encryption in transit is enabled by default by AWS. Encryption at rest of particular records can be configured using KMS key. There are two options – AWS managed CMK or Customer-managed CMK.

  6. To use a customer-managed CMK for encrypting records in Amazon Kinesis Data Streams, you must allow the “put records” role to use the key in KMS key policy. Go to the KMS console and add the following to the KMS key policy:

    {
            "Sid": "Allow use of the key",
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::$aws-account-no:role/$customers-kinesis-put-record-role"
            },
            "Action": [
                "kms:Encrypt",
                "kms:Decrypt",
                "kms:ReEncrypt*",
                "kms:GenerateDataKey*",
                "kms:DescribeKey"
            ],
            "Resource": "*"
        },
        {
            "Sid": "Allow attachment of persistent resources",
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::$aws-account-no:role/$customers-kinesis-put-record-role"
            },
            "Action": [
                "kms:CreateGrant",
                "kms:ListGrants",
                "kms:RevokeGrant"
            ],
            "Resource": "*",
            "Condition": {
                "Bool": {
                    "kms:GrantIsForAWSResource": "true"
                }
            }
        }

  7. Replace the $aws-account-no and $kinesis-put-record-role placeholders with the correct values. Alternatively, to use an AWS managed CMK, just enable that option. No additional setup is needed.

  8. Share the stream name and IAM role ARN that you created above with OneWelcome Identity Platform.

S3 bucket

The data in the S3 bucket is written by the S3 target of Amazon Kinesis Data Firehose in the Amazon S3 Object name format. Records are pushed into the S3 bucket with a UTC time prefix and the event category, as follows:

YYYY/MM/dd/HH/<Event Category(public or log)>

Amazon Kinesis Data Firehose writes files using the JSON lines format. Every file contains multiple JSON value objects separated by a line break.

Example of a file in an S3 bucket

{"events":[{"metadata":{"category":"public","type":"CEvent","eventId":"b85dca63-064e-4687-8a20-424662e30686","aggregateId":"5241cf5a-e75c-4e76-ad90-5ee345cb07a8","payloadVersion":"1.0","metadataVersion":"1.0","producerId":"oneex-test-app-1","producerInstanceId":"1e40c34f-a439-494a-9782-bd78e615af9b","occurredTime":"2022-07-14T10:38:45.962266+02:00","tenantId":"50a7dbf5-ce45-4f57-ab9a-554c23510a11","tags":["EXPORTABLE"],"producerVersion":"local","agent":"An Agent","userAgent":"userAgent","hostIp":"127.0.0.1","traceId":"42bbfa71-e120-4019-bb3b-1bac895d6085"},"payload":{"testProducerInstanceId":"2022-07-14T10:38:38.913027+02:00_1e40","testProducerEventCounter":1,"testProducerOperationCounter":1}},{"metadata":{"category":"public","type":"CEvent","eventId":"adfdc313-65d6-4c34-9ac2-4ed15d631d01","aggregateId":"ef043115-e0c1-4192-8799-838e67d30bd2","payloadVersion":"1.0","metadataVersion":"1.0","producerId":"oneex-test-app-1","producerInstanceId":"1e40c34f-a439-494a-9782-bd78e615af9b","occurredTime":"2022-07-14T10:38:45.941957+02:00","tenantId":"50a7dbf5-ce45-4f57-ab9a-554c23510a11","tags":["EXPORTABLE"],"producerVersion":"local","agent":"An Agent","userAgent":"userAgent","hostIp":"127.0.0.1","traceId":"aac71e65-8ba5-48f5-bf6c-218166c441c8"},"payload":{"testProducerInstanceId":"2022-07-14T10:38:38.913027+02:00_1e40","testProducerEventCounter":3,"testProducerOperationCounter":1}}],"exportSequence":"1657787927925000001"}
{"events":[{"metadata":{"category":"public","type":"CEvent","eventId":"9088e089-d7a4-4dfa-9e94-7d8c05856fdd","aggregateId":"4527fa7c-08af-4784-a937-2371705cf921","payloadVersion":"1.0","metadataVersion":"1.0","producerId":"oneex-test-app-1","producerInstanceId":"1e40c34f-a439-494a-9782-bd78e615af9b","occurredTime":"2022-07-14T10:38:46.494584+02:00","tenantId":"50a7dbf5-ce45-4f57-ab9a-554c23510a11","tags":["EXPORTABLE"],"producerVersion":"local","agent":"An Agent","userAgent":"userAgent","hostIp":"127.0.0.1","traceId":"c4655afa-abb4-479a-b8cd-07e0a331b21d"},"payload":{"testProducerInstanceId":"2022-07-14T10:38:38.913027+02:00_1e40","testProducerEventCounter":12,"testProducerOperationCounter":3}},{"metadata":{"category":"public","type":"CEvent","eventId":"579d6996-dbc5-4422-86b4-0b2f9b0c456c","aggregateId":"e15ebe05-b633-4b14-a4bc-dbc1499aa5ee","payloadVersion":"1.0","metadataVersion":"1.0","producerId":"oneex-test-app-1","producerInstanceId":"1e40c34f-a439-494a-9782-bd78e615af9b","occurredTime":"2022-07-14T10:38:46.651749+02:00","tenantId":"50a7dbf5-ce45-4f57-ab9a-554c23510a11","tags":["EXPORTABLE"],"producerVersion":"local","agent":"An Agent","userAgent":"userAgent","hostIp":"127.0.0.1","traceId":"93eb21aa-8778-495d-8bf8-c9c291b3465f"},"payload":{"testProducerInstanceId":"2022-07-14T10:38:38.913027+02:00_1e40","testProducerEventCounter":14,"testProducerOperationCounter":4}}],"exportSequence":"1657787928184000001"}

Each line contains a JSON value object with an events attribute that contains an array of events.

Example JSON value object from the file in the S3 bucket

{
  "events": [
    {
      "metadata": {
        "category": "public",
        "type": "CEvent",
        "eventId": "b85dca63-064e-4687-8a20-424662e30686",
        "aggregateId": "5241cf5a-e75c-4e76-ad90-5ee345cb07a8",
        "payloadVersion": "1.0",
        "metadataVersion": "1.0",
        "producerId": "oneex-test-app-1",
        "producerInstanceId": "1e40c34f-a439-494a-9782-bd78e615af9b",
        "occurredTime": "2022-07-14T10:38:45.962266+02:00",
        "tenantId": "50a7dbf5-ce45-4f57-ab9a-554c23510a11",
        "tags": [
          "EXPORTABLE"
        ],
        "producerVersion": "local",
        "agent": "An Agent",
        "userAgent": "userAgent",
        "hostIp": "127.0.0.1",
        "traceId": "42bbfa71-e120-4019-bb3b-1bac895d6085"
      },
      "payload": {
        "testProducerInstanceId": "2022-07-14T10:38:38.913027+02:00_1e40",
        "testProducerEventCounter": 1,
        "testProducerOperationCounter": 1
      }
    },
    {
      "metadata": {
        "category": "public",
        "type": "CEvent",
        "eventId": "adfdc313-65d6-4c34-9ac2-4ed15d631d01",
        "aggregateId": "ef043115-e0c1-4192-8799-838e67d30bd2",
        "payloadVersion": "1.0",
        "metadataVersion": "1.0",
        "producerId": "oneex-test-app-1",
        "producerInstanceId": "1e40c34f-a439-494a-9782-bd78e615af9b",
        "occurredTime": "2022-07-14T10:38:45.941957+02:00",
        "tenantId": "50a7dbf5-ce45-4f57-ab9a-554c23510a11",
        "tags": [
          "EXPORTABLE"
        ],
        "producerVersion": "local",
        "agent": "An Agent",
        "userAgent": "userAgent",
        "hostIp": "127.0.0.1",
        "traceId": "aac71e65-8ba5-48f5-bf6c-218166c441c8"
      },
      "payload": {
        "testProducerInstanceId": "2022-07-14T10:38:38.913027+02:00_1e40",
        "testProducerEventCounter": 3,
        "testProducerOperationCounter": 1
      }
    }
  ],
  "exportSequence": "1657787927925000001"
}

Configuring the S3 bucket

To set up an S3 bucket in your AWS account so that OneWelcome Identity Platform can push events to it:

  1. Create a KMS key:
    • Key type: “Symmetric”
    • Key usage: “Encrypt and decrypt”
    • Key material origin: “KMS”, Regionality: doesn’t matter)

  2. Add a KMS key policy statement allowing access to the key from the Onewelcome AWS account:

    {
    "Version": "2012-10-17",
    "Id": "key-consolepolicy",
    "Statement": [
        {
            "Sid": "Allow an external account to use this KMS key",
            "Effect": "Allow",
            "Principal": {
            # CHANGE THIS
                "AWS": "arn:aws:iam::185813010098:role/events-mycustomer-production"
            },
            "Action": [
                "kms:Encrypt",
                "kms:Decrypt",
                "kms:ReEncrypt*",
                "kms:GenerateDataKey*",
                "kms:DescribeKey"
            ],
            "Resource": "*"
        }
    ]
}

  3. The Statement.Principal.AWS[1] role is the Amazon Kinesis Data Firehose role, ARN, that is created by OneWelcome Identity Platform. Replace the current value in the snippet above with the value supplied by OneWelcome Identity Platform.

  4. Create the S3 bucket with the following policy:

    {
  "Version": "2012-10-17",
  "Id": "PolicyID",
  "Statement": [
    {
      "Sid": "StmtID",
      "Effect": "Allow",
      "Principal": {
      # CHANGE THIS
        "AWS": "arn:aws:iam::185813010098:role/events-mycustomer-production"
      },
      "Action": [
        "s3:AbortMultipartUpload",
        "s3:GetBucketLocation",
        "s3:GetObject",
        "s3:ListBucket",
        "s3:ListBucketMultipartUploads",
        "s3:PutObject",
        "s3:PutObjectAcl"
      ],
      "Resource": [
      # CHANGE THIS
        "arn:aws:s3:::customers_bucket",
        "arn:aws:s3:::customers_bucket/*"
      ]
    }
  ]
}

  5. The Statement.Principal.AWS role is the Amazon Kinesis Data Firehose role, ARN, that is created by OneWelcome Identity Platform. Replace the current value with the value provided by OneWelcome Identity Platform.

  6. Verify that the Statement.Resource reflects the bucket name created and known by you.

Both the KMS key and S3 bucket must reside in the same region.

Public event payload

This section describes the OneWelcome Identity Platform public events generated by modules of the OneWelcome Identity Platform. Events are transmitted in JSON format.

Example event in JSON format

{
  "metadata": {
     "type":"AuthorizationGroupDeletedEvent"
     //other metadata fields, check documentation for details
  },
  "payload": {
     "authorizationGroupId":"a4a474cc-7347-4de1-8f21-9dd2939346dc"
  }
}

Public events access module

Event type Description Payload fields
DeviceDeregisteredEvent A device with all registered users has been revoked. clientId:String
DeviceRegisteredEvent A device has been registered clientId:String, appName:String, platform:String, appVersion:String, osVersion:String
DeviceUpdatedEvent A device has been updated clientId:String, appName:String, platform:String, appVersion:String, osVersion:String
UserDeviceDeregisteredEvent The user's registration has been removed from the client userId:UUID, clientId:String
UserDeviceRegisteredEvent User registered on client. userId:UUID, clientId:String

Public events delegated administration module

Event type Description Payload fields
AuthorizationGroupAttributesChangedEvent Attributes are changed for the authorization group authorizationGroupId:UUID, attributesAdded:List, attributesUpdated:List, attributesRemoved:List
AuthorizationGroupCreatedEvent Authorization group is created authorizationGroupId:UUID, name:String, parentId:UUID
AuthorizationGroupDeletedEvent Authorization group is deleted authorizationGroupId:UUID
AuthorizationGroupMemberAddedEvent Member is added to authorization group authorizationGroupId:UUID, userId:UUID
AuthorizationGroupMemberRemovedEvent Member is removed from authorization group authorizationGroupId:UUID, userId:UUID
AuthorizationGroupPoliciesChangedEvent Policies of authorization group have been changed authorizationGroupId:UUID, policiesAdded:List, policiesRemoved:List
AuthorizationGroupResourcesChangedEvent Resources of authorization group have been changed authorizationGroupId:UUID, resourcesAdded:List, resourcesRemoved:List
AuthorizationGroupUpdatedEvent Authorization group is updated authorizationGroupId:UUID, oldName:String, newName:String
AuthorizationMemberPermissionAssignmentsChangedEvent Member permissions have been changed for the authorization group authorizationGroupId:UUID, userId:UUID, permissionsAdded:List, permissionsRemoved:List
AuthorizationMemberPolicyAssignmentsChangedEvent Member policies have changed for the authorization group authorizationGroupId:UUID, userId:UUID, policiesAdded:List, policiesRemoved:List
AuthorizationMemberResourceAssignmentsChangedEvent Members resources have been changed for the authorization group authorizationGroupId:UUID, userId:UUID, resourcePrivilegesAdded:List, resourcePrivilegesRemoved:List
AuthorizationPolicyCreatedEvent Policy is created id:UUID, name:String
AuthorizationPolicyDeletedEvent Policy is deleted id:UUID
AuthorizationPolicyUpdatedEvent Policy is updated id:UUID, oldName:String, newName:String
AuthorizationResourceCreatedEvent Resource is created id:UUID, name:String, externalId:String, resourceTypeId:UUID
AuthorizationResourceDeletedEvent Resource is deleted id:UUID
AuthorizationResourceTypeCreatedEvent Resource type is created id:UUID, name:String, policyId:UUID
AuthorizationResourceTypeDeletedEvent Resource type is deleted id:UUID
AuthorizationResourceTypeUpdatedEvent Resource type is updated id:UUID, oldName:String, newName:String
AuthorizationResourceUpdatedEvent Resource is updated id:UUID, oldName:String, newName:String, oldExternalId:String, newExternalId:String

Model objects

Model object Fields
Attribute key:String, value:String
Permission One of GROUP_MANAGE, GROUP_POLICY_MANAGE, GROUP_RESOURCE_MANAGE, PERMISSION_MANAGE, PERSON_POLICY_MANAGE, PERSON_RESOURCE_MANAGE, GROUP_MEMBER_MANAGE, POLICY_MANAGE, RESOURCE_MANAGE
ResourcePrivilege resourceId:UUID, privilegeId:UUID

Public events credentials module

Event type Description Payload fields
PasswordUpdatedEvent User's password is updated userId:UUID

Public events identity module

Event type Description Payload fields
IdentityProviderLinkedEvent Identity provider is linked to user identityProviderId:String, name:String, authenticationLevel:Integer, userId:UUID
IdentityProviderUnlinkedEvent Identity provider is unlinked from user identityProviderId:String, name:String, authLevel:Integer, userId:UUID
IdentityUpdatedEvent Identity is updated userId:UUID, gender:Gender, emailAddresses:List, phoneNumbers:List, addresses:List
, customAttributes:List, name:Name
InvitationGeneratedEvent Invitation is generated userId:UUID
UserActivatedEvent User is activated userId:UUID
UserBlockedEvent User is blocked userId:UUID
UserCreatedEvent User is created userId:UUID
UserDeactivatedEvent User is deactivated userId:UUID
UserDeletedEvent User is deleted userId:UUID
UserSignedInEvent User signed in userId:UUID, identityProviderId:String, date:OffsetDateTime, destination:String (This is the Service Provider that initiated the authentication request and to which the user will be redirected, unless the flow is interrupted due to custom logic)
UserUnblockedEvent User is unblocked userId:UUID

Model objects

Model object Fields
Address houseNumber:Integer, houseNumberAddition:String, streetName:String, postalCode:String, city:String, region:String, country:String, primary:Boolean, verified:Boolean
CustomAttribute name:String, value:Object, valueType:CustomAttributeType
CustomAttributeType One of SINGLE, LIST, MAP
EmailAddress value:String, primary:Boolean, verified:Boolean
Gender type:GenderType, customValue:String (Required only for type=OTHER)
GenderType One of MALE, FEMALE, OTHER, UNSPECIFIED
Name givenName:String, familyName:String, displayName:String, initials:String
PhoneNumber value:String, primary:Boolean, verified:Boolean

Compatibility guidelines

  • JSON may contain 'null' values. Future versions of OneWelcome Identity Platform may omit event attributes if no value is available. For compatibility reasons, OneWelcome Identity Platform advises to not depend on any processing logic that relies on the presence of attributes having a 'null' value.
  • Future releases of OneWelcome Identity Platform may introduce new events and new event sub-attributes. Any processing of OneWelcome Identity Platform's events should anticipate such changes. OneWelcome Identity Platform considers the introduction of these additional items as being 'backwards compatible'.

On this page