# Authentication Monad signs users in through one identity provider: Auth0, Amazon Cognito, or local authentication with Ory Kratos running in your cluster. Read this page before you create the `api` and `ui` Secrets, because the provider decides which keys they hold, and local authentication is also turned on in your values. ## Choose a provider | Provider | Where users and passwords live | What you set up | Users | | --- | --- | --- | --- | | Auth0 (the default) | Your Auth0 tenant | An API, applications and an Action in the tenant; keys in the `api` and `ui` Secrets | Any number. Inviting a new email address creates the user in the tenant and emails them a password reset. | | Amazon Cognito | Your Cognito user pool | An app client and a domain on the pool; keys in the `api` and `ui` Secrets | Any number. You create users in the pool, and each signs in once before you can invite them to an organization. | | Local authentication | Kratos in your cluster, which stores its data in Postgres | Values only | One admin; more through [SSO](/docs/sso/index) | `MONAD_AUTH_TYPE` selects the provider: `auth0`, `cognito` or `local`, in lowercase. Unset means `auth0`. The api, api-grpc and ui must all use the same provider: - **Auth0 and Cognito**: put `MONAD_AUTH_TYPE` in the `api` and `ui` Secrets. The api and api-grpc both load the `api` Secret, so they always agree. - **Local authentication**: set it in your values on all three, as shown in [Enable local authentication](#enable-local-authentication). The chart reads it there to check that Kratos is on. Signing in with SAML single sign-on works with Auth0 and local authentication. The console does not offer it with Cognito. The `api` and `ui` Secrets, and how to create them with kubectl or External Secrets Operator, are covered in [The api and ui Secrets](/docs/guides/self-managed/before-you-install#the-api-and-ui-secrets). This page lists the keys each provider adds to them. With External Secrets Operator, each key name below is a `secretKey` in `api.externalsecret.data` or `ui.externalsecret.data`; the chart's default lists hold the Auth0 keys, and a list you set replaces them. :::warning[One provider per env file] If you create the Secrets from env files, copy only your provider's lines. kubectl rejects a file that repeats a key, so a file holding two providers' `MONAD_AUTH_TYPE` fails to create the Secret. ::: ## Auth0 ### Set up your Auth0 tenant The examples use `monad.example.com`, the first entry in your `hostnames` value, and `your-tenant.us.auth0.com` as the tenant domain. 1. **Create an API** for Monad. Its identifier, such as `https://monad.example.com/api`, is the audience in both Secrets. Use the RS256 signing algorithm. 2. **Create a Regular Web Application** for the console, with: - Allowed Callback URLs: `https://monad.example.com/auth/callback/auth0` - Allowed Logout URLs: `https://monad.example.com/login` 3. **Enable the `Username-Password-Authentication` database connection** for that application. Monad creates the users you invite in this connection and sends their password resets through it. 4. **Create a Machine to Machine Application** and authorize it for the Auth0 Management API with every scope below: | Scope | What Monad uses it for | | --- | --- | | `read:users` | Finding an existing user by email when you invite someone | | `create:users` | Creating an invited user in the `Username-Password-Authentication` connection | | `update:users` | Resending the email verification message | | `read:authentication_methods` | Showing a user's multi-factor authentication status | | `create:guardian_enrollment_tickets` | Enrolling a user in multi-factor authentication | | `create:user_tickets` | Creating the set-password link in an invitation email | | `update:users_app_metadata`, `read:connections`, `create:connections`, `update:connections`, `delete:connections` | Getting a Management API token at all: the api names these and `update:users` when it requests the token, and Auth0 refuses the token if any of them is not granted | 5. **Add a post-login Action** that puts the user's email address in the access token. The api reads it from the `https://monad.security.com/app_metadata` claim and rejects every request whose `email_verified` there is not `true`: ```js exports.onExecutePostLogin = async (event, api) => { api.accessToken.setCustomClaim("https://monad.security.com/app_metadata", { email: event.user.email, email_verified: event.user.email_verified, }); }; ``` Deploy the Action and add it to the Login flow. ### Auth0 keys | Key | Secret | Value | | --- | --- | --- | | `MONAD_AUTH_TYPE` | `api` and `ui` | `auth0` | | `MONAD_AUTH_AUTH0_DOMAIN` | `api` | The tenant domain, without `https://`, such as `your-tenant.us.auth0.com` | | `MONAD_AUTH_AUTH0_API_AUDIENCE` | `api` | The API's identifier | | `MONAD_AUTH_AUTH0_API_CLIENT_ID` | `api` | The console application's client ID | | `MONAD_AUTH_AUTH0_MACHINE_CLIENT_ID` | `api` | The Machine to Machine application's client ID | | `MONAD_AUTH_AUTH0_MACHINE_CLIENT_SECRET` | `api` | The Machine to Machine application's client secret | | `MONAD_AUTH_AUTH0_MACHINE_AUDIENCE` | `api` | The Management API's identifier, `https://your-tenant.us.auth0.com/api/v2/` | | `AUTH_AUTH0_ISSUER` | `ui` | The tenant URL with no trailing slash, such as `https://your-tenant.us.auth0.com` | | `AUTH_AUTH0_CLIENT_ID` | `ui` | The console application's client ID | | `AUTH_AUTH0_CLIENT_SECRET` | `ui` | The console application's client secret | | `AUTH_AUTH0_API_AUDIENCE` | `ui` | The API's identifier | The api and api-grpc do not start while any of the `api` Secret's Auth0 keys is missing. As env-file lines, the `api` Secret's keys: ```bash MONAD_AUTH_TYPE=auth0 MONAD_AUTH_AUTH0_DOMAIN= MONAD_AUTH_AUTH0_API_AUDIENCE= MONAD_AUTH_AUTH0_API_CLIENT_ID= MONAD_AUTH_AUTH0_MACHINE_CLIENT_ID= MONAD_AUTH_AUTH0_MACHINE_CLIENT_SECRET= MONAD_AUTH_AUTH0_MACHINE_AUDIENCE=https:///api/v2/ ``` And the `ui` Secret's, alongside its `AUTH_SECRET`: ```bash MONAD_AUTH_TYPE=auth0 AUTH_AUTH0_ISSUER=https:// AUTH_AUTH0_CLIENT_ID= AUTH_AUTH0_CLIENT_SECRET= AUTH_AUTH0_API_AUDIENCE= ``` ## Amazon Cognito ### Set up your user pool The examples use `monad.example.com`, the first entry in your `hostnames` value. 1. **Use a user pool whose users sign in with an email address.** The api rejects every request from a user whose `email_verified` claim is not `true`, so users need verified addresses. 2. **Give the pool a domain.** With a Cognito domain the URL is `https://.auth..amazoncognito.com`. 3. **Create an app client with a client secret**, with: - Allowed callback URL: `https://monad.example.com/auth/callback/cognito` - Allowed sign-out URL: `https://monad.example.com/login` - OAuth grant type: authorization code - OpenID Connect scopes: `openid`, `email` and `profile` The console signs in with the app client and sends its ID token to the api, which accepts only tokens issued to that client by that pool. The api downloads the pool's signing keys from `https://cognito-idp..amazonaws.com//.well-known/jwks.json` when it starts and does not start without them, so it needs outbound access to that address. ### Cognito keys | Key | Secret | Value | | --- | --- | --- | | `MONAD_AUTH_TYPE` | `api` and `ui` | `cognito` | | `MONAD_AUTH_COGNITO_AWS_REGION` | `api` | The pool's region, such as `us-east-1` | | `MONAD_AUTH_COGNITO_USER_POOL_ID` | `api` | The pool ID | | `MONAD_AUTH_COGNITO_CLIENT_ID` | `api` and `ui` | The app client ID, the same in both | | `MONAD_AUTH_COGNITO_DOMAIN` | `api` | The domain prefix. Only the api's `/api/v1/login` development endpoint uses it, but the api and api-grpc do not start without it. | | `MONAD_AUTH_COGNITO_SECRET` | `ui` | The app client secret | | `MONAD_AUTH_COGNITO_ISSUER_URL` | `ui` | `https://cognito-idp..amazonaws.com/` | | `MONAD_AUTH_COGNITO_DOMAIN` | `ui` | The pool's domain as a URL, used to sign out, such as `https://.auth..amazoncognito.com` | As env-file lines, the `api` Secret's keys: ```bash MONAD_AUTH_TYPE=cognito MONAD_AUTH_COGNITO_AWS_REGION= MONAD_AUTH_COGNITO_USER_POOL_ID= MONAD_AUTH_COGNITO_CLIENT_ID= MONAD_AUTH_COGNITO_DOMAIN= ``` And the `ui` Secret's, alongside its `AUTH_SECRET`: ```bash MONAD_AUTH_TYPE=cognito MONAD_AUTH_COGNITO_CLIENT_ID= MONAD_AUTH_COGNITO_SECRET= MONAD_AUTH_COGNITO_ISSUER_URL=https://cognito-idp..amazonaws.com/ MONAD_AUTH_COGNITO_DOMAIN=https://.auth..amazoncognito.com ``` ## Local authentication Local authentication needs no external identity provider. It gives you a single admin user, whose password and second factors [Ory Kratos](https://www.ory.sh/kratos/) holds. Kratos stores its data in Postgres: the chart's Postgres by default, or your own if you [provide the Kratos Secret yourself](#provide-the-kratos-secret-yourself). ### Enable local authentication 1. Keep both Secrets in place without provider keys. `ui` still needs its `AUTH_SECRET`, and `api` must exist even if it is empty. A `MONAD_AUTH_TYPE` left in either Secret is overridden by the value below. 2. Set `MONAD_AUTH_TYPE` to `local` on the api, api-grpc and ui, and turn on Kratos: ```yaml api: env: MONAD_AUTH_TYPE: value: local api-grpc: env: MONAD_AUTH_TYPE: value: local ui: env: MONAD_AUTH_TYPE: value: local kratos: enabled: true ``` The chart fails to render when the api's `MONAD_AUTH_TYPE` is `local` without `kratos.enabled: true`, or the other way round. It does not check api-grpc or ui, so set all three: api-grpc falls back to Auth0 when the variable is unset and does not start without Auth0 keys. The install notes print a warning when api-grpc or ui is not set to `local`. If your values already have an `api`, `api-grpc` or `ui` block, add `env.MONAD_AUTH_TYPE` to it rather than repeating the key: a repeated top-level key replaces the earlier one without an error. ### What it deploys - A Kratos Deployment, plus a courier StatefulSet when you turn on [email](#email). Kratos creates its tables when it starts. - With the chart's Postgres, a `kratos` database and a `kratos` role that owns it. - A Secret named `monad-kratos-secrets`, holding the Kratos database password and connection string and its cookie and cipher secrets, unless you [provide it yourself](#provide-the-kratos-secret-yourself). When you deploy with `helm install`/`helm upgrade` or the Flux helm-controller, the chart generates `monad-kratos-secrets` once and keeps it across upgrades and uninstalls. Do not delete it: the next upgrade would generate new values. Tools that render with `helm template`, such as Argo CD, cannot keep it: every render generates new values, which rotates the Kratos database password and the cookie and cipher secrets. With those tools, provide the Secret yourself. The Kratos Services are reachable only inside the cluster. Kratos sets no resource requests by default; see [Resources](/docs/guides/self-managed/scheduling#resources) for `kratos.deployment.resources`. ### Provide the Kratos Secret yourself Provide the Secret yourself when you deploy with a tool that renders with `helm template`, such as Argo CD, or when Kratos uses your own Postgres. The chart cannot generate it for your own Postgres and fails to render if you try. 1. Turn off generation by adding `secret.generate: false` to the `kratos` block from [Enable local authentication](#enable-local-authentication): ```yaml kratos: enabled: true secret: generate: false ``` 2. Create a Secret named `monad-kratos-secrets` in the release namespace with these keys: | Key | Value | | --- | --- | | `dsn` | The Postgres connection URI Kratos uses | | `secretsDefault`, `secretsCookie`, `secretsCipher` | Random 32-character strings Kratos signs and encrypts with. Generate them once and keep them. | **With the chart's Postgres**, the Secret must also be of type `kubernetes.io/basic-auth`, with `username: kratos` and the `password` the `dsn` uses. CloudNativePG sets the `kratos` role's password from it. The chart still creates the `kratos` database and role, and `monad-db-rw` is the Postgres Service: ```bash KRATOS_DB_PASSWORD="$(openssl rand -hex 16)" kubectl create secret generic monad-kratos-secrets -n monad \ --type=kubernetes.io/basic-auth \ --from-literal=username=kratos \ --from-literal=password="$KRATOS_DB_PASSWORD" \ --from-literal=dsn="postgres://kratos:${KRATOS_DB_PASSWORD}@monad-db-rw/kratos?sslmode=prefer" \ --from-literal=secretsDefault="$(openssl rand -hex 16)" \ --from-literal=secretsCookie="$(openssl rand -hex 16)" \ --from-literal=secretsCipher="$(openssl rand -hex 16)" ``` **With your own Postgres**, the chart creates no database or role. Create a database for Kratos and a user that owns it ([Kratos on your own Postgres](/docs/guides/self-managed/database#kratos-on-your-own-postgres)), and point `dsn` at it, such as `postgres://:@:5432/kratos?sslmode=require`. Percent-encode the password if it contains characters such as `@`, `:` or `/`. The type, `username` and `password` are not needed, and the database can be empty: ```bash kubectl create secret generic monad-kratos-secrets -n monad \ --from-literal=dsn='postgres://:@:5432/kratos?sslmode=require' \ --from-literal=secretsDefault="$(openssl rand -hex 16)" \ --from-literal=secretsCookie="$(openssl rand -hex 16)" \ --from-literal=secretsCipher="$(openssl rand -hex 16)" ``` If you sync the Secret with External Secrets Operator, keep the values in your secrets manager and set the type with the ExternalSecret's `target.template.type`. The chart's `examples/local-auth-external-postgres.yaml` combines local authentication, your own Postgres and a Kratos Secret you provide; see [Get the chart and its examples](/docs/guides/self-managed/install#get-the-chart-and-its-examples). ### First sign-in After the install completes, open the Monad console. The login page sends you to **Create the admin account**. Enter an email address and a password of 8 to 72 characters, then sign in with them on the login page. The setup page is available only until the admin exists; after that it sends you back to the login page. ### Installs that already have an admin An install first created with chart 2.94.0 or earlier already has its admin and skips setup. The admin's email is `admin@monad.local`, and the `app-bootstrap-admin` Secret holds the generated `username` and `password`: ```bash kubectl get secret app-bootstrap-admin -n monad -o jsonpath='{.data.password}' | base64 -d ``` Sign in with them, change the password under **User settings**, then delete the Secret: Monad does not read it. ### Email Without email, the admin can use only an authenticator app as a second factor. To also allow one-time codes sent by email: 1. Create a Secret holding your SMTP connection URI, percent-encoding the user and password if they contain reserved characters: ```bash kubectl create secret generic monad-kratos-smtp -n monad \ --from-literal=connectionURI='smtps://:@mail.example.com:465/' ``` 2. Turn on the courier by adding these keys to your `kratos` block. Mail is sent from `no-reply@monad.local` unless you set `from_address`; set it if your SMTP server will not relay that address: ```yaml kratos: enabled: true courier: enabled: true kratos: config: courier: smtp: from_address: no-reply@example.com ``` Codes are sent to the admin's login email. ### Multi-factor authentication Sign in as the admin and open **User settings** from the user menu. The **Password** section changes the admin password. The **Multi-factor authentication** section enrolls an authenticator app (scan the QR code and enter the code it shows) and, if you turned on [email](#email), email codes. After enrolling, select **Regenerate** in the **Recovery codes** row, enter your password, and save the codes. They are not shown again. Once MFA is on, login asks for a code after the password. You can enter a recovery code instead. ### Additional users Local authentication has only the admin user; you cannot invite others. For more users, sign in as the admin and set up SSO under **Single Sign-On** in the organization settings. See [SSO](/docs/sso/index).