Application Onboarding (SSO Integration)¶

Connect a new application to Authentik SSO using OIDC, SAML, or the Authentik Proxy provider. All configuration is managed via Ansible playbooks run from the ansible server.

Access Control Model¶

Authentik uses group-based expression policies to control which users can see and access each application. New users have no application access until they are added to the appropriate groups.

User attempts to access app
    ↓
Expression Policy evaluates group membership
    ↓
Pass → Application visible + SSO login allowed
Fail → Application hidden from portal

Policies use policy_engine_mode: "all" — a user must pass every bound policy.

Application Matrix¶

Application	Group	URL	Provider	Admin Group	User Group	SSO Playbook
Dev GitLab	Dev	`https://gitlab.dev.cwiq.io`	OIDC	`dev-gitlab-admins`	`dev-gitlab-users`	`sso/configure-gitlab-sso.yml -e gitlab_environment=dev`
Shared GitLab	Shared	`https://gitlab.shared.cwiq.io`	OIDC	`shared-gitlab-admins`	`shared-gitlab-users`	`sso/configure-gitlab-sso.yml -e gitlab_environment=shared`
Vault	Shared	`https://vault.shared.cwiq.io`	OIDC	`vault-admins`	`vault-users`	`sso/configure-vault-sso.yml`
Grafana	Shared	`https://grafana.shared.cwiq.io`	OIDC	`grafana-admins`	`grafana-users`	`sso/configure-grafana-sso.yml`
Semaphore	Shared	`https://semaphore.shared.cwiq.io`	OIDC	`semaphore-admins`	`semaphore-users`	`sso/configure-semaphore-oidc.yml`
Taiga	Shared	`https://taiga.dev.cwiq.io`	OIDC	`taiga-admins`	`taiga-users`	`sso/configure-taiga-sso.yml`
Icinga	Shared	`https://icinga.dev.cwiq.io`	Proxy	`icinga-admins`	`icinga-users`	`sso/configure-icinga-sso.yml`
SonarQube	Shared	`https://sonarqube.shared.cwiq.io`	Proxy	`sonarqube-admins`	`sonarqube-users`	`sso/configure-sonarqube-sso.yml`
AWS Console	Shared	AWS Identity Center	SAML	—	`aws-users` (or `aws-*`)	`sso/configure-aws-sso.yml`
DefectDojo	Shared	`https://defectdojo.shared.cwiq.io`	SAML	`defectdojo-admins`	`defectdojo-users`	`sso/configure-defectdojo-sso.yml`
ReportPortal	Shared	`https://reportportal.shared.cwiq.io`	SAML	`reportportal-admins`	`reportportal-users`	`sso/configure-reportportal-sso.yml`
Nexus (Shared)	Shared	`https://nexus.shared.cwiq.io`	Proxy	`nexus-admins`	`nexus-users`	`../nexus/configure-authentik-sso.yml`
Nexus (Dev)	Dev	`https://nexus.dev.cwiq.io`	Proxy	`nexus-admins`	`nexus-users`	`../nexus/configure-authentik-sso.yml -e nexus_environment=dev`

OIDC Discovery URLs¶

Application	Discovery URL
Dev GitLab	`https://sso.shared.cwiq.io/application/o/dev-gitlab/.well-known/openid-configuration`
Shared GitLab	`https://sso.shared.cwiq.io/application/o/shared-gitlab/.well-known/openid-configuration`
Vault	`https://sso.shared.cwiq.io/application/o/vault/.well-known/openid-configuration`
Grafana	`https://sso.shared.cwiq.io/application/o/grafana/.well-known/openid-configuration`
Semaphore	`https://sso.shared.cwiq.io/application/o/semaphore/.well-known/openid-configuration`
Taiga	`https://sso.shared.cwiq.io/application/o/taiga/.well-known/openid-configuration`

Connecting a New Application¶

Prerequisites¶

Before running any SSO playbook:

Deploy Authentik (see Architecture)

Application groups and policies must exist — run once:

ansible-playbook -i inventory.ini policies/configure-application-groups.yml
ansible-playbook -i inventory.ini policies/configure-application-policies.yml

Run from Ansible Server¶

All SSO playbooks run from the ansible server via ansible-helper:

ssh ansible@ansible-shared-cwiq-io
ansible-helper
cd authentik

OIDC Applications (GitLab, Vault, Grafana, Semaphore, Taiga)¶

# GitLab (specify environment)
ansible-playbook -i inventory.ini sso/configure-gitlab-sso.yml \
  -e "gitlab_environment=shared"

# Vault
ansible-playbook -i inventory.ini sso/configure-vault-sso.yml

# Grafana
ansible-playbook -i inventory.ini sso/configure-grafana-sso.yml

The playbook outputs the client_id and client_secret. Store these in Vault for the application to use:

vault kv put secret/cwiq/shared/gitlab/oidc \
  client_id="shared-gitlab" \
  client_secret="<output_from_playbook>"

Proxy Provider Applications (Icinga, SonarQube, Nexus)¶

Proxy providers let Authentik sit in front of an application and inject HTTP headers for authentication without the application natively supporting OIDC:

ansible-playbook -i inventory.ini sso/configure-icinga-sso.yml
ansible-playbook -i inventory.ini sso/configure-sonarqube-sso.yml

SAML Applications (AWS Identity Center, DefectDojo, ReportPortal)¶

# AWS Identity Center
ansible-playbook -i inventory.ini sso/configure-aws-sso.yml
ansible-playbook -i inventory.ini sso/configure-aws-scim.yml  # SCIM user sync

# DefectDojo
ansible-playbook -i inventory.ini sso/configure-defectdojo-sso.yml

# ReportPortal
ansible-playbook -i inventory.ini sso/configure-reportportal-sso.yml

Application Groups¶

Applications are organized into portal groups for visibility:

Group	Default For
`Shared`	All shared-environment services (GitLab, Vault, Grafana, etc.)
`Dev`	Dev-environment services (Dev GitLab, Dev Nexus)

group field is mandatory in all API calls

Every Authentik application MUST have the group field set in both CREATE (POST) and UPDATE (PATCH) API calls. Applications without a group appear ungrouped in the portal and are easy to lose.

For environment-aware playbooks, the group derives from the environment variable:

# → group: "Shared"
ansible-playbook sso/configure-gitlab-sso.yml -e gitlab_environment=shared

# → group: "Dev"
ansible-playbook sso/configure-gitlab-sso.yml -e gitlab_environment=dev

# Override for any playbook
ansible-playbook sso/configure-vault-sso.yml -e authentik_app_group=Dev

Granting Application Access to Users¶

After connecting an application, add users to the appropriate groups:

# Grant Vault access
ansible-playbook -i inventory.ini groups/add-user-to-group.yml \
  -e "user_email=john.doe@cwiq.io" \
  -e "group_name=vault-users"

# Grant Shared GitLab access
ansible-playbook -i inventory.ini groups/add-user-to-group.yml \
  -e "user_email=john.doe@cwiq.io" \
  -e "group_name=shared-gitlab-users"

# Grant Grafana admin access
ansible-playbook -i inventory.ini groups/add-user-to-group.yml \
  -e "user_email=john.doe@cwiq.io" \
  -e "group_name=grafana-admins"

Or via Semaphore: User Management > Add User to Group (template 20).

Alternatively, via the Admin UI: Directory > Groups > [group] > Users > Add existing user.

Access Policy Reference¶

Policy	Expression Logic
`dev-gitlab-access-policy`	`dev-gitlab-admins` OR `dev-gitlab-users`
`shared-gitlab-access-policy`	`shared-gitlab-admins` OR `shared-gitlab-users`
`vault-access-policy`	`vault-admins` OR `vault-users`
`grafana-access-policy`	`grafana-admins` OR `grafana-users`
`semaphore-access-policy`	`semaphore-admins` OR `semaphore-users`
`icinga-access-policy`	`icinga-admins` OR `icinga-users`
`aws-access-policy`	`aws-users` OR any `aws-*` group
`sonarqube-access-policy`	`sonarqube-admins` OR `sonarqube-users`
`defectdojo-access-policy`	`defectdojo-admins` OR `defectdojo-users`
`reportportal-access-policy`	`reportportal-admins` OR `reportportal-users`

Troubleshooting¶

User cannot see an application:

Check group membership: Admin UI > Directory > Users > [user] > Groups
Verify the policy is bound: Applications > [app] > Policy/Group/User Bindings
Test the policy: Customization > Policies > [policy] > Test with the user's email

OIDC "Not found" error in GitLab:

# Verify discovery URL is accessible
curl -s https://sso.shared.cwiq.io/application/o/shared-gitlab/.well-known/openid-configuration | jq .issuer

The issuer value must match exactly what GitLab has configured.

Redirect URI mismatch:

The callback URI in GitLab/Vault must be registered in Authentik. Check in: Admin UI > Providers > [provider] > Redirect URIs.

Application existence check in playbooks:

Use direct slug endpoint, not list filter

Authentik 2025.10 has a bug where ?slug= list filters return count: 1 with an empty results array. Always use the direct slug endpoint:

# Correct
url: "https://{{ authentik_hostname }}/api/v3/core/applications/{{ app_slug }}/"
status_code: [200, 404]

# Broken in 2025.10 — do not use
url: "https://{{ authentik_hostname }}/api/v3/core/applications/?slug={{ app_slug }}"

Architecture — HA infrastructure, health endpoints
User Lifecycle — Onboarding new users and assigning groups
MFA — TOTP enforcement across all SSO applications