Skip to main content

​
Atoti Intelligence SDK

This is part of the Atoti Intelligence SDK offer.
This guide explains how to enable the self-issued OAuth 2.1 mode on the Atoti MCP Server, where the Atoti server acts as its own authorization server. MCP clients (Claude Code, Claude Desktop, Cursor, Cline, VS Code’s MCP support, Gemini CLI) drive the standard browser-based PKCE flow directly against Atoti. No external identity provider is required. Users sign in with their existing Atoti credentials. No separate IdP, no extra user store.

​
What self-issued mode is

The Atoti MCP Server supports two OAuth 2.1 modes, selected by atoti.server.endpoint.mcp.oauth2.mode: In self-issued mode the Atoti server is both the OAuth 2.1 authorization server and the resource server. It publishes the standard metadata documents, handles Dynamic Client Registration, and issues JWTs signed with Atoti’s own keys. The MCP client’s authorization flow is identical to external mode; only the server the client talks to changes.

​
Prerequisites

  • The Atoti MCP Server is already running. See Atoti MCP server setup guide.
  • Atoti Server is configured with an RSA keypair via atoti.jwt.key.* (recommended). When no keypair is configured, an ephemeral key is generated at startup (see Signing keys for the implications).

​
Minimal configuration

Self-issued mode requires only four lines. Add the following to application.yml:
No authorization-server URL, no client registration, no IdP setup. Atoti handles everything.

​
How the browser PKCE flow works

The following steps describe the full authorization flow as a client such as Claude Code experiences it.
  1. The client sends POST /mcp and receives 401 with WWW-Authenticate: Bearer realm="mcp", resource_metadata="...".
  2. The client fetches /.well-known/oauth-protected-resource (RFC 9728). The document advertises the same origin as the authorization server.
  3. The client fetches /.well-known/oauth-authorization-server (RFC 8414). The document advertises authorization_endpoint, token_endpoint, registration_endpoint, jwks_uri, and PKCE S256 support.
  4. The client performs anonymous Dynamic Client Registration at POST /oauth2/register (also accepted at POST /register) and receives a generated client_id.
  5. The client opens the system browser at /oauth2/authorize. The user is redirected to Atoti’s own branded login page at /login and signs in with existing Atoti credentials.
  6. After sign-in, the browser is shown a consent page at /oauth2/consent titled “Allow Atoti to connect to <client name>?” listing the requested scopes (for example, mcp.read, mcp.write). The user clicks Allow or Deny.
  7. On Allow, the browser redirects back to the client’s loopback URI with an authorization code. On Deny, access_denied is returned to the client and no token is issued.
  8. The client exchanges the code at POST /oauth2/token for a JWT access token and a refresh token.
  9. The client calls POST /mcp with Authorization: Bearer <jwt>. Atoti validates the token and the user’s Atoti roles authorize the requested MCP tools.

​
Endpoints exposed in self-issued mode

When mode=self-issued, the following endpoints become active in addition to the standard /mcp endpoint:

​
Key design points

​
Identity and keys

Self-issued mode reuses Atoti’s existing identity stack. End users authenticate against the same user store that secures the rest of the Atoti deployment (the application’s configured UserDetailsService or authentication manager). The issued JWTs are signed with Atoti’s own RSA keypair, validated by Atoti’s normal JWT filter, and carry the user’s real Atoti roles into /mcp authorization. No separate key material or user store is needed. Self-issued mode requires the application to provide a UserDetailsService (or authentication manager) bean. Atoti deployments already supply one — the basic-authentication fallback registers a UserDetailsService whenever any authentication is configured. For local development without a full deployment, the apps/basic sample application supplies an in-memory user store. If no UserDetailsService is configured, the server still starts but logs a warning, and the browser login cannot authenticate users until one is provided: atoti.server.endpoint.mcp.oauth2.mode=self-issued is active but no UserDetailsService is configured, so the OAuth 2.1 browser login cannot authenticate users.

​
Signing keys

The server selects the signing key in the following order of precedence:
  1. Atoti’s configured RSA keypair (recommended). Set via atoti.jwt.key.* or activeviam.jwt.key.*. The same key signs MCP tokens and all other Atoti JWTs.
  2. A PKCS#12 or JKS keystore, configured via atoti.server.endpoint.mcp.oauth2.authserver.jwk.keystore-location, ...keystore-password, and ...key-alias.
  3. An ephemeral keypair, generated at startup. This fallback is for development only: all issued tokens become invalid on restart, and a warning is logged at startup.
For production deployments, use option 1 or 2 so that tokens survive server restarts.

​
Issuer URI

atoti.server.endpoint.mcp.oauth2.authserver.issuer is optional. When unset, the issuer and all advertised absolute URLs are derived from the incoming HTTP request. Set it explicitly when the server runs behind a reverse proxy that rewrites the host or scheme, or enable Spring Boot’s ForwardedHeaderFilter via server.forward-headers-strategy=framework.

​
MCP transport

The starter configures spring.ai.mcp.server.protocol=STREAMABLE by default, which exposes a single POST /mcp endpoint. This is the transport expected by current MCP clients. Override to SSE if the deployment requires the older server-sent events transport. After a user authenticates, the browser is shown a consent page at /oauth2/consent titled “Allow Atoti to connect to <client name>?”. The page lists the requested OAuth scopes (for example, mcp.read, mcp.write) and presents Allow and Deny buttons.
  • Allow completes the flow: an authorization code is issued and the client exchanges it for a JWT.
  • Deny returns access_denied to the client; no token is issued.
Consent is requested on every authorization request, including when the user already has an active Atoti browser session. Consent is never remembered across requests. The consent page itself is protected by the deployment’s existing human security filter chain (the same authentication method as the rest of the Atoti UI). A browser that arrives at /oauth2/consent unauthenticated is redirected to the Atoti login page first. A non-browser caller receives 401. CSRF protection. The Allow/Deny decision is protected by a single-use session-bound consent key: the key is generated when the gate stashes the pending authorization request, and consumed on the subsequent /oauth2/authorize pass. An attacker cannot forge a consent POST without knowing that key, which lives only in the server-side session. For production deployments, also set server.servlet.session.cookie.same-site=Lax so the session cookie is not sent on cross-site navigations, providing defence-in-depth against CSRF on the consent endpoint. To disable the consent step and restore the previous behavior (a code is issued immediately after authentication), set atoti.server.endpoint.mcp.oauth2.authserver.consent.enabled to false.

​
Property reference

All properties are under the atoti.server.endpoint.mcp.oauth2 prefix unless noted.

​
Limitations and security notes

Open Dynamic Client Registration. The /oauth2/register endpoint accepts unauthenticated registration requests by design: any caller can register a client, but no token is issued until a user completes interactive login at /oauth2/authorize. For deployments with strict registration policies, place the endpoint behind rate-limiting or a registration filter. In-memory client store. Dynamically registered clients are held in memory. They are lost on server restart, but clients re-register transparently on the next connection attempt. Ephemeral signing key. If no RSA keypair is configured (neither atoti.jwt.key.* nor a keystore), an ephemeral key is generated at startup. All tokens issued with that key become invalid on restart. A warning is logged. Use a persistent key in production. Token lifetime. Access tokens default to one hour. Configure atoti.server.endpoint.mcp.oauth2.authserver.access-token-ttl to a shorter value in security-sensitive environments.

​
When to use each OAuth 2.1 mode