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 |
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_TYPEin theapianduiSecrets. The api and api-grpc both load theapiSecret, so they always agree. - Local authentication: set it in your values on all three, as shown in 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. 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.
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.
-
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. -
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
- Allowed Callback URLs:
-
Enable the
Username-Password-Authenticationdatabase connection for that application. Monad creates the users you invite in this connection and sends their password resets through it. -
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:usersFinding an existing user by email when you invite someone create:usersCreating an invited user in the Username-Password-Authenticationconnectionupdate:usersResending the email verification message read:authentication_methodsShowing a user's multi-factor authentication status create:guardian_enrollment_ticketsEnrolling a user in multi-factor authentication create:user_ticketsCreating the set-password link in an invitation email update:users_app_metadata,read:connections,create:connections,update:connections,delete:connectionsGetting a Management API token at all: the api names these and update:userswhen it requests the token, and Auth0 refuses the token if any of them is not granted -
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_metadataclaim and rejects every request whoseemail_verifiedthere is nottrue:CodeDeploy 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:
Code
And the ui Secret's, alongside its AUTH_SECRET:
Code
Amazon Cognito
Set up your user pool
The examples use monad.example.com, the first entry in your hostnames value.
- Use a user pool whose users sign in with an email address. The api rejects every request from a user whose
email_verifiedclaim is nottrue, so users need verified addresses. - Give the pool a domain. With a Cognito domain the URL is
https://<prefix>.auth.<region>.amazoncognito.com. - 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,emailandprofile
- Allowed callback URL:
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.<region>.amazonaws.com/<user-pool-id>/.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.<region>.amazonaws.com/<user-pool-id> |
MONAD_AUTH_COGNITO_DOMAIN | ui | The pool's domain as a URL, used to sign out, such as https://<prefix>.auth.<region>.amazoncognito.com |
As env-file lines, the api Secret's keys:
Code
And the ui Secret's, alongside its AUTH_SECRET:
Code
Local authentication
Local authentication needs no external identity provider. It gives you a single admin user, whose password and second factors Ory Kratos holds. Kratos stores its data in Postgres: the chart's Postgres by default, or your own if you provide the Kratos Secret yourself.
Enable local authentication
-
Keep both Secrets in place without provider keys.
uistill needs itsAUTH_SECRET, andapimust exist even if it is empty. AMONAD_AUTH_TYPEleft in either Secret is overridden by the value below. -
Set
MONAD_AUTH_TYPEtolocalon the api, api-grpc and ui, and turn on Kratos:Code
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. Kratos creates its tables when it starts.
- With the chart's Postgres, a
kratosdatabase and akratosrole 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.
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 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.
-
Turn off generation by adding
secret.generate: falseto thekratosblock from Enable local authentication:Code -
Create a Secret named
monad-kratos-secretsin the release namespace with these keys:Key Value dsnThe Postgres connection URI Kratos uses secretsDefault,secretsCookie,secretsCipherRandom 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, withusername: kratosand thepasswordthedsnuses. CloudNativePG sets thekratosrole's password from it. The chart still creates thekratosdatabase and role, andmonad-db-rwis the Postgres Service:CodeWith 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), and point
dsnat it, such aspostgres://<user>:<password>@<host>:5432/kratos?sslmode=require. Percent-encode the password if it contains characters such as@,:or/. The type,usernameandpasswordare not needed, and the database can be empty:Code
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.
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:
Code
Sign in with them, change the password under User settings, then delete the Secret: Monad does not read it.
Without email, the admin can use only an authenticator app as a second factor. To also allow one-time codes sent by email:
-
Create a Secret holding your SMTP connection URI, percent-encoding the user and password if they contain reserved characters:
Code -
Turn on the courier by adding these keys to your
kratosblock. Mail is sent fromno-reply@monad.localunless you setfrom_address; set it if your SMTP server will not relay that address:Code
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 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.