STRAZAdocs
Markdown

AI agents as identities

An AI agent provisioned by your identity manager signs in to Straza with its own key and no browser, and leaves again when the identity manager retires it.

Who
Admin
Where
Terminal with strazactl and curl, and a terminal on the agent's machine

In short

Your IGA creates and retires AI agents over SCIM the way it does people, each marked as an agent and naming its sponsor. An agent signs in with its own Ed25519 key, which the Straza background service on its machine holds, and never with a browser. Revoking the key or deactivating the agent ends its running sessions.

On this page

Your identity manager creates and retires AI agents the way it does people, and each agent reaches Straza with its own identity and a key instead of a password. You work as the admin in one terminal and on the agent’s machine in another. At the end one agent is provisioned over SCIM, enrolled with a key and no browser, and retired again.

How an agent differs from a person

An AI agent is an identity like a person, born in your identity manager and provisioned over SCIM. Two things differ. Its record says it is an agent and names the person behind it, so policy can treat it as an agent and approvals can reach that person. Its credential is an Ed25519 key registered on the identity, so it enrolls with no browser and no password.

The identity manager cuts an agent the way it cuts a person. Once the record is deactivated, the next token grant fails and every running session is revoked.

Before you start

  • strazactl with STRAZA_SERVER and an admin API token in STRAZA_API_TOKEN, or a console session that holds the identity area. The steps mint another token, which takes tokens:write, a root-equivalent grant, so mint a Full root token for 30 days in the console as Mint an admin API token shows, and revoke it when you are done.
  • The straza binary on the agent’s machine.
  • An admin API token in ADMIN_API_TOKEN, for the SCIM request and the two admin API reads below. Mint it with strazactl api-token create --name idm-agents --scope scim:read,scim:write,identity:read. In the console, mint it under Settings, API tokens, New API token with the job Custom, scim set to read and write and identity set to read.

The command examples ran against a standalone server at http://localhost:8420, with the agent’s side on the same host. The console steps and the midPoint notes describe the demo stack.

  1. Provision the identity

    Send the user with the agent schema in schemas, userType agent, and the Straza extension carrying agencyMode and sponsor. In the demo stack midPoint sends this request. Here it is sent with curl:

    Terminal SCIM, as the identity manager
    curl -s -H "Authorization: Bearer $ADMIN_API_TOKEN" -H 'Content-Type: application/scim+json' \
      -X POST http://localhost:8420/scim/v2/Users -d '{"schemas":["urn:ietf:params:scim:schemas:core:2.0:User","urn:ietf:params:scim:schemas:extension:agent:2.0:Agent","urn:straza:params:scim:schemas:extension:2.0:User"],"externalId":"idm-agent-0001","userName":"scout-bot","displayName":"Scout bot","title":"Scout agent","userType":"agent","active":true,"urn:straza:params:scim:schemas:extension:2.0:User":{"agencyMode":"autonomous","sponsor":"alice"}}' \
      | jq -c '{id, userName, userType, active, ext: .["urn:straza:params:scim:schemas:extension:2.0:User"]}'

    You should see

    "kind":"nhi" and the sponsor alice under ext.

    {"id":"01a15d8e-856f-7d10-9e63-a550763da368","userName":"scout-bot","userType":"agent","active":true,"ext":{"agencyMode":"autonomous","kind":"nhi","locked":false,"origin":"scim","sponsor":"alice"}}

    Each field tells Straza something different.

    Field What Straza does with it
    The agent schema, or userType agent Records the identity as an AI agent. An AI agent never decides an approval, and it may sign in with a key. Either signal is enough, for a connector that cannot send the schema.
    agencyMode Policy can match it with match.identity.agencyMode. With autonomous, a rule that asks for the requester’s own confirmation denies, because no person stands behind the session. supervised and interactive change nothing beyond what a policy matches on them.
    sponsor The username of the person behind the agent. An approval rule that names no deciders and no approver roles goes to this person, and a rule can name them beside approver roles with deciders: [sponsor].
    manager of the SCIM enterprise User extension Becomes the agent’s sponsor. Generic SCIM has the rules.

    The read-only kind in the SCIM render is nhi only when the create carried the agent schema, and it never changes after creation. A row created with userType agent alone reads kind human there for good, while the admin surface and the key sign-in treat it as an agent. The mismatch stays visible to a certifier.

    In midPoint the persona archetype and a sponsor reference on the user produce these values, so the seeded agent sam-sre-agent arrives this way with no mapping of its own. The demo stack’s PolicySet routes the seeded agent’s gated calls with deciders: [sponsor]. Every identity selector a policy can use is in the PolicySet grammar.

    1. Users
    The demo stack's Users page with the people and agents that arrived over SCIM The demo stack's Users page with the people and agents that arrived over SCIM
    Users on the demo stack, where the agents carry the badge AI agent and the origin SCIM. Show the whole screen

    You should see

    A scout-bot row with the kind badge AI agent and the origin badge SCIM.

    Terminal Straza administration
    strazactl users list

    You should see

    scout-bot with ORIGIN scim.

    USERNAME     STATUS    ORIGIN  EMAIL              ID
    scout-bot    active    scim                       01a15d8e-856f-7d10-9e63-a550763da368

    The listing is trimmed to the new row.

  2. Generate the key

    CLI only

    The key is made on the agent’s machine, so this step runs in its terminal.

    Generate the key on the agent’s machine, as the agent’s user. straza service, the Straza background service on that machine, makes the key and keeps the private half, so it never reaches the agent. It runs on Linux, macOS and Windows, as Headless agents says. The command prints the exact registration line:

    Terminal 2 on the agent's machine
    straza keygen --user scout-bot

    You should see

    The Public key: line, which the next step registers.

    NHI key generated (the Straza background service holds the private half).
    Public key: pzXwnoH6Vcc/cs+T/gxsrZ/SGMzU7J7nQSgfKWy5AUg=
    
    An administrator registers it with:
      strazactl users nhi-key set scout-bot pzXwnoH6Vcc/cs+T/gxsrZ/SGMzU7J7nQSgfKWy5AUg=
    (or: PUT /v1/admin/users/{id}/nhi-key {"public_key":"pzXwnoH6Vcc/cs+T/gxsrZ/SGMzU7J7nQSgfKWy5AUg="})
    Then enroll headless:
      straza enroll --server <strazad-url> --headless --user scout-bot
  3. Register the public key

    Register the public half on the identity, as the admin. One key belongs to each identity, so registering again rotates it, and Straza refuses a key for a human identity.

    1. Users
    2. scout-bot
    3. Register key
    The sheet of the AI agent build-bot with the Assertion key form open and its public key pasted The sheet of the AI agent build-bot with the Assertion key form open and its public key pasted
    The Assertion key section with the public key pasted and Register key. Show the whole screen

    The Assertion key section shows only on an AI agent. Paste the key under Public key, base64, 32 bytes and press Register key.

    You should see

    The badge registered with the key’s fingerprint.

    If this fails
    Paste the public key. The server refuses anything that is not exactly a 32-byte Ed25519 key.
    The field was empty. Paste the whole value from the Public key: line, with its closing =.
    Terminal Straza administration
    strazactl users nhi-key set scout-bot pzXwnoH6Vcc/cs+T/gxsrZ/SGMzU7J7nQSgfKWy5AUg=

    You should see

    key registered for scout-bot.

    key registered for scout-bot. The agent can now `straza enroll --headless --user scout-bot`

    strazactl has no read of the key’s posture. The admin API answers it and never returns the key itself:

    Terminal admin API
    curl -s -H "Authorization: Bearer $ADMIN_API_TOKEN" http://localhost:8420/v1/admin/users/01a15d8e-856f-7d10-9e63-a550763da368/nhi-key
    {"created":"2026-10-21T08:23:04.034349172Z","fingerprint":"sha256:86f2e918a060dc958b8483ba0248f82acf8e4d21fe658c2cd589f897b4f848a8","registered":true,"user_id":"01a15d8e-856f-7d10-9e63-a550763da368"}
  4. Assign a role and enroll

    Roles arrive the way they do for a person: the identity manager adds the identity to the role’s group. The example added scout-bot to the application role scout-tools-readers with a members PATCH, the request Generic SCIM shows. The identity’s groups then listed the role.

    Enrollment needs no person, because the service signs a short-lived token with the key. strazad’s discovery document names the issuer that accepts the key as nhi_issuer. On the agent’s machine, enroll and check what the service holds:

    Terminal 2 on the agent's machine
    straza enroll --server http://localhost:8420 --headless --user scout-bot

    You should see

    Enrolled headless as scout-bot., followed by a sentence that the Straza background service holds this agent’s key.

    Enrolled headless as scout-bot. The Straza background service holds this agent's key and starts each of its sessions.
    Terminal 2 on the agent's machine
    straza status
    service    straza service v1.0.0-1570-gaf326165-dirty (custody user)
    server     http://localhost:8420
    identity   scout-bot (AI agent, no device, key l4kywJ7bjSeu)
    session    none (start a harness session)
    audit      nothing waiting to upload

    No harness has started a session yet, so the session line says so. Once one starts, a session line names the harness window, the session id, the user, how long its token lasts and the state of its kill switch. The identity line says AI agent, no device, because the key mints every session token and no device exists. Headless agents proves a governed call from such an agent.

  5. Verify

    An administrator’s view of the identity shows every fact in one record.

    1. Users
    2. scout-bot

    You should see

    Origin that starts your identity manager, over SCIM, Agency autonomous, Sponsor alice, the role scout-tools-readers, and the Assertion key badge registered.

    Terminal admin API
    curl -s -H "Authorization: Bearer $ADMIN_API_TOKEN" http://localhost:8420/v1/admin/users/01a15d8e-856f-7d10-9e63-a550763da368 \
      | jq -c '{username, kind, user_type, origin, sponsor, agency_mode, effective_roles, nhi_key_registered}'
    {"username":"scout-bot","kind":"nhi","user_type":"agent","origin":"scim","sponsor":"alice","agency_mode":"autonomous","effective_roles":["scout-tools-readers"],"nhi_key_registered":true}
  6. Undo

    Revoking the key is the cut for the credential, and the next enrollment attempt fails at once. It also ends every session of the agent that is running. The service still holds the agent’s last ID token, but the server refuses it, because that token names the removed key, so no new session starts with it. Registering a different key ends the running sessions the same way.

    1. Users
    2. scout-bot
    3. Revoke key
    4. Revoke key
    build-bot's sheet with its assertion key registered, its fingerprint and Rotate key build-bot's sheet with its assertion key registered, its fingerprint and Rotate key
    A registered key with its fingerprint, Rotate key and Revoke key. Show the whole screen

    The question reads Revoke the assertion key of scout-bot? and says The running sessions of scout-bot end now, and it can no longer mint sessions with the client_credentials grant.

    Terminal Straza administration
    strazactl users nhi-key unset scout-bot
    key revoked for scout-bot

    A new enrollment on the agent’s machine is then refused:

    Terminal 2 on the agent's machine
    straza enroll --server http://localhost:8420 --headless --user scout-bot
    straza: the identity provider refused the agent's sign-in (invalid_client): client authentication failed. Check the registered key or client, and that the user is an active agent

    Retiring the identity is the identity manager’s act. A SCIM deactivation or delete disables the account, revokes its sessions and removes its per-user grants. An administrator can also soft-delete it with DELETE /v1/admin/users/{id}, which answers {"status":"deleted"} and removes the row from strazactl users list. A delete the database refuses answers 500 and changes nothing. Neither the console nor strazactl has a delete.

Caveats

Humans are excluded from the key grant on purpose, so a stolen key can never become a password-equivalent login for a person.

In the enterprise profile an agent has a second way to sign in, the identity provider’s own client-credentials grant. There the agent has a client id and secret at the identity provider, which the service reads from a file only it can read and never from the agent’s environment, as Headless agents describes. strazad resolves the token’s subject to the provisioned identity’s externalId. An agent with a registered key uses the key, and an agent without one uses the identity provider. A deployment that registers no keys has nothing to configure. An agent that an older Straza client enrolled with a key file or a client secret in its environment still checks in without a proof, which the server accepts. Register a new key from straza keygen through the service with strazactl users nhi-key set, and rotate every client secret that sat in an agent’s environment. Standalone and enterprise compared shows both profiles.

Next

  • Headless agents enrolls an agent that no identity manager feeds and proves its first governed call.
  • midPoint hands an agent an access package from midPoint.
Walked on v1.0.0-1570-gaf326165-dirty on 2026-10-21, except the console steps, the midPoint notes, the admin API token and the session end at a key revoke, none of them walked.

An Alpine 3.20 container against a standalone server, both built from an uncommitted working tree, where the SCIM request, the role made with strazactl roles create and its members PATCH, every strazactl and curl block, and keygen, the headless enrollment, status and the refused enrollment through a straza service started with STRAZA_HOME in the agent's home directory all ran. That run came before strazactl stopped signing in, so the admin API token the steps now hand to strazactl was written in on 2026-11-01 and not walked. The administrator's commands and the agent's commands ran as the same OS user with separate home directories. The console steps and the midPoint notes describe the demo stack and were not run. The Undo sentences that say a key removal ends the running sessions and refuses the held ID token, and the dialog text there, were written from the code on 2026-10-27 and not walked. Console screenshots show strazad v1.0.0-1752-g76005024, enterprise and strazad v1.0.0-1753-ga27c516c, standalone.

Search documentation

Search page titles, commands, and article text.

↑ ↓ Choose resultEnter OpenEsc Close