Configurare Single Sign-On con un provider OAuth generico

Articolo
12/09/2024

Copilot Studio supporta l'accesso singolo (SSO) con provider di autenticazione compatibili con OAuth 2.0. SSO consente agli agenti sul tuo sito web di registrare i clienti se hanno effettuato l'accesso alla pagina o all'app in cui è distribuito agente.

Prerequisiti

Creare o utilizzare un canvas personalizzato che supporti il flusso SSO del provider OAuth generico

Quando l'autenticazione argomento viene attivata negli agenti connessi a un provider generico OAuth 2.0, Copilot Studio invia un messaggio contenente un URL sicuro, che viene utilizzato per pubblicare l'token di accesso dell'utente.

Il canvas personalizzato o una pagina in cui è integrato il canvas dovrebbe implementare il seguente modello:

Ottieni un token di accesso per l'utente che ha effettuato l'accesso dal tuo provider di autenticazione OAuth 2.0, utilizzando il tuo metodo preferito.
Intercetta un messaggio in arrivo da Copilot Studio ed estrarre l'URL protetto.
Pubblica il token di accesso nell'URL protetto.

Estrai l'URL protetto e pubblica il token

Il canvas personalizzato intercetta i messaggi in arrivo utilizzando un concetto di middleware, ovvero un codice eseguito nel contesto della ricezione dei messaggi da Copilot Studio.

Per rispondere alle richieste di accesso, il canvas personalizzato deve intercettare i messaggi con allegati che contengono tipo di contenuto application/vnd.microsoft.card.oauth. Gli allegati OAuthCard contengono una proprietà content.tokenPostResource.sasUrl, da cui è possibile estrarre l'URL protetto. Infine, il canvas personalizzato dovrebbe pubblicare il token di accesso dell'utente nell'URL protetto.

Il seguente codice JavaScript è un esempio di codice middleware che estrae l'URL sicuro e pubblica un token. Se il post ha esito positivo, il middleware restituisce false. Se il post non ha esito positivo o se l'attività non ha la proprietà application/vnd.microsoft.card.oauth, restituisce next(…args).

const activityMiddleware = () => next => (...args) => {
  if (args[0].activity.attachments?.[0]?.contentType === 'application/vnd.microsoft.card.oauth') {
    var postEndpoint = args[0].activity.attachments?.[0].content.tokenPostResource.sasUrl;

    // Perform an HTTP POST to the secure URL with the body of:
    // {
    //     "token": <user_token> 
    // } 

    if(success)
       return false;
    else
       return next(...args);
  } else {
    return next(...args);
  }
};

Codice di esempio completo

L'implementazione di un'app o di un canvas personalizzato che ottiene un token per un utente che ha effettuato l'accesso e pubblica il token in Copilot Studio varia in base al provider di autenticazione. Per ulteriori informazioni, consulta la documentazione del provider di autenticazione per ulteriori dettagli sui flussi di accesso e sull'ottenimento dei token di accesso. Per un esempio di riferimento che utilizza OKTA, consulta SSO di terze parti con OKTA.

Utilizzo del token in Copilot Studio

I token pubblicati utilizzando l'URL sicuro vengono popolati nella variabile System.User.AccessToken in Copilot Studio. I creatori di agente possono utilizzare questa variabile di sistema per accedere alle API protette connesse al provider autenticato che ha generato il token.

Nell'esempio seguente, una chiamata HTTP è configurata con un'intestazione dell'autorizzazione che utilizza System.User.AccessToken.

Screenshot che illustra una chiamata HTTP che accede a un'APU sicura.

Canali supportati

L'SSO con un provider di autenticazione OAuth generico è un modello personalizzato, che può essere implementato da un canvas personalizzato o da qualsiasi altro client che funziona con l'API Directline.

Condividi tramite