Organisation authentication provider setup

Organisation authentication lets each organisation route sign-in through its own identity source while TOW still keeps ownership of memberships, roles, project access, and permissions.

The architecture is:

TOW organisation login
  -> authentik OIDC provider for that organisation
    -> organisation identity source
       Google Workspace, Microsoft Entra ID, Okta, LDAP, SAML, or OIDC

TOW never connects directly to Google, Microsoft, Okta, LDAP, or SAML. TOW talks to authentik over OIDC. authentik talks to the upstream identity provider.

Before you start

Ask the server admin to confirm these deployment prerequisites:

• Server authentication mode is oidc.
• auth.organization_auth.enabled is true.
• ORG_AUTH_SECRET_KEY is set so organisation secrets can be encrypted at rest.
• AUTHENTIK_PUBLIC_URL and AUTHENTIK_BOOTSTRAP_TOKEN are configured.
• The TOW public URL is stable and uses HTTPS.
• The organisation auth source type you want is allowed by server policy.

Then open:

Settings -> Organisation -> Authentication

Only organisation owners and admins can edit organisation authentication. Server admins can also open the related authentik administration page when deeper authentik troubleshooting is needed.

The setup order

Use this order for every provider:

1. Pick the identity source preset in TOW.
2. Fill the provider details in TOW.
3. Save changes.
4. Click Sync now to create or update the organisation-specific TOW application/provider in authentik.
5. Configure the upstream provider to trust authentik.
6. Click Test in TOW.
7. Invite a pilot user from that organisation and test login.
8. Enable verified-domain routing only after the domain is verified.

warning

Do not paste upstream secrets into tickets, chat, screenshots, docs, or support bundles. Client secrets, LDAP bind passwords, SAML private keys, and tokens are write-only in TOW. Leaving a secret field blank keeps the existing encrypted value.

info

Sync now handles the TOW-facing authentik application/provider for this organisation. The upstream identity provider still has to be configured in its own admin console, and some deployments may require a server admin to mirror the saved source values into the matching authentik Source until source automation is enabled for that environment.

Callback and redirect URLs

There are two different callback URLs. Mixing them up is the most common setup failure.

URL	Used by	Purpose
TOW OIDC callback	authentik's TOW OAuth2/OIDC provider	Sends the user back from authentik to TOW. Usually {PUBLIC_APP_URL}/api/auth/oidc/callback. The TOW sync step manages this.
TOW post-logout redirect	authentik's TOW OAuth2/OIDC provider	Sends the user back to TOW after provider logout when enabled. Usually {PUBLIC_APP_URL}/login?logged_out=1. The TOW sync step manages this.
authentik source callback or ACS URL	Google, Okta, Microsoft Entra ID, or another upstream IdP	Sends the user from the upstream provider back to authentik. Copy this from the authentik Source screen, or ask a server admin for it if your TOW deployment does not show it yet.

For upstream OIDC providers such as Google Workspace or Okta OIDC, register the authentik OAuth Source callback URL in the upstream provider.

For upstream SAML providers such as Microsoft Entra ID or Okta SAML, register the authentik SAML Source ACS URL and Entity ID in the upstream provider.

Field reference

These are the fields organisation admins see in TOW and where the values come from.

TOW field	Use it for	Where to get it
Source type	Selects LDAP, SAML, or upstream OIDC.	Pick the preset that matches the organisation's identity system.
Slug	Stable login route, for example /login?org=acme.	Usually the organisation name in lowercase letters, numbers, and dashes.
Allowed email domains	Domains that can route to this organisation after verification.	The organisation's email domains, for example acme.example.
Require verified email	Rejects OIDC users unless the IdP marks email as verified.	Enable for Google Workspace and most OIDC providers that supply email_verified.
MFA required	Records that this organisation requires an extra factor.	Organisation security policy. Confirm the matching authentik flow or policy enforces it before rollout.
Passkeys required	Records that this organisation requires passkey-capable authentication.	Organisation security policy. Confirm the matching authentik flow or policy enforces it before rollout.
Client ID	Public identifier for an upstream OIDC client.	Created in Google Cloud, Okta, or another OIDC provider.
Client secret	Secret for the upstream OIDC client.	Shown by the upstream OIDC provider when the client is created or rotated.
Issuer URL	Canonical OIDC issuer.	Provider docs or discovery document.
Discovery URL	OIDC .well-known/openid-configuration URL.	Provider docs. Often {issuer}/.well-known/openid-configuration.
Scopes	OIDC claims authentik requests.	Usually openid profile email. Add groups only when the provider supports it.
Metadata URL	SAML IdP metadata document.	The upstream SAML app's metadata URL or metadata XML download page.
Directory URL	LDAP or LDAPS endpoint.	Active Directory or LDAP admin, for example ldaps://dc01.example.local:636.
Bind DN	LDAP service account used for searches.	Directory admin, usually the service account's distinguished name.
Bind password	Password for the LDAP service account.	Directory admin or password vault.
User base DN	LDAP subtree containing users.	Directory admin, for example OU=Users,DC=example,DC=local.
Group base DN	LDAP subtree containing groups.	Directory admin, for example OU=Groups,DC=example,DC=local.

Google Workspace

Use Google Workspace as an upstream OIDC provider.

What you need from Google

• OAuth client ID.
• OAuth client secret.
• Google issuer and discovery URL.
• The authorised redirect URI, which must be the authentik OAuth Source callback URL.

Create the Google OAuth client

1. Sign in to the Google Cloud console with a Google Workspace admin or a user allowed to create OAuth clients.
2. Select an existing project or create a new project for TOW authentication.
3. Open Google Auth Platform or APIs & Services -> Credentials.
4. Configure the app branding and audience. For most Workspace-only deployments, choose an internal audience when Google allows it.
5. Open Clients and create an OAuth client.
6. Select Web application.
7. Name it something clear, for example TOW authentik source.
8. Add the authentik OAuth Source callback URL as an Authorized redirect URI.
9. Create the client.
10. Copy the Client ID and Client secret immediately. Google may only show the full secret when it is created.

Google's own docs for this flow are Manage OAuth Clients and OpenID Connect with Google.

Fill TOW

Choose the Google Workspace preset.

TOW field	Value
Source type	Upstream OIDC
Issuer URL	https://accounts.google.com
Discovery URL	https://accounts.google.com/.well-known/openid-configuration
Client ID	Google OAuth client ID
Client secret	Google OAuth client secret
Scopes	openid profile email
Email claim	email
Username claim	email
First name claim	given_name
Last name claim	family_name
Groups claim	hd
Require verified email	Enabled

hd is Google's hosted-domain claim. It is useful for audit and future mapping, but TOW does not auto-grant roles from it.

Test

1. Save changes in TOW.
2. Click Sync now.
3. Click Test.
4. Invite a Google Workspace user whose email matches the organisation invite.
5. Open the invite link in a private browser window and confirm the user lands in the correct organisation.

If Google shows redirect_uri_mismatch, the redirect URI registered in Google does not exactly match the authentik source callback URL.

Microsoft Entra ID

Use Microsoft Entra ID as an upstream SAML provider. This is the recommended Microsoft setup for most organisation-owned enterprise SSO.

What you need from Microsoft

• App Federation Metadata URL, or downloaded federation metadata XML.
• SAML signing certificate, if you cannot use metadata URL.
• The SAML attributes Microsoft sends for email, name, and groups.
• The authentik SAML Source ACS URL and Entity ID to enter in Microsoft.

Create the Enterprise Application

1. Sign in to the Microsoft Entra admin center.
2. Open Identity -> Applications -> Enterprise applications.
3. Create a new application.
4. Choose Create your own application if TOW is not in the gallery.
5. Name it, for example TOW authentik source.
6. Open Single sign-on.
7. Choose SAML.
8. In Basic SAML Configuration, enter the authentik SAML Source values:
   • Identifier (Entity ID): authentik SAML Source Entity ID.
   • Reply URL (Assertion Consumer Service URL): authentik SAML Source ACS URL.
   • Sign on URL: the TOW public URL or authentik launch URL supplied by your server admin.
9. In Attributes & Claims, confirm Microsoft sends email, given name, surname, and optionally groups.
10. In SAML Certificates, copy the App Federation Metadata Url.
11. Assign the application to the users or groups allowed to sign in.

Microsoft's setup docs are Enable SAML single sign-on for an enterprise application and SAML-based single sign-on: configuration and limitations.

Fill TOW

Choose the Microsoft Entra ID preset.

TOW field	Value
Source type	SAML
Metadata URL	The App Federation Metadata Url from Microsoft
Require signed assertions	Enabled
Email attribute	http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
Username attribute	http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
First name attribute	http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
Last name attribute	http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
Groups attribute	http://schemas.microsoft.com/ws/2008/06/identity/claims/groups

Test

1. Save changes in TOW.
2. Click Sync now.
3. Click Test. TOW checks that the metadata URL is reachable and structurally valid.
4. Use Microsoft's Test single sign-on action.
5. Invite a pilot user who is assigned to the Microsoft Enterprise Application.
6. Confirm the invite login creates or links only that organisation membership.

If the user authenticates in Microsoft but returns without an email, fix Attributes & Claims first. TOW requires a usable email for invite matching and account linking.

Okta

Okta can be configured with SAML or OIDC. Use SAML when you want the simplest enterprise setup. Use OIDC when your Okta tenant already standardises on OIDC app integrations.

Okta SAML

What you need from Okta

• Okta app metadata URL.
• SAML attributes for email, login, first name, last name, and groups.
• The authentik SAML Source ACS URL and Entity ID.

Create the Okta SAML app

1. Sign in to the Okta Admin Console.
2. Open Applications -> Applications.
3. Click Create App Integration.
4. Select SAML 2.0.
5. Name the app, for example TOW authentik source.
6. In SAML Settings, enter:
   • Single sign-on URL: authentik SAML Source ACS URL.
   • Audience URI (SP Entity ID): authentik SAML Source Entity ID.
7. Add Attribute Statements:
   • email -> user.email
   • login -> user.login
   • firstName -> user.firstName
   • lastName -> user.lastName
8. Add a Group Attribute Statement named groups if you want group names recorded for future mapping.
9. Finish the wizard.
10. Assign the app to the allowed users or groups.
11. Open the app's Sign On tab and copy the metadata URL from the SAML metadata details.

Okta's own docs are Create SAML app integrations and the SAML field reference.

Fill TOW

Choose the Okta preset.

TOW field	Value
Source type	SAML
Metadata URL	Okta app metadata URL, often https://your-org.okta.com/app/<app-id>/sso/saml/metadata
Require signed assertions	Enabled
Email attribute	email
Username attribute	login
First name attribute	firstName
Last name attribute	lastName
Groups attribute	groups

Okta OIDC

What you need from Okta

• Okta issuer URL.
• Okta discovery URL.
• Client ID.
• Client secret.
• The authentik OAuth Source callback URL.

Create the Okta OIDC app

1. Sign in to the Okta Admin Console.
2. Open Applications -> Applications.
3. Click Create App Integration.
4. Select OIDC - OpenID Connect.
5. Choose Web Application.
6. Use Authorization Code flow.
7. Add the authentik OAuth Source callback URL as the sign-in redirect URI.
8. Save the app.
9. Copy the generated Client ID and Client secret.
10. Confirm the issuer. Many Okta tenants use:

https://your-org.okta.com/oauth2/default

Some tenants use a custom authorization server. Use the issuer that matches the authorization server assigned to this app.

Okta's own docs are Create OpenID Connect app integrations and Manage secrets and keys for OIDC app client authentication.

Fill TOW

Use the Generic OIDC preset, then enter Okta values.

TOW field	Value
Source type	Upstream OIDC
Issuer URL	https://your-org.okta.com/oauth2/default or your custom authorization server issuer
Discovery URL	{issuer}/.well-known/openid-configuration
Client ID	Okta OIDC app Client ID
Client secret	Okta OIDC app Client secret
Scopes	openid profile email groups if groups are enabled, otherwise openid profile email
Email claim	email
Username claim	preferred_username or email
First name claim	given_name
Last name claim	family_name
Groups claim	groups
Require verified email	Enabled when Okta sends email_verified

Active Directory or LDAP

Use LDAP when the organisation has on-prem Active Directory, OpenLDAP, or another LDAP-compatible directory.

What you need from the directory admin

• Directory hostname and port.
• TLS mode: LDAPS, StartTLS, or none for a private test network only.
• Read-only bind service account.
• Bind DN or bind username accepted by the directory.
• Bind password.
• User base DN.
• Group base DN.
• LDAP filters.
• Attribute names.
• Private CA certificate, if LDAPS or StartTLS uses an internal CA.

Prepare Active Directory

1. Create a dedicated read-only service account, for example svc-tow-auth.
2. Do not use a Domain Admin account.
3. Give the service account permission to read the user and group OUs used for login.
4. Prefer LDAPS on port 636. Use StartTLS on port 389 only when your directory policy requires it.
5. Export the issuing CA certificate if the domain controller uses an internal certificate authority.
6. Confirm the distinguished names for the user and group OUs.

Fill TOW

Choose the Active Directory preset.

TOW field	Example
Source type	LDAP / Active Directory
Directory URL	ldaps://dc01.example.local:636
TLS mode	LDAPS
Bind DN	CN=svc-tow-auth,OU=Service Accounts,DC=example,DC=local
Bind password	Service account password
User base DN	OU=Users,DC=example,DC=local
User filter	(&(objectClass=person)(mail=*))
Group base DN	OU=Groups,DC=example,DC=local
Group filter	(objectClass=group)
Username	sAMAccountName
Email	mail
First name	givenName
Last name	sn
CA certificate	PEM root or intermediate CA, if needed

If the organisation wants to allow only members of a specific AD group, ask the AD admin for that group's distinguished name and use a stricter user filter. Example:

(&(objectClass=person)(mail=*)(memberOf=CN=TOW Users,OU=Groups,DC=example,DC=local))

authentik's LDAP details are documented in LDAP Source.

Test

1. Save changes in TOW.
2. Click Test. TOW checks that the LDAP endpoint is reachable.
3. Click Sync now.
4. Ask the server admin to confirm authentik can bind and search if the test passes but users cannot log in.
5. Invite a pilot AD user whose mail attribute matches the invite.

If LDAPS fails, confirm DNS, port 636, firewall rules, certificate trust, and that the directory URL does not include credentials.

Generic SAML

Use Generic SAML when the provider is not Microsoft Entra ID or Okta, or when the organisation uses ADFS, PingFederate, OneLogin, Shibboleth, or another SAML IdP.

Ask the IdP admin for

• IdP metadata URL, or metadata XML file.
• Entity ID.
• SSO URL.
• Signing certificate.
• Whether assertions are signed.
• Email attribute name.
• Username attribute name.
• First name and last name attribute names.
• Groups attribute name, if group names are sent.

Give the IdP admin

• authentik SAML Source Entity ID.
• authentik SAML Source ACS URL.
• Requested NameID format, usually email address.
• Required attributes: email, username, first name, last name.

Fill TOW

Choose the Generic SAML 2.0 preset.

TOW field	Value
Source type	SAML
Metadata URL	IdP metadata URL
Require signed assertions	Enabled unless the IdP truly cannot sign assertions
Email attribute	IdP email attribute, often email or a URI claim
Username attribute	Stable username or email attribute
First name attribute	IdP first name attribute
Last name attribute	IdP last name attribute
Groups attribute	Group attribute, if provided

Use authentik's SAML Source guide as the protocol reference.

Generic OIDC

Use Generic OIDC for identity providers that support OpenID Connect discovery.

Ask the IdP admin for

• Issuer URL.
• Discovery URL.
• Client ID.
• Client secret.
• Supported scopes.
• Email, username, first name, last name, and groups claim names.
• Whether email_verified is trustworthy.

Give the IdP admin

• authentik OAuth Source callback URL.
• Client type: confidential web application.
• Flow: authorization code.
• PKCE: enabled when available.
• Redirect URI: exactly the authentik OAuth Source callback URL.

Fill TOW

Choose the Generic OIDC preset.

TOW field	Value
Source type	Upstream OIDC
Issuer URL	The provider's issuer URL
Discovery URL	Usually {issuer}/.well-known/openid-configuration
Client ID	Provider-issued Client ID
Client secret	Provider-issued Client secret
Scopes	Usually openid profile email
Email claim	Usually email
Username claim	Usually preferred_username, email, or sub
First name claim	Usually given_name
Last name claim	Usually family_name
Groups claim	Usually groups, if supported
Require verified email	Enable only if the provider sends a reliable email_verified claim

Use authentik's OAuth Source guide and the OpenID Connect Discovery specification as references.

Login routing

TOW can route users to the right organisation authentication config in three ways.

Route	When to use it
Invite link	Best first test. The invite determines the organisation.
/login?org=<slug>	Good for organisation bookmarks and help desk instructions.
Email domain discovery	Good for mature setups after domain verification.

Domain routing is intentionally disabled until the domain is verified. If two organisations claim the same verified domain, routing fails closed instead of guessing.

Domain verification

1. Add the organisation email domain in TOW, for example example.com.
2. Save changes.
3. Copy the verification token shown next to the domain.
4. Create the requested DNS TXT record with your DNS provider.
5. Ask a server admin to verify or approve the domain if automatic DNS verification is not enabled in your deployment.
6. Use domain-based routing only after the domain is marked verified in TOW.

Until then, use invite links or /login?org=<slug>.

Final validation checklist

Before telling the whole organisation to switch over:

• The source config is saved.
• The per-organisation authentik app/provider is synced.
• The upstream provider has the correct authentik callback or ACS URL.
• The upstream client secret or LDAP bind password is stored in TOW as a write-only secret.
• TOW Test passes.
• A pilot invite login works in a private browser window.
• Logout returns to the TOW-owned UI, or redirects through provider logout first when that option is enabled.
• A user without an invite or existing linked identity is rejected.
• The organisation domain is verified before domain routing is enabled.
• MFA and passkey requirements are enforced by the organisation's authentik flow when those options are enabled.
• At least one organisation owner can still sign in.

Troubleshooting

Symptom	Likely cause	Fix
redirect_uri_mismatch from Google or Okta	Upstream OIDC client has the wrong redirect URI.	Register the authentik OAuth Source callback URL exactly.
User signs into IdP but TOW rejects them	No valid invite or existing linked identity.	Send an invite to the exact email claim returned by the provider.
TOW says email is not verified	Require verified email is enabled but the provider does not send email_verified: true.	Fix provider claims or disable the requirement only if policy allows it.
SAML metadata test fails	Metadata URL is private, blocked, or not XML metadata.	Use a reachable metadata URL or ask the IdP admin for the correct federation metadata.
SAML login succeeds but names are blank	Attribute names do not match what the IdP sends.	Inspect the SAML assertion in the IdP test tool and update mapping fields.
LDAP test cannot connect	DNS, firewall, port, or TLS issue.	Confirm network path from the TOW backend/authentik network to the directory host.
LDAP bind works but no users can login	Base DN or filter excludes them.	Broaden the filter temporarily, then tighten it after the correct OU/group is confirmed.
Groups appear but roles do not change	TOW stores groups for audit and future mapping, but does not auto-grant roles from groups yet.	Assign TOW roles and project access inside TOW.

When in doubt, test with a single pilot user and a short-lived invite before opening the provider to a whole organisation.