Managed AgentsEnterprise configuration

Single sign-on

Copy page



Let people and services call your self-hosted Claude Managed Agents server with tokens from your identity provider.

By default, your server accepts one shared key, the server API key. With single sign-on, each person or service can also call the server with a token from your OpenID Connect (OIDC) identity provider. The server gives the caller a role from the groups in the token. The server API key keeps working as an administrator credential.

This page shows how to add your identity provider, what each role can do, and how to let developers log in from a terminal.

Add your identity provider

1. 1

   Register the server in your identity provider

   Register the server as an API with an identifier such as api://cma-server, and have clients request tokens for it.

2. 2

   List the identity provider in the settings file

   Add an entry under auth.issuers in the settings file:

   auth:
     issuers:
       - name: okta
         issuer_url: https://login.example.com/oauth2/default
         audiences: [api://cma-server]
         roles:
           - group: cma-admins
             role: admin
           - group: "eng-*"
             role: developer

   

   • name labels the issuer in log lines, and the server records it as part of the creator of each resource. Don’t change it once people have created resources.
   • issuer_url must equal the iss claim of your tokens.
   • audiences lists the values that a token’s aud claim can carry, such as the identifier from the first step.
   • roles maps a group to admin, developer, or user. The highest matching role wins.

   For the other fields, see Issuer entries. If your provider is Microsoft Entra ID, also see Microsoft Entra ID.

3. 3

   Restart the server and check sign-in

   Restart the server. A caller sends the token as Authorization: Bearer <token>, on any route that accepts the server API key.

   For every request that a token authenticated, the server logs auth=oidc, the issuer’s name, and the caller’s subject (sub=).

If sign-in fails

Microsoft Entra ID

Entra ID differs from other providers in two ways. Both settings go in the issuer entry:

• The person: Entra ID gives a person a different sub in each client application, so the default would record one person as several creators. Set subject_claim: oid.
• The groups: Entra ID leaves the groups claim out of a token if the person belongs to many groups. That person then matches no roles entry. To prevent this, have Entra ID emit only the groups assigned to the application. Or assign app roles to people in Entra ID, and set groups_claim: roles so that the server reads app roles in place of groups.

What each role can do

developer and user have the same access. A caller with either role:

• Can’t see a resource that someone else created. The resource is absent from lists, and a request for its ID gets the same answer as a request for an unknown ID. That includes everything created with the server API key before you turned on single sign-on.
• Can’t share a resource with another caller or a group.

Map admin to exact group names. An administrator can also start a session that uses any user’s vault. So give the role only to groups that you trust with every user’s MCP tokens.

Let developers log in from a terminal

Developers can log in through your identity provider and then use the ant CLI under their own identity, without the server API key. You do the first two steps, and each developer does the third.

1. 1

   Register an application in your identity provider

   Register a native (“public”) application that has:

   • No client secret
   • The authorization code grant with PKCE
   • The redirect URI http://127.0.0.1/callback

   Some providers need one of the other redirect URIs.

2. 2

   Add the application to the issuer entry

   Add login_client_id and login_scopes to the issuer entry, and restart the server:

   login_client_id: 0oa1b2c3d4e5f6g7h8i9
   login_scopes: [openid, cma-server.access]

   

   login_scopes lists the scopes that your provider needs to issue a token whose aud claim is in the issuer entry’s audiences list.

3. 3

   Log in

   Each developer runs the login from the top of the extracted archive:

   ./cma-server-admin login https://cma.example.com

   

   The server’s URL must be https://, or http:// to localhost, 127.0.0.1, or ::1. With one of the other redirect URIs, add its flag to the command.

   The command opens the provider’s sign-in page in a browser and then writes an ant CLI profile named cma-server. Pass --profile cma-server to any ant command, or run ant profile activate cma-server to make the profile the default.

When the token expires, the developer runs login again. To have the ant CLI renew the token instead, add offline_access to login_scopes.

Other redirect URIs

To list the other flags, add -h to the login command.

Let people sign in to the console on your server

The console on your server signs people in through the application that you registered for the terminal login. To finish its setup, see Set up sign-in.