Authentication¶

Pixee Enterprise Server authenticates through the embedded Authentik identity provider. To use your own IdP, connect it to Authentik as a federated source — there is no direct platform-to-IdP integration to configure. You point Authentik at your IdP, and the platform talks to Authentik.

Info

Support for OIDC compatible identity providers is in active development, contact support@pixee.ai to request additional support.

Embedded Identity Provider (Authentik)¶

Pixee Enterprise Server includes Authentik as an embedded identity provider. This provides a full-featured identity management solution without requiring an external OIDC provider.

Features¶

User management with web-based admin interface
Support for local users and passwords
Federation with external identity providers (Google Workspace, Oracle, etc.)
Self-service password change
Session management
Pixee-branded login experience

Email / SMTP Support

To enable email features such as self-service password reset, email verification, and notification emails, configure the SMTP / Email Settings section in the admin console. An SMTP server (e.g., your organization's mail relay, Gmail, SendGrid) is required. Without SMTP configured, password resets must be performed by an administrator through the Authentik admin interface or by using the recovery key command described below.

Configuration¶

Embedded ClusterHelm Deployment

Authentik initializes on deployment with the Pixee OIDC application pre-configured. The admin console shows the default admin credentials and the direct login link for administrators under Config → Authentication.

To enable Authentik in Helm deployments, set the following in your values.yaml:

authentik:
  enabled: true
  authentik:
    secret_key: "<generate a secure random string - must not change after install>"
    bootstrap:
      password: "<initial admin password for akadmin user>"
    postgresql:
      host: "<postgresql-host>"
      name: "authentik"
      user: "authentik"
      password: "<database-password>"
    redis:
      host: "<redis-host>"
      port: 6379
  # Inject the OIDC client secret into the Authentik worker so the blueprint can
  # read it via !Env. References the same secret used by the platform.
  worker:
    env:
      - name: PIXEE_OIDC_CLIENT_SECRET
        valueFrom:
          secretKeyRef:
            name: oidc-client-secrets
            key: secret

global:
  pixee:
    access:
      enabled: true
      oidc:
        client:
          id: "pixee"
          secret: "<generate a secure random string>"

Initial Setup¶

After deploying:

Embedded ClusterHelm Deployment

Access the admin interface by navigating to:
```
https://<your-domain>/authentik/
```
Log in with username akadmin and the password shown in the admin console config page (your license ID). After logging in, click the Admin interface button to access user management.
Change the admin password (recommended) - Navigate to Directory > Users, select akadmin, and update the password. This change will persist across upgrades.
Create additional users as needed through the Authentik admin interface

Find the admin password in your values.yaml under authentik.authentik.bootstrap_password
Access the admin interface by navigating to:
```
https://<your-domain>/authentik/
```
Log in with username akadmin and the configured password, then click the Admin interface button.
Create additional users as needed through the Authentik admin interface

Recovery Access

If you need to reset a user's password, the easiest way is to create a recovery link from the Authentik admin UI:

Navigate to Directory → Users and select the user
Click Create Recovery Link — you can set how long the link stays valid (default: 30 minutes)
Send the link to the user; they will be prompted to set a new password

As a CLI fallback, you can generate a recovery link via kubectl:

kubectl exec -n <namespace> deploy/<release-name>-authentik-server -- ak create_recovery_key 30 akadmin

This generates a recovery URL valid for 30 minutes.

Upgrades and Persistence

User accounts, passwords, and settings are stored in the Authentik database and persist across upgrades
Password changes made by users or admins will not be overwritten during upgrades
The OIDC application configuration is managed declaratively and will be updated automatically during upgrades

Using Authentik behind a load balancer on a non-standard port

If your Pixee Enterprise Server is accessed through a load balancer on a non-standard port (e.g., port 5443), you must configure the reverse proxy settings for OIDC authentication to work correctly. See Reverse Proxy Settings — Non-Standard Port for setup instructions.

Admin Access — the `pixee-admins` Group¶

The pixee-admins Authentik group is the single source of truth for privileged access in Pixee Enterprise Server. Members of this group receive admin rights on two surfaces:

User Platform — full organization admin access (manage repos, users, settings)
Superset Dashboards — Superset Admin role (manage datasets, database connections, roles)

Users not in pixee-admins sign in to Superset as Gamma (read-only dashboard viewers with access to the Pixee Platform database).

Superset role changes apply at next login

Superset recomputes a user's roles when they sign in, so adding someone to pixee-admins — or removing them — reaches a signed-in user only on their next login.

Roles set in the Superset UI are replaced on login

AUTH_ROLES_SYNC_AT_LOGIN is enabled, so Authentik group membership is the only role knob for SSO users. Any role assigned manually inside the Superset UI — including sql_lab — is silently overwritten the next time that user logs in. Make role decisions in Authentik, not in Superset.

Default membership¶

akadmin (the Authentik bootstrap superuser) is seeded into pixee-admins automatically as a break-glass account:

Fresh installs — akadmin is added by the Authentik blueprint on first deploy.
Upgrades from earlier versions — akadmin is added by a one-time Helm hook Job on the first upgrade that includes this feature. If the Authentik blueprint had not yet applied at the time of that upgrade, the Job exits with an error visible in the Kubernetes Job logs. Verify membership after upgrade using the Adding a user to pixee-admins steps below, and add akadmin manually if needed.

You should add your operational user accounts to this group and avoid using akadmin for day-to-day work.

Adding a user to `pixee-admins`¶

In the Authentik admin interface, go to Directory → Groups
Click on pixee-admins
On the Users tab, click Add existing user and select the user
Click Add — changes take effect on the user's next login

Enforcing the admin role¶

Membership in pixee-admins is only acted upon in Resolution Center once role enforcement is turned on. Enforcement is off by default: every signed-in user has full access in Resolution Center, which is how Pixee behaved before roles existed. Superset is not governed by this toggle — it always maps pixee-admins to Superset Admin and everyone else to Gamma, as described at the top of this section.

Populate pixee-admins first

With enforcement on, editing organization preferences is restricted to members of pixee-admins. If the group holds only akadmin, that break-glass account is the only one that can make those changes.

Embedded ClusterHelm Deployment

Navigate to the admin console, select the Config tab, then go to the Authentication section
Select Enforce role-based access control
Save and deploy the configuration

global:
  pixee:
    access:
      enabled: true
      authorization:
        enabled: true

Enforcement requires authentication. With access.enabled false the platform logs a warning and leaves enforcement off, since there is no authenticated user whose roles it could check.

User Management¶

Users are managed through the Authentik admin interface at https://<your-domain>/authentik/if/admin/.

Creating Users¶

In the admin interface, go to Directory → Users and click Create
Fill in the user's details (username, display name, email) and click Create
After creating the user, select them and click Create Recovery Link to generate a one-time password setup link — you can choose how long the link stays valid
Send the recovery link to the user; they will be prompted to set their password on first visit

For more details, see the Authentik documentation on creating users and creating recovery links.

Editing and Deleting Users¶

Go to Directory → Users, select a user, and update their details or deactivate their account
Users created here can log in to Pixee Enterprise Server

Federating External Identity Providers¶

Authentik supports federating external identity providers so users can log in with their existing corporate credentials. After creating a source for your identity provider (see provider-specific sections below), you must add it to the login page.

Works behind a corporate egress proxy

Authentik honors the standard HTTP_PROXY / HTTPS_PROXY / NO_PROXY environment variables. When you configure an outbound HTTP proxy in the admin console, those values flow through to Authentik automatically, so back-channel calls to your identity provider (token exchange, userinfo, JWKS) route through the proxy. The no_proxy exclusion list is also honored if you need certain hosts to bypass the proxy.

Choosing a setup method¶

Each provider below can be set up three ways. They reach the same result and are interchangeable (the CLI applies the very same blueprint you would run in the UI), so pick based on the access you have:

Method	Automation	Access needed	Best when
CLI (`pixee-idp`)	Fully automated. One command creates the source and mappings and puts it on the login page	Cluster / `kubectl`	You have shell access and want the fewest steps (e.g. a Pixee-assisted screen-share)
Authentik UI (run the blueprint)	Mostly automated. The shipped blueprint creates the source and mappings; you add it to the login page by hand	Authentik web admin only	Identity admins without cluster access, or a GitOps/auditable flow
Manual (by hand)	Fully manual. You build the source, mappings, and login binding yourself	Authentik web admin only	Advanced or unsupported setups the other two do not cover

Each provider's Step 2 presents these as tabs. If you will use the CLI, set up its alias once (The pixee-idp CLI, below); the UI and manual methods need no cluster access.

The `pixee-idp` CLI¶

Several provider setups below offer a CLI method that automates the Authentik-side wiring. It uses pixee-idp, an in-cluster helper that spins up a short-lived pod per command and tears it down. Nothing is installed on a host and no credential is stored in the chart or admin console. Set it up once, then use it for any provider (connect, emit, status, auto-redirect).

The helper ships automatically whenever the embedded Authentik broker is in use; there is no separate toggle. (Plain Helm deployments activate it by supplying a scoped token: --set authentik.federation.pixeeIdp.token=<token>, or point at your own with authentik.federation.pixeeIdp.existingSecret.)

Open a cluster shell and define the alias:

# From the Pixee Enterprise Server virtual machine
sudo ./pixee shell
pixee-idp() { sh -c "$(kubectl get cm pixee-idp-launcher -n kotsadm -o 'jsonpath={.data.pixee-idp}')" pixee-idp "$@"; }

(Helm deployments: run the alias from any shell with kubectl access to the release namespace, replacing kotsadm.)

You can then run pixee-idp emit <provider> (no credentials needed) to print a provider's redirect URI and prerequisites. The provider-specific CLI tabs below assume this alias is defined.

This step is the same for all federated identity providers. After creating a source in Authentik:

In the Authentik admin interface, go to Flows and Stages → Flows
Click on default-authentication-flow
Go to the Stage Bindings tab
Click Edit Stage on the default-authentication-identification stage
Under Source settings, add your identity provider source to the Selected sources field
Click Update to save

Users will now see the identity provider as a login option on the Authentik login page. Settings made on this stage (selected sources, user fields, recovery flow) are preserved across deploys — the Pixee Helm chart does not overwrite them. To redirect users directly to the identity provider instead of showing a selection page, see Auto-Redirect to Identity Provider. To show a self-service password recovery link, see Enable "Forgot Password?" Link on the Login Page.

Granting the Pixee Admin Role¶

Pixee's role-based access control is driven by Authentik group membership, independent of which identity provider a user signs in through. The chart ships an Authentik group named pixee-admins: any user in it receives the Pixee admin role (Pixee reads this from the pixee_roles claim Authentik adds to the token). Users who are not in the group sign in as regular, non-admin users.

To grant a federated user the admin role, add them to pixee-admins using whichever approach fits your identity provider:

Assign membership directly in Authentik (works for any provider). Go to Directory → Groups → pixee-admins → Users → Add existing user, and add the user. This is the simplest option and a good fit when only a handful of people need admin.
Map an upstream group by name (for providers that send groups). If your identity provider includes group membership in its token (e.g. Microsoft Entra, Okta, Oracle), name a group pixee-admins on the provider side and set the source's Group matching mode to Link to a group with identical name (name_link). Authentik then keeps membership in sync with your IdP automatically. Some providers need one setting turned on before they send groups at all: see Okta, Entra, and Oracle. Google is the exception — it omits group membership from OIDC tokens, so use group → admin sync (a Directory API lookup) or add admins directly.

The group starts empty

On a fresh install no federated user has the Pixee admin role until you add them to pixee-admins. Add your first administrator before relying on a federated identity provider for admin access. (The built-in akadmin account can always sign in via the direct-login flow to manage groups.)

Federated Users Are Made Internal Automatically¶

Authentik distinguishes internal users (full members who can reach the Application Dashboard and manage their own API tokens) from external users (redirected straight to their default application, with no dashboard access). Users enrolled through an external identity provider (IdP) are frequently created as external, which locks them out of the dashboard.

Pixee Enterprise Server handles this for you in two ways, with no configuration required:

New users arrive internal at enrollment. Authentik's default source-enrollment flow otherwise creates users as external; the Pixee blueprint overrides that flow's User Write stage to create internal users instead.
Existing users are converted by a deploy job that sweeps federated users (external and linked to a source) to internal. It is scoped to source-linked users, so local accounts (such as akadmin) and service accounts are never touched.

Custom enrollment flows

The new-user override applies to the default source-enrollment flow, which is what OAuth and SAML sources use unless you change it. If you point a source at a custom enrollment flow, set that flow's User Write stage "User type" to Internal in the Authentik UI — the deploy job will also catch such users on the next deploy.

Disable Self-Service for Federated Users¶

When an external IdP owns your users' credentials and profiles, Authentik's self-service "Change password" and "Update details" controls no longer apply. You can hide them with a single toggle.

Embedded ClusterHelm Deployment

In the admin console, select the Config tab, enable "Disable Authentik self-service", then save and deploy.

Set the following in your values.yaml and upgrade:

authentik:
  disableSelfService: true

When enabled:

the "Change password" card is hidden;
the "Update details" form is hidden (the user-settings flow is removed from the brand).

These are applied declaratively, so turning the toggle off re-enables them (restores Authentik's defaults). Leave it off for local/embedded-user setups, where users manage their own accounts through these same controls.

Administrators and MFA

Administrators can still set or reset local-account passwords under Directory → Users, and the "Forgot password?" recovery flow still works. This toggle does not hide the MFA device cards: Authentik renders them whenever the authenticator setup stages exist, with no per-user setting to remove them. Whether federated users are challenged for local Authentik MFA depends on your source's authentication flow and any bound policies (it is not skipped automatically); their identity provider enforces its own MFA upstream regardless.

Optional: Customize Username Derivation¶

By default, Authentik populates each new federated user's username from the OIDC preferred_username claim — typically the full UPN (e.g. john.smith@example.com). To derive a shorter username from the email or UPN claim instead (e.g., john.smith from john.smith@example.com):

In the Authentik admin interface, go to Customization → Property Mappings → Create → OAuth Source Property Mapping
Configure the mapping with one of the following, depending on your identity provider:
Google OAuthMicrosoft Entra ID (OAuth)
- Name: Google Email to Username
- Expression:
  
  return {"username": info.get("email", "").split("@")[0]}
- Name: Entra UPN to Username
- Expression:
  
  # Authentik's Entra type reads Microsoft Graph fields # (userPrincipalName, mail, displayName) — NOT the standard OIDC # claims (preferred_username, email). Derive the username from the # UPN, and fall back to the UPN for email when the account has no # mailbox (mail is null — common for bare *.onmicrosoft.com users). upn = info.get("userPrincipalName") mail = info.get("mail") or (info.get("otherMails") or [None])[0] return { "username": upn, "email": mail or upn, "name": info.get("displayName", ""), }
The mail-to-upn fallback matters because the source matches users on email (email_link): if mail is null and nothing is supplied, Authentik refuses the login with "authenticate with the source you've previously signed up with" (see the troubleshooting table below). Falling back to the UPN — which is already email-formatted — gives every account a usable email. This is the same mapping the shipped Pixee - Entra ID federation blueprint and the pixee-idp CLI bind automatically, so you only need to create it by hand for a fully manual setup.
Click Finish
Go to Directory → Federation and Social login → edit the OAuth source for that identity provider
Under User Property Mappings, add the mapping you just created to the Selected User Property Mappings field
Click Update

New users will now be assigned a username automatically based on the identity provider's claim.

Troubleshooting Property Mappings¶

Most installs work without any custom mapping — Authentik's built-in extraction reads preferred_username, name, and email from any standard OIDC source and populates the user record automatically. The mapping above is only needed if you want a different username derivation (e.g. stripping the @<host> suffix).

If sign-in fails with "Aborting write to empty username" or new user records have empty fields:

Inspect what the IdP actually returned, by temporarily adding a debug log line to the property mapping's Python expression.

Open the Authentik admin UI at https://<your-domain>/authentik/if/admin/ and navigate to Customization → Property Mappings. Click on the mapping you want to debug — the edit panel opens on the right. The form has several fields; the one you want is the multi-line Expression text area, which contains the Python code that runs during sign-in.

Before (the expression you already have, for example):
```
upn = info.get("preferred_username") or info.get("email")
return {"username": upn.split("@")[0] if upn else None}
```
After — add ak_logger.warning(...) as the first line. The existing code stays underneath, untouched:
```
ak_logger.warning("oauth source claims", info_keys=list(info.keys()), info=dict(info))
upn = info.get("preferred_username") or info.get("email")
return {"username": upn.split("@")[0] if upn else None}
```
Click Update to save. Then attempt a sign-in — the expression runs and writes a structured JSON log line to the authentik-server pod's stdout.

About ak_logger

ak_logger is a Python name pre-injected into every Authentik property-mapping expression (alongside info, properties, request). It's not a CLI tool or a script file; it only exists inside the Expression text area when Authentik evaluates the mapping. See Authentik's Sources expression property mappings reference for the full list of available names and other example debug snippets.

Read the resulting log line from the authentik-server pod:
Embedded ClusterHelm Deployment
# From the Pixee Enterprise Server virtual machine sudo ./pixee shell kubectl logs -n kotsadm \ -l app.kubernetes.io/component=server,app.kubernetes.io/name=authentik \ --tail=200 | grep "oauth source claims"
kubectl logs -n <namespace> \ -l app.kubernetes.io/component=server,app.kubernetes.io/name=authentik \ --tail=200 | grep "oauth source claims"
Replace <namespace> with the namespace you installed the chart into (often default).
The matching line is a JSON object. The first positional argument to ak_logger.warning(...) lands in the event field, keyword arguments become top-level fields, and the logger field is set to the mapping's Name — useful for filtering to a specific mapping with grep '"logger":"<your-mapping-name>"'.

Interpret the info dict and act on what's missing:

Symptom in `info`	Likely cause	Fix
Only `sub` and `picture` present	The source isn't requesting OpenID Connect scopes, or the IdP isn't granting them	On the Authentik source, expand Protocol settings and set Additional Scopes to `email profile`. For Entra/Azure App Registrations, also confirm under API permissions that `email`, `openid`, `profile` are added under Microsoft Graph → Delegated AND show "Granted for \<tenant>" in the Status column
`name` present, `preferred_username`/`email` missing	The user account has no UPN/email on the IdP side, or `email` permission isn't admin-consented	Either grant the missing permissions on the IdP, or fall back to deriving the username from `name` in the mapping (see the Entra tab above)
(Entra) Login denied with "authenticate with the source you've previously signed up with"; log shows `Refusing to use none property property=email`	The Entra account has no mailbox, so Graph returns `mail: null`. Because the source matches on email, Authentik refuses rather than create a user with no email. Common on bare `*.onmicrosoft.com` accounts	Fall back to the UPN for email in the mapping: `"email": info.get("mail") or info.get("userPrincipalName")` (see the Entra tab above). The shipped blueprint and `pixee-idp` CLI already do this
(Entra) `Failed to save user` / `duplicate key value violates unique constraint "authentik_core_user_username_key"`	A user with that username already exists but with a different (or empty) email, so the matcher can't link to it and tries to enroll a colliding one — usually a leftover from earlier testing	Set the existing user's email to match the incoming one so `email_link` links it, or delete the stale user so enrollment recreates it cleanly
All claims present but mapping still fails	Likely a Python error in the expression	Look for `Failed to execute property mapping` lines in the same log

Remove the debug line from the mapping expression once the issue is identified — it's noisy at sign-in volume.

Google OAuth¶

Pixee Enterprise Server supports Google as an identity provider using OAuth 2.0 / OpenID Connect. This works with any Google account (personal Gmail or Google Workspace).

Setup is the same three steps regardless of method: (1) create the OAuth client in Google Cloud → (2) create the source and put it on the login page → (3) grant the admin role. Only step 2 differs by method — the pixee-idp CLI, the Authentik UI, or fully by hand.

Step 1 — Create the OAuth client in Google Cloud (all methods)¶

Go to Google Cloud Console and select or create a project
Go to APIs & Services → Credentials → Create Credentials → OAuth client ID
If prompted, configure the OAuth consent screen first:
- User Type: Internal (restricts sign-in to your Google Workspace organization) or External (any Google account)
- App name: Pixee Enterprise Server; Authorized domains: your domain (e.g. getpixee.com)
Create the OAuth client ID:
- Application type: Web application
- Authorized redirect URI (must be exact, including the trailing slash): https://<your-domain>/authentik/source/oauth/callback/google/
Copy the Client ID and Client Secret.

Tip

The CLI prints this exact redirect URI (and the group-sync prerequisites) with pixee-idp emit google-oauth — no credentials needed.

Pick one of the three methods (Choosing a setup method) and follow it end to end. All reach the same result (Google on the login page). Note the Google specifics: the blueprint method still needs the login-page button added by hand, because a blueprint cannot edit the login stage (see the note below). (Group sync and auto-redirect are optional add-ons covered afterward.)

CLI (pixee-idp)Authentik UI (run the blueprint)Manual (by hand)

Set up the pixee-idp alias once (see The pixee-idp CLI above), then:

pixee-idp connect google-oauth   # enter Client ID; the secret is a hidden prompt (never logged)

connect creates the source, binds the username mapping, and adds it to the login page — the whole step in one command. pixee-idp status google-oauth shows the result (secrets masked). Done — test sign-in.

The chart ships a Pixee - Google Workspace federation blueprint, disabled so its placeholder credentials never auto-apply.

Customize → Blueprints → on the Pixee - Google Workspace federation row, click the edit (pencil) icon under Actions.
At the top, toggle Enabled on.
Scroll to the bottom and expand Additional settings — the Context field is there. Enter your credentials as a mapping (this exact format):
```
{google_client_id: "<your client id>",
 google_client_secret: "<your client secret>",
 google_source_enabled: true}
```
Update to save, then — back on the Blueprints list — click the Apply (▶ play) icon under Actions on that row.
Add the source to the login page: Flows & Stages → Stages → edit default-authentication-identification → add Google Workspace under Sources → Update (see Adding a Source to the Login Page). Then test sign-in.

Save ≠ Apply — click the ▶ Apply action

Saving the instance (even with Enabled on) does not create the source — it can even show status: successful, which is misleading. Only the ▶ Apply icon under Actions on the Blueprints row creates it.

google_source_enabled is required, and is why the seed is safe to ship

The Enabled toggle in step 2 enables the blueprint; google_source_enabled enables the source it creates. Omit it and the blueprint applies cleanly but produces a Google source that is switched off, so the login button does nothing.

It exists because the shipped seed must validate on a cluster with no internet access. Authentik verifies a Google source by fetching accounts.google.com/.well-known/openid-configuration — but only when the source is enabled — and it validates this seed on every install, whether or not you use Google. A seed that shipped enabled would fail that fetch on an air-gapped cluster and, because a blueprint applies atomically, take down all of Pixee sign-in with it. pixee-idp connect google-oauth sets this key for you.

No helper required.

Directory → Federation and Social login → Create → Google OAuth Source
Configure (fields not listed can keep their defaults):
- Name: Google Workspace; Slug: google (must match the redirect URI …/callback/google/)
- Consumer Key / Secret: your Client ID / Secret from Step 1
- User matching mode: Link to a user with identical email address (the default won't link returning users by email)
- Group matching mode: default for login only; Link to a group with identical name (name_link) if you'll enable group sync
Click Create. Google sends no username, so add a username property mapping and select it under the source's User Property Mappings (see Customize Username Derivation), or new users are prompted to pick a username on first sign-in.
Add the source to the login page: Flows & Stages → Stages → edit default-authentication-identification → add Google Workspace under Sources → Update (see Adding a Source to the Login Page). Then test sign-in.

Step 3 — Grant the Pixee admin role¶

A federated user signs in with no elevated access until you make them an admin. Because Google does not include group membership in its OAuth/OIDC tokens, the name-matching approach doesn't apply — add admins to the pixee-admins group directly in Authentik, or set up group → admin sync below to promote members of a Workspace group automatically. See Granting the Pixee Admin Role for the details.

Google Workspace group to admin sync¶

Google login authenticates users on its own — this step is only needed if you want members of a Google Workspace group to automatically become Pixee admins. Google does not put group membership in the OIDC token, so Authentik resolves it by calling the Google Directory API at each login with a service-account key.

The service-account key is stored in Authentik's database

The key is held in the blueprint context (readable by any Authentik admin), never a mounted file or Kubernetes Secret — a deliberate self-service tradeoff. If that's unacceptable, manage pixee-admins membership by hand instead. See Notes & limitations.

The Google-side prerequisites (the CLI cannot do these for you — they require Google Cloud and Google Workspace admin access):

Create a service account and key. In Google Cloud Console, select or create a project and enable the Admin SDK API (APIs & Services → Library → Admin SDK API → Enable). Create a service account (IAM & Admin → Service accounts) — it needs no project IAM roles, since its group-read access comes from the delegation below. Add a JSON key (Keys → Add key → Create new key → JSON) and download it; this is the JSON you supply when applying. Note the service account's numeric client ID (its "Unique ID") — you need it in the next step.
Grant domain-wide delegation. In the Google Workspace Admin console → Security → Access and data control → API controls → Domain-wide delegation → Manage domain-wide delegation → Add new, enter the service account's client ID and authorize exactly the scope https://www.googleapis.com/auth/admin.directory.group.readonly. Delegation can take a few minutes to propagate.
Pick the impersonation admin and the admin group. Note a Workspace admin email for the service account to impersonate (the Directory API requires a real admin subject) and the email of the Workspace group whose members should become Pixee admins.

Then enable it. The groups mapping ships already bound to the Google source but inert — with no credentials it returns nothing before it even calls Google, so a plain login never touches it. Supplying the credentials below is all that activates it (no separate "bind the mapping" step for the blueprint/CLI methods).

CLI (pixee-idp)Authentik UI (blueprint)Manual (no blueprint)

pixee-idp enable-sync google-oauth   # paste the service-account JSON at the prompt (Ctrl-D)

Fills the credentials and activates the (already-bound) mapping — one step.

Customize → Blueprints → Pixee - Google Workspace federation → edit Context, add the three values → Apply. That's it — the mapping is already bound, so nothing else to do.

google_sa_key: '<the service-account JSON, as a string>'
google_delegated_admin: admin@yourcompany.com
google_admin_group: pixee-admins@yourcompany.com

(Pasting the multi-line JSON key into the YAML Context is fiddly — the CLI's enable-sync is easier for the key.)

If you created the source by hand (no blueprint), build the mapping yourself: Customization → Property Mappings → Create → OAuth Source Property Mapping, name it Pixee Google Workspace Groups, and use a Directory-API expression with your service-account JSON, delegated-admin email, and admin-group email inlined (use the shipped blueprint's mapping as the template). Then add it under the Google Workspace source's User Property Mappings and Update.

Rotating the key is a re-run, not a redeploy. Group lookup fails open: if the Directory API is unreachable or misconfigured, login still succeeds (the user just gets no admin role).

Notes & limitations¶

The login-page button and auto-redirect are stage edits, not blueprint steps. Authentik's blueprint apply merges the identification stage's user_fields (it can add a source but never clear it), so auto-redirect can't be a blueprint and a blueprint that sets user_fields leaves a harmless duplicate (Authentik dedupes at render). Do these via the CLI (pixee-idp auto-redirect) or the UI stage editor — both replace cleanly.
In the UI, save ≠ apply. Editing/saving a blueprint instance doesn't run it (it may even show status: successful); click the ▶ Apply action on the Blueprints row.
Group sync stores the service-account key in Authentik's database (blueprint context, readable by any Authentik admin) — never a file or Kubernetes Secret. Manage pixee-admins by hand if that's unacceptable.
The Directory-API mapping is Google-specific. Other IdPs (Entra, Okta, Oracle) can put groups in the token, so they use name_link and need no Directory-API mapping. Oracle still needs a mapping of its own, but only to normalize the shape of the groups it sends — see Oracle group to admin sync.

Okta (OAuth)¶

Pixee Enterprise Server supports Okta as a federated identity provider through Authentik using OAuth 2.0 / OpenID Connect. Unlike Google, Okta puts group membership in the token, so promoting an Okta group to Pixee admin is automatic (name_link), with no service account and no separate sync command. See Okta group to admin sync for the one Okta-side requirement.

Setup is the same three steps regardless of method: (1) create the OIDC app in Okta, (2) create the source and put it on the login page, (3) grant the admin role. Only step 2 differs by method: the pixee-idp CLI, the Authentik UI, or fully by hand.

Step 1 — Create the OIDC app in Okta (all methods)¶

Create a Web Application (OIDC) app integration in the Okta Admin Console following Okta's guide for creating OpenID Connect app integrations. Only these values are Pixee-specific:

Sign-in redirect URI (exact, including the trailing slash): https://<your-domain>/authentik/source/oauth/callback/okta/
Assignments: assign the users/groups who should be able to sign in
Afterward, capture the Client ID, Client secret, and your Okta org URL (e.g. https://mycompany.okta.com) for Step 2

Use the org URL, not the -admin console URL

Authentik needs your org domain, mycompany.okta.com. The admin console host mycompany-admin.okta.com does not serve the OAuth endpoints and will return 404 at sign-in. (The CLI strips -admin automatically; set it correctly yourself in the UI/blueprint path.)

Tip

pixee-idp emit okta prints the exact redirect URI and the group-sync prerequisites, with no credentials needed.

Pick one of the three methods (Choosing a setup method). All reach the same result (Okta on the login page):

CLI (pixee-idp)Authentik UI (run the blueprint)Manual (by hand)

Set up the pixee-idp alias once (see The pixee-idp CLI above), then:

pixee-idp connect okta   # prompts: Client ID, Client secret (hidden), Okta org URL

connect creates the source (deriving the OIDC endpoints from the org URL), binds the username and groups mappings, and adds it to the login page, the whole step in one command. pixee-idp status okta shows the result (secret masked). Done. Test sign-in.

The chart ships a Pixee - Okta federation blueprint, disabled so its placeholder credentials never auto-apply. In Customize → Blueprints, edit its Context with your okta_client_id, okta_client_secret, okta_source_enabled: true, and the okta_authorization_url / okta_token_url / okta_profile_url endpoints (see Authentik's Okta docs for the exact URL patterns), toggle Enabled on, and click the ▶ Apply action. Then add the source to the login page (Flows & Stages → Stages → edit default-authentication-identification → add Okta under Sources → Update; see Adding a Source to the Login Page).

okta_source_enabled is required, and is why the seed is safe to ship

The Enabled toggle enables the blueprint; okta_source_enabled enables the source it creates. Omit it and the blueprint applies cleanly but produces an Okta source that is switched off, so the login button does nothing.

It exists so the shipped seed can never make a network call while it still holds placeholders. Authentik fetches a source's discovery document when it validates one — but only when the source is enabled — and it validates this seed on every install, whether or not you use Okta. Because a blueprint applies atomically, a fetch that could not complete would take down all of Pixee sign-in with it. This seed also omits the discovery URLs, so today there is nothing to fetch; the flag keeps that true if the Okta source type ever gains a default one. pixee-idp connect okta sets this key for you.

Create the source by hand following Authentik's Okta OAuth source guide: slug okta, your Client ID/secret as Consumer key/secret, and the authorize / token / userinfo endpoints for your org. Then add it to the login page.

Step 3 — Grant the Pixee admin role¶

Add admins to the pixee-admins group directly in Authentik, or set up Okta group → admin sync below to promote members of an Okta group automatically. See Granting the Pixee Admin Role for the details.

Okta group to admin sync¶

Name an Okta group pixee-admins, put your admins in it, and Authentik links it to the Pixee admin role automatically at each login, provided the group name reaches Authentik. Authentik reads claims from the userinfo endpoint, and getting Okta groups there has one firm requirement:

Use a custom authorization server. Okta's org authorization server returns groups from /userinfo only when the groups scope is requested, and Authentik's Okta client requests exactly openid email profile — never groups — so on the org server the claim never arrives. A custom server's claims default to Any scope, which is why it works without one being requested. Point the source at your custom (usually default) server: pass https://<org>.okta.com/oauth2/default to connect (or set the …/oauth2/default/v1/… endpoints in the UI). Adding a groups scope on the Okta side does not help — nothing asks for it.
Add a groups claim, and allow your app. On that custom server, following Okta's own guides:
- Customize tokens with a groups claim: add a groups claim with Include in token type: ID Token (userinfo mirrors ID-token claims, not access-token), Value type: Groups, filter Matches regex .*.
- Create access policies and rules: the custom server needs an access policy assigned to your app with a rule permitting the Authorization Code grant (without a rule, Okta returns access_denied / "Policy evaluation failed").

Group sync fails open: if groups don't arrive, login still succeeds; the user just receives no admin role (grant pixee-admins by hand in Authentik).

Hand-granting stops working once sync has run

Authentik removes only the groups this source linked (groupsourceconnection__source), which is what protects hand-granted admins before sync is ever configured. But that source link is permanent: once Okta has synced pixee-admins even once, a later login whose claim is missing strips the group again — and re-granting by hand will not survive the login after that. If sync breaks, repair the claim rather than re-granting.

Auth-only is simpler

If you don't need automatic group→admin promotion, skip the custom server entirely: the org authorization server (https://<org>.okta.com) is enough for login, and you assign pixee-admins by hand.

Microsoft Entra ID (OAuth)¶

Pixee Enterprise Server supports Microsoft Entra ID (formerly Azure AD) as a federated identity provider through Authentik using OAuth 2.0 / OpenID Connect. Authentik's Entra type fetches group membership from Microsoft Graph natively, using the signed-in user's own token (no service account), so group to admin sync is an opt-in scope with no service account and no property mapping.

Pick one of the three methods (Choosing a setup method). All reach the same result (Entra ID on the login page).

Step 1: Create the Entra app registration (all methods)¶

Create an app registration following Authentik's Entra ID OAuth guide. Only these values are Pixee-specific:

Redirect URI (exact, including the trailing slash): https://<your-domain>/authentik/source/oauth/callback/entra/
Capture the Application (client) ID and a client secret Value.
For a single-tenant app, note the Directory (tenant) ID. Multi-tenant apps use the default /common/ endpoints.

Tip

pixee-idp emit entra prints the exact redirect URI and the group-sync prerequisites, with no credentials needed.

CLI (pixee-idp)Authentik UI (run the blueprint)Manual (by hand)

Set up the pixee-idp alias once (see The pixee-idp CLI above), then:

pixee-idp connect entra   # prompts: Client ID, Client secret (hidden), tenant ID

connect creates the source and adds it to the login page. It prompts for the tenant ID: single-tenant apps require it (leaving it blank uses the multi-tenant /common/ endpoint, which single-tenant apps reject with AADSTS50194); multi-tenant apps can leave it blank. --tenant-id <id> overrides the prompt for non-interactive use. pixee-idp status entra shows the result (secret masked). Done. Test sign-in.

The chart ships a Pixee - Entra ID federation blueprint, disabled so its placeholder credentials never auto-apply. In Customize → Blueprints, edit its Context with your entra_client_id, entra_client_secret and entra_source_enabled: true (and, to pin a single tenant, put your tenant ID in place of common in entra_authorization_url / entra_token_url), toggle Enabled on, and click the ▶ Apply action. Then add Microsoft Entra ID to the login page (see Adding a Source to the Login Page).

entra_source_enabled is required, and is why the seed is safe to ship

The Enabled toggle enables the blueprint; entra_source_enabled enables the source it creates. Omit it and the blueprint applies cleanly but produces an Entra source that is switched off, so the login button does nothing.

It exists because the shipped seed must validate on a cluster with no internet access. Authentik verifies an Entra source by fetching login.microsoftonline.com — but only when the source is enabled — and it validates this seed on every install, whether or not you use Entra. A seed that shipped enabled would fail that fetch on an air-gapped cluster and, because a blueprint applies atomically, take down all of Pixee sign-in with it. pixee-idp connect entra sets this key for you.

Create the source by hand following Authentik's Entra ID OAuth guide: slug entra, your Application (client) ID and client secret Value. Then add it to the login page. Authentik derives the username from userPrincipalName; to customize it see Optional: Customize Username Derivation.

Step 3: Grant the Pixee admin role¶

Add admins to the pixee-admins group directly in Authentik, or set up Entra group to admin sync below to promote members of an Entra group automatically. See Granting the Pixee Admin Role for the details.

Entra group to admin sync¶

Name an Entra group pixee-admins, add your admins to it, and Authentik promotes its members to Pixee admin. Authentik's Entra type fetches the user's group membership from Microsoft Graph using their own token (no service account), then matches by group name. Group sync is opt-in, because it needs one Graph permission with admin consent:

On the app registration, add the delegated Microsoft Graph permission GroupMember.Read.All and grant admin consent for it (see Microsoft: Grant tenant-wide admin consent; this permission is also covered under "Group Member" in Authentik's Entra guide).
In Entra → Groups → New group, create a Security group (Group type: Security) named exactly pixee-admins and add your admins as members. Leave "Microsoft Entra roles can be assigned to the group" set to No — that toggle is for assigning Entra directory roles to the group and is unrelated to the Pixee admin role, which is granted purely by group name matching (name_link). If a pixee-admins group already exists, reuse it. (Authentik matches on the group's display name, so the group's type does not otherwise matter, but a plain security group is the right choice.)
Turn it on: pixee-idp enable-sync entra (or set entra_additional_scopes to https://graph.microsoft.com/GroupMember.Read.All in the blueprint Context and Apply).

Grant admin consent BEFORE enabling

If the GroupMember.Read.All scope is requested but admin consent has not been granted, Entra's Graph call fails and Authentik aborts the login. Grant admin consent first. If login breaks, turn the scope back off with pixee-idp enable-sync entra --disable (or clear entra_additional_scopes and Apply). With the scope off (the default), authentication always works.

Once consent is in place, group sync fails open with respect to group membership: a user who is in no matching group still signs in, just without the admin role (grant pixee-admins by hand in Authentik).

It does not fail open on Graph availability. While the scope is on, every Entra login makes a delegated Graph call for the user's groups, and Authentik treats a failed call as an unusable profile and aborts the login. So a Graph outage, a throttled tenant, or admin consent revoked later blocks sign-in for all Entra users, not just their admin role. The fast way out is pixee-idp enable-sync entra --disable, which removes the scope and takes Graph off the login path (authentication works again immediately; grant the admin role by hand until sync is re-enabled).

Large directories: provision over SCIM instead

Because the Graph lookup happens on every login, Authentik recommends Entra ID SCIM provisioning for organizations with many users and groups. Entra pushes users and groups into Authentik ahead of time, which removes both the per-login delay and the login-path dependency on Graph described above. Group-to-admin matching still works by name, so a pixee-admins group provisioned over SCIM grants the Pixee admin role the same way.

Google Workspace (SAML)¶

Pixee Enterprise Server supports Google Workspace as an external identity provider using SAML.

Step 1: Create a SAML App in Google Workspace¶

Go to Google Admin Console (admin.google.com) → Apps → Web and mobile apps → Add app → Add custom SAML app
Enter a name (e.g., Pixee Enterprise Server) and click Continue
Copy the SSO URL and Certificate from Google — you will need these for the Authentik source configuration
Under Service Provider Details, set:
- ACS URL: https://<your-domain>/authentik/source/saml/google/acs/
- Entity ID: https://<your-domain>/authentik/source/saml/google/metadata
- Name ID format: EMAIL
- Name ID: Basic Information > Primary email
Check the Signed response checkbox
Click Continue, then Finish

Enable the app for users

By default, new SAML apps in Google Workspace are OFF for everyone. You must turn it on:

Click on the newly created app
Click User access
Set the service status to ON for everyone (or for the appropriate organizational units)
Click Save

Step 2: Create a SAML Source in Authentik¶

Follow the Authentik documentation for Google Workspace SAML integration to create a SAML source using the SSO URL and Certificate from Step 1.

In the Authentik admin interface, go to Directory → Federation and Social login → Create → SAML Source
Set the Name (e.g., Google Workspace) and Slug (e.g., google)
Set the Icon field to /static/authentik/sources/google.svg so the Google logo appears on the login page
Set the SSO URL to the value copied from Google (e.g., https://accounts.google.com/o/saml2/idp?idpid=<your-idp-id>)
Set the Binding Type to Redirect (required for auto-redirect to work)
Upload the Signing Certificate downloaded from Google

After creating the source, add it to the login page.

Troubleshooting¶

403 app_not_configured_for_user: This means either the Entity ID doesn't match or the app isn't enabled for the user. Verify that the Entity ID in Google Admin Console exactly matches the Authentik metadata URL (case-sensitive), and that the app is turned ON for the user's organizational unit.
No Signature exists in the Response element: Enable the Signed response checkbox in the Google Admin Console SAML app under Service Provider Details.
"Permission denied" on login: Verify the Pixee application in Authentik is linked to the pixee provider. Check Applications > Pixee Enterprise Server > Provider assignment.

Oracle Identity Domains (OAuth)¶

Pixee Enterprise Server supports Oracle Identity Domains as a federated identity provider through Authentik using OAuth 2.0 / OpenID Connect. Oracle has no dedicated Authentik source type, so it uses the generic OpenID Connect type with all three endpoint URLs set explicitly. Group to admin sync is an opt-in scope: Oracle returns group membership only when the groups scope is requested. See Oracle group to admin sync.

Setup is the same three steps regardless of method: (1) create the confidential application in Oracle, (2) create the source and put it on the login page, (3) grant the admin role. Only step 2 differs by method: the pixee-idp CLI, the Authentik UI, or fully by hand.

Step 1 — Create the confidential application in Oracle (all methods)¶

Go to OCI Console → Identity & Security → Domains and select your domain
Navigate to Integrated applications → Add application → Confidential Application
Enter a name (e.g. Pixee Enterprise Server) and click Next
Under Client configuration, check "Configure this application as a client now"
Set Allowed Grant Types to Authorization Code

Set Redirect URL to (exact, including the trailing slash):

https://<your-domain>/authentik/source/oauth/callback/oracle/

Leave Token issuance policy set to All
Click Finish, then Activate the application
Copy the Client ID and Client Secret, and note your Domain URL (under Domain information, e.g. https://idcs-<guid>.identity.oraclecloud.com). The OIDC endpoints are derived from it.

Warning

Do not register Authentik as a Social Identity Provider in Oracle. Oracle should handle password authentication directly.

Tip

pixee-idp emit oracle prints the exact redirect URL and the group-sync prerequisites, with no credentials needed.

Pick one of the three methods (Choosing a setup method). All reach the same result (Oracle on the login page):

CLI (pixee-idp)Authentik UI (run the blueprint)Manual (by hand)

Set up the pixee-idp alias once (see The pixee-idp CLI above), then:

pixee-idp connect oracle   # prompts: Client ID, Client secret (hidden), domain URL

connect creates the source (deriving the three OIDC endpoints from the domain URL), binds the username and groups mappings, and adds it to the login page, the whole step in one command. pixee-idp status oracle shows the result (secret masked). Done. Test sign-in.

The chart ships a Pixee - Oracle Identity Domains federation blueprint, disabled so its placeholder credentials never auto-apply. In Customize → Blueprints, edit its Context with your oracle_client_id, oracle_client_secret, oracle_source_enabled: true, and the oracle_authorization_url / oracle_token_url / oracle_profile_url endpoints (the patterns are in the manual tab below), toggle Enabled on, and click the ▶ Apply action. Then add the source to the login page (Flows & Stages → Stages → edit default-authentication-identification → add Oracle Identity Domains under Sources → Update; see Adding a Source to the Login Page).

oracle_source_enabled is required, and is why the seed is safe to ship

The Enabled toggle enables the blueprint; oracle_source_enabled enables the source it creates. Omit it and the blueprint applies cleanly but produces an Oracle source that is switched off, so the login button does nothing.

It exists so the shipped seed can never make a network call while it still holds placeholders. Authentik fetches a source's discovery document when it validates one — but only when the source is enabled — and it validates this seed on every install, whether or not you use Oracle. Because a blueprint applies atomically, a fetch that could not complete would take down all of Pixee sign-in with it. This seed also omits the discovery URLs, so today there is nothing to fetch; the flag keeps that true if the generic OpenID Connect source type ever gains a default one. pixee-idp connect oracle sets this key for you.

This method sets up authentication, which works exactly as it does via the other two methods. Group → admin sync needs one extra step here: Oracle returns group membership as objects rather than names, so a hand-created source also needs the normalizing property mapping the blueprint ships. Enabling sync without it breaks sign-in for anyone in an Oracle group — see the warning in that section for how to add it by hand.

Create the source by hand following Authentik's OAuth source guide using the OpenID Connect type, with slug oracle (it must match the redirect URL …/callback/oracle/) and your Client ID / Secret as the Consumer key / secret. Set User matching mode to Link to a user with identical email address. Your Oracle endpoint URLs follow this pattern (replace <your-idcs-instance> with your domain identifier):

Authorization URL: https://<your-idcs-instance>.identity.oraclecloud.com/oauth2/v1/authorize
Access token URL: https://<your-idcs-instance>.identity.oraclecloud.com/oauth2/v1/token
Profile URL: https://<your-idcs-instance>.identity.oraclecloud.com/oauth2/v1/userinfo

You can confirm them in your domain's discovery document at https://<your-idcs-instance>.identity.oraclecloud.com/.well-known/openid-configuration. Then add the source to the login page.

Note

All three endpoint URLs must be set explicitly. Do not rely solely on the OIDC Well-known URL to auto-populate them, or sign-in redirects loop back to Authentik.

Step 3 — Grant the Pixee admin role¶

Add admins to the pixee-admins group directly in Authentik, or set up Oracle group → admin sync below to promote members of an Oracle group automatically. See Granting the Pixee Admin Role for the details.

Oracle group to admin sync¶

Name an Oracle group pixee-admins, add your admins to it, and Authentik promotes its members to Pixee admin by matching the group name (name_link). Group sync is opt-in, because it depends on one extra OAuth scope:

Authentik reads a generic OIDC source's claims from the userinfo endpoint, and Oracle returns group membership there only when the groups scope is requested. Oracle documents the scope set for browser login flows as openid approles groups, whose access token "can be used with /oauth2/v1/userinfo to get the user's roles and groups". Requesting that scope set is therefore what turns sync on. Pixee only reads groups; approles is inert.

In your identity domain, create a group named exactly pixee-admins and add your admins as members. If one already exists, reuse it.
Confirm your identity domain offers the scope — it is available by default on a confidential application with no custom scopes defined, and Oracle documents no setting that grants it:
```
curl -s https://<your-idcs-instance>.identity.oraclecloud.com/.well-known/openid-configuration | jq '.scopes_supported'
```
Look for groups in the list. If it is absent, stop here — enabling sync would block sign-in (see the warning below).
Turn it on: pixee-idp enable-sync oracle (or set oracle_additional_scopes to approles groups in the blueprint Context and Apply).

A rejected scope blocks sign-in for everyone

The scope is sent to /oauth2/v1/authorize, so if your domain does not allow it, Oracle rejects the request with invalid_scope and no one can sign in. Turn it back off with pixee-idp enable-sync oracle --disable (or clear oracle_additional_scopes and Apply). With the scope off (the default), authentication always works. Pixee reads only groups; approles rides along because it is the scope set Oracle documents for browser login flows.

Once the scope is in place, group sync fails open: a user who is in no matching group still signs in, just without the admin role (grant pixee-admins by hand in Authentik).

Hand-granting stops working once sync has run

Authentik removes only the groups this source linked (groupsourceconnection__source), which is what protects hand-granted admins before sync is ever configured. But that source link is permanent: once Oracle has synced pixee-admins even once, a later login without the group claim strips the group again, and re-granting by hand will not survive the login after that. If sync breaks, restore the claim rather than re-granting.

Custom Claims cannot be used for this

Oracle's Custom Claims API adds claims to the access token or identity token (tokenType is AT, IT, or BOTH), never to the userinfo response. Because Authentik reads claims from userinfo, a custom groups claim never reaches it. Use the scope above instead.

Group sync requires the source created by the CLI or the blueprint

Oracle returns groups as a list of objects keyed id, name and $ref — for example {"id": "0db0…", "name": "pixee-admins", "$ref": "https://…/Groups/0db0…"} — rather than as plain group names, and Authentik cannot consume that form on its own. The blueprint ships a property mapping that normalizes it, and pixee-idp connect oracle binds that mapping for you.

A source you created by hand has no such mapping, so enabling group sync on it makes sign-in fail with a server error on the callback for every user who belongs to at least one Oracle group. Users who belong to no group are unaffected, which can make the problem look intermittent.

If you created the source by hand and want group sync, two things must be in place before you enable the scope:

Set the source's Group matching mode to Link to a group with identical name (name_link). The default matches on identifier instead, which makes Authentik try to create a group named pixee-admins; because that group already exists, the sign-in fails. The CLI and blueprint set this for you.
Build the mapping: Customization → Property Mappings → Create → OAuth Source Property Mapping, name it Pixee Oracle Groups, and copy the expression verbatim from the shipped Pixee - Oracle Identity Domains federation blueprint (Customize → Blueprints). Then add it under the Oracle source's User Property Mappings and Update. Copy the expression as-is rather than writing your own — the way it returns its result is deliberate and load-bearing, and is explained in the blueprint's comments.

Troubleshooting¶

"Permission denied" on login: Verify the Pixee application in Authentik is linked to the pixee provider. Check Applications → Pixee Enterprise Server → Provider assignment.
Redirect loop on Oracle login: Ensure the Authorization, Token, and Profile URLs are all explicitly set on the Oracle source. If any are blank, the redirect loops back to Authentik.
Oracle shows Authentik login button: Remove any Social Identity Provider entries for Authentik from Oracle under Security → Identity providers.
invalid_scope at Oracle after enabling group sync: your domain does not offer the scope to this application. Confirm with curl -s https://<your-idcs-instance>.identity.oraclecloud.com/.well-known/openid-configuration | jq '.scopes_supported'; if groups is absent, turn sync back off with pixee-idp enable-sync oracle --disable and grant the admin role in Authentik instead. If groups is offered but approles is not, narrow the request instead of abandoning sync: set oracle_additional_scopes to just groups in the blueprint Context and Apply. Pixee reads only groups, so a narrowed field is a fully working install — pixee-idp status oracle still reports group sync ON, and enable-sync oracle leaves it alone rather than restoring the pair your domain rejects. Sign-in is blocked for everyone until you do one or the other.
Sign-in works but no one becomes an admin: group sync is probably off (the default). pixee-idp status oracle reports additional_scopes and whether group sync is on. Also check that the Oracle group is named exactly pixee-admins and that group_matching_mode is name_link.
Server error on the callback after enabling group sync: the source is missing the groups property mapping, or its Group matching mode is not name_link. This affects only users who belong to at least one Oracle group, so it can look intermittent. Sources created by pixee-idp connect oracle or by the blueprint have both; a hand-created source needs them added (see Oracle group to admin sync).

LDAP¶

Pixee Enterprise Server supports LDAP directories as an authentication source through Authentik's LDAP federation. Users authenticate with their existing LDAP credentials — Authentik verifies passwords directly against the LDAP server and syncs user accounts automatically.

Prerequisites¶

Gather the following from your LDAP administrator:

Server URL: ldap://ldap.example.com or ldaps://ldap.example.com (LDAPS recommended for production)
Bind DN: A service account DN for searching the directory (e.g., cn=svc-pixee,ou=service-accounts,dc=example,dc=com)
Bind Password: Password for the service account
Base DN: Where to search for users (e.g., dc=example,dc=com)
User Object Filter: LDAP filter for user objects (e.g., (objectClass=person))
Group Object Filter: LDAP filter for group objects (e.g., (objectClass=groupOfUniqueNames))

Network Access

The Pixee Enterprise Server cluster must be able to reach the LDAP server. The default ports are 389 (LDAP) and 636 (LDAPS), but non-standard ports are supported via the Server URI (e.g., ldap://ldap.example.com:3389). Verify network connectivity and firewall rules before configuring.

Step 1: Create an LDAP Source in Authentik¶

In the Authentik admin interface, go to Directory → Federation and Social login → Create → LDAP Source
Configure the connection settings:
- Name: A descriptive name (e.g., Corporate LDAP)
- Slug: ldap (or a descriptive slug like corporate-ldap)
- Server URI: Your LDAP server URL (e.g., ldaps://ldap.example.com)
- Bind CN: The service account DN
- Bind Password: The service account password
- Base DN: The search base for your directory (e.g., dc=example,dc=com)
Configure the search settings:
- User Property Mappings: Select all the default LDAP property mappings (these map LDAP attributes to Authentik user fields)
- Group Property Mappings: Select the default LDAP group property mappings
- User object filter: LDAP filter for user objects (e.g., (objectClass=person)) — adjust for your directory
- Group object filter: LDAP filter for group objects (e.g., (objectClass=groupOfUniqueNames)) — adjust for your directory
- Group membership field: member (or uniqueMember depending on your directory schema)
- Object uniqueness field: uid (adjust for your directory)
Under password settings, ensure the following are disabled:
- Update internal password on login: When enabled, Authentik stores a copy of the user's LDAP password internally. Disable this so that passwords are always verified directly against the LDAP server.
- User password writeback: When enabled, password changes in Authentik are written back to the LDAP server. Disable this unless you want users to change their LDAP password through Authentik.
Click Create

Step 2: Verify User Sync¶

After creating the LDAP source, trigger a sync and verify:

Go to Directory → Federation and Social login, click on your LDAP source, and click Run sync
Go to Directory → Users and verify that LDAP users have been imported
Go to Directory → Groups and verify that LDAP groups have been imported

If users are not appearing after sync, check the sync logs:

In the Authentik admin interface, go to Events → Logs
Look for entries with action configuration_error — these indicate sync failures with details about what went wrong
Alternatively, check the Authentik worker pod logs directly:
```
kubectl logs -n <namespace> deploy/<release-name>-authentik-worker --tail=200 | grep -i "ldap\|configuration_error\|username"
```
Common errors in the logs include:
- "Username was not set by propertymappings": Ensure a property mapping that sets the username field is selected on the LDAP source under User Property Mappings
- "Could not find page in cache": The sync pagination timed out — try running the sync again, or increase the ldap.task_timeout_hours setting
- "LDAPServerPoolExhaustedError": Authentik cannot connect to the LDAP server — check network connectivity and TLS settings

Sync Schedule

By default, Authentik syncs LDAP users and groups periodically (every 120 minutes). You can trigger a manual sync at any time from the LDAP source configuration page. Adjust the sync frequency in the LDAP source's Advanced settings if needed.

After creating the source, add it to the login page.

Once added, users will see an LDAP login option. When a user enters their LDAP credentials, Authentik authenticates them directly against the LDAP server.

How LDAP Authentication Works

When users log in via the LDAP source, Authentik performs a bind operation against the LDAP server using the user's credentials. With the recommended password settings above (both disabled), passwords are not stored in Authentik and are always verified directly against the LDAP server. If a user changes their LDAP password, the change takes effect immediately.

Troubleshooting¶

"Connection refused" or timeout: Verify network connectivity from the cluster to the LDAP server. Check that the correct port (389 for LDAP, 636 for LDAPS) is open.
"Invalid credentials" on bind: Verify the Bind DN and password.
"Username was not set by propertymappings": Ensure a property mapping that sets the username field is selected on the LDAP source under User Property Mappings.
No users synced: Check the Base DN and user object filter. Use ldapsearch to verify the filter returns results from outside the cluster.
Users synced but cannot log in: Ensure the LDAP source is added to the login page identification stage (see Adding a Source to the Login Page).
"Permission denied" after LDAP login: Verify the Pixee application in Authentik is linked to the pixee provider. Check Applications > Pixee Enterprise Server > Provider assignment.
TLS/certificate errors with LDAPS: If using a self-signed or internal CA certificate, you may need to add the CA certificate to the Authentik server's trust store.

By default, the Authentik sign-in form does not show a "Forgot password?" link. Administrators can always trigger a password reset for any user from the Authentik admin console (Directory → Users → \<user> → Copy recovery link / Send recovery link via email) without any additional configuration — that path works out of the box.

To let end users self-service password recovery directly from the sign-in form, link the bundled pixee-recovery-flow to the identification stage:

In the Authentik admin interface, go to Flows and Stages → Stages
Edit default-authentication-identification
Under Flow settings, set Recovery flow to Password Recovery (pixee-recovery-flow)
Click Update to save

The "Forgot password?" link will now appear on the sign-in form. Clicking it walks the user through email-based password recovery.

SMTP required for email recovery

Self-service password recovery delivers a one-time-use reset link by email. Configure SMTP in the admin console (Config → SMTP / Email Settings) before enabling this link — otherwise users who click "Forgot password?" will hit a stage that cannot send mail. Administrator-triggered recovery via the admin console works regardless, but only the Send recovery link via email button needs SMTP; Copy recovery link always works.

Federated users

If users sign in through an external identity provider (Entra, Okta, etc.), they reset their password at the upstream provider — Authentik's password recovery only applies to local Authentik accounts (e.g. akadmin, breakglass accounts). For federated-only installs you can skip this step.

Auto-Redirect to Identity Provider¶

By default, when a federated identity provider is added as a source, users see the Authentik login page with both username/password fields and the identity provider button. To skip this page and redirect users directly to the identity provider, clear the identification stage's user fields (with no user fields and exactly one source, Authentik redirects automatically).

Auto-redirect cannot be a blueprint

This step must be done with the CLI or the UI stage editor — not a downloadable/shipped blueprint. Authentik's blueprint apply merges the stage's user_fields, so a blueprint can never clear them; only a direct edit (which both the CLI and the UI stage editor perform) can.

CLI (pixee-idp)Authentik UI

pixee-idp auto-redirect            # enable — clears the form, redirects to the sole source
pixee-idp auto-redirect disable    # revert — restores the username form (source stays a button)

It guards first (exactly one source, the local-admin escape-hatch flow exists, no passwordless flow), then clears user_fields and binds the source.

Flows and Stages → Stages → edit default-authentication-identification
Under User fields, deselect all (remove Username, Email, etc.)
Under Sources, ensure only the identity provider source is selected
Ensure Passwordless flow is not set — auto-redirect only works when this is empty
Click Update

Bookmark the local-admin escape hatch first

Once auto-redirect is on, the normal login page goes straight to the IdP, so local accounts (e.g. akadmin) can no longer use it. They sign in at the chart-provisioned direct-login flow instead: https://<your-domain>/authentik/if/flow/direct-authentication-flow/. Bookmark it before enabling.

SAML Binding Type

For SAML sources, ensure the Binding Type on the source is set to Redirect rather than POST. With Redirect binding, Authentik performs a direct HTTP 302 to the identity provider. POST binding requires an intermediate page to submit the SAML request form.

Multiple Identity Providers

If more than one source is configured on the identification stage, auto-redirect is disabled and users will see a source selection page instead.

When auto-redirect is enabled, administrators who need to log in with username/password (e.g., the akadmin account) can no longer use the default login page. The chart automatically provisions a dedicated direct-login flow for this purpose, so no manual setup is required.

Administrators can log in directly at:

https://<your-domain>/authentik/if/flow/direct-authentication-flow/

The admin console shows this link for your deployment under Config → Authentication, next to the default admin credentials.

This flow presents a username/password form with no identity provider sources, so it bypasses the auto-redirect configured on the default flow. It reuses the built-in MFA validation and login stages.

Every login goes through Authentik, so pick the tab matching what you are seeing. In the commands below, <release-name> is pixee-enterprise-server on an embedded cluster and <namespace> is kotsadm.

Sent to your IdPLost akadmin passwordAuthentik unhealthyBreak glass

Symptom: the login page redirects straight to your identity provider, and you need a local account instead. Common when your IdP is down, or when your own account there cannot get in.

Authentik is healthy here; only the login page is sending you upstream. Sign in at the direct login flow, which presents a username/password form with no identity provider sources:

https://<your-domain>/authentik/if/flow/direct-authentication-flow/

Symptom: you can reach an Authentik login form but no password you have works.

Generate a one-time recovery link for akadmin, valid for 30 minutes. This works from outside the browser and needs no SMTP, so it is also the answer when password reset email is not configured:

kubectl exec -n <namespace> deploy/<release-name>-authentik-server -- \
  ak create_recovery_key 30 akadmin

Open the printed URL to set a new password.

Symptom: the login page errors, hangs, or never loads. Usually the server cannot reach its PostgreSQL database or its Valkey cache.

Every other recovery route goes through Authentik, so confirm this is what you are looking at first:

kubectl get pods -n <namespace> -l app.kubernetes.io/name=authentik
kubectl exec -n <namespace> deploy/<release-name>-platform -- \
  curl -sS -o /dev/null -w '%{http_code}\n' \
  http://<release-name>-authentik-server/authentik/-/health/ready/

A readiness response of 204 means Authentik is fine and your problem is one of the other tabs. Anything else, or no response at all, means it cannot serve logins.

The Authentik server logs usually name the cause. A support bundle runs this same check as "Verify Authentik is ready to serve logins" and collects those logs alongside it:

kubectl logs -n <namespace> deploy/<release-name>-authentik-server --tail=100

If the database is the problem, the bundle's database analyzer and the CloudNativePG cluster status are the next place to look. Repair Authentik and logins resume with no further action. If you need access to Pixee before you can repair it, see the Break glass tab.

Use only when Authentik cannot be repaired quickly and you need access now. Every option in the other tabs requires a working Authentik, so this is the one route that does not.

Start the platform with authentication turned off:

kubectl set env -n <namespace> deploy/<release-name>-platform \
  PIXEE_AUTHENTICATION_ENABLED=false PIXEE_ACCESS_ENABLED=false

The platform restarts and serves without a login. Authentik keeps running untouched, so you can carry on repairing it.

This removes all authentication

While those variables are set, anyone who can reach the deployment has full access and requests are attributable to nobody. Treat it as an outage measure on a trusted network, restore authentication as soon as Authentik is healthy, and review the platform audit trail afterwards for anything that happened during the window.

Restore authentication by removing the override:

kubectl set env -n <namespace> deploy/<release-name>-platform \
  PIXEE_AUTHENTICATION_ENABLED- PIXEE_ACCESS_ENABLED-

Deploying again from the admin console also restores it, because the Deployment is re-rendered from your saved configuration. That is deliberate: the override cannot outlive the next deploy, so a deployment cannot be left permanently unauthenticated by forgetting to undo this. It also means an upgrade landing while you are still repairing Authentik will re-enable authentication and lock you out again, so finish the repair before deploying.

Authentication¶

Embedded Identity Provider (Authentik)¶

Features¶

Configuration¶

Initial Setup¶

Admin Access — the pixee-admins Group¶

Default membership¶

Adding a user to pixee-admins¶

Enforcing the admin role¶

User Management¶

Creating Users¶

Editing and Deleting Users¶

Federating External Identity Providers¶

Choosing a setup method¶

The pixee-idp CLI¶

Adding a Source to the Login Page¶

Granting the Pixee Admin Role¶

Federated Users Are Made Internal Automatically¶

Disable Self-Service for Federated Users¶

Optional: Customize Username Derivation¶

Troubleshooting Property Mappings¶

Google OAuth¶

Step 1 — Create the OAuth client in Google Cloud (all methods)¶

Step 2 — Create the source and add it to the login page¶

Step 3 — Grant the Pixee admin role¶

Google Workspace group to admin sync¶

Notes & limitations¶

Okta (OAuth)¶

Step 1 — Create the OIDC app in Okta (all methods)¶

Step 2 — Create the source and add it to the login page¶

Step 3 — Grant the Pixee admin role¶

Okta group to admin sync¶

Microsoft Entra ID (OAuth)¶

Step 1: Create the Entra app registration (all methods)¶

Step 2: Create the source and add it to the login page¶

Step 3: Grant the Pixee admin role¶

Entra group to admin sync¶

Google Workspace (SAML)¶

Step 1: Create a SAML App in Google Workspace¶

Step 2: Create a SAML Source in Authentik¶

Troubleshooting¶

Oracle Identity Domains (OAuth)¶

Step 1 — Create the confidential application in Oracle (all methods)¶

Step 2 — Create the source and add it to the login page¶

Step 3 — Grant the Pixee admin role¶

Oracle group to admin sync¶

Troubleshooting¶

LDAP¶

Prerequisites¶

Step 1: Create an LDAP Source in Authentik¶

Step 2: Verify User Sync¶

Step 3: Add LDAP to the Login Page¶

Troubleshooting¶

Enable "Forgot Password?" Link on the Login Page¶

Auto-Redirect to Identity Provider¶

Direct Login for Administrators¶

Recovering Access When You Cannot Sign In¶

Admin Access — the `pixee-admins` Group¶

Adding a user to `pixee-admins`¶

The `pixee-idp` CLI¶