Websocket Client/Dispatcher Protocol#

Communication between local clients and the dispatcher are done through a websocket, as defined by RFC 6455.

All messages on the established connection are UTF-8 JSON encoded payloads. They do not require any acknowledgement from the other party. Unknown or malformed messages are not acknowledged as such (no NACK), simply ignored.

Client to server messages#

All messages emitted by the client and received by the server have two optional, single components:

A “creation” section, identified by the create key, indicating what kind of resource to create.
A “registration” section, identified by the register_to key, indicating what kind of event to register to.

Both these sections, if present, contain a type attribute, allowing the server to adapt its decoding depending on the kind of resource to create, or the kind of event to subscribe to.

Such messages are represented by ClientMessage.

Callback state creation#

This “creation” section, identified by the callback section type, allows creating a stored state for the listener to adapt its behaviour for the provided callback state, and emit events for this callback state.

This section has the following properties:

type: should be set to "callback".
state: the state to store the configuration for, e.g. "abc".
final_redirect_url: the optional final redirect URL to redirect the end user to, e.g. "https://example.org/callback?state=def".

If set to null, the listener won’t redirect the end user before sending the event on the message queues; see Callback endpoints using the TeaL Web listener for more information.
with_fragment: whether to force gathering the fragment, if the state is found by the base callback, e.g. false.

See Callback endpoints using the TeaL Web listener for more information on this behaviour.
expires_at: the ISO 8601 formatted UTC expiration date and time for the stored state, e.g. "2022-12-31T23:59:59.00".

This expiration date and time must be set, and within 7 days of the current UTC date and time. If provided with a timezone, it will first be converted to UTC before processing.

An example section for a basic callback with redirection is the following:

{
    "type": "callback",
    "state": "abc",
    "final_redirect_url": "https://example.org/callback?state=def",
    "with_fragment": false,
    "expires_at": "2022-12-31T23:59:59.00"
}

An example section for a callback without redirection and with fragment gathering:

{
    "type": "callback",
    "state": "abc",
    "final_redirect_url": null,
    "with_fragment": true,
    "expires_at": "2022-12-31T23:59:59.00"
}

This structure is represented by CallbackCreation.

Callback event registration#

This “registration” section, identified by the callback type, allows registering to callback events regarding a given state.

This section has the following properties:

type: should be set to callback.
state: the state for which to get callback events.

An example section for registering callback events regarding a given state:

{
    "type": "callback",
    "state": "abc"
}

This structure is represented by CallbackRegistration.

OpenID CIBA callback event registration#

This “registration” section, identified by the openid_ciba_callback type, allows registering to callback events regarding a given OpenID CIBA authentication request identifier.

This section has the following properties:

type: should be set to openid_ciba_callback.
request_id: the request identifier for which to get OpenID CIBA callback events.

An example section for registering OpenID CIBA callback events regarding a given request identifier is:

{
    "type": "openid_ciba_callback",
    "request_id": "21d27ce8-a41a-4115-ace1-b5c1e6b2570c"
}

This structure is represented by OpenIDCIBACallbackRegistration.

Powens domain webhook registration#

This “registration” section, identified by the powens_domain type, allows registering to Powens webhook events regarding a specific Powens domain.

This section has the following properties:

type: should be set to powens_domain.
powens_domain: the Powens domain for which to listen for webhooks.

An example section for registering Powens webhook events regarding a given Powens domain:

{
    "type": "powens_domain",
    "powens_domain": "budgea.biapi.pro"
}

This structure is represented by PowensDomainRegistration.

Combining creation and registration sections#

When preparing a state for a redirect flow, you may want to combine callback state creation and event binding. You can do this simply by having both a creation and a registration section.

For example:

{
    "create": {
        "type": "callback",
        "state": "abc",
        "final_redirect_url": "https://example.org/callback?state=def",
        "with_fragment": false,
        "expires_at": "2022-12-31T23:59:59.00"
    },
    "register_to": {
        "type": "callback",
        "state": "abc"
    }
}

Server to client messages#

All messages emitted from the server to the client have a type attribute, allowing you to adapt the message decoding depending on its value.

Callback creation failure#

This message signals the failure of a callback state creation from the client. If the client request also had a registering section, it has not been run.

Such a message has the following properties:

type: is set to "callback_creation_failure".
state: the state for which creation has failed.
detail: the human-readable reason for which the callback creation has failed.

An example of such a message is the following:

{
    "type": "callback_creation_failure",
    "state": "abc",
    "detail": "Callback expiration date was too early."
}

Note

This message is only present for human-assisted debugging, since the only errors in which such a message is produced could be determined in advance by the client from the format of their message.

A correct use of this message would be to simply display it as a warning somewhere in your logs, to be able to trace an invalid usage of TeaL by your application.

This structure is represented by CallbackCreationFailedServerMessage.

Callback message#

This message signals a callback event on one of the registered callback states.

Such a message has the following properties:

type: is set to "callback".
timestamp: the ISO 8601 encoded timezone-naive UTC date and time of the event.
state: is set to the callback state for which the event was produced, e.g. "abc".
url: is set to the full obtained URL, e.g. "https://teapots.fr/callback?state=abc&code=def".

An example of such a message is the following:

{
    "type": "callback",
    "timestamp": "2022-12-31T23:59:59.000000",
    "state": "abc",
    "url": "https://teapots.fr/callback?state=abc&code=def"
}

This structure is represented by CallbackServerMessage.

OpenID CIBA callback message#

This message signals an OpenID CIBA callback event on one of the registered request identifiers. For more information on the structure of such a message, please consult the definition of OpenIDCIBACallbackServerMessage directly.

An example of such a message is the following:

{
    "type": "openid_ciba_callback",
    "timestamp": "2022-12-31T23:59:59.000000",
    "request_id": "1c266114-a1be-4252-8ad1-04986c5b9ac1",
    "access_token": "8d67dc78-7faa-4d41-aabd-67707b374255",
    "push_token": {
        "access_token": "G5kXH2wHvUra0sHlDy1iTkDJgsgUO1bN",
        "token_type": "Bearer",
        "refresh_token": "4bwc0ESC_IAhflf-ACC_vjD_ltc11ne-8gFPfA2Kx16",
        "expires_at": "2023-01-01T00:01:59.000000",
        "id_token": "eyJhb...A7udg"
    },
    "push_error": null
}

Powens webhook message#

This message signals a Powens webhook event.

The type of such an event is powens_webhook. For more information on the structure of such a message, please consult the definition of PowensWebhookServerMessage directly.

An example of such a message is the following:

{
    "type": "powens_webhook",
    "timestamp": "2022-12-31T23:59:59.000000",
    "domain": "budgea.biapi.pro",
    "event": "USER_CREATED",
    "hmac_signature": null,
    "user_token": "abc",
    "payload": "{...}"
}