Authenticate end users with your own identity provider authentication

By default, every action in your app is public. Any LLM platform with your MCP server URL can call those actions, and your handler cannot identify the end user.

Turn on authentication when an action needs to know which end user is asking — for example, to return their orders, entitlements, or account details. The LLM platform signs the user in with your identity provider (IdP), sends the resulting access token with every call, and your handler receives the verified identity.

In this guide: Learn how to connect your identity provider and choose which actions require sign-in. Use the verified identity in your handlers, deploy the app, and test sign-in and protected actions.

Authentication setup is an advanced task. Complete Infrastructure setup, Create actions, and Deploy your app first.

How it works

You bring your own identity provider. Your deployed app is only an OAuth 2.1 resource server — it verifies tokens that your authorization server issued. It never issues tokens, and Adobe never stores your client ID or client secret.

┌── Your identity provider ───────────────────────────────────────────────┐
│  Authorization server — you own it                                      │
│  Issues access tokens, holds the user directory, defines the scopes     │
└─────────────────────────────────────────────────────────────────────────┘
        ▲  2  user signs in, platform gets an access token
        │                                    │
        │  1  platform discovers your        │  3  every tools/call carries
        │     authorization server from      │     Authorization: Bearer <token>
        │     your app's metadata            ▼
┌── LLM platform (ChatGPT, Claude, …) ────────────────────────────────────┐
└─────────────────────────────────────────────────────────────────────────┘
                                             │
                                             ▼
┌── Your LLM App on Adobe I/O Runtime ────────────────────────────────────┐
│  Resource server — verifies the token's signature, issuer, audience,    │
│  and expiry, then enforces the auth mode you set for each action        │
│                                                                         │
│  Your handler reads the verified identity from its second argument      │
└─────────────────────────────────────────────────────────────────────────┘

Configure authentication per environment. Stage and Production hold independent settings. Verify the configuration against a development IdP tenant before enabling authentication on Production.

Before you begin

Copy the resource identifier

Your app’s resource identifier is its MCP server URL. Every access token your identity provider issues for the app must name that exact URL as its audience. This audience binding prevents use of a token issued for another service.

Keep the copied MCP server URL for the identity provider configuration in the next step. Paste the URL rather than retyping it. The audience check requires an exact string match, including the path. A single character difference causes every token to fail validation.

Configure your identity provider

The steps vary by provider. Configure the following four items.

Turn on authentication

For field requirements, see Authentication settings.

Choose an auth mode for each action

When you turn on Enable authentication, every action currently set to None changes to Required. Under Per-action configuration, review that assignment and set the mode each action needs:

Actions already set to Required or Optional keep their existing mode.

For a Required or Optional action, add the Scopes it needs. Every scope must already appear in Scopes supported so the app advertises each required permission to LLM platforms. The platform blocks saving until you resolve any scope mismatch.

Scopes supported controls the available scopes. Removing a scope from that list immediately removes the scope from every action that required it. Add each scope to the list before assigning the scope to an action.

Selecting Require auth on all actions changes None actions to Required, but preserves actions already set to Optional. To require sign-in for every action, change any remaining Optional rows to Required individually. Clearing the checkbox returns every action to None.

Select Save when you are done. Auth mode and scope changes save alongside the app-level settings.

ChatGPT supports mixed auth modes within one app and applies each action’s mode individually. Public actions do not prompt for sign-in; protected actions prompt as needed.

Claude also supports mixed apps through lazy authentication. With Sign in when needed selected during connector setup, public actions remain usable anonymously and the platform asks for sign-in when a Required action is called. An app whose actions are all Required requires sign-in before use. See LLM platform behavior for the distinction between a required action and an optional handler requesting sign-in.

Deploy the change

Authentication changes take effect on this app’s next deploy. Deploy the app again to the environment you configured. See Deploy your app.

Your MCP server URL does not change. Refresh the connection’s metadata and verify that its authentication settings match the app’s new configuration. A platform may require you to reconnect or recreate the connection when its authentication method changes.

Read the identity in your handler

A verified identity reaches your handler as the second argument whenever the caller sends a valid token, regardless of the action’s auth mode. An Optional action can use that identity to personalize results when available and return an anonymous result otherwise.

Use getAuthenticatedUser to read the signed-in user:

const { getAuthenticatedUser } = require('@adobe/llm-apps-runtime');

module.exports = async ({ orderId }, extra) => {
  const userId = getAuthenticatedUser(extra);

  if (!userId) {
    return { content: [{ type: 'text', text: 'Sign in to see your orders.' }] };
  }

  const order = await fetchOrderForUser(userId, orderId);

  return {
    content: [{ type: 'text', text: `Order ${order.id} is ${order.status}.` }],
    structuredContent: order
  };
};

The runtime verifies the token for you. For a Required action, it blocks every call that lacks a valid token with the listed scopes. The handler runs only for an authorized caller. Use hasScope to choose handler behavior based on a permission — for example, in an Optional action.

To request sign-in during a conversation, return extra.challengeAuth() from the handler. The helper is available only on Optional actions:

module.exports = async ({ signIn }, extra) => {
  if (signIn && !extra.authInfo) {
    return extra.challengeAuth({
      error: 'invalid_token',
      errorDescription: 'Sign in to see member pricing.'
    });
  }

  return {
    content: [{
      type: 'text',
      text: extra.authInfo ? await memberDeals() : await publicDeals()
    }]
  };
};

Use an explicit input parameter, such as signIn in this example, to decide when to request authentication. Do not infer that decision from the user’s wording.

Set error to match the reported condition. Use invalid_token when the caller has no valid session and needs to sign in, as in the example above. Use insufficient_scope when the caller is signed in but the token lacks a required scope. Each LLM platform chooses the prompt wording and how to respond to the error code. Send the code that accurately describes the condition.

Request authentication only when the required identity is missing, as the !extra.authInfo check does in this example. Signing in does not resolve an unconditional challenge: the handler requests authentication again on every call.

Keep the identity server-side. Pass only the data the widget needs into structuredContent. Never include an access token in structuredContent. See Customize a generated handler.

For the full contract, see Handler auth API.

Test the protected app

Your existing plugin or connector uses the updated configuration after deployment. To create a new connection, follow the instructions for your platform:

ChatGPT

In the New Plugin dialog, set Authentication to match how you configured the app’s actions:

An Optional action always accepts anonymous calls, so an app that contains one is never fully gated — choose Mixed even if every action is set to Optional. Only Required refuses unauthenticated callers.

See Test the ChatGPT plugin for the rest of the dialog.

Claude

Add the custom connector and review its authentication settings. For a mixed public/protected app, choose Sign in when needed when available. To request sign-in before connector use, select Sign in now. The dialog varies by account or organization; see Test the Claude connector.

Verify

If sign-in does not start, or a token is rejected, see Troubleshooting.

Security guidance

What’s next