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.
• 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.

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 4 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 on successful login.	For use only with the login flow.
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.
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. This is the only action type available 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 Updating claims at token refresh to learn more about Actions in Ory OAuth2 & OpenID Connect.