What are prehooks?

Frontegg empowers you to control crucial aspects of your user management with prehooks.

Thanks to our comprehensive user management platform, Frontegg records and monitors vital user-related processes, including but not limited to user signup and user invites events. Prehooks help you devise the desired responses after pivotal events happen in your app and gain utmost control over your users' flow.

By configuring prehooks, your application will receive a REST call whenever the associated event occurs. This call - coupled with the ensuing response - allows your application to make informed decisions. For example, you can dynamically determine whether to proceed with a specific user management flow or terminate it— all based on the logic set in your prehook configuration.

Prehooks use cases

Prehooks are a powerful tool for various situations where you need to manage your user's journey. Here are some potential scenarios where prehooks can be beneficial:

• User signup control: you can limit user sign-up to users belonging to a specific account (domain). This ensures that only authorized users can create an account:

• Membership invitation limitations: Prehooks can be set to limit the number of new member invitations based on a predetermined number. This can be used if you want to enforce a trial period, for instance. Or when accounts may have run out of user seats as part of their subscription plan:

• Custom claims to JWTs: With prehooks, you can add custom claims to JWTs. This allows you to customize the authentication process to suit your specific needs.
• IP-Based signup restrictions: If you want to prevent signups from specific IP addresses, prehooks can be used to enforce this restriction. This can be useful for security or regional compliance reasons.
• Overriding default flows & Organization-based signups: By returning a tenantId in authentication prehooks, you can override Frontegg's default flows, giving you more control over the user authentication process. This method is particularly useful for allowing users from the same organization to sign up to existing accounts— this can be done by passing the tenantId of where you’d like to add the user.

Determining a user flow

Whenever a user opts to perform a specific action, you can set a triggered event prehook, upon which the user will be enrolled in a specific flow, according to the prehook's set logic. In the following schema, you can see that a prehook can determine the user's journey after it is triggered (Continue, Block, Challenge, Lock). More on prehook verdicts in the following section.

Prehook verdicts

When a user is enrolled in a prehook, you can choose which of the four possible verdicts will be enabled for that prehook— challenge, allow, block, lock:

• Continue: The user is allowed to proceed with the flow.
• Block: The user is not compliant with the flow requirements and is not allowed to continue with the flow.
• Challenge: The user falls within the rules that require a challenge (usually for enhanced security measures).
• Lock: The user is locked when trying to perform a specific flow/action. This verdict can be used in cases such as locking users after periods of inactivity or if a user enters the wrong password multiple times in a row.

The example below shows a JWT generation prehook:

 
  {
    "continue": "boolean", // deprecated (refer to documentation)
    "verdict": "allow | block",
    "error": {
      "status": "number",
      "message": "string[]"
    },
    "response": {
      "claims": {
        "tenantId": "string",
        "customClaims": "Record<string, unknown> | null"
      }
    }
  }

User OpenID Connect authentication prehook example:

  {
    "continue": "boolean", // deprecated (refer to documentation)
    "verdict": "challenge | allow | block | lock",   
    "error": {
      "status": "number",
      "message": "string[]"
    },
    "response": {
      "user": {
        "firstName": "string | null",
        "lastName": "string | null",
        "email": "string | null",
        "roleIds": "string[] | null",
        "metadata": "JSON | null",
        "profilePictureUrl": "string | null"
      }
    }
  }

Step-By-Step prehook setup

Subscribing to prehook events is done in 3 simple steps:

Step 1: Create a prehook event

Open the Frontegg portal, then navigate to [ENVIRONMENT] ➜ Configurations ➜ Prehooks.

• Click the Create Prehook button.

Step 2: Enter prehook details

The next step would be to set your prehook information, and choose your prehook type. The Code type will indicate if the prehook is either an API or a custom prehook.

• Select a triggering event for your prehook.
• Insert your preferred display name and description.
• The URL should be the address where you will receive the prehook data. The URL acts as an address where Frontegg sends a JSON message when the assigned event happens.
• For the secret key, enter a value that is confidential (see note).

Step 3: Test your prehook

To finalize your hook creation, test your prehook to verify everything was setup correctly.

Click the run test button and then await the response— You should see the prehook data received and the response Frontegg expects from your application. If the response is valid, your prehook is ready to go, and you can enable it.

Working with prehook events

You may want to adjust the configuration of prehooks when subscribing. Read on to learn how to work with prehook events.

JWT custom claims

If you want to customize the data encoded by the JWT, you need to subscribe to a prehook event for JWT Generation. This will allow you to intercept the JWT and customize the JWT claims.

For JWT Generation prehooks, Frontegg sends a new prehook event every time the hosting application requests a new JWT.

The prehook event sent to the hosting application contains whatever data Frontegg has stored for each claim in the table below.

To override the default claims, include the data that you want to change in your prehook response.

You can include the following claims in your prehook response:

After customizing your JWT claims, you can test your hook:

Single prehook view

After testing and creating your prehook, you can view and adjust its settings. Each prehook has a Logs tab where you can see the triggered events associated with that prehook. Note that you can't change the Trigger event for custom prehooks after the connection is initiated.

Prehook event list

The following list shows all available events that can be associated with prehooks: