Configure single sign-on and device login

What you are configuring

Atlasberg has had single sign-on for the portal and the console for a while. Device login extends it to the developer's terminal: the person signs in with the corporate identity, the terminal receives a personal token, and the gateway swaps that token for the team's virtual key on every request. This tutorial sets up both halves.

[Figure: Identity and SSO screen of the console with the OIDC provider tab open - Settings > Identity and SSO. Four tabs: Provider (OIDC), Groups and teams, Local login, Devices. The three status pills on the right tell you what is on.]

No secret goes through the screen: The client secret only as the name of a variable; the local password only goes in, hashed with PBKDF2, and never comes out. Saving validates before writing and applies live. Open sessions stay valid: a scope change does not sign the whole company out.

• Tab: Provider (OIDC) | What it does: Issuer, client id, redirect, scopes, claims, corporate CA, cookie, session duration, Entra overage. Test connection runs the OIDC discovery and lists the endpoints. The client secret is entered as the NAME of an environment variable, never as a value.
• Tab: Groups and teams | What it does: Rules from directory group to gateway team, with priority, and the default team for whoever signs in with no mapped group. Below, the directory sync block.
• Tab: Local login | What it does: Username and password accounts on the appliance (closed network and console emergency account): create, change password, grant or remove console access, delete.
• Tab: Devices | What it does: Turn the flow on and off, token and code validity, poll interval, ceiling per person. Below, the table of every issued token with revoke one and revoke all of a person.

Step by step

• Field: Device login enabled | Default: on | Limits and effect: Turning it off drops every token immediately and closes the flow routes.
• Field: Token validity (hours) | Default: 168 | Limits and effect: From 1 to 2160. Seven days balances comfort and someone leaving the company.
• Field: Code validity (minutes) | Default: 10 | Limits and effect: From 1 to 30. Time for the person to go from the terminal to the portal.
• Field: Poll interval (seconds) | Default: 5 | Limits and effect: Minimum 1. A terminal that polls sooner receives slow_down.
• Field: Active tokens per person | Default: 5 | Limits and effect: Minimum 1. Past the ceiling, the oldest is revoked.

1. Register the gateway in the identity provider

In Entra ID, Keycloak or AD FS, create a web application with the redirect URL the screen suggests, in the format https://llm.company.com/api/atlasberg/sso/callback. Note the client id and the client secret. In Entra, if the organization has people in more than two hundred groups, turn on the directory overage option later.

2. Put the secret in the appliance, not in the screen

The client secret enters as an environment variable of the container, for example ATLASBERG_SSO_CLIENT_SECRET. In Docker, through --env or the compose environment file; in Kubernetes, through a Secret mounted as a variable. The screen only takes the variable name. A literal value is refused. The read shows the name and whether the variable is set, never the content.

3. Provider (OIDC) tab

Check Single sign-on (OIDC) enabled. Issuer: Entra is https://login.microsoftonline.com/<tenant>/v2.0, Keycloak is https://kc.internal/realms/company; discovery runs on /.well-known/openid-configuration. Client ID and the name of the secret variable. Redirect URL: click Use suggested and register exactly that value in the provider. Scopes: openid profile; on Keycloak add groups. If the provider uses an internal certificate, the path of the PEM mounted in the container. Test connection: green means the gateway reached the provider and read the endpoints. Save and apply: SSO becomes available in the portal at once.

4. Groups and teams tab

Each directory group maps to a gateway team. The team decides the virtual key, the budget and the policies the person receives. Two ways: put the group GUID in the team's SourceID field under Governance, and the match is automatic; or write the rule here, with a priority, which wins over the automatic rule. Whoever signs in with no mapped group lands in the default team, or in no team, in which case they authenticate but inference is refused until an administrator binds one.

5. Local login tab

Needed on a closed network without a provider, and recommended in any case as the console emergency account. Create the account with username, name, a password of at least twelve characters and the Console access option. The password is hashed with PBKDF2 before touching the disk and is never shown. Change password, remove console access and delete are on the same table. Removing an account revokes its personal tokens.

6. Devices tab

Turn on Device login enabled and adjust the policy if the defaults do not fit. Save and apply. Turning it off later drops every token immediately and closes the flow routes.

7. Distribute the CLI

Three ways, and they can coexist. Developers with Node install it with npm install -g @atlasberg/cli (or run npx @atlasberg/cli without installing). On a closed network, the developer downloads the CLI under My devices in the portal, for their system, and puts the file on the PATH under the name atlasberg. In companies with managed workstations, the same binary can ship in the IT's standard package: it has no dependencies and needs no installation. The gateway serves the builds itself at /api/atlasberg/sso/downloads/<file>, for Linux (x86_64 and arm64), macOS (Intel and Apple Silicon) and Windows. After that, the developer's script is Tutorial 3: atlasberg login, confirm in the portal, eval "$(atlasberg env)".

Device policy

docker run -d --name atlasberg ... \
  -e ATLASBERG_SSO_CLIENT_SECRET='<client secret>' \
  -e ATLASBERG_PROXIES_CONFIAVEIS='10.0.0.0/8' \
  atlasberg-proxy:<version>

The same thing, through the file

Everything above can also be versioned as <app-dir>/sso.json. Edited by hand, it requires a gateway restart; edited through the screen, it is applied live. Local accounts created by the screen are stored as salt, hash and iterations, never as a password.

{
  "enabled": true,
  "issuer": "https://login.microsoftonline.com/<tenant>/v2.0",
  "client_id": "<app-id>",
  "client_secret": "env.ATLASBERG_SSO_CLIENT_SECRET",
  "redirect_url": "https://llm.company.com/api/atlasberg/sso/callback",
  "scopes": ["openid", "profile"],
  "directory_graph": { "enabled": true },
  "group_teams": [{ "group_id": "<group-guid>", "team_id": "team-eng", "priority": 10 }],
  "default_team": "",
  "local_login": { "enabled": true, "console_group": "atlasberg-console", "accounts": [] },
  "device_flow": { "enabled": true, "token_ttl_hours": 168, "code_ttl_minutes": 10,
                   "poll_interval_seconds": 5, "max_tokens_per_user": 5 }
}

Sync the team tree with the directory

Under Groups and teams, the Directory sync block. It needs an application credential separate from the login one: in Entra ID, an application with Group.Read.All and User.Read.All; in Keycloak, a client with a service account and the view-users and query-groups roles. The secret enters as the name of an environment variable, like the SSO one.

What not to promise: Without the sync, a person leaving the directory is only felt on the token when it expires, seven days by default, or when someone revokes it. With the sync, within an hour. Plain AD FS has no group read API: sync only with Entra ID or Keycloak. The CLI keeps the token in a file with restricted permissions, not in the system keychain.

• Archiving never deletes: the team is renamed with [archived] and its keys are deactivated, because cost history and the trail need to keep resolving the name. If the group comes back, the team is reactivated.
• The same credential checks, every cycle, who was disabled in the directory and revokes that person's personal tokens.
• Whoever signs in with a group that has no team yet gets the team created right there, on the first login.
• With the control plane frozen by an expired license, team changes wait; the revocation of whoever left keeps running.

1. Create the template team

Under Governance, a team with the budgets, the rate limit and the key with the providers every new team should inherit.

2. Define the filter

The prefix of the groups that become teams (only those enter), such as ai-, or the list of ids.

3. Choose the unit

Department or company of the members, by majority, or the parent group chain on Keycloak. Or do not assign.

4. Preview

The gateway reads the directory and shows what it would create, rename and archive, without changing anything.

5. Save and Sync now

After that the cycle runs by itself at the chosen interval, sixty minutes by default, and the last run stays visible on the screen with counters and errors.

Network, proxies and TLS

• The new routes live under /api/atlasberg/sso/ and /api/atlasberg/identidade/, in the same process and the same port. The portal must be reachable by the employee's browser and by the developer's terminal at the same public URL, with TLS.
• The session cookie is Secure and SameSite=Strict: in production the gateway must sit behind HTTPS, through the ingress or the edge.
• Behind a load balancer, set ATLASBERG_PROXIES_CONFIAVEIS with the CIDRs of the edge. Only with the connection coming from one of them does the gateway read X-Forwarded-For, X-Forwarded-Proto and X-Forwarded-Host. Without it, the whole company shows up with one IP: a per-origin limit becomes a limit for everyone and the approval screen shows the balancer's address. On Kubernetes, the chart exposes identity.trustedProxies.
• The terminal prints the address the gateway knows as its own. Order of preference: the origin of the SSO redirect URL, then what the trusted proxy reports, then the host of the connection itself.

Operating routine

• Situation: Someone left the company | What to do: Remove the person from the group in the directory for new sessions, and under Devices click Revoke all of this person for the terminals. If the account was local, removing the account does both.
• Situation: Lost laptop | What to do: The person revokes it under My devices, or the administrator revokes that token by device name and origin.
• Situation: Suspected abuse | What to do: Turning device login off on the screen drops every token at once, without touching portal sessions.
• Situation: License expired | What to do: Revoking a token or all of a person's keeps working with the control plane frozen. Editing the identity configuration freezes with the rest.
• Event: auth.device.started | When: A terminal asked for a code. Unauthenticated actor, origin in the details.
• Event: auth.device.approved | When: The person approved. Actor is the person; team and device in the details.
• Event: auth.device.denied | When: The person denied.
• Event: auth.token.issued | When: The terminal collected the token. Public identifier of the token in the details.
• Event: auth.token.revoked | When: Revocation, with the reason: person, administrator, ceiling, logout or directory.
• Event: config.change (resource sso) | When: Every write through the identity screen, with the section changed and who changed it.

What the audit trail records

Authenticating with the token on an AI request does not generate its own event, on purpose: it is the normal inference path, already covered by admission events and metrics, and one event per request would let a stolen token inflate the trail.

Do it all with an AI agent

If you would rather delegate, paste the prompt below into Claude Code or another AI agent with terminal access. It is written to ask for everything it needs before touching anything, show a plan, wait for your confirmation and only then execute. It never asks for the value of a provider key and never writes a secret into a repository file.

For developers: sign in from the terminal

What the person sees: the command, the code, the portal, the variables.

Reference: Settings in the console

Every screen of the Settings menu, including Identity and SSO.

You are my Atlasberg Platform administrator and you are going to configure single sign-on (OIDC), the group to team mapping and device login, following https://atlasberg.com/docs/tutoriais/configurar-sso and the reference at https://atlasberg.com/docs/api/gestao. Work through the gateway's identity API with curl. Never invent values: ask.

Before any change, ask me, one question at a time:
1. The public gateway URL (example: https://llm.company.com) and how to authenticate to the management API (administrator username and password). Never echo the password and never write it to a file.
2. The identity provider: Entra ID, Keycloak or AD FS. The issuer (Entra: https://login.microsoftonline.com/<tenant>/v2.0; Keycloak: https://<host>/realms/<realm>).
3. The client id of the application registered in the provider and the NAME of the appliance environment variable that holds the client secret (example: ATLASBERG_SSO_CLIENT_SECRET). Do not ask me for the secret value. If the variable is not yet set on the container, tell me how to set it (Docker --env or a Kubernetes Secret) and wait until I confirm I restarted.
4. The scopes (default openid profile; on Keycloak add groups) and, if the provider uses an internal certificate, the path of the CA PEM mounted in the container.
5. The group to team rules: for each directory group (GUID in Entra, name or id in Keycloak), which gateway team receives its people. If the team does not exist yet, say it must be created under Governance > Teams first. And the default team for whoever signs in with no mapped group, or none.
6. Whether I want local login enabled (recommended as the console emergency account) and the name of the group that grants console access (default atlasberg-console). I create the local accounts and passwords myself on the Local login tab; you will not handle passwords.
7. The device policy: on or off, token validity in hours (default 168, from 1 to 2160), code validity in minutes (default 10), poll interval in seconds (default 5) and active tokens per person (default 5).
8. Whether there is a load balancer or edge in front of the gateway and, if so, its CIDRs for ATLASBERG_PROXIES_CONFIAVEIS.
9. Whether I want to sync the team tree with the directory (Entra ID or Keycloak only): client id of the read application, name of the secret variable, prefix of the groups that become teams (example: ai-), id of the template team and interval in minutes (default 60).

When you have everything, show the final configuration as a table and ask for confirmation. Only then execute, checking every status and stopping at the first error:
a) GET /api/atlasberg/identidade/config and keep the response: it has the sections provedor, grupos, login_local, dispositivos and diretorio, and that is the shape the PUT expects. Never send a literal secret; the client_secret_env field takes only the variable name.
b) POST /api/atlasberg/identidade/config/testar with {"issuer":"...","ca_cert_path":"...","client_secret_env":"..."} and show me the discovered endpoints. If it fails, stop and show me the error.
c) PUT /api/atlasberg/identidade/config with the response from step a) modified: provedor.enabled true, issuer, client_id, client_secret_env, redirect_url equal to <gateway>/api/atlasberg/sso/callback, scopes, ca_cert_path if any; grupos.group_teams as a list of {"group_id":"...","team_id":"<team id>","priority":10} and grupos.default_team; login_local.enabled and console_group; dispositivos with enabled, token_ttl_hours, code_ttl_minutes, poll_interval_seconds and max_tokens_per_user; diretorio per item 9, or untouched. Check with a new GET that it is as planned.
d) Tell me exactly what to register in the identity provider: the redirect URL from step c) and, in Entra, the overage option if there are people in more than two hundred groups.
e) If there is a load balancer, remind me to set ATLASBERG_PROXIES_CONFIAVEIS on the container and restart; explain that without it every user shows up with the balancer's IP.
f) Sync, if I asked for it: POST /api/atlasberg/identidade/diretorio/previa and show me what would be created, renamed and archived; only after my confirmation, POST /api/atlasberg/identidade/diretorio/sincronizar.
g) Tests: POST /api/atlasberg/sso/device/code with {"client_name":"test"} must return a user_code in the XXXX-XXXX format; GET /api/atlasberg/sso/downloads shows whether the CLI builds are available to developers. The provider login cannot be tested without a browser: ask me to open the portal and confirm the SSO button shows and the login works.
h) Deliver a summary of what is configured, what I still need to do (local accounts on the screen, registration in the provider, CLI distribution) and the tutorial's operating routine (someone leaving, lost laptop, suspected abuse).

Rules: if an endpoint answers differently from what is expected, show the response and ask before working around it. Do not turn local login off without telling me. Do not change anything outside the identity section.

About Atlasberg Platform

Atlasberg Platform is the control layer between a company and every AI model: each request is authenticated with a virtual key, filtered by policy and DLP, routed to the right provider and written to a hash-chained audit trail. It exposes an OpenAI-compatible API, so applications only swap the base URL.

The same artifact runs in Atlasberg Cloud, in your VPC, on-premises or fully air-gapped, and is priced by capacity and modules, never per seat.

This page is part of the official documentation. To talk to the engineering team, write to [email protected] or use https://atlasberg.com/contato. Answers come within one business day.