Skip to main content

Hooks

Hooks execute logic after a flow (login, registration, settings, ...):

  • Before login: is executed when a login flow starts.
  • After login: is executed after a successful identification and authentication of the user, but before the kratos session is created.
  • Before registration: is executed when a registration flow starts.
  • After registration: is executed when a registration was successful:
    • Before persisting: runs before the identity is saved in the database.
    • After persisting: runs after the identity was saved in the database.
  • After recovery: is executed after a password has been successfully recovered.
  • After settings: is executed when a settings was successful:
    • Before persisting: runs before the identity is saved in the database.
    • After persisting: runs after the identity was saved in the database.
  • After verification: is executed when the verification of an account was successful.

There are hooks, which can be configured only for a particular flow (login, registration, settings, ...) method (password, oidc, profile) and hooks, which can be configured for all methods of any flow.

To configure hooks for all methods of a particular flow, following pattern must be used:

"path/to/my/kratos.config.yml
selfservice:
  flows:
    <login|registration|recovery|...>:
      <before|after>:
        hooks:
          - hook: <hook 1 name>
            <hook 1 specific configuration>
          - hook: <hook 2 name>
            <hook 2 specific configuration>
          ...

Following pattern must be followed to configure hooks for a particular flow method:

"path/to/my/kratos.config.yml
selfservice:
  flows:
    <login|registration|recovery|...>:
      <before or after>:
        <particular method>:
          hooks:
            - hook: <hook 1 name>
              <hook 1 specific configuration>
            - hook: <hook 2 name>
              <hook 2 specific configuration>
            ...

Hooks configured on a particular method level always override the hooks configured on the flow level. So given the following example

"path/to/my/kratos.config.yml
selfservice:
  flows:
    login:
      before:
        hooks:
          - hook: hook_1
            # hook_1 specific configuration
      after:
        hooks:
          - hook: hook_2
            # hook_2 specific configuration
        password:
          hooks:
            - hook: hook_3
              # hook_3 specific configuration
        # ...

hook_1 is always run when the flow is started. On the finalization of the flow, hook_2 is not run for the password method, but for the oidc method (for example). If the password method is used, then hook_3 will run.

All flows​

Following hooks can be configured for all flows.

Web-Hooks​

Web-Hooks can be configured for every, but error and logout flow and can be configured on either the before/after level or at the level of a particular method. Support for Web-Hooks before execution of a method is currently supported only for registration and login methods.

note

As of today Web-Hooks cannot control the execution of the flow by patching/updating particular properties of flow specific object upon Web-Hook completion. It will however cancel the execution of the flow if the call to the Web-Hook end point fails either due to a network error or if the end point responses with an HTTP code > 300.

The configuration for a web-hook goes into the hooks property either on the flow before/after, or the method level and has the following structure:

"path/to/my/kratos.config.yml
- hook: web_hook
  config:
    url: https://test.kratos.ory.sh/after_verification_hook
    method: POST # GET, DELETE, etc
    body: file:///path/of/my/jsonnet/file
    auth:
      type: <some-type>
      config: <type-specific-config>

The configuration section of a web-hook consists of

  • url - the url, the web-hook should call (mandatory)
  • method - the HTTP method (GET, POST, ...), the web-hook should use (mandatory)
  • body - URI of a jsonnet template, used by the web-hook to render the payload to send (optional). Use a file://path/to/body.jsonnet URL for referring to local files. This property is ignored for HTTP methods, which do not support sending of HTTP body payloads.
  • auth - configuration of authentication and authorization mechanisms to be used by the web-hook

Web-Hooks bind the flow, as well as request headers (request_headers), request method (request_method), and the request url (request_url) of the flow into the jsonnet template for all methods and execution paths (before and after). For the after execution path of all flows, it binds the identity object into the jsonnet template as well. These objects are available through a ctx object. E.g. to create a body looking like { user_id: <some-id> } to be send to the web hook end point, the jsonnet template would look like this: function(ctx) { user_id: ctx.identity.id }

Web-Hook Authentication and Authorization Mechanisms​

For auth following mechanisms are supported:

  • Authentication via an Api Key. Type must be set to api_key.
  • Authentication via Basic Authentication. Type must be set to basic_auth.

For api_key the config looks as follows:

name: Some-Name
value: The-Value-of-My-Key
in: header # alternatively cookie

All properties are mandatory.

For basic_auth the config looks as follows:

user: My-User
password: My-Pass-Value

All properties are mandatory.

Login​

Hooks running before or after successful user login are defined per Self-Service Registration Method in ORY Kratos' configuration file.

Before​

path/to/my/kratos.config.yml
selfservice:
  flows:
    login:
      before:
        hooks:
          - hook: web_hook
            # web-hook specific configuration

After​

path/to/my/kratos.config.yml
selfservice:
  flows:
    login:
      after:
        password:
          hooks:
            - hook: revoke_active_sessions
            - hook: require_verified_address

revoke_active_sessions​

The revoke_active_sessions will delete all active sessions for that user on successful login. This hook is available for all supported methods:

path/to/my/kratos.config.yml
selfservice:
  flows:
    login:
      after:
        <method>:
          hooks:
            - hook: revoke_active_sessions
              # can not be configured

require_verified_address​

The require_verified_address will ensure, the user can login only if its email address is verified. This hook is available for the password method only:

path/to/my/kratos.config.yml
selfservice:
  flows:
    login:
      after:
        password:
          hooks:
            - hook: require_verified_address
              # can not be configured

Please be aware, that since require_verified_address hook is enforcing a verified address before the user can login, a typo in an email address done by the user either during the registration or as part of a self service flow (email change) will make the login for that user impossible. So you should think about measures to prevent such situations, like requiring two email addresses being configured by the user, thus having a backup if something goes wrong.

Registration​

Hooks running before or after successful user registration are defined per Self-Service Registration Method in ORY Kratos' configuration file.

Before​

path/to/my/kratos.config.yml
selfservice:
  flows:
    registration:
      before:
        hooks:
          - hook: web_hook
            # web-hook specific configuration

After​

path/to/my/kratos.config.yml
selfservice:
  flows:
    registration:
      after:
        oidc:
          hooks:
            - hook: session
        password:
          hooks:
            - hook: session

session​

Adding the session hook signs the user immediately in once the account has been created. It runs after the identity has been saved to the database.

info

Using this job as part of your post-registration workflow makes your system vulnerable to Account Enumeration Attacks because a threat agent can distinguish between existing and non-existing accounts by checking if Set-Cookie was sent as part of the registration response.

To use this hook, you must first define one or more (for secret rotation) secrets. You can either choose to use the "default" secrets or the more specific "cookie" secrets. The other required config is setting the hook in after work flows:

path/to/my/kratos.config.yml
secrets:
  cookie:
    - something-super-secret # The first entry will be used to sign and verify session cookies

    # All other entries will be used to verify session cookies that were signed before "something-super-secret" became
    # the current signing secret.
    - old-session-secret
    - older-session-secret
    - ancient-session-secret

selfservice:
  flows:
    registration:
      after:
        <method>:
          hooks:
            - hook: session
              # can not be configured

Depending on the registration flow type the behavior changes.

Registration Flow via Browser​

When performing a registration flow with a Browser, this hook sends a Set-Cookie HTTP header which contains the session cookie.

Therefore, the user is logged in immediately.

Registration Flow via API​

When performing a registration flow with an API client (e.g. mobile apo), this hook creates a session and returns the session token and the session itself in the response body as application/json:

{
  "session": {
    "id": "..."
    // ...
  },
  "session_token": "...",
  "identity": {
    "id": "..."
    // ...
  }
}
info

Because the HTTP reply is handled by the hook itself, no other hooks can be executed because the HTTP reply can not be modified further (e.g. HTTP Status Code was already sent as 200 and cannot be changed to 301). You must ensure that the session hook is the last hook in your configuration!

Settings​

Hooks running after successfully updating user settings and are defined per Self-Service Settings Method in Ory Kratos' configuration file.

After​

path/to/my/kratos.config.yml
selfservice:
  flows:
    settings:
      after:

Only Web-Hooks hooks are available for this flow at the moment.