Event Streams enable SGNL to receive events that comply with the Security Event Token (SET) Specification. This includes Shared Signals Framework events like CAEP and RISC.
SGNL’s event streams are a special type of System of Record, and you can find our standards-based templates right next to other SoRs that you may be using in SGNL’s System of Record Catalog. Similar to all other SoRs, Event Stream SoR’s enabling the modeling of different entities that are then stored in the graph, enabling you to create CAEP Hub Actions when you receive an event.
While Event Stream SoRs like our CAEP and RISC templates share similarities with other SoRs in terms of how you model entities/attributes and how data is propagated to the graph, this is where many of the similarities end.
A few important things to know:
id attribute in SGNL, this should be the jti field in the SET, they’re also required to have a subject attribute in SGNL that should correspond to one of the Subject identifiers in the JWTCreating an Event Stream is fairly straightforward, with the steps below you can get started with your first set of events, and quickly expand to other event sources.
Login to SGNL with an account that has at least SoR Administrator Permissions
From the Dashboard, Add a new System of Record
Using the SGNL Catalog, select the CAEP Events SoR
Give the Event Stream a name – if you don’t have an existing SSF Transmitter, you can use SGNL’s CAEP Hub or caep.dev for this purpose and name this stream accordingly, save it after you’re done
Head over to Settings, as you’ll need to enable either Authentication or Signing on this Event Stream source before you can use it – SGNL’s well-known endpoint for CAEP Hub is available by default at https://config.sgnlapis.cloud/metadata/v1/.well-known/ssf-configuration for the SGNL SaaS
Note: If you’re not yet sure how you’re going to use this event stream, it might be easier at this juncture to enable Authentication and not Signing, and simply use Postman or cURL to send your first few messages, if doing this, just generate a new token and store it somewhere safely for now
Take note of your Push Event API, that’s where you and/or your partners will send SETs to
Head over to the Events section of the Event Stream and verify all the events you will want to receive are there – at this point it’s most likely interesting to look at the configuration of one of the events and verify that the JSONPath Syntax that is in use to parse attributes out of the SET reflects the schema of your Security Event Tokens – if you aren’t sure, just leave them as-is for now
You now want to create a relationship or two between events objects in your graph – you’ll commonly want to create your first relationship from the subject of the token to some authoritative source for that value, i.e. if you are sending an email as the sub_id, you might want to create a relationship between the Event’s subject attribute and the mail attribute in your IdP or Email Provider SoR
Once everything looks good, return to the Events page and enable one of the Events, Session Revoked is a good start, also enable the Event Stream from the top right
You’re ready to start receiving events – you can now proceed to configure your SSF/SET Transmitter to send (POST) events, or use CAEP Hub or caep.dev to test – if you’re looking for some quick testing steps, follow along below
So you have a new Event Stream configured and looking to test it out? CAEP Hub and caep.dev are the best possible test beds for this purpose, but we’ll go through the fastest possible way below.
This guide assumes that you’ve completed creating your first Event Stream. What you’ll need is:
{
"aud": "https://sgnl.ai",
"events": {
"https://schemas.openid.net/secevent/caep/event-type/session-revoked": {
"event_timestamp": 1729743269,
"subject": {
"email": "alice@wholesalechips.co",
"format": "email"
}
}
},
"iat": 1729743269,
"iss": "https://ssf.wholesalechips.co/",
"jti": "ABJmMDgxZGMtZmVjYy11NjA1LWFjY2QtNzAiM2UEZmYzZTBh",
"sub_id": {
"email": "alice@wholesalechips.co",
"format": "email"
}
}
Note: Ensure you haven’t used the jti previously for this event stream, SGNL will reject duplicate JTI’s
eyJhbGciOiJub25lIiwidHlwIjoiSldUIn0. and append a period . – the result should look a little something like:eyJhbGciOiJub25lIiwidHlwIjoiSldUIn0.ewogICJhdWQiOiAiaHR0cHM6Ly9zZ25sLmFpIiwKICAiZXZlbnRzIjogewogICAgImh0dHBzOi8vc2NoZW1hcy5vcGVuaWQubmV0L3NlY2V2ZW50L2NhZXAvZXZlbnQtdHlwZS9zZXNzaW9uLXJldm9rZWQiOiB7CiAgICAgICJldmVudF90aW1lc3RhbXAiOiAxNzI5NzQzMjY5LAogICAgICAic3ViamVjdCI6IHsKICAgICAgICAiZW1haWwiOiAiYWxpY2VAd2hvbGVzYWxlY2hpcHMuY28iLAogICAgICAgICJmb3JtYXQiOiAiZW1haWwiCiAgICAgIH0KICAgIH0KICB9LAogICJpYXQiOiAxNzI5NzQzMjY5LAogICJpc3MiOiAiaHR0cHM6Ly9zc2Yud2hvbGVzYWxlY2hpcHMuY28vIiwKICAianRpIjogIkFCSm1NRGd4WkdNdFptVmpZeTExTmpBMUxXRmpZMlF0TnpBaU0yVUVabVl6WlRCaCIsCiAgInN1Yl9pZCI6IHsKICAgICJlbWFpbCI6ICJhbGljZUB3aG9sZXNhbGVjaGlwcy5jbyIsCiAgICAiZm9ybWF0IjogImVtYWlsIgogIH0KfQ.
curl --location 'https://events.sgnlapis.cloud/events/ssf/v1/11111111-2222-3333-4444-555555555555' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJ.. (Your Auth Token)' \
--data 'eyJhbGciOiJub25lIiwidHlwIjoiSldUIn0.ewogICJhdWQiOiAiaHR0cHM6Ly9zZ25sLmFpIiwKICAiZXZlbnRzIjogewogICAgImh0dHBzOi8vc2NoZW1hcy5vcGVuaWQubmV0L3NlY2V2ZW50L2NhZXAvZXZlbnQtdHlwZS9zZXNzaW9uLXJldm9rZWQiOiB7CiAgICAgICJldmVudF90aW1lc3RhbXAiOiAxNzI5NzQzMjY5LAogICAgICAic3ViamVjdCI6IHsKICAgICAgICAiZW1haWwiOiAiYWxpY2VAd2hvbGVzYWxlY2hpcHMuY28iLAogICAgICAgICJmb3JtYXQiOiAiZW1haWwiCiAgICAgIH0KICAgIH0KICB9LAogICJpYXQiOiAxNzI5NzQzMjY5LAogICJpc3MiOiAiaHR0cHM6Ly9zc2Yud2hvbGVzYWxlY2hpcHMuY28vIiwKICAianRpIjogIkFCSm1NRGd4WkdNdFptVmpZeTExTmpBMUxXRmpZMlF0TnpBaU0yVUVabVl6WlRCaCIsCiAgInN1Yl9pZCI6IHsKICAgICJlbWFpbCI6ICJhbGljZUB3aG9sZXNhbGVjaGlwcy5jbyIsCiAgICAiZm9ybWF0IjogImVtYWlsIgogIH0KfQ.'
202 Accepted response as a resultThere are a range of troubleshooting tools within SGNL to help troubleshoot issues you might see with Event Streams in SGNL
SGNL’s Event Stream APIs will provide standards-confirming response codes and error codes - in many cases, these responses and messages will enable you or your partners to debug the cause of the issue without further investigation. A successful Event Push is accepted with a 202 status code.
It really starts with SGNL Logs and we have a number of logs that are interesting to Administrators in SGNL, by heading over to Logs and Event Streams, you’ll have a number of log channels.
You can start with Event Received Logs, this will give you a full output of the Event that was received, inclusive of the whole base64 payload. You can decode this JWT in order to understand the values that were present.
You can verify that not only was the event received by SGNLs APIs, but it was also stored from the Event Stored logs that list out the JTI for each event that has been successfully stored.
The Event Failed logs, these logs are designed to provide a comprehensive mechanism for debugging issues with Event Streams. Some common problems that cause event reciept to fail
iat and exp are of type DateTime (not Strings), and need to be configured as such