Autenticazione degli utenti finali con il proprio provider di identità authentication

Per impostazione predefinita, ogni azione nell’app è pubblica: qualsiasi piattaforma LLM con l’URL del server MCP può chiamarla e il gestore non è in grado di identificare l’utente finale.

Attiva l’autenticazione quando un’azione deve sapere quale utente finale richiede, ad esempio per restituire ordini, adesioni o dettagli dell’account. La piattaforma LLM firma l’utente con il provider di identità (IdP), invia il token di accesso risultante a ogni chiamata e il gestore riceve l’identità verificata.

Percorso: Copia l’identificatore della risorsa → configura il provider di identità → attivare l’autenticazione → impostare una modalità di autenticazione per ogni azione → distribuire → leggere l’identità nel gestore → testare l’app protetta.

Si tratta di un ramo avanzato, non fa parte del percorso di prima esecuzione. Completa Crea automaticamente la tua prima app e Distribuisci prima l’app.

Come funziona

Hai il tuo provider di identità. L’app distribuita è solo un server di risorse OAuth 2.1. Verifica i token emessi dal server di autorizzazione. Non emette mai token e Adobe non memorizza mai l’ID client o il segreto client.

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

L’autenticazione è configurata per ambiente. Stage e Produzione contengono impostazioni indipendenti, pertanto puoi verificare la configurazione in base a un tenant IdP di sviluppo prima di abilitarla in Produzione.

Prima di iniziare

Copia l’identificatore della risorsa

L’identificatore di risorsa dell’app è l’URL del server MCP. Ogni token di accesso che il provider di identità rilascia per questa app deve denominare tale URL esatto come pubblico. Il binding è ciò che impedisce a un token coniato per un altro servizio di essere riprodotto contro la tua app.

Mantieni questo valore: ne hai bisogno nel provider di identità nel passaggio successivo. Incolla l’URL copiato anziché digitarlo nuovamente. Il controllo del pubblico è una corrispondenza esatta della stringa, che include qualsiasi componente del percorso; pertanto, una differenza di carattere singolo impedisce la convalida di ogni token.

Configurare il provider di identità

I passaggi esatti variano a seconda del provider, ma ogni provider ha bisogno degli stessi quattro elementi.

Attiva autenticazione

Per informazioni sull’accettazione di ogni campo, vedere Impostazioni di autenticazione.

Scegli una modalità di autenticazione per ogni azione

Quando si attiva Abilita autenticazione, ogni azione attualmente impostata su Nessuna cambia in Obbligatorio. In Configurazione per azione, controlla l’assegnazione e imposta la modalità necessaria per ogni azione:

Le azioni già impostate su Obbligatorie o Facoltative mantengono la modalità esistente.

Per un’azione Obbligatorio o Facoltativo, aggiungi i Ambiti necessari. Ogni ambito deve già essere visualizzato in Ambiti supportati. In caso contrario, l’app richiederà un’autorizzazione che non viene annunciata alle piattaforme LLM. Il salvataggio è bloccato fino alla risoluzione della mancata corrispondenza.

Ambiti supportati è l’autorità per questo elenco. Se si rimuove un ambito da esso, tale ambito viene rimosso da ogni azione che lo richieda non appena si apporta la modifica, quindi aggiungere prima un ambito, quindi assegnarlo a un’azione.

Autenticazione obbligatoria per tutte le azioni imposta ogni azione su Obbligatoria. Se si cancella, verrà restituita ogni azione a None.

Al termine, seleziona Salva. Le modifiche alla modalità di autenticazione e all’ambito vengono salvate insieme alle impostazioni a livello di app.

Sono supportate le modalità di combinazione in un’app, alcune azioni pubbliche e altre gestite, e ChatGPT applica singolarmente la modalità di ogni azione: solo le azioni gestite richiedono l’accesso dell’utente.

Distribuire la modifica

Le modifiche di autenticazione hanno effetto sulla prossima distribuzione di questa app. Distribuisci nuovamente l’app nell’ambiente configurato. Consulta Distribuire l’app.

L’URL del server MCP non cambia, quindi tutti i plug-in o i connettori già creati continuano a funzionare. Ora è gestita, quindi ai suoi utenti viene richiesto di effettuare l’accesso la prossima volta che lo utilizzano.

Leggi l’identità nel gestore

Un’identità verificata raggiunge il gestore come secondo argomento. È presente ogni volta che il chiamante invia un token valido, indipendentemente dalla modalità di autenticazione dell’azione, quindi un’azione Facoltativa può personalizzare il risultato quando è presente un token e restituire comunque un risultato quando non lo è.

Utilizza getAuthenticatedUser per leggere l’utente connesso:

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

Non è necessario verificare il token personalmente. Per un’azione Obbligatoria, il runtime blocca ogni chiamata priva di un token valido che contiene gli ambiti elencati, pertanto il gestore viene eseguito solo per un chiamante autorizzato. Utilizzare hasScope quando si desidera eseguire un ramo su un’autorizzazione anziché fare affidamento sul gate, ad esempio in un’azione Facoltativa.

Un’azione Facoltativa può richiedere all’utente di accedere a metà conversazione restituendo extra.challengeAuth(). Questa opzione è disponibile solo per Azioni facoltative:

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

Decidere se eseguire l’escalation da un parametro di input esplicito, come signIn in questo caso, anziché esaminare la formulazione dell’utente.

Imposta error in modo che corrisponda alla condizione segnalata. Utilizzare invalid_token quando il chiamante non dispone di una sessione valida e deve accedere, come nell’esempio precedente, e insufficient_scope quando il chiamante è già connesso ma il token non dispone di un ambito necessario per l’azione. La piattaforma LLM sceglie il testo della richiesta che l’utente vede, e quanto varia con questo valore in base alla piattaforma — quindi invia il codice che descrive la condizione con precisione.

Eseguire la verifica solo quando l’identità necessaria è effettivamente mancante, come nel caso del controllo !extra.authInfo. L’accesso non può soddisfare un gestore che lancia una sfida incondizionata, pertanto all’utente viene richiesto di eseguire di nuovo l’autenticazione a ogni chiamata.

Mantieni il lato server dell’identità. Passa solo ciò di cui il widget ha bisogno in structuredContent e non inserire mai il token di accesso. Vedere Personalizzare un gestore generato.

Per il contratto completo, vedi API di autenticazione gestore.

Testare l’app protetta

Il plug-in o il connettore esistente rileva la modifica dopo la distribuzione. Per configurarne uno da zero:

ChatGPT

Nella finestra di dialogo Nuovo plug-in, imposta Autenticazione in modo che corrisponda alla configurazione delle azioni dell’app:

Un’azione Facoltativa accetta sempre chiamate anonime, pertanto un’app che ne contiene una non è mai completamente gestita. Scegliere Mista anche se ogni azione è impostata su Facoltativa. Solo Richiesto rifiuta i chiamanti non autenticati.

Per il resto della finestra di dialogo, consulta Test del plug-in ChatGPT.

Claude

Aggiungi il connettore personalizzato, quindi seleziona Connetti e completa l’accesso presentato dal provider di identità. Nessuna scelta di autenticazione da effettuare: Claude cancella l’intero connettore ogni volta che viene gestita un’azione. Vedere Verificare il connettore Claude.

Verificare

Se l’accesso non viene avviato o se un token viene rifiutato, vedere Risoluzione dei problemi.

Linee guida sulla sicurezza

Passaggio successivo