Aggiungere l'accesso Single Sign-On
In questa unità si apprenderà come aggiungere l'accesso Single Sign-On a un'estensione di messaggio usando Microsoft Entra.
Configurare l'app Teams con l'accesso Single Sign-On
L'app Microsoft Teams supporta l'accesso Single Sign-On (SSO) tramite Microsoft Entra. L'accesso SSO consente agli utenti di accedere una sola volta e di accedere a più applicazioni senza dover eseguire di nuovo l'accesso.
Per configurare l'accesso Single Sign-On, configurare la registrazione dell'app Microsoft Entra per la risorsa Azure Bot per effettuare richieste per conto dell'utente.
Nella registrazione dell'app Microsoft Entra configurare le impostazioni seguenti:
- URI ID applicazione, un identificatore univoco per la registrazione dell'app usato per identificare la risorsa che il client deve usare durante l'avvio di un flusso single sign-on nell'app.
- Ambiti, l'autorizzazione concessa al bot per accedere ai dati utente.
- Applicazioni client autorizzate, le applicazioni client a cui è consentito richiedere i token dalla registrazione dell'app.
Nel manifesto dell'app l'oggetto webApplicationInfo viene configurato con l'ID del bot e l'URI dell'ID applicazione. Determinano la risorsa che il client deve usare durante l'avvio di un flusso single sign-on nell'app.
Il frammento di codice seguente mostra come l'oggetto webApplicationInfo viene configurato nel file manifesto dell'app:
"webApplicationInfo": {
"id": "dbeb8ea7-8ac3-4bb2-bcba-b210b087a73a",
"resource": "api://grttxrk0-5130.uks1.devtunnels.ms/botid-dbeb8ea7-8ac3-4bb2-bcba-b210b087a73a"
}
Configurare la connessione OAuth
La risorsa Azure Bot fornisce l'accesso al servizio token di Bot Framework. Il servizio token viene usato per ottenere un token di accesso per l'utente usando le impostazioni di connessione OAuth configurate. I token vengono archiviati in modo sicuro nel servizio e vengono recuperati quando necessario nel codice del bot.
Per creare un'impostazione di connessione, configurare le impostazioni seguenti:
- Nome : nome dell'impostazione di connessione.
- Provider di servizi : provider di identità usato dalla connessione per autenticare gli utenti. Le impostazioni di connessione supportano diversi provider di identità, tra cui Microsoft Entra.
- ID client : ID client da una registrazione dell'app Microsoft Entra configurata con le autorizzazioni necessarie per accedere ai dati utente.
- Segreto client : il segreto client di una registrazione dell'app Microsoft Entra configurata con le autorizzazioni necessarie per accedere ai dati utente.
- URL di Scambio token: URL che il client deve usare per avviare un flusso di Single Sign-On nell'app.
- ID tenant : ID tenant in cui si trova la registrazione dell'app Microsoft Entra.
- Ambiti : l'autorizzazione concessa al bot per accedere ai dati utente.
Il frammento di codice seguente illustra come configurare un'impostazione di connessione OAuth in un file Bicep:
resource botServiceProductsAPIConnection 'Microsoft.BotService/botServices/connections@2022-09-15' = {
parent: botService
name: 'Products API'
location: 'global'
properties: {
serviceProviderDisplayName: 'Azure Active Directory v2'
serviceProviderId: '30dd229c-58e3-4a48-bdfd-91ec48eb906c'
clientId: productsApiEntraAppClientId
clientSecret: productsApiEntraAppClientSecret
scopes: 'api://${backendApiEntraAppClientId}/Product.Read'
parameters: [
{
key: 'tenantID'
value: 'common'
}
{
key: 'tokenExchangeUrl'
value: 'api://${botAppDomain}/botid-${botEntraAppClientId}'
}
]
}
}
Consiglio
È consigliabile creare nuove registrazioni dell'app Microsoft Entra per l'autenticazione da utente a servizio. La registrazione dell'app usata con il servizio Azure Bot deve rimanere separata e usata per l'autenticazione da servizio a servizio tra il servizio Web e il servizio bot.
La registrazione dell'app Microsoft Entra usata con l'impostazione di connessione deve essere configurata per usare l'URI https://token.botframework.com/.auth/web/redirect di reindirizzamento per ottenere correttamente un token di accesso dal servizio token bot framework. L'URI di reindirizzamento viene usato per restituire il token di accesso al servizio token dopo l'autenticazione dell'utente.
Poiché l'URI di reindirizzamento del servizio token è ospitato in un dominio esterno, deve essere incluso nel file manifesto dell'app. La matrice validDomains indica al client quali domini devono essere usati dall'app. Garantisce che il client possa considerare attendibile il dominio durante l'avvio di un flusso di Single Sign-On.
Il frammento di codice seguente mostra come aggiungere il dominio al file manifesto dell'app:
"validDomains": [
"token.botframework.com"
]
Autenticare le query utente
Per autenticare le query utente in un'estensione di messaggio, usare Bot Framework SDK per ottenere un token di accesso per l'utente dal servizio token bot framework. Il token di accesso può quindi essere usato per accedere ai dati da un servizio esterno.
Verificare prima di tutto se esiste un token per l'utente nel servizio token.
Il frammento di codice seguente illustra come ottenere UserTokenClient e usare il metodo GetUserTokenAsync per restituire un token di accesso per l'utente usando un'impostazione di connessione OAuth denominata:
var userTokenClient = turnContext.TurnState.Get<UserTokenClient>();
var tokenResponse = await userTokenClient.GetUserTokenAsync(userId, connectionName, channelId, magicCode, cancellationToken);
Se non viene restituito un token, è necessario chiedere all'utente di accedere. Creare una risposta che esegue il rendering di un collegamento nell'interfaccia utente, che l'utente può seguire per avviare il flusso di accesso.
Il frammento di codice seguente mostra come viene usato il metodo GetSignInResourceAsync per restituire un collegamento di accesso dal servizio token e includerlo nella risposta dell'estensione del messaggio:
var resource = await userTokenClient.GetSignInResourceAsync(connectionName, activity, null, cancellationToken);
return new MessagingExtensionResponse
{
ComposeExtension = new MessagingExtensionResult
{
Type = "auth",
SuggestedActions = new MessagingExtensionSuggestedAction
{
Actions = [
new() {
Type = ActionTypes.OpenUrl,
Value = resource.SignInLink,
Title = "Sign In",
},
],
},
},
};
Quando l'utente segue il collegamento di accesso, acconsente alle autorizzazioni richieste nel campo Ambiti dell'impostazione di connessione OAuth. Dopo che l'utente ha concesso il consenso alle autorizzazioni, il servizio token ottiene un token di accesso e lo archivia in modo sicuro nel servizio.
La volta successiva che l'utente avvia una ricerca nell'estensione del messaggio, nel servizio token verrà trovato un token di accesso. Il token di accesso restituito può essere usato per accedere ai dati da un servizio esterno.