Authentication

Union.ai self-hosted deployments use OpenID Connect (OIDC) for user authentication and OAuth 2.0 for service-to-service authorization.

Unlike serverless and BYOC deployments where Union.ai manages authentication for you, self-hosted deployments require you to create and manage OAuth applications in your own identity provider (e.g. Okta, Microsoft Entra ID, Google Workspace, or any OIDC-compliant provider). Union.ai does not provision or manage these applications — you are responsible for their lifecycle, credential rotation, and access policies.

Overview

Self-hosted authentication requires creating five OAuth2 client applications in your own identity provider (plus an optional sixth for CI/CD). Each application serves a different authentication flow:

Identity provider requirements

You must use an OIDC-compliant identity provider that you manage outside of Union.ai. Any standards-compliant provider will work. Union.ai uses Okta for its internal deployments, but you can use whichever provider your organization already uses.

Your identity provider must support:

1. OpenID Connect Discovery — /.well-known/openid-configuration or /.well-known/oauth-authorization-server endpoint
2. Authorization Code flow — for browser and CLI login
3. Client Credentials flow — for service-to-service tokens
4. PKCE (Proof Key for Code Exchange) — for the CLI public client
5. Custom scopes — ability to create an all scope (or equivalent)
6. Custom claims — ability to emit sub and preferred_username claims in access tokens. An identity type claim (identitytype or equivalent) is recommended for authorization.

Authorization server setup

Create a custom authorization server (or equivalent) in your identity provider. The setup differs by provider:

Identity type claim requirements

Union.ai uses an identity type claim to distinguish human users from service applications. This distinction is required for Union (built-in RBAC) authorization and affects how access control decisions are made.

Your IdP must emit a claim that maps to the identitytype concept, with values that distinguish user tokens from application tokens. The claim name and values are configurable:

Subject claim requirements

Union.ai uses the JWT sub claim as the primary identifier for all callers — users and service accounts alike. This value is used for:

• Authorization decisions — matching callers to roles and permissions
• Trusted identity validation — verifying internal service-to-service callers
• Audit logging — recording who performed each action
• Resource ownership — the “Owned By” relationship in the console

Your IdP must emit a sub claim in all access tokens. If your IdP’s client_credentials tokens use a different claim for the caller identity (or omit sub entirely), configure subjectClaimNames to specify a fallback chain:

# In flyte.configmap.adminServer.auth.appAuth.externalAuthServer:
subjectClaimNames:
  - sub          # Standard OIDC subject (tried first)
  - client_id    # OAuth2 client ID (common fallback)
  - azp          # Authorized party (alternative)

The platform tries each claim in order and uses the first non-empty value as the caller’s identity.

Step 1: Create OAuth2 applications

Application 1: Browser login (Confidential)

Used by the web console for user authentication.

Note the Client ID (set as flyte.configmap.adminServer.auth.userAuth.openId.clientId) and the Client Secret (stored in the dedicated flyteadmin-oidc-client-secret Secret under the key client_secret, read via userAuth.openId.clientSecretFile — see Step 3).

Application 2: CLI (Public)

Used by uctl and flytectl for CLI-based authentication with PKCE.

Note the Client ID (set as flyte.configmap.adminServer.auth.appAuth.thirdPartyConfig.flyteClient.clientId).

Application 3: Service-to-service (Confidential)

Used by control plane services (executions, cluster, identity, etc.) to authenticate with each other through NGINX when OIDC is enabled.

Note the Client ID (used as INTERNAL_CLIENT_ID) and the Client Secret (stored in Kubernetes secrets).

Application 4: Operator (Confidential)

Used by data plane services (operator, propeller, cluster-resource-sync) to authenticate to the control plane.

Note the Client ID (used as AUTH_CLIENT_ID in data plane configuration) and the Client Secret (stored in Kubernetes secrets).

Application 5: EAGER (Confidential)

Used for task pod authentication. The encoded credentials form the EAGER_API_KEY.

Note the Client ID and Client Secret — these are encoded into the EAGER_API_KEY.

Step 2: Configure control plane

Authentication is configured in the flyte.configmap.adminServer.auth block in your control plane Helm values. This block defines how the admin service validates tokens, which clients are trusted, and how browser login works.

You also need to set a few global variables for service-to-service authentication:

global:
  INTERNAL_CLIENT_ID: "<service-to-service-client-id>"  # App 3
  AUTH_TOKEN_URL: "<token-endpoint-url>"                 # OAuth2 token endpoint
  OIDC_S2S_SCOPE: ""                                    # Leave empty for Okta, set to "api://<app>/.default" for Entra ID

Then configure the auth block. Select your identity provider below:

flyte:
  configmap:
    adminServer:
      server:
        security:
          useAuth: true
      auth:
        appAuth:
          authServerType: External
          externalAuthServer:
            baseUrl: "https://dev-123456.okta.com/oauth2/default"
            metadataUrl: ".well-known/oauth-authorization-server"
            allowedAudience:
              - "https://<your-domain>"
          thirdPartyConfig:
            flyteClient:
              clientId: "<cli-client-id>"           # App 2
              redirectUri: "http://localhost:53593/callback"
              scopes:
                - all
        userAuth:
          openId:
            baseUrl: "https://dev-123456.okta.com/oauth2/default"
            clientId: "<browser-login-client-id>"   # App 1
            scopes:
              - profile
              - openid
              - offline_access
          cookieSetting:
            sameSitePolicy: LaxMode
            domain: "<your-domain>"

global:
  INTERNAL_CLIENT_ID: "<service-to-service-client-id>"
  AUTH_TOKEN_URL: "https://dev-123456.okta.com/oauth2/default/v1/token"
  OIDC_S2S_SCOPE: ""   # Okta defaults to "all"

flyte:
  configmap:
    adminServer:
      server:
        security:
          useAuth: true
      auth:
        appAuth:
          authServerType: External
          externalAuthServer:
            baseUrl: "https://login.microsoftonline.com/<tenant-id>/v2.0"
            metadataUrl: ".well-known/openid-configuration"
            allowedAudience:
              - "api://<app-name>"
              - "<browser-login-client-id>"    # App 1 Client ID
          identityTypeClaimsForApps:
            idtyp:
              - app
          thirdPartyConfig:
            flyteClient:
              clientId: "<cli-client-id>"           # App 2
              redirectUri: "http://localhost:53593/callback"
              scopes:
                - "api://<app-name>/.default"
              audience: "api://<app-name>"
        userAuth:
          openId:
            baseUrl: "https://login.microsoftonline.com/<tenant-id>/v2.0"
            clientId: "<browser-login-client-id>"   # App 1
            scopes:
              - profile
              - openid
              - offline_access
          cookieSetting:
            sameSitePolicy: LaxMode
            domain: "<your-domain>"
          idpQueryParameter: "idp"

global:
  INTERNAL_CLIENT_ID: "<service-to-service-client-id>"
  AUTH_TOKEN_URL: "https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token"
  OIDC_S2S_SCOPE: "api://<app-name>/.default"

flyte:
  configmap:
    adminServer:
      server:
        security:
          useAuth: true
      auth:
        appAuth:
          authServerType: External
          externalAuthServer:
            baseUrl: "<issuer-url>"
            metadataUrl: ".well-known/openid-configuration"
            allowedAudience:
              - "<audience>"
          thirdPartyConfig:
            flyteClient:
              clientId: "<cli-client-id>"           # App 2
              redirectUri: "http://localhost:53593/callback"
              scopes:
                - all
        userAuth:
          openId:
            baseUrl: "<issuer-url>"
            clientId: "<browser-login-client-id>"   # App 1
            scopes:
              - profile
              - openid
              - offline_access
          cookieSetting:
            sameSitePolicy: LaxMode
            domain: "<your-domain>"

global:
  INTERNAL_CLIENT_ID: "<service-to-service-client-id>"
  AUTH_TOKEN_URL: "<issuer-url>/token"      # Your IdP's token endpoint
  OIDC_S2S_SCOPE: ""                        # Set if your IdP requires a specific scope for client_credentials

            subjectClaimNames:
              - sub
              - client_id
              - azp

Step 3: Create Kubernetes secrets (control plane)

The control plane needs secrets for the browser login app (App 1) and the service-to-service app (App 3):

# Browser-login (App 1) OIDC client secret, in its own dedicated secret.
# flyteadmin reads it via userAuth.openId.clientSecretFile (configured below).
kubectl create secret generic flyteadmin-oidc-client-secret \
  --from-literal=client_secret='<BROWSER_LOGIN_CLIENT_SECRET>' \
  -n <controlplane-namespace>

# Add service-to-service client secret to the controlplane secrets
kubectl create secret generic <controlplane-secrets> \
  --from-literal=pass.txt='<DB_PASSWORD>' \
  --from-literal=client_secret='<SERVICE_TO_SERVICE_CLIENT_SECRET>' \
  -n <controlplane-namespace> --dry-run=client -o yaml | kubectl apply -f -

Point flyteadmin at the browser-login secret by mounting it and setting clientSecretFile in your control plane values (see the chart’s examples/values.oidc-client-secret.yaml):

flyte:
  flyteadmin:
    # additionalVolumes / additionalVolumeMounts are list-valued (Helm replaces,
    # not merges) — keep any chart-default entries you rely on alongside this one.
    additionalVolumes:
      - name: oauth-client-secret
        secret:
          secretName: flyteadmin-oidc-client-secret
    additionalVolumeMounts:
      - name: oauth-client-secret
        mountPath: /etc/secrets/oauth
        readOnly: true
  configmap:
    adminServer:
      auth:
        userAuth:
          openId:
            clientSecretFile: /etc/secrets/oauth/client_secret

Step 4: Configure data plane

Add the operator client ID to your data plane overrides file:

global:
  AUTH_CLIENT_ID: "<operator-client-id>"  # App 4

Create the data plane auth secret:

kubectl create secret generic union-secret-auth \
  --from-literal=client_secret='<OPERATOR_CLIENT_SECRET>' \
  -n <dataplane-namespace>

Step 5: Configure EAGER_API_KEY

The EAGER_API_KEY is a base64-encoded string containing the EAGER app credentials. It enables task pods to authenticate to the control plane.

Generate the key:

# Format: base64("<domain>:<eager-client-id>:<eager-client-secret>:")
echo -n "<your-domain>:<eager-client-id>:<eager-client-secret>:" | base64

Create the Kubernetes secret in the data plane namespace:

kubectl create secret generic <eager-secret-name> \
  --from-literal=<eager-secret-key>='<BASE64_ENCODED_EAGER_API_KEY>' \
  -n <dataplane-namespace>

Provision the task-pod key automatically with the operator

Rather than encoding the EAGER_API_KEY and creating the data plane secret by hand, you can let the data plane operator mint it and write it to the task-pod secret store, where the pod webhook injects it into task pods. Enable it in the data plane Helm values:

config:
  operator:
    apiKey:
      enabled: true

This relies on the embedded Kubernetes secret manager (proxy.secretManager.enabled, enabled by default). The operator scopes the key to its own cluster, so in a multi-data-plane organization each data plane provisions and rotates its own EAGER_API_KEY without overwriting another’s. With this enabled you skip the manual base64 encoding and kubectl create secret steps above.

Seed EAGER credentials without creating an OAuth app (apiKeyOverrides)

Some identity providers cannot create service (client_credentials) OAuth applications programmatically, or you may run a control plane with no identity-provider integration at all. In that case the control plane cannot register an EAGER client on demand when a task pod requests its key.

Instead of registering an app, seed the EAGER client credentials as a Kubernetes Secret and point the identity service at it with apiKeyOverrides. When a key request matches an override, the identity service returns the seeded credentials from the mounted Secret rather than creating a new OAuth application in your IdP.

Configure overrides in your control plane Helm values:

services:
  identity:
    apiKeyOverrides:
      - key: EAGER_API_KEY
        existingSecret:
          name: eager-default-creds  # no clusterName — control-plane-wide fallback
      - key: EAGER_API_KEY
        clusterName: dp-1            # this override applies only to the dp-1 data plane
        existingSecret:
          name: eager-dp-1-creds     # Secret holding the seeded EAGER client credentials
      - key: EAGER_API_KEY
        clusterName: dp-2
        existingSecret:
          name: eager-dp-2-creds

• key — the system key to override (EAGER_API_KEY).
• clusterName (optional) — scopes the override to one data plane. A key request resolves on (organization, key, clusterName), preferring the entry that matches the requesting data plane’s cluster and falling back to a nameless entry (the control-plane-wide default, shown first above). With multiple data planes, give each its own clusterName entry and seeded Secret so their credentials stay independent.
• existingSecret.name — a Secret you create in the control plane namespace holding the seeded EAGER client’s ID and secret. By default the chart reads the keys client_id and client_secret; set clientIdKey / clientSecretKey if your Secret uses different keys.

Create one seeded Secret per data plane:

kubectl create secret generic eager-dp-1-creds \
  --from-literal=client_id='<EAGER_CLIENT_ID>' \
  --from-literal=client_secret='<EAGER_CLIENT_SECRET>' \
  -n <controlplane-namespace>

With an override in place you do not create App 5 in your IdP for that data plane — the seeded credentials serve its EAGER_API_KEY directly.

Step 6: Deploy

Deploy or upgrade both the control plane and data plane with the updated configurations:

# Upgrade control plane
helm upgrade unionai-controlplane unionai/controlplane \
  --namespace <controlplane-namespace> \
  -f values.<cloud>.yaml \
  -f my-overrides.yaml \
  --skip-crds --timeout 15m --wait

# Upgrade data plane
helm upgrade unionai-dataplane unionai/dataplane \
  --namespace <dataplane-namespace> \
  -f values.<cloud>.yaml \
  -f dataplane-overrides.yaml \
  --skip-crds --timeout 10m --wait

Verification

# Check admin service logs for auth initialization
kubectl logs -n <controlplane-namespace> deploy/<admin-service> | grep -i auth

# Test the /me endpoint (should return 401 without a token)
kubectl exec -n <controlplane-namespace> deploy/<admin-service> -- \
  curl -s -o /dev/null -w "%{http_code}" \
  https://<controlplane-ingress>.<controlplane-namespace>.svc.cluster.local/me -k

# Test CLI login
uctl config init --host https://<your-domain>
uctl get project

# Check data plane operator auth
kubectl logs -n <dataplane-namespace> -l app.kubernetes.io/name=operator --tail=50 | grep -i "token\|auth"

Summary of secrets

Self-hosted vs. self-managed authentication

Troubleshooting

Admin service auth endpoints return 404

Ensure useAuth: true is set under flyte.configmap.adminServer.server.security. Without this, the /login, /callback, and /me endpoints are not registered.

Token validation fails with “audience mismatch”

The allowedAudience in the admin service configuration must include https://<your-domain>. This should match the audience configured on your authorization server.

Data plane cannot authenticate to control plane

# Verify AUTH_CLIENT_ID is set
kubectl get configmap -n <dataplane-namespace> -o yaml | grep -i auth_client

# Check that union-secret-auth exists
kubectl get secret union-secret-auth -n <dataplane-namespace> \
  -o jsonpath='{.data.client_secret}' | base64 -d

# Check operator logs
kubectl logs -n <dataplane-namespace> -l app.kubernetes.io/name=operator --tail=50 \
  | grep -i "auth\|token\|401"

CLI login fails

Ensure the CLI app (App 2) redirect URIs include http://localhost:53593/callback and PKCE is enabled. Test with:

uctl config init --host https://<your-domain>
uctl get project

Entra ID: AADSTS1002012 invalid_scope for service-to-service

Client_credentials flows in Entra ID require the /.default scope. Ensure OIDC_S2S_SCOPE is set to api://<app-name>/.default in your globals.

Subject not found in token

If flyteadmin logs show subject claim not found, your IdP’s client_credentials tokens may not include a sub claim. Configure subjectClaimNames in the auth block to specify a fallback chain (e.g., ["sub", "client_id"]).