Skip to main content

Set up team login

The local AstraBox deployment does not require login. Before making AstraBox available to a team, connect it to an identity provider or place it behind an authentication gateway. Authentication establishes who the user is; authorization determines which AstraBox resources and operations that user can access.

Supported login methods​

A deployment uses one of these identity methods:

MethodHow it worksUse when
OIDCAstraBox redirects the browser to an identity provider and creates a signed login cookie after the user returnsPeople sign in to the AstraBox console through your identity provider
Trusted identity headersAn authentication gateway signs the user in and forwards their identity to AstraBoxThe gateway already protects all browser and API traffic
Verified JWTAstraBox verifies a bearer token and reads the configured user and group claimsExisting clients or a gateway already provide signed JWTs
LocalAstraBox uses one local administrator identity without loginOne-person use on a loopback-only installation

Do not expose the local method to another network. It provides no authentication.

With OIDC, AstraBox uses the Authorization Code flow with PKCE, verifies the ID Token, and returns a signed HttpOnly login cookie.

How a browser signs in to AstraBox A browser opens the AstraBox console without a login cookie, and AstraBox redirects it to the identity provider with a PKCE challenge. The person signs in at the provider, which is either the bundled Casdoor or one the organization already runs, and the provider redirects the browser back to /api/v1/auth/callback with a one-time code. AstraBox exchanges that code, the PKCE verifier and its client secret for an ID token carrying the user and groups, verifies it, and returns its own signed HttpOnly login cookie. opens the console, not signed in yet redirect to the provider, with a PKCE challenge the provider authenticates the user and returns identity redirect back with a one-time code GET /api/v1/auth/callback the code, the PKCE verifier, the client secret ID token: user and groups signed login cookie, HttpOnly Browser the person signing in AstraBox service verifies the ID token Identity provider bundled Casdoor or your own LEGEND the identity provider you configure one step of the sign-in what comes back the login cookie AstraBox creates

Turn on the bundled login service​

AstraBox ships Casdoor, an open-source identity service, as a Compose overlay, containers/compose.sso.yaml. The overlay runs Casdoor beside AstraBox and switches the console to OIDC login against it.

On an installation, run the installer again with ASTRABOX_INSTALL_TEAM_LOGIN=casdoor set, as in Install a release, or answer yes to its team-login question. It sets COMPOSE_FILE in the installation's containers/.env, so the stack it starts, and every docker compose command run in that directory, includes the overlay. Running it again keeps team login on and keeps the generated secrets.

From a clone, start the stack with the overlay:

scripts/compose.sh -f containers/compose.sso.yaml up -d

Open http://127.0.0.1:8088 and sign in as admin. Its password was generated once into the deployment's secrets directory: .astrabox/database-secrets in the installation directory, ~/astrabox by default, or in a clone.

tr -d '\r\n' < ~/astrabox/.astrabox/database-secrets/casdoor_admin_password

The same directory holds the OAuth client secrets. Back it up and protect it.

Casdoor also has an administrator of its own, built-in/admin, which manages every organization in Casdoor. Casdoor creates it with the password 123 (Casdoor server installation); at its first start the bundled configuration replaces that password with a generated one, kept in casdoor_builtin_admin_password in the same directory. Casdoor checks it again at every start and keeps a password an administrator set in its place. That check signs in with the generated password and then with 123, so a password of your own costs two failed sign-ins per start, and Casdoor locks an account for 15 minutes after five.

Casdoor lets its administrators sign in to every application, so AstraBox accepts only accounts of the astrabox organization, which the bundled configuration seeds and names in ASTRABOX_CASDOOR_ORGANIZATION. Any other account, built-in/admin included, is refused with IDENTITY_ORGANIZATION_REJECTED, and so is a client token from any OAuth client but the bundled API client, astrabox-api. A browser session records the organization its sign-in checked; one that names no organization, or another, is signed out and must sign in again.

After the first sign-in:

  1. Replace or secure the bootstrap admin account of the astrabox organization.
  2. Add users and configure any MFA or external login providers your team needs.
  3. Back up the secrets directory with the rest of the deployment data.
  4. Test AstraBox with both an administrator and an ordinary user.

Self-signup is disabled in the bundled configuration. Members of the astrabox-admin group receive the AstraBox administrator role. When the overlay is active, Management console → Integrated services provides shortcuts to Casdoor identity management and API access.

Brand the sign-in page​

Casdoor's sign-in page shows the astrabox-console application's logo, with the application's display name as the logo's text alternative. The browser tab shows the application's title and favicon, or, where those are empty, the organization's display name and favicon. An administrator changes them at any time in the Casdoor console, under Applications and Organizations.

The application's Providers list adds other ways to sign in. Casdoor supports OAuth providers such as Google, Microsoft Entra ID (Azure AD), Okta, GitHub, GitLab and Slack, SAML and LDAP, and regional providers such as DingTalk, Lark (Feishu) and WeCom (Casdoor OAuth providers). Create the provider under Providers, then add it to the application. The bundled configuration enables none of them.

Keep the organization's name, astrabox: the bundled configuration accepts accounts of that organization only. A deployment that connects its own Casdoor with another organization names it in ASTRABOX_CASDOOR_ORGANIZATION, as described below.

AstraBox and Casdoor both listen on this host's loopback address. To sign in from other computers, see Put the login flow behind a proxy.

Connect an existing OIDC provider​

Set the provider and console client on the AstraBox service:

ASTRABOX_WEB_IDENTITY=oidc
ASTRABOX_OIDC_ISSUER=https://login.example.com
ASTRABOX_OIDC_CLIENT_ID=astrabox-console
ASTRABOX_OIDC_CLIENT_SECRET=<oidc-client-secret>

Register the following callback URL with the provider:

https://<astrabox-host>/api/v1/auth/callback

When AstraBox is published under a path, the callback URL includes that path, such as https://<astrabox-host>/astrabox/api/v1/auth/callback; see Publish AstraBox under a path.

AstraBox reads user groups from the groups claim by default and grants the administrator role to members of astrabox-admin. Change the claim and group name when your provider uses different values:

ASTRABOX_OIDC_GROUPS_CLAIM=roles
ASTRABOX_OIDC_ADMIN_GROUP=platform-admins

When the provider is Casdoor, also set ASTRABOX_CASDOOR_ORGANIZATION to the organization whose accounts may sign in. Casdoor lets the administrators of its built-in organization sign in to every application, and AstraBox reads each account's organization from the owner claim of the JWTs Casdoor issues.

Set ASTRABOX_OIDC_REDIRECT_URL when the public callback address differs from the origin AstraBox receives through the proxy. Its path is the callback path below ASTRABOX_PUBLIC_PATH_PREFIX, such as /api/v1/auth/callback at the root of the host; the server refuses to start with any other path. If the AstraBox service reaches the provider through a private address, keep the public issuer in ASTRABOX_OIDC_ISSUER and put the private address in ASTRABOX_OIDC_INTERNAL_ISSUER.

The browser login cookie is HttpOnly and lasts seven days by default. Change its lifetime with ASTRABOX_AUTH_SESSION_TTL_SECONDS. For multiple AstraBox replicas, set the same ASTRABOX_AUTH_SESSION_SECRET on every replica so a login remains valid when requests move between them.

Put AstraBox behind an authentication gateway​

Trusted identity headers​

Use trusted headers when a gateway such as an authentication proxy already handles login. Select the method and configure a shared gateway secret:

ASTRABOX_WEB_IDENTITY=trusted_header
ASTRABOX_TRUSTED_HEADER_GATEWAY_SECRET=<shared-random-value>

By default, AstraBox reads the user ID from x-forwarded-user, the display name from x-forwarded-preferred-username, the email from x-forwarded-email, and groups from x-forwarded-groups. Configure different header names when the gateway uses another convention.

The gateway must remove client-supplied identity headers, add the authenticated values itself, and send the configured gateway secret. Block every path that can reach AstraBox without passing through that gateway.

Verified JWT​

Use verified JWTs when callers or an authentication gateway already attach a bearer token:

ASTRABOX_WEB_IDENTITY=jwt
ASTRABOX_JWT_ISSUER=https://login.example.com
ASTRABOX_JWT_AUDIENCE=astrabox

AstraBox verifies the signature, expiry, configured issuer and audience, then maps the user and group claims. You can configure a JWKS URL directly instead of using issuer discovery. This method does not provide a browser redirect; the client or gateway must attach the token to each request.

Sign out​

The account menu sends one same-origin POST /api/v1/auth/logout, with browser credentials. This POST is not retried automatically. The identity deployment returns one of two results:

ResultMeaningConsole behavior
204 No ContentThe deployment has ended this browser's sessionRead GET /api/v1/auth/session without caching; navigate to the console root only if it returns authenticated: false
200 application/json with redirect_urlThe browser must visit the identity provider to finish logoutNavigate the top-level browser to that HTTP(S) URL; the provider owns logout and the return to the console

The bundled OIDC route returns 204 and deletes the AstraBox session cookie at the deployment's public path. It ends the console session; it does not end the identity provider's own browser session.

An external identity deployment registers its session, login and logout routes through astrabox.api.routers or astrabox.api.extensions.register_extension_router. Its resolver still uses the astrabox.web.identity interface. A provider that requires browser navigation returns an unwrapped JSON object, for example:

{"redirect_url":"https://identity.example.com/logout?return_to=https%3A%2F%2Fconsole.example.com%2Fastrabox%2F"}

The adapter constructs this URL from its configured provider origin and the provider's supported parameters. It includes the allowed console return URL; astrabox.deploy.public_path.public_url(request, "/") composes the console root with its public path prefix. Return addresses follow the provider's registration or allowlist rules. The console does not add provider parameters, read provider credentials or change the reported authentication state.

Return navigation instructions as 200 JSON rather than an HTTP redirect from the POST: fetching a redirect does not navigate the browser. Provider logout can require its own browser session, as in OpenID Connect RP-Initiated Logout 1.0. Any deployment-owned cleanup precedes the response; a navigation instruction does not assert that provider logout has completed. On return, the console reads the real session probe again.

HTTP errors, transport failures, invalid navigation instructions and a 204 whose session probe does not confirm signed-out state leave the current page in place and show an error. They do not clear the saved sign-in destination or force navigation to the home page. An external deployment must implement its actual logout operation; a 204 with an unchanged authenticated probe is refused.

Authorization after login​

A successful login does not automatically make a user an administrator. Group mapping supplies the administrator role; resource ownership and Agent authorization are checked separately for each operation. Test both ordinary and administrator accounts before opening the deployment to a team.

Conversations created before team login was turned on belong to the local single-user identity, so accounts that sign in afterwards do not see them. Agents, Assistants and RuntimeProfiles stay available.

Every signed-in user may create Agents and Assistants. What an Agent's own fields make its sandbox reach and use is limited to what an administrator made available: repository deploy keys an administrator listed, Credentials an administrator assigned, and hosts the RuntimeProfile allows or that are public (see What an Agent's own extensions may reach and Access GitHub). When users should only use the Agents an administrator publishes, as on an open or public deployment, reserve creation to administrators:

ASTRABOX_AUTHORING_ADMIN_ONLY=true

Everyone else can still use the Agents an administrator makes available to them, and receives FORBIDDEN (403) on create.

Machine integrations use OAuth Access Tokens, verified JWTs, or the credential accepted by the authentication gateway. See Authenticate API requests for token exchange, scopes, and request headers.

Put the login flow behind a proxy​

With the bundled login service, a browser on another computer needs two addresses: the console, and Casdoor's sign-in page, where the console sends it to sign in. AstraBox (port 8088) and Casdoor (port 8087) listen on loopback only, so give each an HTTPS hostname on a reverse proxy on the same host:

Public URLProxied toPublished paths
https://astrabox.example.comhttp://127.0.0.1:8088All
https://login.example.comhttp://127.0.0.1:8087Casdoor's sign-in page and its OAuth 2.0 and OIDC endpoints

Keep both loopback bindings, so that the proxy is the only way in.

Give AstraBox its public URLs​

On an installation, run the installer with:

ASTRABOX_INSTALL_TEAM_LOGIN=casdoor
ASTRABOX_CONSOLE_ORIGIN=https://astrabox.example.com
ASTRABOX_OIDC_ISSUER=https://login.example.com

It writes both URLs to ~/astrabox/containers/.env, and with them the two settings the server derives from the console's URL:

ASTRABOX_OIDC_REDIRECT_URL=https://astrabox.example.com/api/v1/auth/callback
ASTRABOX_ALLOWED_HOSTS=astrabox.example.com,localhost,127.0.0.1,[::1]

When the console is published under a path, also set ASTRABOX_PUBLIC_PATH_PREFIX, such as /astrabox (see Publish AstraBox under a path). The installer then writes the callback below that path, https://astrabox.example.com/astrabox/api/v1/auth/callback, and Casdoor registers the same URL.

From a clone, set these four in the environment of scripts/compose.sh, and ASTRABOX_PUBLIC_PATH_PREFIX when the console is published under a path.

SettingWhy it is needed
ASTRABOX_OIDC_ISSUERCasdoor publishes it as its issuer and serves its sign-in page under it. AstraBox checks each ID Token's issuer against it.
ASTRABOX_CONSOLE_ORIGINCasdoor registers the console's callback under it.
ASTRABOX_PUBLIC_PATH_PREFIXOnly when the console is published under a path. Casdoor registers the console's callback, and AstraBox names it, below this path.
ASTRABOX_OIDC_REDIRECT_URLThe proxy reaches AstraBox over plain HTTP, so AstraBox cannot derive the public HTTPS callback from the request. With this set, AstraBox sends Casdoor the callback Casdoor registered and marks its login cookie Secure.
ASTRABOX_ALLOWED_HOSTSAstraBox answers only the Host names it lists, and the list replaces the default one, so it keeps the loopback names the installer and the CLI use. The installer keeps a list you wrote, and refuses one without the console's host and 127.0.0.1.

Set the public URLs when you turn team login on. Casdoor registers the console's callback, <console URL>/api/v1/auth/callback, when it first starts, and later starts add only missing records. If the console's URL changes afterwards, also change the Redirect URLs of the astrabox-console application in Casdoor's console.

Configure the proxy​

This nginx configuration publishes the whole console, and only the parts of Casdoor that browsers and API clients use to sign in:

# The console: every path.
server {
    listen 443 ssl;
    server_name astrabox.example.com;
    ssl_certificate     /etc/nginx/tls/astrabox.example.com.crt;
    ssl_certificate_key /etc/nginx/tls/astrabox.example.com.key;
    # Files upload through the console; nginx accepts 1 MB by default.
    client_max_body_size 100m;

    location / {
        proxy_pass http://127.0.0.1:8088;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        # Session events and terminal output arrive as long-lived streams.
        proxy_buffering off;
        proxy_read_timeout 1h;
    }
}

# Casdoor: its sign-in page and its OAuth 2.0 and OIDC endpoints only.
server {
    listen 443 ssl;
    server_name login.example.com;
    ssl_certificate     /etc/nginx/tls/login.example.com.crt;
    ssl_certificate_key /etc/nginx/tls/login.example.com.key;

    location ~ ^/(login/oauth/|static/|\.well-known/|api/login/oauth/|api/(login|get-app-login|get-account|userinfo|logout)$) {
        proxy_pass http://127.0.0.1:8087;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # Casdoor's management console and the rest of its API.
    location / {
        return 404;
    }
}
Casdoor pathWhat it serves
/login/oauth/authorizeThe authorization endpoint: the sign-in page the console sends browsers to
/api/login/oauth/access_token, /api/login/oauth/refresh_token, /api/login/oauth/introspectThe token, refresh and introspection endpoints, where API clients exchange their credentials
/api/userinfo, /api/logoutThe userinfo and end-session endpoints
/.well-known/openid-configuration, /.well-known/jwksOIDC discovery and the keys that sign ID Tokens
/static/, /api/get-app-login, /api/get-account, /api/loginThe sign-in page's files, and the calls it makes

Casdoor documents its OAuth 2.0 and OIDC endpoints in OAuth 2.0, and its discovery document lists them for a running server. The sign-in page's calls are those of casbin/casdoor:3.128.0, the version the overlay pins; check them again when you change that version. The AstraBox server itself reaches Casdoor inside the deployment, at http://casdoor:8000, not through the proxy.

/api/login also signs in Casdoor's own administrator, built-in/admin, so keep its generated password as private as the other secrets.

Manage Casdoor from the AstraBox host​

Casdoor's management console stays at http://127.0.0.1:8087. From another computer, reach it through an SSH tunnel:

ssh -L 8087:127.0.0.1:8087 <astrabox-host>

The Management console → Integrated services shortcuts open Casdoor at the issuer, where this proxy answers 404. Point them at the tunnel in containers/.env, then run the installer again:

ASTRABOX_CASDOOR_ADMIN_URL='http://127.0.0.1:8087'
ASTRABOX_CASDOOR_API_ACCESS_URL='http://127.0.0.1:8087/applications/astrabox/astrabox-api'

Environment entry policy​

Authentication establishes identity. ASTRABOX_ENVIRONMENT_ENTRY_POLICY=members requires an explicit grant in the serving Environment's member list. Platform administrators may enter under their administrator role; that entry is logged when they are not members.

A deployment can install a policy under the astrabox.environment.entry entry-point group and select its name with ASTRABOX_ENVIRONMENT_ENTRY_POLICY. Implement astrabox.seams.environment_entry.EnvironmentEntryPolicy:

async def can_enter(self, user, *, environment_name: str, operation: str) -> bool:
    return await self.directory.can_enter_environment(user.user_id, environment_name)

The platform supplies the verified identity, its database-bound Environment and the operation. The policy returns a bool; an exception or another result refuses access with ENVIRONMENT_ENTRY_POLICY_UNAVAILABLE. Unknown policy names refuse startup. A bootstrap embedding the service may instead register an instance with register_environment_entry_policy in astrabox.providers.environment_entry before constructing the app.

Use the same policy and authoritative identity source on every replica. Decisions are evaluated when entering; the platform does not copy enterprise users into its member table. An anonymous identity is never passed to a policy. API and protocol entry and the accessible-Environment list use the same decision; the client cannot select another Environment through a header or resource id. Agent and personal-resource ACLs, administrator roles and credential delegation still apply after entry. Capability links retain their own authorization.

Before inviting users​

For any team deployment:

  • terminate HTTPS at a trusted reverse proxy or ingress;
  • add the public hostname to ASTRABOX_ALLOWED_HOSTS;
  • keep the identity provider's management console private;
  • prevent clients from reaching the AstraBox service port directly;
  • store OIDC client secrets, gateway secrets, JWT keys, and login-cookie signing keys in protected secret storage;
  • verify login, logout, expired cookies, ordinary-user authorization, administrator access, and provider errors.

For desktop applications that only need model inference, configure independent OIDC model applications instead of reusing either platform client or granting AstraBox membership.