Configure authentication

Either point your install at Dibbla's hosted auth, or run the Auth Service in your cluster.

The Dibbla platform has a single auth contract — a token signed by an Auth Service, validated against <auth-service-url>/api/v1/tokens/validate. Where that Auth Service runs is up to you.

Pick a path

Most teams start with hosted auth and only move to self-hosted when a compliance or air-gap requirement forces it.

Use Dibbla’s hosted auth

End state: users in your cluster sign in at app.dibbla.com with Dibbla’s app registration; tokens issued there are accepted by your platform services.

1. Create your org on Dibbla

Sign in at app.dibbla.com with the email you want as the owner. Create an org via the dashboard (or POST /api/v1/orgs with {"name": "Your Org"}). The org’s slug is what you’ll use everywhere below.

2. Mint a long-lived API token

In Settings → API tokens, create a token. This is what your platform services and your CLI will both use.

3. Point your Helm install at hosted auth

Override the platform services’ AUTH_SERVICE_URL so they validate tokens against app.dibbla.com instead of an in-cluster auth service:

api-gateway:
  env:
    AUTH_SERVICE_URL: https://app.dibbla.com
    AUTH_LOGIN_URL: https://app.dibbla.com

deploy-api:
  env:
    AUTH_SERVICE_URL: https://app.dibbla.com

You can also drop the in-cluster auth-service workload, the bundled Postgres, and Redis since nothing inside your cluster needs them. The Helm chart doesn’t yet expose a clean auth-service.enabled: false toggle — until it does, you have two options:

• Leave the bundled services running and just ignore them. They consume resources but don’t interfere; the env-var overrides above are what matters.
• Apply a Kustomize overlay after helm template that strips the auth-service Deployment, the bundled postgresql StatefulSet, and the redis workloads.

4. Configure the CLI

dibbla login --api-url https://your-platform.example.com --api-key dib_…

The CLI talks to your platform; your platform validates the token against Dibbla’s hosted auth.

5. How sign-in feels for your users

1. User opens an app at https://my-app.example.com.
2. The API Gateway redirects them to https://app.dibbla.com (because AUTH_LOGIN_URL points there).
3. They sign in with Google or Microsoft using Dibbla’s app registration.
4. They’re redirected back to my-app.example.com with a Dibbla-issued token.
5. Your API Gateway validates the token against https://app.dibbla.com/api/v1/tokens/validate and lets them through.

Self-host the auth service

End state: a fully self-contained install. No outbound dependency on Dibbla; you own the OAuth client and the signing keys.

1. Register an OAuth client

In the Google Cloud Console, create an OAuth client ID of type Web application. Authorized redirect URI:

https://app.example.com/auth/google/callback

Replace app.example.com with whatever you set for auth-service.redirectBaseUrl. Capture the client ID and client secret.

(Microsoft Entra works similarly — see Microsoft Entra (Azure AD) below for the env var shape.)

2. Generate signing keys

openssl rand -hex 32   # JWT secret
openssl rand -hex 32   # Signing key

3. Set Helm values

auth-service:
  google:
    clientId: <your-oauth-client-id>
    clientSecret: <your-oauth-client-secret>
  jwt:
    secret: <your-jwt-secret>
  signingKey: <your-signing-key>
  redirectBaseUrl: https://app.example.com
  allowedRedirectBaseUrls: https://app.example.com

allowedRedirectBaseUrls is comma-separated. Add additional UIs (the deploy UI on a different host, an internal console, etc.) here so the callback can return users to the correct origin.

4. Create the first organization and admin user

Once the platform is running, curl the admin endpoint:

curl -X POST https://api.example.com/api/v1/admin/orgs \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Your Org",
    "domains": ["example.com"],
    "admin_email": "[email protected]",
    "admin_name": "Your Name"
  }'

Fields:

• name (required) — display name. The slug is derived from this.
• domains (optional) — email domains that auto-join this organization on first sign-in.
• admin_email, admin_name (optional) — when present, the admin is granted the owner role on the new org. If a user with this email already exists, they’re added to the org instead of recreated.

The first user signs in via the OAuth flow at https://app.example.com — Google redirects to your callback URL, the Auth Service issues a session, and the user lands in the dashboard with owner permissions on the org you just created.

5. Configure the CLI

dibbla login --api-url https://api.example.com --api-key dib_…

Microsoft Entra (Azure AD)

Microsoft sign-in is a first-class chart value alongside Google. Add the auth-service.microsoft block to values.yaml:

auth-service:
  google:
    clientId: <your-google-client-id>
    clientSecret: <your-google-client-secret>
  microsoft:
    clientId: <your-ms-client-id>
    clientSecret: <your-ms-client-secret>
    tenantId: <your-ms-tenant-id> # UUID, or "common" / "organizations" / "consumers"

Either provider alone, or both side-by-side. In the Microsoft Entra portal: App registrations → New registration → Web → Redirect URI https://app.<base-domain>/auth/microsoft/callback. Capture the Application (client) ID, generate a client secret under Certificates & secrets, and use either the Directory (tenant) ID or one of the special values (common for any account, organizations for any work/school account, consumers for personal MSAs only).

The chart wires MICROSOFT_CLIENT_ID / MICROSOFT_CLIENT_SECRET / MICROSOFT_TENANT_ID into the auth-service Deployment automatically.

What happens on subsequent sign-ins

• Users whose email domain matches an org’s domains list are auto-joined as a regular member on first sign-in.
• Users without a matching domain need to be invited explicitly by an org owner.
• Every API call from dibbla carries the user’s JWT (or an API token), and the API Gateway validates it against whichever Auth Service AUTH_SERVICE_URL points at.

Workload identity (workers & tool servers)

Apps deployed on your install that use the Go worker SDK authenticate to the workflow engine automatically — with no API token. The platform mints a workload identity for every deployment: a projected, auto-rotating Kubernetes ServiceAccount token that the SDK (v0.0.18+) picks up and presents on connect. The Auth Service validates it against your cluster’s TokenReview API and resolves which organization and deployment is calling. There is nothing for your users to provision, rotate, or leak — and an expired-token outage is structurally impossible.

Requirements (all defaults — listed for completeness):

• Chart ≥ 0.5.0 with auth-service.rbac.create: true (the default). This grants the Auth Service the two permissions it needs: tokenreviews create and serviceaccounts get.
• The token audience must agree between the two services. Both default to dibbla-control-plane; override with deploy-api env DIBBLA_WORKLOAD_AUDIENCE and auth-service env WORKLOAD_AUDIENCE — always together.
• To disable the feature entirely: set WORKLOAD_IDENTITY_ENABLED=false on the Auth Service and DIBBLA_WORKLOAD_AUDIENCE="" on Deploy API. Workers then need a personal API token (ak_…) as before.

Local development is unchanged: a worker running outside the cluster sets SERVER_API_TOKEN to a personal API token from the console, which always takes precedence.