OIDC client setup

To integrate an application with FlexGalaxy identity, register it as an OIDC client in DotID. DotID issues OAuth 2.0 / OpenID Connect tokens that your application can exchange for an authenticated session, and your service can validate those tokens against the issuing realm’s JWKS endpoint.

This page covers registration, client types, and the conventions DotID enforces.

Register your application as an OIDC client

Platform operators register first-party clients through the admin console:

  1. Sign in to admin-console.flexgalaxy.ai/stargate with platform admin credentials.

  2. Open the Applications section and choose Register OIDC client.

  3. Fill in:

    • Client ID — a short, stable identifier (lower-kebab-case). This becomes the value of the client_id parameter in OAuth requests.

    • Display name — what users see on the consent screen.

    • Realm — which realm hosts the client (see Realms and which to register against below).

    • Client type — confidential or public.

    • Redirect URIs — exact-match URIs the client may receive auth codes at.

    • Allowed scopes — typically openid profile email plus any custom scope your service needs.

  4. On save, DotID returns the client ID and (for confidential clients) the client secret. Store the secret in your service’s secret manager — it is shown once.

Tenant administrators register account-scoped clients through their account-administration console, which forwards to the same backend with the tenant realm preselected.

Client types

DotID supports the two standard OAuth 2.0 client types.

Confidential clients

A confidential client runs server-side and can keep a secret. It authenticates to the token endpoint using its client_secret (or, for stricter setups, a private-key JWT). Use confidential clients for:

  • Backend services that exchange authorization codes server-side.

  • Service-to-service calls that use the client credentials grant.

  • Any flow where the client process is not exposed to end users.

Recommended baseline: confidential client + Authorization Code grant + PKCE with S256. The combination of a client secret and PKCE protects against both client-impersonation and code-interception attacks.

Public clients

A public client cannot keep a secret (browser SPAs, mobile apps, CLIs). It authenticates only by proving possession of the original PKCE code verifier. Configure as:

  • client_type: public

  • pkce_required: true

  • pkce_method: S256

DotID rejects authorization-code exchanges from public clients that do not include a PKCE verifier.

Realms and which to register against

DotID is multi-realm. Which realm hosts your client determines which users can sign in to it and which APIs trust the tokens it issues.

  • Platform-wide clients — register against the flexgalaxy realm. These are clients that any FlexGalaxy.AI user (across accounts) may sign in to.

  • Tenant clients — register against the per-account realm acc-<account-id>. These accept only users who belong to that specific account.

  • Identity Center clients — register against idc-<account-id>-<region>. These integrate with the account’s Identity Center for permission-set assumption flows.

  • Platform-administration clients — register against the flexgalaxy realm. The master realm is reserved for break-glass kcadm.sh access, not normal operator tooling.

See API authentication and JWT validation for which tokens your service should accept.

Redirect URIs

DotID enforces exact-match redirect URIs. A registered URI of https://app.example.com/oauth2/callback does not match https://app.example.com/oauth2/callback/ (note the trailing slash) or https://app.example.com/oauth2/callback?foo=bar (extra query). Register every URI variant your application actually uses.

Rules:

  • HTTPS is required for all production redirect URIs. http://localhost is permitted for local development only.

  • Wildcards are not allowed in redirect URIs.

  • The conventional callback path is /oauth2/callback. Stick to the convention unless you have a reason not to.

  • Loopback redirects for CLI/native flows should use http://127.0.0.1:<port>/callback (any port, exact path).

Scopes you can request

Scope

Effect

openid

Required for OIDC. Issues an ID token.

profile

Adds name, preferred_username, and other profile claims to the ID token.

email

Adds email and email_verified claims.

groups

Adds a groups array claim listing the user’s group memberships.

offline_access

Issues a refresh token. Required for long-running background processes.

Custom scopes (e.g. dotid:audit:read) can be defined per realm by platform operators. Request only the scopes your service genuinely needs — over-broad scope requests are flagged on the consent screen and erode user trust.

See API authentication and JWT validation for how to validate the tokens these scopes produce.