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 chamar essas ações 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.

Neste guia: Saiba como conectar seu provedor de identidade e escolher quais ações exigem entrada. Use a identidade verificada em seus manipuladores, implante o aplicativo e teste as ações de logon e protegidas.

A configuração da autenticação é uma tarefa avançada. Conclua primeiro a Configuração de infraestrutura, Criar ações e Implantar seu aplicativo.

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

Configurar autenticação por ambiente. O Preparo e a Produção contêm configurações independentes. Verifique a configuração em relação a um locatário IdP de desenvolvimento antes de habilitar a autenticação na Produção.

Antes de começar

Copiar o identificador de recurso

O identificador de recursos do seu aplicativo é a URL do servidor MCP. Todos os tokens de acesso com problemas do provedor de identidade do aplicativo devem nomear esse URL exato como público-alvo. Essa associação de público impede o uso de um token emitido para outro serviço.

Mantenha o URL do servidor MCP copiado para a configuração do provedor de identidade na próxima etapa. Cole o URL em vez de digitá-lo novamente. A verificação de público-alvo requer uma correspondência exata de sequência, incluindo o caminho. Uma única diferença de caractere faz com que cada token falhe na validação.

Configurar o provedor de identidade

As etapas variam de acordo com o provedor. Configure os quatro itens a seguir.

Ativar autenticação

Para obter os requisitos do campo, 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 para que o aplicativo anuncie cada permissão necessária para plataformas LLM. A plataforma bloqueia o salvamento até que você resolva qualquer incompatibilidade de escopo.

Escopos com suporte controla os escopos disponíveis. A remoção de um escopo dessa lista remove imediatamente o escopo de cada ação que o exigiu. Adicione cada escopo à lista antes de atribuir o escopo a uma ação.

Selecionar Exigir autenticação em todas as ações altera as ações Nenhuma para Obrigatório, mas preserva as ações já definidas como Opcional. Para exigir a entrada em cada ação, altere as Opcionais linhas restantes para Obrigatório individualmente. Desmarcar a caixa de seleção retorna cada ação como 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.

O ChatGPT oferece suporte a modos de autenticação mistos em um aplicativo e aplica o modo de cada ação individualmente. As ações públicas não solicitam o logon; as ações protegidas solicitam, conforme necessário.

Claude também oferece suporte a aplicativos mistos por meio de autenticação lenta. Com Entrar quando necessário selecionado durante a configuração do conector, as ações públicas permanecem utilizáveis anonimamente e a plataforma solicita entrada quando uma ação Obrigatório é chamada. Um aplicativo cujas ações são todas Obrigatórias requer entrada antes do uso. Consulte Comportamento da plataforma LLM para obter a distinção entre uma ação necessária e um manipulador opcional solicitando entrada.

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.

A URL do servidor MCP não é alterada. Atualize os metadados da conexão e verifique se suas configurações de autenticação correspondem à nova configuração do aplicativo. Uma plataforma pode exigir que você reconecte ou recrie a conexão quando seu método de autenticação mudar.

Ler a identidade no seu manipulador

Uma identidade verificada atinge seu manipulador como o segundo argumento sempre que o chamador envia um token válido, independentemente do modo de autenticação da ação. Uma ação Opcional pode usar essa identidade para personalizar resultados quando disponíveis e retornar um resultado anônimo caso contrário.

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

O tempo de execução verifica o token para você. Para uma ação Obrigatório, ele bloqueia todas as chamadas que não tenham um token válido com os escopos listados. O manipulador é executado somente para um chamador autorizado. Use hasScope para escolher o comportamento do manipulador com base em uma permissão — por exemplo, em uma ação Opcional.

Para solicitar entrada durante uma conversa, retorne extra.challengeAuth() do manipulador. O auxiliar 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()
    }]
  };
};

Use um parâmetro de entrada explícito, como signIn neste exemplo, para decidir quando solicitar autenticação. Não inferir essa decisão a partir do texto do usuário.

Defina error para corresponder à condição reportada. Use invalid_token quando o chamador não tiver uma sessão válida e precisar entrar, como no exemplo acima. Use insufficient_scope quando o chamador estiver conectado, mas o token não tiver um escopo necessário. Cada plataforma do LLM escolhe a redação de prompt e como responder ao código de erro. Envie o código que descreve com precisão a condição.

Solicite autenticação somente quando a identidade necessária estiver ausente, como faz a verificação !extra.authInfo neste exemplo. Fazer logon não resolve um desafio incondicional: o manipulador solicita a autenticação novamente em cada chamada.

Manter a identidade do lado do servidor. Transmita apenas os dados de que o widget precisa para structuredContent. Nunca inclua um token de acesso em structuredContent. 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 usa a configuração atualizada após a implantação. Para criar uma nova conexão, siga as instruções para sua plataforma:

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 e revise as configurações de autenticação. Para um aplicativo misto público/protegido, escolha Fazer logon quando necessário quando disponível. Para solicitar a entrada antes do uso do conector, selecione Entrar agora. A caixa de diálogo varia de acordo com a conta ou organização. 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