Email codes setup

One of the authorization methods with Citadel SSO is authorization by email code. You can use this as your primary authorization method or as second factor.

There are two options for sending the e-mail codes with the Citadel SSO. Either you let Citadel send the emails for you or you want to send your emails yourself so you can brand them correctly.

When you choose to send the emails on your end Citadel will send the email codes, email addresses and type of event to you through EventBridge.

In order to receive messages from the SSO EventBridge you need to set up the trust on your end by setting up the following rule:

import { EventBus, EventBusPolicy, Rule } from "aws-cdk-lib/aws-events";
import { AccountPrincipal, PolicyStatement } from "aws-cdk-lib/aws-iam";

const principalAccountId = "{principalAccountId}";
const eventBus = EventBus.fromEventBusName(this, "DefaultEventBus", "default");

new EventBusPolicy(this, "EventBusPolicy", {
  eventBus,
  statement: new PolicyStatement({
    principals: [new AccountPrincipal(principalAccountId)],
    actions: ["events:PutEvents"],
    resources: [eventBus.eventBusArn],
  }),
  statementId: "AllowSsoEvents",
});

new Rule(this, "ExternalEventsRule", {
  eventPattern: {
    source: ["qzila.sso.api"],
    detailType: ["EmailCodeAuth", "EmailCodeResetPassword"],
  },
  eventBus,
  targets: [], // your target goes here
});

note

The principalAccountId might change based on the environment. Also you might want to use different EventBus than the default one. This is just an example. This ID will be provided to you.

Example event:

{
  "DetailType": "EmailCodeAuth",
  "Detail": "{\"userId\":\"uTpssDxx4dawjBpDZVkqtg\",\"code\":\"123456\",\"expiresAt\":\"2024-02-27T15:47:07.196Z\",\"emailAddress\":\"user@example.com\"}",
  "Source": "qzila.sso.api"
}

note

The Detail contains stringified JSON which can be expressed as following TypeScript interface:

interface EmailAuthCode {
  readonly userId: string;
  readonly code: string;
  readonly expiresAt: string;
  readonly emailAddress: string;
}