Authenticating Scaling Groups

---

Use Chalk as an identity provider (IdP) to let users sign into applications running on scaling groups with their Chalk account. Your application integrates with Chalk through OpenID Connect (OIDC), using the authorization code flow. You can share one client registration across your team’s native Chalk scaling groups, including groups you create later.

Your application handles the login redirect, callback, and user session through its OIDC library. Registering a client does not automatically add login handling to your application. For API callers that send a Chalk access token with each request, see Authentication. For a workload’s own identity when calling Chalk APIs, see Workload Identity.

​

Register a shared client

As a team administrator, open Settings > Identity Providers in the dashboard and create an IdP client:

1. Give the client a name, such as Scaling group applications.
2. Select Allow all scaling group URLs.
3. Under Scaling group redirect paths, enter /idp/authorize.
4. Leave Allowed environment IDs empty to allow all team environments, or enter the environment IDs that applications should be allowed to request.
5. Keep Public client (PKCE only, no client secret) unchecked for a server application that can hold a client secret.
6. Create the client and save its Client ID, Client Secret, and Issuer. The client secret is shown only once.

We recommend Allow all scaling group URLs for applications you manage on Chalk. Chalk checks the callback against your team’s current scaling group URLs and the configured redirect paths, so you do not need to register each group’s full URL separately. Use Redirect URIs for additional explicit callbacks, such as a local development URL.

​

Use a consistent callback path

We recommend implementing /idp/authorize as the callback route in every application. Set each application’s OIDC redirect URI to its own scaling group web_url followed by that path:

<scaling-group-web-url>/idp/authorize

For example, two applications can use the same client registration and callback path while receiving callbacks at their own hosts. Enter only /idp/authorize in Scaling group redirect paths; configure the full URL in each application. The path must match exactly and must not contain a query string or fragment.

The callback is a route in your application. Chalk’s authorization endpoint also ends in /idp/authorize, but lives on the Chalk API host. Send users to the authorization endpoint to start login; Chalk sends them back to your application’s callback with an authorization code.

​

Share the client credentials

Store the client ID and secret as shared Chalk secrets, then reference those secrets from each scaling group. This lets applications reuse the registration without copying credentials into source code or container images.

For example, save secrets named CHALK_IDP_CLIENT_ID and CHALK_IDP_CLIENT_SECRET, then add them to your existing scaling group definition:

import chalkcompute

# image is your application's image, including its OIDC login and callback routes.
sg = chalkcompute.ScalingGroup(
    name="internal-app",
    image=image,
    port=8080,
    secrets=[
        chalkcompute.Secret.from_chalk_env("CHALK_IDP_CLIENT_ID"),
        chalkcompute.Secret.from_chalk_env("CHALK_IDP_CLIENT_SECRET"),
    ],
).deploy()

Configure your application’s OIDC library to read these environment variables as its client ID and client secret. These names are an application convention; injecting them alone does not configure login. Make the secrets available in each environment where you deploy the applications. See Secrets for injection and aliasing options.

Keep the client secret in server-side code. Share this client only among applications you trust with the same credentials; use separate registrations when applications need independent credentials or revocation.

​

Configure the provider URLs

Use the Issuer shown in the client details to configure OIDC discovery. For Chalk’s hosted API, the endpoints are:

Setting	URL
Issuer	https://api.chalk.ai/idp
Discovery	https://api.chalk.ai/idp/.well-known/openid-configuration
Authorization	https://api.chalk.ai/idp/authorize
Token	https://api.chalk.ai/idp/token
User info	https://api.chalk.ai/idp/userinfo
Signing keys	https://api.chalk.ai/idp/jwks.json

For customer-hosted clouds, the authorization URL changes to your cloud’s Chalk API host. Use the issuer from your deployment’s dashboard, rather than hardcoding api.chalk.ai. For an issuer of https://<your-chalk-api-host>/idp, the authorization URL is https://<your-chalk-api-host>/idp/authorize. Discovery, token, user info, and signing-key URLs use that deployment’s host as well. Prefer discovery so your OIDC library reads the endpoints from the provider.

Configure the authorization code flow with the openid scope. Add email and profile if your application needs those user details. To request an identity scoped to a particular Chalk environment, add chalk:env:<environment_id>; the environment must be permitted by the client configuration and accessible to the user.

Your OIDC library should manage state, nonce, and PKCE, exchange the code on the server, validate the returned ID token against the provider’s issuer, audience, and signing keys, and establish your application’s session. Keep the callback reachable during login so that it can receive the authorization response before a user has an application session.