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ò richiamare tali azioni 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.

In questa guida: Scopri come connettere il provider di identità e scegliere quali azioni richiedono l’accesso. Utilizza l’identità verificata nei gestori, distribuisci l’app e verifica l’accesso e le azioni protette.

La configurazione dell’autenticazione è un’attività avanzata. Completa Configurazione infrastruttura, Crea azioni 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      │
└─────────────────────────────────────────────────────────────────────────┘

Configura l’autenticazione per ambiente. Stage e Production contengono impostazioni indipendenti. Verificare la configurazione rispetto a un tenant IdP di sviluppo prima di abilitare l’autenticazione 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 l’app deve denominare tale URL esatto come pubblico. Questo binding di pubblico impedisce l’utilizzo di un token rilasciato per un altro servizio.

Nel passaggio successivo, conserva l’URL del server MCP copiato per la configurazione del provider di identità. Incolla l’URL anziché digitarlo nuovamente. Il controllo del pubblico richiede una corrispondenza esatta della stringa, incluso il percorso. Una differenza di carattere singolo fa sì che ogni token non superi la convalida.

Configurare il provider di identità

I passaggi variano a seconda del provider. Configura i quattro elementi seguenti.

Attiva autenticazione

Per i requisiti dei campi, 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, pertanto l’app annuncia ogni autorizzazione richiesta alle piattaforme LLM. La piattaforma blocca il salvataggio fino a quando non risolvi eventuali discrepanze nell’ambito.

Gli ambiti supportati controllano gli ambiti disponibili. La rimozione di un ambito dall’elenco comporta la rimozione immediata dell’ambito da ogni azione necessaria. Aggiungere ogni ambito all’elenco prima di assegnarlo a un’azione.

Se si seleziona Richiedi autenticazione per tutte le azioni, Nessuna azioni diventeranno Richieste, ma verranno mantenute le azioni già impostate su Facoltative. Per richiedere l’accesso per ogni azione, modifica le righe rimanenti Facoltativo in Obbligatorio singolarmente. Deselezionando la casella di controllo, ogni azione viene restituita a None.

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

ChatGPT supporta modalità di autenticazione miste all’interno di un’app e applica singolarmente la modalità di ogni azione. Le azioni pubbliche non richiedono l’accesso; le azioni protette richiedono invece l’accesso in base alle esigenze.

Claude supporta anche le app miste tramite autenticazione lazy. Con Accesso quando necessario selezionato durante la configurazione del connettore, le azioni pubbliche rimangono utilizzabili in modo anonimo e la piattaforma richiede l’accesso quando viene chiamata un’azione Obbligatorio. Un’app le cui azioni sono tutte Obbligatorie richiede l’accesso prima dell’uso. Per la distinzione tra un’azione richiesta e un gestore facoltativo che richiede l’accesso, vedere comportamento piattaforma LLM.

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 viene modificato. Aggiorna i metadati della connessione e verifica che le impostazioni di autenticazione corrispondano alla nuova configurazione dell’app. Una piattaforma potrebbe richiedere di riconnettersi o di ricreare la connessione quando cambia il relativo metodo di autenticazione.

Leggi l’identità nel gestore

Un’identità verificata raggiunge il gestore come secondo argomento ogni volta che il chiamante invia un token valido, indipendentemente dalla modalità di autenticazione dell’azione. Un’azione Facoltativa può utilizzare tale identità per personalizzare i risultati quando disponibili e restituire un risultato anonimo in caso contrario.

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

Il runtime verifica il token automaticamente. Per un’azione Obbligatorio, vengono bloccate tutte le chiamate prive di token valido con gli ambiti elencati. Il gestore viene eseguito solo per un chiamante autorizzato. Utilizzare hasScope per scegliere il comportamento del gestore in base a un’autorizzazione, ad esempio in un’azione Facoltativa.

Per richiedere l’accesso durante una conversazione, restituire extra.challengeAuth() dal gestore. L’helper è 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()
    }]
  };
};

Utilizzare un parametro di input esplicito, ad esempio signIn, per decidere quando richiedere l’autenticazione. Non dedurre tale decisione dalla formulazione dell’utente.

Imposta error per corrispondere alla condizione riportata. Utilizzare invalid_token quando il chiamante non dispone di una sessione valida e deve effettuare l’accesso, come nell’esempio precedente. Usa insufficient_scope quando il chiamante ha effettuato l’accesso ma il token non ha l’ambito richiesto. Ogni piattaforma LLM sceglie il testo del prompt e la modalità di risposta al codice di errore. Invia il codice che descrive accuratamente la condizione.

Richiedi l’autenticazione solo quando manca l’identità richiesta, come fa il controllo !extra.authInfo in questo esempio. L’accesso non risolve una sfida incondizionata: il gestore richiede nuovamente l’autenticazione a ogni chiamata.

Mantieni il lato server dell’identità. Passa solo i dati necessari al widget in structuredContent. Non includere mai un token di accesso in structuredContent. Vedi Personalizzare un gestore generato.

Per il contratto completo, vedi API di autenticazione gestore.

Testare l’app protetta

Il plug-in o il connettore esistente utilizza la configurazione aggiornata dopo la distribuzione. Per creare una nuova connessione, segui le istruzioni per la tua piattaforma:

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 e rivedi le impostazioni di autenticazione. Per un’app mista pubblica/protetta, scegli Accedi quando necessario quando disponibile. Per richiedere l’accesso prima dell’utilizzo del connettore, selezionare Accedi ora. La finestra di dialogo varia in base all’account o all’organizzazione. 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