Overview

Ory Actions are an extensibility mechanism provided by the Ory Network that allows you to integrate with third-party services:

• CRM platforms, such as Mailchimp or HubSpot
• Payment gateways, such as Stripe
• Business analytics tools, such as Google Analytics, Mixpanel, or Segment
• Integration platforms, such as Zapier or IFTT

With Ory Actions, you can define custom business logic and automate the behavior of the system in response to events that occur in your Ory-powered applications. You can write Actions in any programming language and trigger them through events such as user registration, or users resetting their passwords. This gives you a flexible way to extend the capabilities of Ory Network, integrate with other services to streamline your workflows, and improve the overall experience of your users.

Ory Actions is a feature supported by two of the Ory services:

• Ory Identities: Execute actions in response to user-related events such as login, registration, account recovery, account verification, or user settings update.
• Ory OAuth2 and OpenID Connect: Execute actions in response to refreshing OAuth 2.0 Access Tokens.

Actions in Ory Identities

Ory Identities is an identity management solution that supports actions for user-related events: login, registration, account recovery, account verification, or user settings update.

Actions triggered after events

• Login actions allow you to automate behavior in response to users logging in to your application. For example, you can use Ory Actions to update user information in your database or send welcome emails to users that log in for the first time.
• Registration actions allow you to automate behavior in response to users registering in your application. For example, you can use Ory Actions to automatically create a user account in your database or add the user to your mailing list.
• Account recovery actions allow you to automate behavior in response to users initiating the account recovery process. For example, you can use Ory Actions to send a password reset email to the user or update user information in your database.
• Verification actions allow you to automate behavior in response to users verifying their accounts. For example, you can use Ory Actions to update user information in your database or send welcome emails to users who verified their accounts.
• Settings actions allow you to automate behavior in response to users updating their account settings. For example, you can use Ory Actions to update user information in your database or send confirmation or summary emails to users.

Actions triggered before events

You can use Ory Actions before events such as user login, registration, triggering account recovery or verification, and updating account settings.

For example, you can enforce invite-only registration in your application by triggering an action that checks if certain criteria are met before the registration flow starts. This can be useful for controlling the number of users that have access to your application and ensuring that only authorized users can register.

You can also use Ory Actions to add additional security checks when users initiate login, registration, account recovery or verification, and settings update flows. For example, you can create logic that checks the IP address of the user to ensure that the request is coming from a trusted location or to verify that the user's email address is associated with a valid domain.

By using Ory Actions you can have a high degree of control over the flow of events in your application and improve the overall security and user experience.

Action triggers

Ory Identities supports the following action triggers:

• before login: The hook runs when the user starts the login flow.
• after login: The hook runs when the user is successfully authenticated, before the system issues an Ory Session.
• failure login: The hook runs in the background when Ory rejects a login attempt's credentials.
• before registration: The hook runs when a registration flow starts.
• after registration: The hook runs when a user successfully registers in the system.
• before recovery: The hook runs when the user starts the recovery flow.
• after recovery: The hook runs when the user successfully recovers their password.
• before settings: The hook runs when the user starts the account settings flow.
• after settings: The hook runs when the user successfully changes their account settings.
• before verification: The hook runs when the user starts the verification flow.
• after verification: The hook runs when the user verifies their account.

info

before actions run when Ory Kratos Identities creates the flow, not when the user submits it. Their payload has no transient_payload, no identity, and no credentials, because none of that exists yet. To act on data the user submits, such as a CAPTCHA or risk token, use the matching after trigger with can_interrupt: true. The after login action runs before Ory Kratos Identities issues a session, and the after registration action runs before it persists the identity, so both can still block the flow.

Login failure trigger

The failure trigger is available on Ory Network and in the Ory Enterprise License (OEL). Ory Open Source (OOS) doesn't include it.

Use the failure login trigger to report rejected login attempts to your own endpoint, for example a fraud detection service. Ory Kratos Identities runs the trigger's hooks once for every login attempt that it rejects because of one of these:

• A wrong password or TOTP code, or a lookup secret (recovery code) that is wrong or already used. A password for an identifier that has no account counts as wrong.
• A wrong or already used login code.
• An identifier that Ory Kratos Identities rejects because no account matches it, in identifier-first login and code login. For identifier-first login, this applies only when account enumeration mitigation is off.
• A passkey, WebAuthn, or device authentication assertion that fails verification.
• An account that has no security key, passkey, or DeviceAuthn device registered for the method the user chose.
• A social sign-in provider that denies the login, or a provider response that Ory Kratos Identities rejects. This includes a native id_token that fails verification.
• A social sign-in that Ory Kratos Identities can't complete with the provider, for example because the provider is unavailable or misconfigured. This covers failures of the token exchange, the user info request, and the signing key fetch.

The trigger doesn't run for:

• Requests that Ory Kratos Identities can't process, such as malformed submissions, failed CSRF checks, and expired flows.
• Users who are already signed in.
• Attempts that brute-force protection refuses.
• Attempts that a web hook blocks.
• Internal errors.
• Test flows that check a social sign-in provider's configuration.
• Failures on a registration flow, including a social sign-up that would have turned into a login.
• Enterprise SSO (SAML) sign-in failures.

Only the web_hook action runs on this trigger, and it always runs in the background. The response to the user doesn't wait for it, and the web hook can't change that response. The configuration rejects can_interrupt: true and response.parse: true, and response.ignore has no effect.

Ory Kratos Identities ignores your endpoint's response and makes one delivery attempt with a 10-second timeout. It doesn't retry a failed delivery.

ory get identity-config --format yaml

selfservice:
  flows:
    login:
      failure:
        hooks:
          - hook: web_hook
            config:
              url: https://example.com/login-failed
              method: POST
              body: base64://ENCODED_JSONNET

The trigger has no hooks per authentication method. To handle only some methods, read ctx.failure.method in the Jsonnet template and cancel the web hook for the others.

The Jsonnet context has the fields that every login web hook gets, such as flow, request_headers, request_url, location, and ip_labels. It has no identity or session. Instead, ctx.failure describes the rejected attempt:

{
  "method": "password",
  "identifier": "[email protected]",
  "identity_id": "9f425a8d-7efc-4768-8f23-7647a74fdf13"
}

• method is the authentication method of the attempt, for example password, code, totp, or oidc.
• provider is the ID of the social sign-in provider. It's present only for the oidc method.
• identifier is the identifier that the user submitted, such as an email address. It's present only for the password, code, and identifier_first methods.
• identity_id is the ID of the identity that Ory Kratos Identities matched to the attempt, and null when the attempt wasn't matched to an identity. For a second factor, such as a TOTP code, it's the ID of the signed-in identity.

ctx.flow.transient_payload is the transient_payload of the rejected request. For a social sign-in in the browser, it's the transient_payload of the request that started the sign-in.

The context doesn't contain the password, code, token, or assertion that the user submitted. On a failed social sign-in callback, ctx.request_url is the callback URL with its query parameters, including the authorization code and state. Every web hook that runs on that request gets the same URL.

The failure trigger and the LoginFailed event in live event streams complement each other. LoginFailed also covers failed login flows that this trigger skips, such as throttled or malformed attempts, but doesn't carry the transient_payload. Use the failure trigger when your endpoint needs the transient_payload or the submitted identifier for each rejected attempt.

Triggers based on authentication methods

You can further customize the behavior of the system by defining what action to trigger based on the authentication method used to sign in, register, and update user settings.

For example, when a user signs in with a password, you can use Ory Actions to send a welcome email to the user or update user information in your database. When a user signs in using OIDC, you can use Ory Actions to enrich your CRM with data from the social sign-in provider.

Authentication method	Description
password	Sign-in and sign-up with username/email and password combo.
oidc	Sign-in and sign-up through OIDC-compliant OAuth2 identity providers.
totp	MFA Sign-in with a TOTP code from apps such as Google Authenticator.
webauthn	MFA Sign-in with WebAuthn-compatible factors (FaceID, YubiKey) or paswordless sign-up and sign-in.
lookup_secret	MFA Sign-in with recovery codes.

Available actions

There are 6 actions you can use to extend self-service user flows. The web_hook action allows you to trigger any custom, external logic.

info

Some actions can only be used for specific flows and methods.

Action	Description	Details
session	Signs in the user immediately after they create an account.	For use only with the after registration flow. To use it, you must define secrets for secret rotation.
revoke_active_sessions	Revokes all other active sessions of the user.	For use only with the after login flow, the after recovery flow, and the after settings flow for authentication methods such as password.
require_verified_address	Allows users to sign in only when they verified their email address.	For use only with the after login flow, password method only.
verify_new_address	Changes the user's address after they verify the new address.	For use only with the after settings flow, profile method only.
notify_previous_addresses	Notifies the user's previous addresses when they change a verifiable address.	For use only with the after settings flow, profile method only. Accepts a recipients configuration.
web_hook	Allows to trigger external and custom logic. Can be used with all flows and methods except error and logout.	Requires providing webhook configuration. It is the most common action type for the after settings flow. See an example of using webhooks here.

Trigger precedence

The graph below shows when triggers happen.

• Ory executes the before actions when the user starts a flow.
• Ory executes the after actions when the user submits or completes the flow.
• When an authentication method specifies actions, it overrides the default actions for the flow.

With the following configuration, hook_3 is executed when the user logs in with a password, hook_2 is executed when the user logs in with any other method, for example through social sign-in, and hook_1 is executed for all login flows when the user starts the flow.

ory get identity-config --format yaml

selfservice:
  flows:
    login: # Defines for which flow triggers the action.
      before: # When the user starts the flow
        hooks:
          - hook: hook_1 # Specifies which hook is triggered.
      after: # When the user submits the flow
        hooks:
          - hook: hook_2 # is executed for all authentication methods except password
        password:
          hooks:
            - hook: hook_3 # is executed only for password method

Actions in Ory OAuth2 & OpenID Connect

Read OAuth2 webhooks to learn more about Actions in Ory OAuth2 & OpenID Connect.