External Identity Provider Integration¶

This guide explains how to connect AKKO to your organization's existing identity provider (IdP). AKKO uses Keycloak as its identity broker, which supports virtually any OIDC or LDAP-based IdP out of the box.

Overview¶

By default, AKKO ships in demo mode with a bundled directory service directory and pre-configured users. In production, you will want to connect your corporate identity system instead. AKKO supports three integration patterns:

Pattern	IdP Type	Keycloak Feature	Use Case
Identity Brokering	Azure AD, Okta, Google	Identity Providers (OIDC)	Cloud-native SSO
User Federation	Active Directory, OpenLDAP	User Federation (LDAP)	On-premises directory
SAML Brokering	Any SAML 2.0 IdP	Identity Providers (SAML)	Legacy enterprise SSO

All patterns result in users appearing in Keycloak with AKKO roles, enabling seamless SSO across all 33+ platform services.

Switching to Enterprise Mode¶

Set the deployment mode in your values file:

# values-enterprise.yaml (or values-production.yaml)
global:
  auth:
    mode: "enterprise"

    # Bootstrap admin created before federation is active
    initialAdmin:
      enabled: true
      username: "admin-akko"
      email: "admin@corp.example.com"

# Disable the bundled directory service — your corporate IdP replaces it
akko-lldap:
  enabled: false

See helm/examples/values-enterprise.yaml for a complete working example.

1. Azure AD / Entra ID (OIDC Brokering)¶

Step 1: Create an App Registration in Azure¶

Go to Azure Portal > Microsoft Entra ID > App registrations > New registration
Configure:
Name: AKKO Platform
Supported account types: Single tenant (your org only)
Redirect URI: https://keycloak.<your-domain>/realms/akko/broker/azure-ad/endpoint
After creation, note the Application (client) ID and Directory (tenant) ID
Go to Certificates & secrets > New client secret and note the Value
Go to API permissions > Add a permission > Microsoft Graph:
openid, profile, email, User.Read
Optional: GroupMember.Read.All (for group sync)
Click Grant admin consent

Step 2: Configure Token Claims¶

Go to Token configuration > Add groups claim:

Select Security groups
For the ID token, choose Group ID

This ensures Azure AD group memberships are included in the OIDC token.

Step 3: Configure Keycloak¶

Log in to Keycloak Admin at https://keycloak.<your-domain>/admin
Select the akko realm
Go to Identity Providers > Add provider > OpenID Connect v1.0
Configure:

Field	Value
Alias	`azure-ad`
Display Name	`Sign in with Microsoft`
Discovery Endpoint	`https://login.microsoftonline.com/<TENANT_ID>/v2.0/.well-known/openid-configuration`
Client ID	`<APPLICATION_CLIENT_ID>`
Client Secret	`<CLIENT_SECRET_VALUE>`
Default Scopes	`openid profile email`
Sync Mode	`force`
Trust Email	`On`

Click Save

Step 4: Map Azure AD Groups to AKKO Roles¶

Under the identity provider configuration, go to Mappers > Add mapper:

Field	Value
Name	`azure-group-role-mapper`
Mapper Type	`Claim to Role`
Claim	`groups`
Claim Value	`<AZURE_GROUP_OBJECT_ID>` (e.g., the ID of "Data-Engineers")
Role	`akko-engineer`

Repeat for each Azure AD group you want to map:

Azure AD Group	AKKO Role	Description
IT-Admins	`akko-admin`	Platform administrators
Data-Engineers	`akko-engineer`	Data engineers
Business-Analysts	`akko-analyst`	Business analysts
Compliance-Team	`akko-user`	Data stewards
Management	`akko-viewer`	Read-only access

Automation with values-enterprise.yaml

The global.auth.ldap.roleMapping values are designed for LDAP federation. For OIDC brokering, group-to-role mapping is configured in the Keycloak Admin UI or via the Admin REST API. Consider scripting this setup using the same pattern as configure-federation.sh.

2. Okta (OIDC Brokering)¶

Step 1: Create an Okta Application¶

In Okta Admin Console, go to Applications > Create App Integration
Choose OIDC - OpenID Connect and Web Application
Configure:
App integration name: AKKO Platform
Grant type: Authorization Code
Sign-in redirect URI: https://keycloak.<your-domain>/realms/akko/broker/okta/endpoint
Sign-out redirect URI: https://keycloak.<your-domain>/realms/akko/broker/okta/endpoint/logout_response
Under Assignments, assign the users or groups that should access AKKO
Note the Client ID and Client Secret

Step 2: Configure Keycloak¶

Go to Identity Providers > Add provider > OpenID Connect v1.0
Configure:

Field	Value
Alias	`okta`
Display Name	`Sign in with Okta`
Discovery Endpoint	`https://<your-org>.okta.com/.well-known/openid-configuration`
Client ID	`<OKTA_CLIENT_ID>`
Client Secret	`<OKTA_CLIENT_SECRET>`
Default Scopes	`openid profile email groups`
Sync Mode	`force`
Trust Email	`On`

Click Save

Step 3: Map Okta Groups to AKKO Roles¶

Add claim-to-role mappers exactly as described in the Azure AD section above, using the groups claim. Okta includes group names (not IDs) by default, so you can match on group names directly:

Claim Value	AKKO Role
`Platform-Admins`	`akko-admin`
`Data-Engineers`	`akko-engineer`
`Analysts`	`akko-analyst`
`Viewers`	`akko-viewer`

3. Google Workspace (OIDC Brokering)¶

Step 1: Create OAuth Credentials in Google Cloud¶

Go to Google Cloud Console > APIs & Services > Credentials
Click Create Credentials > OAuth 2.0 Client ID
Configure:
Application type: Web application
Authorized redirect URI: https://keycloak.<your-domain>/realms/akko/broker/google/endpoint
Note the Client ID and Client Secret
Enable the Admin SDK API if you need group sync

Step 2: Configure Keycloak¶

Keycloak has a built-in Google provider:

Go to Identity Providers > Add provider > Google
Configure:

Field	Value
Client ID	`<GOOGLE_CLIENT_ID>`
Client Secret	`<GOOGLE_CLIENT_SECRET>`
Default Scopes	`openid profile email`
Trust Email	`On`
Hosted Domain	`your-company.com` (restricts to your org)

Click Save

Step 3: Map Google Groups to AKKO Roles¶

Google Workspace does not include groups in OIDC tokens by default. You have two options:

Option A: Google Groups mapper (Keycloak extension)

Install the keycloak-google-groups extension and configure it as an identity provider mapper.

Option B: Manual role assignment

Assign AKKO roles manually in Keycloak after users first log in via Google. This is simpler but does not scale for large organizations.

4. LDAP / Active Directory (User Federation)¶

This is the recommended approach for enterprises with an on-premises Active Directory or OpenLDAP server. Keycloak's User Federation feature imports users and groups directly into the Keycloak database.

Step 1: Prepare Your Values File¶

# values-enterprise.yaml
global:
  auth:
    mode: "enterprise"

    initialAdmin:
      enabled: true
      username: "admin-akko"
      email: "admin@corp.example.com"

    ldap:
      connectionUrl: "ldaps://ad.corp.example.com:636"
      bindDn: "cn=svc-akko,ou=service,dc=corp,dc=com"
      bindCredentialSecret: "akko-ldap-bind"
      usersDn: "ou=employees,dc=corp,dc=com"
      groupsDn: "ou=groups,dc=corp,dc=com"
      usernameLDAPAttribute: "sAMAccountName"   # "uid" for OpenLDAP
      vendor: "ad"                               # "other" for OpenLDAP
      roleMapping:
        akko-admin: ["IT-Admins", "Platform-Admins"]
        akko-engineer: ["Data-Engineers", "DevOps"]
        akko-analyst: ["Business-Analysts", "BI-Team"]
        akko-user: ["Compliance"]
        akko-viewer: ["Management"]

Step 2: Create the LDAP Bind Secret¶

The bind credential is stored in a Kubernetes Secret, not in values:

kubectl create namespace akko

kubectl create secret generic akko-ldap-bind \
  --from-literal=password='<LDAP_BIND_PASSWORD>' \
  -n akko

Step 3: Deploy¶

helm upgrade --install akko helm/akko/ -n akko --create-namespace \
  --wait --wait-for-jobs --timeout 20m \
  -f helm/examples/values-dev.yaml \
  -f helm/examples/values-domain.yaml \
  -f values-enterprise.yaml \
  -f values-secrets.yaml \
  --set-file akko-keycloak.realm.data=helm/examples/realm-domain.json

Step 4: Configure Keycloak User Federation (Manual)¶

If you prefer to configure federation manually via the Keycloak Admin UI:

Log in to https://keycloak.<your-domain>/admin
Select the akko realm
Go to User federation > Add LDAP provider
Fill in the connection details:

Field	Value	Notes
Vendor	`Active Directory` or `Other`	AD for Microsoft AD, Other for OpenLDAP
Connection URL	`ldaps://ad.corp.example.com:636`	Use `ldaps://` for TLS (port 636)
Bind DN	`cn=svc-akko,ou=service,dc=corp,dc=com`	Service account with read access
Bind Credential	`<password>`	The LDAP bind password
Users DN	`ou=employees,dc=corp,dc=com`	Where users live in the directory
Username LDAP attribute	`sAMAccountName`	`uid` for OpenLDAP
RDN LDAP attribute	`cn`
UUID LDAP attribute	`objectGUID`	`entryUUID` for OpenLDAP
User object classes	`person, organizationalPerson, user`	`inetOrgPerson` for OpenLDAP
Edit Mode	`READ_ONLY`	Keycloak cannot modify your AD
Import Users	`On`	Sync users to Keycloak DB

Click Save then Synchronize all users

Step 5: Configure Group Mapper¶

Under the LDAP provider, go to Mappers > Add mapper:

Field	Value
Name	`group-mapper`
Mapper Type	`group-ldap-mapper`
Groups DN	`ou=groups,dc=corp,dc=com`
Group Name LDAP Attribute	`cn`
Group Object Classes	`group` (`groupOfUniqueNames` for OpenLDAP)
Membership LDAP Attribute	`member`
Membership Attribute Type	`DN`
Mode	`READ_ONLY`

Click Synchronize LDAP groups to Keycloak.

Step 6: Configure Sync Settings¶

Setting	Recommended Value	Description
Full Sync Period	`300` (5 minutes)	Full re-sync interval in seconds
Changed Users Sync Period	`60` (1 minute)	Incremental sync for changed users
Batch Size	`1000`	Users per sync batch
Pagination	`On`	Required for large directories

Step 7: Map LDAP Groups to AKKO Roles¶

After group sync, create role mappings in Keycloak:

Go to Groups in the sidebar
For each LDAP group (e.g., IT-Admins):
Click the group > Role mapping > Assign role
Select akko-admin (or the appropriate AKKO role)
Repeat for all groups in the mapping table

Verifying the Integration¶

After configuring your IdP, verify end-to-end:

Test login: Open https://cockpit.<your-domain> and click Sign in. You should see a login option for your IdP (or be redirected to your AD login page).

Verify roles: After login, check the user's token:

# In a JupyterHub terminal
curl -s https://keycloak.<your-domain>/realms/akko/protocol/openid-connect/userinfo \
  -H "Authorization: Bearer $JUPYTERHUB_API_TOKEN" | jq .

Check Keycloak: In Keycloak Admin, go to Users and verify that federated users appear with the correct group memberships and role mappings.
Test RBAC: Log in as users with different roles and verify they see the appropriate data and services. See RBAC Administration for the complete role matrix.

Troubleshooting¶

Symptom	Cause	Fix
"Invalid redirect URI" on login	Redirect URI mismatch	Verify the redirect URI in your IdP matches exactly (including `/endpoint` suffix)
Users appear but have no roles	Group-to-role mapping missing	Configure group mappers and role assignments in Keycloak
LDAP connection refused	Firewall or TLS issue	Verify network connectivity from the Keycloak pod; use `ldaps://` on port 636
"User not found" after sync	Users DN incorrect	Check the Users DN path in your LDAP provider configuration
Duplicate users	Federation link missing	Delete local users that conflict with LDAP usernames before enabling federation

External Identity Provider Integration¶

Overview¶

Switching to Enterprise Mode¶

1. Azure AD / Entra ID (OIDC Brokering)¶

Step 1: Create an App Registration in Azure¶

Step 2: Configure Token Claims¶

Step 3: Configure Keycloak¶

Step 4: Map Azure AD Groups to AKKO Roles¶

2. Okta (OIDC Brokering)¶

Step 1: Create an Okta Application¶

Step 2: Configure Keycloak¶

Step 3: Map Okta Groups to AKKO Roles¶

3. Google Workspace (OIDC Brokering)¶

Step 1: Create OAuth Credentials in Google Cloud¶

Step 2: Configure Keycloak¶

Step 3: Map Google Groups to AKKO Roles¶

4. LDAP / Active Directory (User Federation)¶

Step 1: Prepare Your Values File¶

Step 2: Create the LDAP Bind Secret¶

Step 3: Deploy¶

Step 4: Configure Keycloak User Federation (Manual)¶

Step 5: Configure Group Mapper¶

Step 6: Configure Sync Settings¶

Step 7: Map LDAP Groups to AKKO Roles¶

Verifying the Integration¶

Troubleshooting¶

Further Reading¶