Shared Signals

# In this and the following example python snippets, we're using the
# requests library to issue basic HTTPS requests to an example Event
# Transmitter. Note that for this ssf-configuration request, no
# authorization is needed.
ssf_config_response = requests.get(
  "https://transmitter.most-secure.com/.well-known/sse-configuration"
)
ssf_config = ssf_config_response.json()

{
  # This endpoint will be used by the receiver to view or update
  # the configuration of their stream.
  "configuration_endpoint": "https://transmitter.most-secure.com/stream",
  # This endpoint will be used by the receiver to add subjects to their stream.
  "add_subject_endpoint": "https://transmitter.most-secure.com/add-subject",
  # This endpoint will be used by the receiver to remove subjects from their stream.
  "remove_subject_endpoint": "https://transmitter.most-secure.com/remove-subject",
  # This endpoint will be used by the receiver to request a verification event,
  # so that the receiver can have confidence that the stream is working as intended.
  "verification_endpoint": "https://transmitter.most-secure.com/verification",
  # This endpoint will be used by the receiver to get or set the
  # status for the stream as a whole, or for individual subjects on the stream.
  "status_endpoint": "https://transmitter.most-secure.com/status",
  # This is the URL identifier of the transmitter; it matches the iss claim
  # in all events issued by this transmitter.
  "issuer": "https://most-secure.com/",
  # This is the URL of the transmitter's JSON Web Key Set. You can use
  # this to validate and decode the events sent by the transmitter.
  "jwks_uri": "https://transmitter.most-secure.com/jwks.json",
  # This attribute lets the transmitter declare which means of event
  # delivery it supports: pushing, polling, or both.
  "delivery_methods_supported": [
    "https://schemas.openid.net/secevent/risc/delivery-method/push",
    "https://schemas.openid.net/secevent/risc/delivery-method/poll"
  ],
  # This attribute comes into play when Complex Subjects are used.
  # A critical member is one that, if present, must be interpreted by the receiver.
  "critical_subject_members": [
    "user"
  ]
}

stream_config_response = requests.post(
  # Note that this request posts to the configuration_endpoint of the ssf_config
  # returned in the last example.
  url=ssf_config["configuration_endpoint"],
  json={
    # The receiver specifies how it would like to receive events, polling or pushing.
    "delivery": {
      # We are choosing the Polling method.
      "method": "https://schemas.openid.net/secevent/risc/delivery-method/poll",
      # In this example, because we're choosing Polling as our delivery method,
      # we can leave delivery.endpoint_url blank, as it is the Transmitter's
      # responsibility to specify that. If we had chosen Push, we would use this
      # value to tell the Transmitter where to send the events.
      "endpoint_url": None
    },
    # The receiver tells the transmitter what types of events it is interested in
    # getting on this stream by listing the URIs of the event types. The full list
    # of CAEP and RISC events are detailed in the Events section below, however the
    # SSF standard is general enough to cover any kind of event type. In our
    # imaginary scenario, PopularApp only cares about the Credential Compromise event.
    "events_requested": [
      "https://schemas.openid.net/secevent/risc/event-type/credential-compromise",
    ]
    # The receiver tells the transmitter its preferred subject identifier format.
    "format": "email"
  },
  # For this and all remaining requests, we need to include an Authorization header
  # with a Bearer token that the transmitter will be able to use to uniquely identify
  # us as a receiver.
  # These examples use a "secret" that our transmitter maps to PopularApp.
  headers={
    "Authorization": "Bearer 49e5e7785e4e4f688aa49e2585970370",
  }
)
stream_config = stream_config_response.json()

{
  # Read-Only. This URI is the issuer claim identifying the transmitter.
  # It will be included in all events set on this stream. The receiver can
  # check this value to ensure that the event was sent by the expected party.
  "iss": "https://most-secure.com/",
  # Read-Only. This URI or list of URIs is the audience claim identifying
  # the receiver. It will be included in all events sent on this stream.
  # The receiver can check this value to ensure the event is meant for them.
  "aud": "https://popular-app.com",
  # Read-Write. This indicates how events will be shared. If the push delivery
  # method is configured, the URL specified is where the receiver wants the
  # transmitter to push events. If the polling delivery method is configured,
  # the URL specified is the transmitter endpoint where the receiver can poll
  # for events.
  "delivery": {
    "endpoint_url": "https://transmitter.most-secure.com/poll",
    "method": "https://schemas.openid.net/secevent/risc/delivery-method/poll"
  },
  # Read-Only. These are the event types the transmitter supports.
  "events_supported": [
    "https://schemas.openid.net/secevent/caep/event-type/session-revoked",
    "https://schemas.openid.net/secevent/risc/event-type/credential-compromise",
  ],
  # Read-Write. These are the event types that the receiver is interested in.
  "events_requested": [
    "https://schemas.openid.net/secevent/risc/event-type/credential-compromise"
  ],
  # Read-Only. The intersection of events_requested and events_supported.
  "events_delivered": [
    "https://schemas.openid.net/secevent/risc/event-type/credential-compromise"
  ],
  # Read-Write. This optional setting indicates the subject format the receiver
  # wants for events.
  "format": "email",
  # Read-Only. This is the minimum time, in seconds, that a receiver must wait
  # in between verification requests.
  "min_verification_interval": 60
}

{
  "format": "email",
  "email": "user@example.com"
}

add_subject_response = requests.post(
  # note that this request posts to the add_subject_endpoint of
  # the ssf_config returned in the first example
  url=ssf_config["add_subject_endpoint"],
  json={
    # There are many different types of subject identifiers, but for this example we’ll
    # use the email format to identify a user by their email address.
    "subject": {
      "format": "email",
      "email": "reginold@popular-app.com"
    }
  },
  headers = {
    "Authorization": "Bearer 49e5e7785e4e4f688aa49e2585970370"
  }
)

verification_response = requests.post(
  # Note that the request posts to the verification_endpoint of the ssf_config
  # returned in the first example.
  url=ssf_config["verification_endpoint"],
  json={
    # This optional attribute, if included, ensures that the verification event
    # generated by this request will also include the state in the event data.
    "state": "VGhpcyBpcyBhbiBleG"
  },
  headers={
    "Authorization": "Bearer 49e5e7785e4e4f688aa49e2585970370"
  }
)

polling_response = requests.post(
  # Note that this request posts to the delivery endpoint returned when we configured
  # the stream, not to one of the initial set of well-known endpoints we've been
  # using until now.
  url=stream_config["delivery"]["endpoint_url"],
  json={
    # An optional integer value indicating the maximum number of events to be returned.
    # If more than the maximum number of events are available, the event transmitter
    # determines an appropriate algorithm by which to return them. If this parameter is
    # omitted, the transmitter may return any number of events.
    "maxEvents": 1,
    # An optional boolean value that indicates the transmitter should return an
    # immediate response even if fewer than maxEvents results are available
    # (short polling). The default value is false, which indicates the request is to
    # be treated as an HTTP long poll. A long polling request will always return 1 or
    # more events, unless a timeout is reached.
    "returnImmediately": True
  },
  headers={
    "Authorization": "Bearer 49e5e7785e4e4f688aa49e2585970370"
  }
)
events = polling_response.json()

{
  # A JSON object containing zero or more Security Event Tokens (SETs).
  # Each member name is the jti (a unique identifier for the event) of an event,
  # and its value is a string representing the event as an encoded JWT.
  "sets": {
    "1767b10443e511eca7740242ac120002": "eyJ0eXAiOiJzZWNldmVudCtqd..."
  },
  # A boolean value that indicates if more unacknowledged events are available
  # to be returned. If omitted, the receiver may assume no more events are available.
  "moreAvailable": false
}

{
  # Short for 'JWT ID', this is a unique identifier for the SET.
  # It allows receivers to determine whether they have already processed
  # this SET. Notice that it matches the key in the 'sets' object returned
  # from the polling endpoint.
  "jti": "1767b10443e511eca7740242ac120002",
  # This stands for "issued at" and describes the timestamp (in
  # seconds since the epoch) that the SET was issued.
  "iat": 1636741176,
  # Identifies the issuer of the SET. It should uniquely identify the
  # vendor that observed the security event. Notice that it matches the
  # issuer in the stream configuration.
  "iss": "https://most-secure.com/",
  # This is an identifier that the receiver can use to ensure
  # the SET is meant for them to process. The value can be a single URI or a
  # list of URIs. If it is present and the receiver cannot find themselves
  # in the values, the receiver should NOT process the SET.
  "aud": "https://popular-app.com",
  # A map of event URIs to event details. If multiple keys exist, they must
  # all be describing a single logical event. For instance, if the device
  # compliance change event also triggered a session revocation in the issuer,
  # you could potentially bundle those events together in this SET.
  # The common case will be to have one event per SET though. The event details
  # JSON will vary depending on event type. The keys used to indicate
  # the events are standardized and described in the CAEP and RISC specs.
  "events": {
    "https://schemas.openid.net/secevent/sse/event-type/verification": {
      # If the verification request included a state value, it will appear
      # here in the event. Note that this matches the state value sent to
      # the verification endpoint above.
      "state": "VGhpcyBpcyBhbiBleG"
    }
  }
}

 # Grab the jtis that we want to acknowledge from the response json in "events"
jtis_to_ack = list(events["sets"].keys())
requests.post(
  # Acknowledgement of the events and requesting new events both use the same endpoint.
  url=stream_config["delivery"]["endpoint_url"],
  json={
    # An optional array of strings whose values are the jti values of successfully
    # received events that are being acknowledged. Once an event has been acknowledged,
    # the transmitter is released from any obligation to retain the event.
    "acks": jtis_to_ack,
    # The acknowledgement payload doubles in purpose as the subsequent
    # request payload. In this example, we’d like to “disconnect” from the event stream
    # at this point, so we set this value to 0, meaning 0 events will be returned.
    # If we wanted to continue receiving events, we could set this to a non-zero value.
    "maxEvents": 0,
    "returnImmediately": True,
  },
  headers={
    "Authorization": "Bearer 49e5e7785e4e4f688aa49e2585970370",
  }
)