Run actions at sign-in

Run your own rules while a person signs in, to add claims to their token, deny the sign-in, or require multi-factor authentication.

An action is a rule that runs inside sign-in. Use an action to put your own facts in a token, or to decide who gets in: an action can deny a sign-in, or require multi-factor authentication (MFA).

This guide explains the kinds of action, then shows how to add claims to a token from your own server.

Before you begin

You need:

• Access to Settings > Actions in the AuthFI console.
• For a webhook action, an https endpoint on your server that answers within the action's timeout. The default is 2 seconds.

Add an action

In the console, open Settings > Actions and choose New action.

The dialog then shows the fields for the kind you chose. Fill them in, and choose Create (live now).

A new action starts enabled. The action appears in the list with its order, a switch that turns it on or off, and Edit and Delete. An action that can deny a sign-in carries the badge can block.

You set the trigger and the kind when you create an action. To change the rest, choose Edit. To remove an action, choose Delete and confirm with Delete rule.

Triggers

An action runs at one of two points in sign-in.

Actions on one trigger run in the order you set. The first action that denies ends the sign-in.

Kinds of action

For a Condition rule, Effect is one of Require step-up (MFA), Deny (block the flow) and Set a claim. Depending on the effect, you also enter Claim and Value, or Required ACR (optional).

For a Risk rule, enter at least one of the two scores.

For a Claim rule, an empty Value copies the subject.

A webhook action adds claims. To deny a sign-in, use a condition rule or a risk rule.

Add claims from your own server

A webhook action calls your server while the token is being issued, and adds the claims you return.

{
  "subject": "user:[email protected]",
  "context": {
    "subject": "user:[email protected]",
    "roles": ["developer"],
    "permissions": ["read:reports"]
  }
}

import { createRemoteJWKSet, jwtVerify } from "jose";

const keys = createRemoteJWKSet(new URL("https://acme.authfi.io/.well-known/jwks.json"));

// `authorization` is the value of the Authorization header.
export async function fromAuthFI(authorization) {
  const token = (authorization ?? "").replace(/^Bearer /, "");
  const { payload } = await jwtVerify(token, keys, {
    issuer: "https://acme.authfi.io",
    subject: "authfi:actions",
    audience: process.env.ENDPOINT_URL,
    algorithms: ["RS256"],
  });
  return payload;
}

{ "claims": { "plan": "enterprise", "cost_center": "R-204" } }

{ "sub": "[email protected]", "custom": { "plan": "enterprise", "cost_center": "R-204" } }

Check that it works

Sign in to an application in the project and read the token it receives. The claims your server returned appear under custom.

Timeouts and failures

Your server is on the path of every sign-in. Answer from memory or a fast cache.

Treat the claims as helpful rather than essential. A token issued while your server was slow does not carry them, so your application must work when custom is absent.

Guidelines for claims

• Keep claims small. They travel in every token.
• Do not put secrets in claims. Whoever holds a token can read it.
• Name claims for what they mean in your product, not for the system they came from.

Troubleshooting

Next steps