Configurare l'autenticazione nell'agente

Il pacchetto Libreria di Autenticazione Microsoft (MSAL) dell'SDK degli agenti per .NET è un'utilità che consente di creare token di accesso per i client agente e i servizi esterni da un agente self-hosted dell'SDK per agenti Microsoft 365.

Il pacchetto Microsoft.Agents.Athentication.Msal contiene la classe MsalAuth, che è il provider di autenticazione di base. Puoi configurarla per i seguenti tipi di credenziali:

• Tenant singolo con segreto client e multi-tenant con segreto client
• Certificato client con identificazione personale
• Certificato client con nome oggetto (che include SN+I)
• Identità gestita assegnata dall'utente
• Identità gestita assegnata dal sistema
• Credenziali federate
• Identità del carico di lavoro

Installare il pacchetto di autenticazione

Installa il pacchetto di autenticazione MSAL da NuGet:

dotnet add package Microsoft.Agents.Authentication.Msal

Differenze tra tenant singolo e multi-tenant

L'autenticazione tramite segreto client support configurazioni sia a tenant singolo sia muti-tenant.

Configurare una connessione

Il pacchetto di autenticazione MSAL consente di creare e usare più client distinti con il motore di hosting Agents Framework. Con il pacchetto di autenticazione MSAL, puoi specificare più configurazioni di connessione nel file di configurazione dell'applicazione. Ogni configurazione di connessione può essere usata per creare un client di autenticazione denominato a supporto delle comunicazioni con servizi esterni o altri agenti.

Variabili di ambiente per ogni tipo di autenticazione

L'agente ottiene la configurazione MSAL in fase di runtime dalle variabili di ambiente.

Le sezioni seguenti descrivono le impostazioni obbligatorie e facoltative per ciascun tipo di autenticazione supportato da MSAL, con frammenti configurazione di esempio per ciascun tipo.

Tenant singolo con segreto client

Usa queste impostazioni per configurare una connessione a tenant singolo che effettua l'autenticazione con un segreto client.

Ecco un esempio di impostazioni dell'app per ClientSecret con tenant singolo:

  "Connections": {
    "ServiceConnection": {
      "Settings": {
        "AuthType": "ClientSecret",
        "ClientId": "{{BOT_ID}}",
        "ClientSecret": "{{BOT_SECRET}}",
        "AuthorityEndpoint": "https://login.microsoftonline.com/{{BOT_TENANT_ID}}",
        "Scopes": [
            "https://api.botframework.com/.default"
          ],
      }
    }
  }

Multi-tenant con segreto client

Usa queste impostazioni per configurare una connessione multi-tenant che effettua l'autenticazione con un segreto client.

Ecco un esempio di impostazioni dell'app per multi-tenant con segreto client:

  "Connections": {
    "ServiceConnection": {
      "Settings": {
        "AuthType": "ClientSecret",
        "ClientId": "{{BOT_ID}}",
        "ClientSecret": "{{BOT_SECRET}}",
        "AuthorityEndpoint": "https://login.microsoftonline.com/botframework.com",
        "Scopes": [
            "https://api.botframework.com/.default"
          ],
      }
    }
  }

Identità gestita assegnata dall'utente

Usa queste impostazioni per configurare l'acquisizione di token con un'identità gestita assegnata dall'utente.

Ecco un esempio di impostazioni dell'app per l'identità gestita assegnata dall'utente:

  "Connections": {
    "ServiceConnection": {
      "Settings": {
        "AuthType": "UserManagedIdentity",
        "ClientId": "{{BOT_ID}}",
        "Scopes": [
          "https://api.botframework.com/.default"
        ]
      }
    }
  }

Identità gestita assegnata dal sistema

Quando usi l'oggetto SystemManagedIdentity, l'agente ignora qualsiasi ID client specificato e usa l'identità gestita dal sistema.

Ecco un esempio di impostazioni dell'app per il tipo di autenticazione identità gestita assegnata dal sistema:

  "Connections": {
    "ServiceConnection": {
      "Settings": {
        "AuthType": "SystemManagedIdentity",
        "Scopes": [
          "https://api.botframework.com/.default"
        ]
      }
    }
  }

Credenziali federate

Usa queste impostazioni per configurare una connessione che scambia credenziali federate per ottenere token di accesso.

Ecco un esempio di impostazioni app per Federated Credentials:

  "Connections": {
    "ServiceConnection": {
      "Settings": {
        "AuthType": "FederatedCredentials",
        "ClientId": "{{BOT_ID}}",
        "AuthorityEndpoint": "https://login.microsoftonline.com/{{BOT_TENANT_ID}}",
        "FederatedClientId": "{{BOT_FEDERATED_ID}}",
        "Scopes": [
          "https://api.botframework.com/.default"
        ]
      }
    }
  }

Identità del carico di lavoro

Usa queste impostazioni per configurare l'autenticazione dell'identità dei carichi di lavoro usando un file di token federato.

Ecco un esempio di impostazioni dell'app per WorkloadIdentity con tenant singolo:

  "Connections": {
    "ServiceConnection": {
      "Settings": {
        "AuthType": "WorkloadIdentity",
        "ClientId": "{{BOT_ID}}",
        "AuthorityEndpoint": "https://login.microsoftonline.com/{{BOT_TENANT_ID}}",
        "FederatedTokenFile": "{{BOT_FEDERATED_TOKENFILE}}",
        "Scopes": [
          "https://api.botframework.com/.default"
        ]
      }
    }
  }

Credenziali federate opzionali oppure opzioni di asserzione client di identità del carico di lavoro

Usa queste impostazioni facoltative per personalizzare il contenuto delle asserzioni client per le credenziali federate o i flussi di identità dei carichi di lavoro.

  "Connections": {
    "ServiceConnection": {
      "Settings": {
        "AuthType": "WorkloadIdentity",
        "ClientId": "{{BOT_ID}}",
        "AuthorityEndpoint": "https://login.microsoftonline.com/{{BOT_TENANT_ID}}",
        "FederatedTokenFile": "{{BOT_FEDERATED_TOKENFILE}}",
        "Scopes": [
          "https://api.botframework.com/.default"
        ],
        "AssertionRequestOptions": {
            "ClientId": null,
            "TokenEndpoint": null,
            "Claims": null,
            "ClientCapabilities": null,
        }
      }
    }
  }

Certificato con nome oggetto (che include SN+I)

Usa queste impostazioni per configurare l'autenticazione basata su certificato in base al nome del soggetto del certificato, inclusi gli scenari SN+I.

Ecco un esempio di appsettings per un certificato che usa il nome di oggetto e l'emittente (SNI) e multi-tenant:

  "Connections": {
    "ServiceConnection": {
      "Settings": {
        "AuthType": "CertificateSubjectName",
        "ClientId": "{{BOT_ID}}",
        "CertSubjectName": "{{BOT_CERT_SUBJECTNAME}}",
        "SendX5C": true,
        "AuthorityEndpoint": "https://login.microsoftonline.com/botframework.com",
        "Scopes": [
          "https://api.botframework.com/.default"
        ]
      }
    }
  },

Di seguito è riportato un esempio di impostazioni per il nome soggetto del certificato per SN+I e un tenant singolo:

  "Connections": {
    "ServiceConnection": {
      "Settings": {
        "AuthType": "CertificateSubjectName",
        "ClientId": "{{BOT_ID}}",
        "CertSubjectName": "{{BOT_CERT_SUBJECTNAME}}",
        "SendX5C": true,
        "AuthorityEndpoint": "https://login.microsoftonline.com/{{BOT_TENANT_ID}}",
        "Scopes": [
          "https://api.botframework.com/.default"
        ]
      }
    }
  },

Certificato client con identificazione personale

Usa queste impostazioni per configurare l'autenticazione basata su certificato in base all'identificazione personale del certificato.

Ecco un esempio di impostazioni dell'app per un certificato che usa l'identificazione personale del certificato:

  "Connections": {
    "ServiceConnection": {
      "Settings": {
        "AuthType": "Certificate",
        "ClientId": "{{BOT_ID}}",
        "CertThumbprint": "{{BOT_CERT_THUMBPRINT}}",
        "AuthorityEndpoint": "https://login.microsoftonline.com/botframework.com",
        "Scopes": [
          "https://api.botframework.com/.default"
        ]
      }
    }
  },

Provider configurazione predefinito per MSAL

Per semplificare la configurazione, è disponibile un'estensione del provider di servizi per aggiungere le impostazioni di configurazione predefinite per MSAL all'agente.

Ecco un esempio di provider di configurazione MSAL predefinito per un host di base ASP.NET in una classe Program.cs.

Questa operazione viene gestita dall'istanza registrata di IConnections. L'istanza IConnections viene aggiunta per impostazione predefinita quando usi AddAgent.

// Register your AgentApplication
builder.AddAgent<MyAgent>();

Tuttavia, se non usi AddAgent, devi esplicitamente registrare l'istanza IConnections.

    // Add Connections object to access configured token connections.
    builder.Services.AddSingleton<IConnections, ConfigurationConnections>();

Altre opzioni di configurazione MSAL

Esistono diverse opzioni di configurazione condivise che controllano le impostazioni generali per l'acquisizione di token da Microsoft Entra Identity.

Queste impostazioni sono:

Usa le seguenti impostazioni condivise per controllare il timeout delle richieste MSAL, il comportamento dei retry e il livello di dettaglio della registrazione.

Queste impostazioni vengono condivise con tutti i client che creano usando il provider di autenticazione MSAL. Queste impostazioni devono essere lette da un lettore IConfiguration, da una sezione di configurazione denominata "MSALConfiguration".

Di seguito è riportato un esempio della voce in un file appsettings.json:

{
  "MSALConfiguration": {
    "MSALEnabledLogPII": "true",
    "MSALRequestTimeout": "00:00:40",
    "MSALRetryCount": "1"
  },
}

In questo caso, questo blocco di impostazioni indica a tutti i client MSAL creati con il provider MSAL di abilitare la registrazione dei dati personali, impostare il timeout su 40 secondi e ridurre il numero di retry a 1.

Questa estensione cerca una sezione di configurazione denominata "MSALConfiguration" nell'oggetto IConfiguration e da questa crea un oggetto Configurazione MSAL.

Se la sezione MSALConfig non viene trovata, verrà creato l'oggetto di configurazione MSAL usando i valori predefiniti.

    // Add default agent MsalAuth support
    builder.Services.AddDefaultMsalAuth(builder.Configuration);

    // Register your AgentApplication
    builder.AddAgent<MyAgent>();

Supporto della registrazione per l'autenticazione

Il sistema di autenticazione MSAL consente la registrazione indipendente dei flussi di autenticazione per l'integrazione dei dati di telemetria qualora fosse necessario risolvere i problemi di acquisizione dei token.

Per abilitare la registrazione, aggiungi una voce per Microsoft.Agents.Authentication.Msal nelle impostazioni dell'applicazione per impostare un ILogger che consenta di monitorare le operazioni sui token relative alle tue connessioni. Se aggiungi l'opzione MSALEnabledLogPII, vengono inclusi anche i dati personali della tua connessione.

Di seguito è riportato un esempio del blocco di registrazione in questo caso:

  "Logging": {
    "LogLevel": {
      "Default": "Warning",
      "Microsoft.Agents": "Warning",
      "Microsoft.Hosting.Lifetime": "Information",
      "Microsoft.Agents.Authentication.Msal": "Trace"
    }
  }

In questo caso, la registrazione è abilitata per diversi moduli, tra cui Microsoft.Agents.Authentication.Msal, in cui il livello di traccia è "Analisi" per MSAL.

L'SDK JavaScript richiede un oggetto AuthenticationProvider per ottenere i token JSON Web (JWT) per inviare attività al canale di destinazione. Per altre informazioni, vedere Token di accesso in Microsoft Identity Platform.

Il pacchetto @microsoft/agents-hosting fornisce un provider di autenticazione predefinito basato su Libreria di Autenticazione Microsoft (MSAL). Puoi configurarlo per i seguenti tipi di autenticazione:

• Tenant singolo con segreto client
• Multi-tenant con segreto client
• Identità gestita dall'utente
• Identità gestita dal sistema
• Credenziali federate
• Identità del carico di lavoro
• Certificate

Installare il pacchetto di autenticazione

Installa il pacchetto di autenticazione MSAL da npm:

npm install @microsoft/agents-hosting

Confronto tra tenant singolo e multi-tenant

L'autenticazione tramite segreto client e tramite certificato client supportano configurazioni sia a tenant singolo sia muti-tenant.

L'identità gestita assegnata dall'utente, l'identità gestita dal sistema, le credenziali federate e l'identità dei carichi di lavoro supportano solo le configurazioni a singolo tenant.

Configurare una connessione

La libreria di autenticazione MSAL consente di creare e usare più client distinti con il motore di hosting Agents Framework. Utilizzando la libreria di autenticazione MSAL, è possibile definire più configurazioni di connessione nel file di configurazione dell'applicazione. Ogni configurazione di connessione può creare un client di autenticazione denominato per supportare le comunicazioni con i servizi esterni o altri agenti.

Le sezioni seguenti descrivono le impostazioni di configurazione obbligatorie e facoltative per ciascuno dei tipi di autenticazione supportati dal provider di autenticazione MSAL. Includono inoltre frammenti di configurazione di esempio per ciascun tipo.

Variabili di ambiente per ogni tipo di autenticazione

L'agente ottiene la configurazione MSAL in fase di esecuzione dalle variabili di ambiente usando la funzione helper loadAuthConfigFromEnv(): AuthConfiguration. L'oggetto CloudAdapter viene inizializzato con l'oggetto AuthConfiguration.

Le impostazioni di connessione usano il formato CONNECTIONS__<CONNECTION_NAME>__SETTINGS__<PROPERTY>.

Quando è presente AUTHTYPE, l'SDK usa quel valore per selezionare il flusso di acquisizione del token. Quando AUTHTYPE viene omesso, l'SDK torna al comportamento legacy e deduce il flusso di autenticazione dalle proprietà delle credenziali configurate.

Tenant singolo con segreto client

Usa queste impostazioni per configurare una connessione a tenant singolo che effettua l'autenticazione con un segreto client.

CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHTYPE=ClientSecret
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID={app-id-guid}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET={app-registration-secret}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID={tenant-id-guid}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__SCOPE=https://api.botframework.com

La configurazione a tenant singolo con segreto client è quella consigliata per lo sviluppo locale.

Multi-tenant con segreto client

Per gli scenari muti-tenant che usano un segreto del client, impostare l'endpoint dell'autorità sul tenant botframework.com:

CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHTYPE=ClientSecret
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID={app-id-guid}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET={app-registration-secret}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHORITY=https://login.microsoftonline.com/botframework.com
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__SCOPE=https://api.botframework.com

UserManagedIdentity

Usa queste impostazioni per configurare l'acquisizione dei token con un'identità gestita assegnata dall'utente.

CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHTYPE=UserManagedIdentity
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID={managed-identity-client-id}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__SCOPE=https://api.botframework.com

Identità gestita è la configurazione raccomandata per gli scenari di produzione. Per altre informazioni, vedere l'articolo relativo alle identità gestite per le risorse di Azure.

SystemManagedIdentity

Se usi il tipo di autorizzazione SystemManagedIdentity, l'ID client viene ignorato e viene usata l'identità gestita dal sistema per il servizio.

CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHTYPE=SystemManagedIdentity
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__SCOPE=https://api.botframework.com

FederatedCredentials

Usa queste impostazioni per configurare un'app a tenant singolo che esegue l'autenticazione attraverso le credenziali federate.

CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHTYPE=FederatedCredentials
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID={app-id-guid}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID={tenant-id-guid}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHORITY=https://login.microsoftonline.com/{tenant-id-guid}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__FICCLIENTID={managed-identity-client-id}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__SCOPE=https://api.botframework.com

Per altre informazioni, vedi Autenticazione con le credenziali dell'identità federata.

WorkloadIdentity

Usa queste impostazioni per configurare l'acquisizione dei token attraverso le credenziali dell'identità federata di Microsoft Entra.

CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHTYPE=WorkloadIdentity
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID={app-id-guid}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID={tenant-id-guid}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHORITY=https://login.microsoftonline.com/{tenant-id-guid}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__FEDERATEDTOKENFILE=/var/run/secrets/azure/tokens/azure-identity-token
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__SCOPE=https://api.botframework.com

Tenant singolo con certificato client

Usa queste impostazioni per configurare una connessione a singolo tenant che esegue l'autenticazione con un certificato client.

CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHTYPE=Certificate
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID={app-id-guid}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID={tenant-id-guid}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CERTPEMFILE={path-to-pem-file}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CERTKEYFILE={path-to-key-file}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__SCOPE=https://api.botframework.com

Multitenant con certificato client

Per gli scenari muti-tenant che usano il certificato client, imposta l'endpoint dell'autorità sul tenant botframework.com:

CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHTYPE=Certificate
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID={app-id-guid}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CERTPEMFILE={path-to-pem-file}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CERTKEYFILE={path-to-key-file}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHORITY=https://login.microsoftonline.com/botframework.com
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__SCOPE=https://api.botframework.com

Compatibilità con le versioni precedenti dell'SDK Azure Bot Framework

Per caricare la configurazione usando lo stesso formato dell'SDK Azure Bot Framework, usa loadPrevAuthConfigFromEnv(): AuthConfiguration.

Usa questi nomi di impostazioni precedenti quando esegui la migrazione delle configurazioni dell'SDK Bot Framework esistenti.

MicrosoftAppTenantId={tenant-id-guid}
MicrosoftAppId={app-id-guid}
MicrosoftAppPassword={app-registration-secret}

Provider di autenticazione personalizzato

Gli utenti che necessitano di un provider di autenticazione personalizzato possono implementare l'interfaccia:

export interface AuthProvider {
  getAccessToken: (authConfig: AuthConfiguration, scope: string) => Promise<string>
}

Ad esempio, possono implementare il AuthProvider usando @azure/identity:

import { EnvironmentCredential } from "@azure/identity"
import { AuthProvider, AuthConfiguration } from "@microsoft/agents-hosting"
class DevTokenProvider implements AuthProvider {
  async getAccessToken(authConfig: AuthConfiguration): Promise<string> {
    const id = new EnvironmentCredential()
    const tokenResponse = await id.getToken("https://api.botframework.com/.default")
    return tokenResponse.token
  }

Per creare un'istanza di CloudAdapter utilizzando DevTokenProvider

const adapter = new CloudAdapter(authConfig, new DevTokenProvider())

amework.com/.default") restituisce tokenResponse.token }

To instantiate the `CloudAdapter` by using the `DevTokenProvider`

```ts
const adapter = new CloudAdapter(authConfig, new DevTokenProvider())

Il pacchetto Libreria di Autenticazione Microsoft (MSAL) dell'SDK degli agenti per Python è un'utilità che consente di creare token di accesso per i client agente e i servizi esterni da un agente self-hosted dell'SDK per agenti Microsoft 365.

Il pacchetto microsoft-agents-authentication-msal contiene la classe MsalAuth, che è il provider di autenticazione di base. Puoi configurarla per i seguenti tipi di credenziali:

• Segreto client
• Certificato client
• Identità gestita assegnata dall'utente
• Identità gestita assegnata dal sistema

Installare il pacchetto di autenticazione

Installa il pacchetto di autenticazione MSAL da PyPI:

pip install microsoft-agents-authentication-msal

Differenze tra tenant singolo e multi-tenant

L'autenticazione tramite segreto client e tramite certificato client supportano configurazioni sia a tenant singolo sia muti-tenant.

L'identità gestita User-Assigned e l'identità gestita System-Assigned supportano solo le configurazioni a tenant singolo.

Configurare una connessione

La libreria di autenticazione MSAL consente di creare e usare più client distinti con il motore di hosting Agents Framework. Ogni configurazione di connessione crea un client di autenticazione denominato per supportare le comunicazioni con i servizi esterni o altri agenti.

Fornire la configurazione tramite variabili di ambiente che usano la convenzione di denominazione con doppio carattere di sottolineatura (__) per le impostazioni annidate. La classe MsalConnectionManager legge queste variabili per creare istanze di AgentAuthConfiguration per ciascuna connessione denominata.

Variabili di ambiente per ogni tipo di autenticazione

L'agente ottiene la configurazione MSAL in fase di runtime dalle variabili di ambiente usando la funzione helper load_configuration_from_env().

Le sezioni seguenti descrivono le impostazioni di configurazione richieste per ognuno dei tipi di autenticazione supportati, insieme a frammenti di variabili d'ambiente di esempio per ciascun tipo.

Tenant singolo con segreto client

Usa queste impostazioni per configurare una connessione a tenant singolo che effettua l'autenticazione con un segreto client.

CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHTYPE=ClientSecret
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID={app-id-guid}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET={app-registration-secret}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID={tenant-id-guid}

La configurazione a tenant singolo con segreto client è quella consigliata per lo sviluppo locale.

Multi-tenant con segreto client

Per gli scenari muti-tenant che usano un segreto del client, impostare l'endpoint dell'autorità sul tenant botframework.com:

CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHTYPE=ClientSecret
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID={app-id-guid}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET={app-registration-secret}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHORITY=https://login.microsoftonline.com/botframework.com

Identità gestita assegnata dall'utente

Usa queste impostazioni per configurare l'acquisizione di token con un'identità gestita assegnata dall'utente.

CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID={managed-identity-client-id}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHTYPE=UserManagedIdentity

Identità gestita è la configurazione raccomandata per gli scenari di produzione. Per altre informazioni, vedere l'articolo relativo alle identità gestite per le risorse di Azure.

Identità gestita assegnata dal sistema

Se usi il tipo di autorizzazione SystemManagedIdentity, l'ID client viene ignorato e viene usata l'identità gestita dal sistema per il servizio.

CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHTYPE=SystemManagedIdentity

Tenant singolo con certificato client

Usa queste impostazioni per configurare una connessione a singolo tenant che esegue l'autenticazione con un certificato client.

CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHTYPE=certificate
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID={app-id-guid}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID={tenant-id-guid}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CERTPEMFILE={path-to-pem-file}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CERTKEYFILE={path-to-key-file}

Multitenant con certificato client

Per gli scenari muti-tenant che usano il certificato client, imposta l'endpoint dell'autorità sul tenant botframework.com:

CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHTYPE=certificate
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID={app-id-guid}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CERTPEMFILE={path-to-pem-file}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CERTKEYFILE={path-to-key-file}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHORITY=https://login.microsoftonline.com/botframework.com

Configurare la gestione connessione

La classe MsalConnectionManager può gestire più connessioni di autenticazione per il tuo agente. Legge le configurazioni delle connessioni e crea istanze di MsalAuth per ciascuna connessione denominata.

Ecco un esempio di come configurare la gestione connessione e avviare il tuo agente:

from os import environ

from microsoft_agents.hosting.aiohttp import start_agent_process, CloudAdapter
from microsoft_agents.hosting.core import Authorization, AgentApplication, TurnState, MemoryStorage

from dotenv import load_dotenv
from aiohttp.web import Request, Response, Application, run_app
from microsoft_agents.authentication.msal import MsalConnectionManager
from microsoft_agents.activity import load_configuration_from_env

def start_server(
    agent_application: AgentApplication, auth_configuration: AgentAuthConfiguration
):
    async def entry_point(req: Request) -> Response:
        agent: AgentApplication = req.app["agent_app"]
        adapter: CloudAdapter = req.app["adapter"]
        return await start_agent_process(req, agent, adapter)

    APP = Application()
    APP.router.add_post("/api/messages", entry_point)
    APP["agent_configuration"] = auth_configuration
    APP["agent_app"] = agent_application
    APP["adapter"] = agent_application.adapter

    try:
        run_app(APP, host="localhost", port=environ.get("PORT", 3978))
    except Exception as error:
        raise error

load_dotenv()
agents_sdk_config = load_configuration_from_env(environ)

STORAGE = MemoryStorage()
CONNECTION_MANAGER = MsalConnectionManager(**agents_sdk_config)
ADAPTER = CloudAdapter(connection_manager=CONNECTION_MANAGER)
AUTHORIZATION = Authorization(STORAGE, CONNECTION_MANAGER, **agents_sdk_config)

AGENT_APP = AgentApplication[TurnState](
    storage=STORAGE, adapter=ADAPTER, authorization=AUTHORIZATION, **agents_sdk_config
)

start_server(
    agent_application=AGENT_APP, auth_configuration=CONNECTION_MANAGER.get_default_connection_configuration()
)

Vedi l'esempio di avvio rapido di Python per un esempio completo di utilizzo di MsalConnectionManager in un agente Python.

Provider di autenticazione personalizzato

Gli utenti che richiedono un provider di autenticazione personalizzato possono implementare la classe di base AccessTokenProviderBase:

from microsoft_agents.hosting.core import AccessTokenProviderBase

class CustomAuthProvider(AccessTokenProviderBase):
    async def get_access_token(
        self, resource_url: str, scopes: list[str], force_refresh: bool = False
    ) -> str:
        # Implement custom token acquisition logic
        token = await your_custom_token_logic(resource_url, scopes)
        return token

Supporto della registrazione per l'autenticazione

Il sistema di autenticazione MSAL usa il modulo logging di Python standard sotto il nome del logger microsoft_agents.authentication.msal. Per abilitare la registrazione dettagliata di flussi di autenticazione per la risoluzione dei problemi relativi all'acquisizione dei token, configura il logger nella tua applicazione:

import logging

logging.basicConfig(level=logging.WARNING)
logging.getLogger("microsoft_agents.authentication.msal").setLevel(logging.DEBUG)