Autentique usuários finais com seu próprio provedor de identidade authentication

Por padrão, cada ação no aplicativo é pública: qualquer plataforma LLM com o URL do servidor MCP pode chamá-la e o manipulador não pode identificar o usuário final.

Ative a autenticação quando uma ação precisar saber qual usuário final está solicitando — por exemplo, para retornar seus pedidos, direitos ou detalhes da conta. A plataforma LLM faz com que o usuário entre com o seu provedor de identidade (IdP), envia o token de acesso resultante com cada chamada e seu manipulador recebe a identidade verificada.

Jornada: Copiar o identificador de recurso → configurar seu provedor de identidade → ativar autenticação → definir um modo de autenticação para cada ação → implantar → ler a identidade em seu manipulador → testar o aplicativo protegido.

Esta é uma ramificação avançada, que não faz parte da jornada de primeira execução. Conclua Criar o primeiro aplicativo automaticamente e Implantar o aplicativo primeiro.

Como funciona

Você traz seu próprio provedor de identidade. O aplicativo implantado é apenas um servidor de recursos do OAuth 2.1 — ele verifica os tokens emitidos pelo servidor de autorização. Ele nunca emite tokens e o Adobe nunca armazena a ID do cliente ou o segredo do cliente.

┌── 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      │
└─────────────────────────────────────────────────────────────────────────┘

A autenticação está configurada por ambiente. O Preparo e a Produção contêm configurações independentes, de modo que você pode verificar a configuração em relação a um locatário IdP de desenvolvimento antes de habilitá-lo na Produção.

Antes de começar

Copiar o identificador de recurso

O identificador de recursos do seu aplicativo é a URL do servidor MCP. Cada token de acesso que seu provedor de identidade emite para este aplicativo deve nomear esse URL exato como seu público-alvo; essa vinculação é o que impede que um token cunhado para outro serviço seja reproduzido no aplicativo.

Keep this value: você precisará dele no provedor de identidade na próxima etapa. Cole o URL copiado em vez de digitá-lo novamente. A verificação de público-alvo é uma correspondência de sequência exata, incluindo qualquer componente do caminho, portanto, uma única diferença de caractere faz com que cada token falhe na validação.

Configurar o provedor de identidade

As etapas exatas diferem de acordo com o provedor, mas cada provedor precisa das mesmas quatro coisas.

Ativar autenticação

Para saber o que cada campo aceita, consulte Configurações de autenticação.

Escolha um modo de autenticação para cada ação

Quando você ativa a Habilitar autenticação, cada ação atualmente definida como Nenhuma é alterada para Necessária. Em Configuração por ação, revise essa atribuição e defina o modo de que cada ação precisa:

As ações já definidas como Obrigatórias ou Opcionais mantêm o modo existente.

Para uma ação Obrigatória ou Opcional, adicione os Escopos necessários. Todos os escopos já devem aparecer em Escopos com suporte acima; caso contrário, o aplicativo exigirá uma permissão que não anunciará nas plataformas LLM. Salvamento bloqueado até que a incompatibilidade seja resolvida.

Escopos com suporte é a autoridade para esta lista. Se você remover um escopo dele, esse escopo será removido de todas as ações que exigirem essa alteração assim que você fizer a alteração. Portanto, adicione um escopo lá primeiro e, em seguida, atribua-o a uma ação.

Exigir autenticação em todas as ações define cada ação como Necessária. Limpá-la retorna cada ação para Nenhuma.

Selecione Salvar quando terminar. As alterações no modo de autenticação e no escopo são salvas junto com as configurações no nível do aplicativo.

A combinação de modos em um aplicativo — algumas ações públicas, outras restritas — é suportada, e ChatGPT aplica o modo de cada ação individualmente: somente as ações restritas solicitam que o usuário entre.

Implantar a alteração

As alterações de autenticação têm efeito na próxima implantação do aplicativo. Implante o aplicativo novamente no ambiente que você configurou. Consulte Implantar seu aplicativo.

O URL do servidor MCP não é alterado, portanto, qualquer plug-in ou conector já criado continua a funcionar. Agora ele está restrito, portanto, os usuários são solicitados a fazer logon na próxima vez que o usarem.

Ler a identidade no seu manipulador

Uma identidade verificada atinge seu manipulador como o segundo argumento. Ele estará presente sempre que o chamador enviar um token válido, independentemente do modo de autenticação da ação, portanto uma ação Opcional pode personalizar seu resultado quando um token estiver presente e ainda retornar um resultado quando não estiver.

Usar getAuthenticatedUser para ler o usuário conectado:

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
  };
};

Você não precisa verificar o token sozinho. Para uma ação Obrigatório, o tempo de execução bloqueia todas as chamadas que não tenham um token válido carregando os escopos listados, portanto, o manipulador só é executado para um chamador autorizado. Use hasScope quando quiser ramificar em uma permissão em vez de depender da porta — por exemplo, em uma ação Opcional.

Uma ação Opcional pode solicitar que o usuário entre no meio da conversa retornando extra.challengeAuth(). Isto está disponível somente em Ações opcionais:

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()
    }]
  };
};

Decida se escalará a partir de um parâmetro de entrada explícito, como signIn faz aqui, em vez de inspecionar o texto do usuário.

Defina error para corresponder à condição que você está relatando. Use invalid_token quando o chamador não tiver uma sessão válida e precisar entrar, como no exemplo acima, e insufficient_scope quando o chamador já estiver conectado, mas o token não tiver um escopo de que a ação precise. A plataforma LLM escolhe o texto do prompt que o usuário vê e a variação desse texto em relação a esse valor varia de acordo com a plataforma; portanto, envie o código que descreve a condição com precisão.

Desafie somente quando a identidade necessária estiver realmente ausente, como a verificação !extra.authInfo faz aqui. Um manipulador que desafia incondicionalmente não pode ser satisfeito ao fazer logon, portanto, o usuário é solicitado a se autenticar novamente em cada chamada.

Manter a identidade do lado do servidor. Passe somente o que o widget precisa para structuredContent, e nunca coloque o token de acesso lá — consulte Personalizar um manipulador gerado.

Para obter o contrato completo, consulte API de autenticação do manipulador.

Testar o aplicativo protegido

Seu plug-in ou conector existente seleciona a alteração após a implantação. Para configurar um do zero:

ChatGPT

Na caixa de diálogo Novo Plug-in, defina a Autenticação para corresponder à forma como você configurou as ações do aplicativo:

Uma ação Opcional sempre aceita chamadas anônimas, portanto, um aplicativo que contém uma chamada nunca é totalmente restringido — escolha Misto mesmo que cada ação esteja definida como Opcional. Somente Obrigatório recusa chamadores não autenticados.

Consulte Testar o plug-in ChatGPT para o restante da caixa de diálogo.

Claude

Adicione o conector personalizado, selecione Conectar e conclua a entrada que seu provedor de identidade apresenta. Não há opção de autenticação a ser feita — Claude portas o conector inteiro sempre que qualquer ação for fechada. Consulte Testar o conector Claude.

Verificar

Se a entrada não for iniciada ou um token for rejeitado, consulte Solução de problemas.

Orientação de segurança

O que vem a seguir