DocumentationLLM Apps

Authentication reference authentication-reference

Last update: October 19, 2026
IMPORTANT
Adobe LLM Apps is currently in Beta.
Features, workflows, and UI shown here do not necessarily represent the final state of the product. To join the Beta, send an email to llm-apps-beta@adobe.com.

Use this page to look up authentication fields and contracts. For setup instructions, see Authenticate end users with your own identity provider.

Authentication settings authentication-settings

Open Settings > Authentication. Each environment stores its own settings. Use the Workspace picker to select the environment to edit; saving settings never affects the other environment.

Field
Required
Description
Workspace
—
Environment for the authentication settings: Stage or Production
Enable authentication
—
Master switch. When off, every action is public regardless of its auth mode
Issuer
Yes
Your identity provider’s issuer URL and the expected iss claim. Must be HTTPS. Also published as this app’s authorization server. One identity provider per app
Scopes supported
No
The complete set of scopes this app’s actions may require. Published to LLM platforms as the app’s supported scopes
JWKS URI
No
Advanced. The HTTPS URL of your signing key set. Only needed when it differs from what your authorization server’s metadata advertises

Validation rules

Rule
Effect
Issuer is empty while Enable authentication is on
Save is blocked
Issuer or JWKS URI is not an HTTPS URL
Save is blocked
An action requires a scope missing from Scopes supported
Save is blocked until you add the scope or remove it from the action
A scope is removed from Scopes supported
It is removed from every action that required it, immediately, without waiting for a save
Scopes supported is empty
No scope can be granted, so any scope already on an action is removed. No warning is shown in this case
offline_access is listed in Scopes supported or on an action
Removed when the app is deployed, regardless of casing or surrounding whitespace, so the settings page can show a scope the deployed app does not have. offline_access requests a refresh token from your authorization server rather than granting access to this app, so it is not a scope this app advertises. You do not need to list it — the LLM platform requests it from your authorization server directly

Trailing slashes on Issuer are normalized. The iss comparison tolerates the difference, so tokens from a provider that always includes a trailing slash still validate.

Auth modes auth-modes

Set per action under Per-action configuration.

Mode
Token required
Handler receives identity
Advertised to the platform as
None
No
Only when the caller supplies a valid token
noauth
Required
Yes, with every listed scope
Always
oauth2
Optional
No
When a valid token is present
noauth and oauth2

A Required action’s handler never runs without a valid, correctly scoped token. An Optional action’s handler always runs and may request sign-in itself with extra.challengeAuth().

Required is therefore the only mode that rejects unauthenticated callers. An app rejects all anonymous calls only when every action is Required. If any action is None or Optional, the app uses mixed authentication because at least one action accepts anonymous calls.

Auth modes take effect only when Enable authentication is on. Changes take effect on the app’s next deployment.

Changing the authentication switch also rewrites the per-action modes:

Switch change
Effect on per-action modes
Off to on
Every None action becomes Required. Actions already Required or Optional keep their mode
On to off
Every action’s mode and scopes are cleared for that environment. The configuration is not restored if you turn the switch on again

Switching Workspace never rewrites modes. The picker loads the other environment’s saved configuration without changing it.

With Enable authentication on and every action set to None, the app does not require authentication but still publishes its authorization server for discovery. To make the app fully public, turn the switch off.

An app can use different auth modes for individual actions. See LLM platform behavior for how each platform applies them.

Token requirements token-requirements

Your identity provider must issue access tokens that meet all the following requirements. The runtime treats a token that fails any check as absent: the caller is unauthenticated, and a Required action challenges the caller to sign in.

Requirement
Detail
Format
Signed JWT. Opaque tokens are not supported
Signing algorithm
RS256, RS384, RS512, ES256, ES384, ES512, PS256, PS384, or PS512. HMAC algorithms such as HS256 are rejected
iss
Must match Issuer
aud
Must contain the app’s resource identifier — its MCP server URL for that environment
exp
Must be in the future
scope or scp
The runtime reads a space-delimited scope string, or falls back to an array of strings in scp. Use one of these shapes for scopes checked against each action’s requirements
sub
The user identifier your handler reads through getAuthenticatedUser
Transport
Authorization: Bearer <token> request header

Any additional flat claims your provider includes — for example tenant or email — are passed through to your handler. Nested objects are dropped, and long string values are truncated.

Identity provider discovery discovery

Your app publishes its own RFC 9728 protected resource metadata so LLM platforms can locate your authorization server. You do not need to create, host, or configure the protected resource metadata.

Your identity provider must provide the following discovery information:

Requirement
Detail
Authorization server metadata
Your authorization server must publish discovery metadata for LLM clients. Unless JWKS URI is set, this app’s runtime looks specifically for RFC 8414 OAuth authorization-server metadata to locate jwks_uri; it does not fall back to the OIDC discovery path
An issuer with a path
The well-known segment goes before the path, not after it. An issuer at https://auth.example.com/oauth2/default serves its metadata at https://auth.example.com/.well-known/oauth-authorization-server/oauth2/default
Direct signing-key URL
Set JWKS URI when the keys are hosted elsewhere or the provider exposes only OIDC discovery. This bypasses runtime discovery of the keys, not the discovery required by LLM clients

Handler auth API handler-auth-api

The package @adobe/llm-apps-runtime exports the following helpers. Each helper accepts extra, the second argument your handler receives.

Helper
Returns
getAuthenticatedUser(extra)
The signed-in user’s sub claim, or undefined when the call is unauthenticated
hasScope(extra, scope)
true when the caller’s token carries scope

The verified token information is available in extra.authInfo, which is undefined for an unauthenticated call.

Property
Description
authInfo.token
The raw bearer token. Do not log it or return it to the client
authInfo.clientId
The client_id or azp claim, or unknown
authInfo.scopes
Array of granted scopes
authInfo.expiresAt
Token expiry, as the exp claim
authInfo.resource
The app’s resource identifier that the token was validated against
authInfo.extra
sub plus any other flat claims your identity provider included

extra.challengeAuth(options) is available only on Optional actions. Return its result from your handler to ask the user to sign in instead of returning content.

The helper returns a tool-result challenge for ChatGPT. Claude requires a transport-level HTTP challenge. The runtime supplies that challenge for Required actions, but not through the optional-handler helper.

Option
Description
error
An RFC 6750 Bearer error code: invalid_token, insufficient_scope, or invalid_request. Defaults to insufficient_scope
errorDescription
The message shown to the user. Defaults to a generic sign-in prompt
scope
Space-delimited scopes to request. Omit it to let the platform fall back to the app’s supported scopes
IMPORTANT
Always set error explicitly. Use invalid_token for a caller with no valid session, and insufficient_scope only for a caller whose token is valid but lacks a required scope. The runtime passes the value to the LLM platform, which chooses the wording of the sign-in prompt. Send the code that accurately describes the condition rather than the code with your preferred prompt.

LLM platform behavior platform-behavior

Both platforms support public and protected actions in the same app, but their sign-in triggers differ.

Behavior
ChatGPT
Claude
Mixed authentication
Public actions work anonymously; Required actions request sign-in
With Sign in when needed, public actions work anonymously and a protected call starts sign-in
App with every action Required
Configure OAuth authentication
Requires authentication before use
Connector setup
Use No Auth for a public app, OAuth when every action is Required, and Mixed otherwise, where those choices are offered
Review the detected settings. Choose Sign in when needed for mixed apps, or Sign in now for up-front sign-in
Missing identity or required scope
Runtime returns the platform’s authentication challenge
Runtime returns HTTP 401 for missing/invalid identity, or HTTP 403 with an insufficient-scope challenge for a valid token missing a required scope
Optional handler’s extra.challengeAuth()
Can start re-authentication
A successful HTTP tool-result response does not start sign-in. Use a Required action for a portable sign-in gate

See Claude lazy authentication and ChatGPT authentication for current client behavior. Connector UI and policy can vary by account and organization.

recommendation-more-help
llm-apps-help-main-toc