Konfigurer godkendelse i din agent

Når dine Azure Bot Service-ressourcer er klargjort, kan du konfigurere din agent til at godkende med Azure Bot Service. SDK til Microsoft 365-agenter tilbyder fleksible muligheder for konfiguration af godkendelse, så du kan vælge den metode, der bedst matcher programmets behov og sikkerhedskrav.

MSAL-pakken (.NET Agents SDK Microsoft-godkendelsesbibliotek) er et værktøj, der hjælper dig med at oprette adgangstokens til agentklienter og eksterne tjenester fra en selvværtsagent i SDK til Microsoft 365-agenter.

Pakken Microsoft.Agents.Athentication.Msal indeholder klassen MsalAuth, som er den centrale godkendelsesudbyder. Du kan konfigurere den til følgende typer legitimationsoplysninger:

  • Enkelt lejer med klienthemmelighed og multiprofil med klienthemmelighed
  • Klientcertifikat ved hjælp af aftryk
  • Klientcertifikat ved hjælp af emnenavn (herunder SN+I)
  • Brugertildelt administreret identitet
  • Systemtildelt administreret identitet
  • Legitimationsoplysninger i organisationsnetværk
  • Identitet af arbejdsbelastning

Installer godkendelsespakken

Installer MSAL-godkendelsespakken fra NuGet:

dotnet add package Microsoft.Agents.Authentication.Msal

Enkeltlejer versus multiprofil

Godkendelse ved hjælp af klienthemmelighed understøtter både enkeltlejer- og multiprofilkonfigurationer.

Bemærk!

For multiprofil skal du konfigurere Azure Bot-instansen som multiprofil og Microsoft Entra ID-appregistreringen som konti i enhver organisationsmappe (enhver Microsoft Entra ID-lejer - multiprofil). Læs mere i Enkelt- og multiprofil-applikationer.

Konfigurere en -forbindelse

MSAL-godkendelsespakken giver dig mulighed for at oprette og bruge flere forskellige klienter med Agents Framework hosting-programmet. Ved at bruge MSAL-godkendelsespakken kan du konfigurere flere forbindelseskonfigurationer i konfigurationsfilen for programmet. Hver forbindelseskonfiguration kan bruges til at oprette en navngivet godkendelsesklient, der understøtter kommunikation med eksterne tjenester eller andre agenter.

Miljøvariabler for hver godkendelsestype

Agenten henter MSAL-konfiguration under kørsel fra miljøvariabler.

De følgende afsnit beskriver de nødvendige og valgfrie konfigurationsindstillinger for hver af de understøttede godkendelsestyper for MSAL-godkendelse, sammen med eksempler på konfigurationsuddrag for hver type.

Enkelt lejer med klienthemmelighed

Brug disse indstillinger til at konfigurere en enkeltlejerforbindelse, der godkender med en klienthemmelighed.

Navn på indstilling Skriv Standardværdi Description
ClientId Streng Null ClientId (AppId), der skal bruges, når access-tokenet oprettes.
ClientSecret string Null Når AuthType er ClientSecret, Is Secret, der er knyttet til klienten, bør dette kun bruges til test- og udviklingsformål.
AuthorityEndpoint Streng Null Når den er til stede, bruges som autoritet til at anmode om et token fra.
TenantId Streng Null Når til stede og AuthorityEndpoint er null, bruges til at oprette et autoritet til at anmode om et token fra
Områder Liste med strenge Null Standardlister over områder, der skal anmodes om tokens for. Bruges kun, når der ikke sendes nogen områder fra agentens forbindelsesanmodning

Her er et eksempel på appindstillinger for enkeltlejer ClientSecret:

  "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"
          ],
      }
    }
  }

Multiprofil med klienthemmelighed

Brug disse indstillinger til at konfigurere en multiprofilforbindelse, der godkender med en klienthemmelighed.

Navn på indstilling Skriv Standardværdi Description
ClientId Streng Null ClientId (AppId), der skal bruges, når access-tokenet oprettes.
ClientSecret string Null Når AuthType er ClientSecret, Is Secret, der er knyttet til klienten, bør dette kun bruges til test- og udviklingsformål.
AuthorityEndpoint Streng Null Når den er til stede, bruges som autoritet til at anmode om et token fra.
TenantId Streng Null Når til stede og AuthorityEndpoint er null, bruges til at oprette et autoritet til at anmode om et token fra
Områder Liste med strenge Null Standardlister over områder, der skal anmodes om tokens for. Bruges kun, når der ikke sendes nogen områder fra agentens forbindelsesanmodning

Her er et eksempel på appindstillinger for multiprofil med klienthemmelighed:

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

Brugertildelt administreret identitet

Brug disse indstillinger til at konfigurere tokenanskaffelse med en brugertildelt administreret identitet.

Navn på indstilling Skriv Standardværdi Description
ClientId Streng Null Administreret identitet for ClientId, der skal bruges, når access-tokenet oprettes.

Bemærk!

Når du bruger administrerede identitetstyper i din agent, skal du køre din vært eller klient på en Azure-tjeneste og have konfigureret tjenesten med enten en systemtildelt administreret identitet eller en administreret identitet tildelt af brugeren.

Her er et eksempel på appindstillinger for brugertildelt administreret identitet:

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

Systemtildelt administreret identitet

Når du bruger SystemManagedIdentity, ignorerer agenten ethvert angivet klient-id og bruger den systemadministrerede identitet.

Bemærk!

Når du bruger administrerede identitetstyper i din agent, skal du køre din vært eller klient på en Azure-tjeneste og have konfigureret tjenesten med enten en systemtildelt administreret identitet eller en administreret identitet tildelt af brugeren.

Her er et eksempel på appindstillinger for systemtildelt administreret identitet som godkendelsestype:

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

Legitimationsoplysninger i organisationsnetværk

Brug disse indstillinger til at konfigurere en forbindelse, der udveksler legitimationsoplysninger for adgangstokens i organisationsnetværk.

Navn på indstilling Skriv Standardværdi Description
ClientId Streng Null ClientId (AppId), der skal bruges, når access-tokenet oprettes.
AuthorityEndpoint Streng Null Når den er til stede, bruges som autoritet til at anmode om et token fra.
TenantId Streng Null Når til stede og AuthorityEndpoint er null, bruges til at oprette et autoritet til at anmode om et token fra
Områder Liste med strenge Null Standardlister over områder, der skal anmodes om tokens for. Bruges kun, når der ikke sendes nogen områder fra agentens forbindelsesanmodning
FederatedClientId Streng Null Administreret identitet for ClientId, der skal bruges, når access-tokenet oprettes.

Her er et eksempel på appindstillinger for 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"
        ]
      }
    }
  }

Identitet af arbejdsbelastning

Brug disse indstillinger til at konfigurere identitetsgodkendelse af arbejdsbelastning ved hjælp af en tokenfil i organisationsnetværk.

Navn på indstilling Skriv Standardværdi Description
ClientId Streng Null ClientId (AppId), der skal bruges, når access-tokenet oprettes.
AuthorityEndpoint Streng Null Når den er til stede, bruges som autoritet til at anmode om et token fra.
TenantId Streng Null Når til stede og AuthorityEndpoint er null, bruges til at oprette et autoritet til at anmode om et token fra
Områder Liste med strenge Null Standardlister over områder, der skal anmodes om tokens for. Bruges kun, når der ikke sendes nogen områder fra agentens forbindelsesanmodning
FederatedTokenFile Streng Null Tokenfilen (samme som AKS AZURE_FEDERATED_TOKEN_FILE env var)

Her er et eksempel på appindstillinger for enkeltlejer WorkloadIdentity:

  "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"
        ]
      }
    }
  }

Valgfrie indstillinger for legitimationsoplysninger i organisationsnetværket eller klientantagelse for arbejdsbelastningsidentitet

Brug disse valgfrie indstillinger til at tilpasse klientassertionsindholdet for legitimationsoplysninger i organisationsnetværk eller arbejdsbelastningsidentitetsflows.

Navn på indstilling Skriv Standardværdi Description
ClientId Streng Null Klient-id, for hvilket der anmodes om en signeret antagelse
TokenEndpoint Streng Null Det tiltænkte tokenslutpunkt
Krav Streng Null Krav, der skal inkluderes i klientens antagelse
ClientCapabilities String[] Null Egenskaber, som klientprogrammet erklærer. 
  "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,
        }
      }
    }
  }

Certifikat ved hjælp af emnenavn (herunder SN+I)

Brug disse indstillinger til at konfigurere certifikatbaseret godkendelse ved brug af certifikatemnenavn, inklusive SN+I-scenarier.

AuthType Skriv Standardværdi Description
AuthorityEndpoint Streng Null Når den er til stede, bruges som autoritet til at anmode om et token fra.
TenantId Streng Null Når til stede og AuthorityEndpoint er null, bruges til at oprette et autoritet til at anmode om et token fra
Områder Liste med strenge Null Standardlister over områder, der skal anmodes om tokens for. Bruges kun, når der ikke sendes nogen områder fra agentens forbindelsesanmodning
ClientId Streng Null ClientId (AppId), der skal bruges, når access-tokenet oprettes.
CertSubjectName Streng Null Når AuthType er CertificateSubjectName, er dette emnenavnet, der søges efter
CertStoreName Streng "Min" Når AuthType enten er CertificateSubjectName eller Certificate, angiver det certifikatlager, der skal søges i
ValidCertificateOnly bool Sand Kræver, at certifikatet har en gyldig kæde.
SendX5C bool Falsk Aktiverer automatisk rotation af certifikater med passende konfiguration.

Her er et eksempel på appindstillinger for certifikat, der bruger emnenavn for Subject Name and Issuer (SNI) i et multiprofilmiljø:

  "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"
        ]
      }
    }
  },

Her er et eksempel på appindstillinger for certifikatemnenavn for SN+I i et enkeltlejermiljø:

  "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"
        ]
      }
    }
  },

Klientcertifikat ved hjælp af aftryk

Brug disse indstillinger til at konfigurere certifikatbaseret godkendelse med certifikataftryk.

AuthType Skriv Standardværdi Description
AuthorityEndpoint Streng Null Når den er til stede, bruges som autoritet til at anmode om et token fra.
TenantId Streng Null Når til stede og AuthorityEndpoint er null, bruges til at oprette et autoritet til at anmode om et token fra
Områder Liste med strenge Null Standardlister over områder, der skal anmodes om tokens for. Bruges kun, når der ikke sendes nogen områder fra agentens forbindelsesanmodning
ClientId Streng Null ClientId (AppId), der skal bruges, når access-tokenet oprettes.
CertThumbprint Streng Null Aftryk af det certifikat, der skal indlæses, er kun gyldigt, når AuthType er angivet som certifikat
CertStoreName Streng "Min" Når AuthType enten er CertificateSubjectName eller Certificate, angiver det certifikatlager, der skal søges i
ValidCertificateOnly bool Sand Kræver, at certifikatet har en gyldig kæde.
SendX5C bool Falsk Aktiverer automatisk rotation af certifikater med passende konfiguration.

Her er et eksempel på appindstillinger til certifikat ved brug af certifikatets aftryk:

  "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"
        ]
      }
    }
  },

Udbyder af standardkonfiguration MSAL

For at lette konfigurationen giver vi en udvidelse af tjenesteudbyderen til at føje standardkonfigurationsindstillingerne for MSAL til din agent.

Her er et eksempel på MSAL-standardkonfigurationsprovideren for en ASP.NET kernevært i en Program.cs-klasse.

Dette administreres af den registrerede IConnections forekomst. Forekomsten IConnections tilføjes som standard, når du bruger AddAgent.

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

Men hvis du ikke bruger AddAgent, skal du eksplicit registrere IConnections-forekomsten.

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

Flere MSAL-konfigurationsindstillinger

Der er flere delte konfigurationsindstillinger, der styrer generelle indstillinger for hentning af tokens fra Microsoft Entra Identity.

Disse indstillinger er:

Brug følgende delte indstillinger til at styre MSAL-anmodningstimeout, gentagelsesfunktion og logføringsniveau.

Navn på indstilling Skriv Standardværdi Description
MSALRequestTimeout TimeSpan 30 sekunder Denne indstilling styrer, hvor længe klienten venter på et svar fra Microsoft Entra ID, efter at der er sendt en anmodning.
MSALRetryCount Int 3 Denne indstilling styrer, hvor mange forsøg provideren foretager for en individuel anmodning om et token.
MSALEnabledLogPII Bool Falsk Denne indstilling styrer, om MSAL leverer persondata til den tilknyttede logger.

Disse indstillinger deles med alle klienter, der opretter ved hjælp af MSAL-godkendelsesprovideren. Disse indstillinger er beregnet til at blive læst fra en IConfiguration-læser i et konfigurationsafsnit i et afsnit med navnet "MSALConfiguration".

Bemærk!

MSALConfiguration er en valgfri konfiguration. Hvis du ikke angiver denne konfiguration, anvendes standardkonfigurationerne for disse værdier.

Her er et eksempel på posten i en appsettings.json fil:

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

I dette tilfælde vil denne indstillingsblok instruere alle MSAL-klienter, der er oprettet med MSAL-provideren, om at aktivere logføring af persondata, angive timeout til 40 sekunder og reducere antallet af forsøg til 1.

Denne udvidelse søger efter et konfigurationsafsnit med navnet "MSALConfiguration" i dit IConfiguration-objekt og opretter et MSAL Configuration-objekt ud fra det.

Hvis afsnittet MSALConfig ikke blev fundet, oprettes MSAL-konfigurationsobjektet ved hjælp af standardværdier.

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

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

Logføring af understøttelse af godkendelse

MSAL-godkendelsessystemet giver mulighed for uafhængig logføring af godkendelsesflows til telemetriintegration, hvis du skal foretage fejlfinding af tokenanskaffelse.

For at aktivere logføring skal du tilføje en post for Microsoft.Agents.Authentication.Msal i dine applikationsapps indstillinger for at oprette en ILogger rapport om tokenoperationer for dine forbindelser. Hvis du tilføjer indstillingen MSALEnabledLogPII, inkluderer dette også persondata for din forbindelse.

Her er et eksempel på logføringsblokken i dette tilfælde:

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

I dette tilfælde er logføring aktiveret for flere moduler, herunder Microsoft.Agents.Authentication.Msal, hvor sporingsniveauet er "Trace" for MSAL.

JavaScript SDK'en kræver en AuthenticationProvider for at hente JSON Web Token (JWT) til at sende aktiviteter til målkanalen. Du kan finde oplysninger under Adgangstokens i Microsoft-identitetsplatform.

Pakken @microsoft/agents-hosting tilbyder en standardgodkendelsesudbyder baseret på Microsoft-godkendelsesbiblioteket (MSAL). Du kan konfigurere den til følgende godkendelsestyper:

  • Enkelt lejer med klienthemmelighed
  • Multiprofil med klienthemmelighed
  • Brugeradministreret id
  • Systemadministreret identitet
  • Legitimationsoplysninger i organisationsnetværk
  • Identitet af arbejdsbelastning
  • Certifikat

Installer godkendelsespakken

Installer MSAL-godkendelsespakke fra npm:

npm install @microsoft/agents-hosting

Enkeltlejer versus multiprofil

Godkendelse med klienthemmelighed eller klientcertifikat understøtter både enkeltlejer- og multiprofilkonfigurationer.

Brugertildelt administreret identitet, systemadministreret identitet, Legitimationsoplysninger i organisationsnetværk og arbejdsbelastningens identitet understøtter kun enkeltlejerkonfigurationer.

Bemærk!

For multiprofil skal du konfigurere Azure Bot-instansen som multiprofil og Microsoft Entra ID-appregistreringen som konti i enhver organisationsmappe (enhver Microsoft Entra ID-lejer - multiprofil). Læs mere i Enkelt- og multiprofil-applikationer.

Konfigurere en -forbindelse

MSAL-godkendelsesbiblioteket giver dig mulighed for at oprette og bruge flere forskellige klienter med Agents Framework hosting-programmet. Ved at bruge MSAL-godkendelsesbiblioteket kan du konfigurere flere forbindelseskonfigurationer i konfigurationsfilen for programmet. Hver forbindelseskonfiguration kan oprette en navngivet godkendelsesklient for at understøtte kommunikation med eksterne tjenester eller andre agenter.

De følgende afsnit beskriver de nødvendige og valgfrie konfigurationsindstillinger for hver af de understøttede godkendelsestyper for MSAL-godkendelsesudbyderen. De inkluderer også eksempler på konfigurationsuddrag for hver type.

Miljøvariabler for hver godkendelsestype

Agenten henter MSAL-konfiguration under kørsel fra miljøvariabler med hjælpefunktionen loadAuthConfigFromEnv(): AuthConfiguration. CloudAdapter initialiseres med AuthConfiguration.

Forbindelsesindstillinger bruger formatet CONNECTIONS__<CONNECTION_NAME>__SETTINGS__<PROPERTY>.

Hvis AUTHTYPE er angivet, bruger SDK'en værdien til at vælge tokenindhentningsflowet. Når AUTHTYPE udelades, falder SDK'en tilbage til den ældre funktion og udleder godkendelsesflowet ud fra de konfigurerede legitimationsegenskaber.

Enkelt lejer med klienthemmelighed

Brug disse indstillinger til at konfigurere en enkeltlejerforbindelse, der godkender med en klienthemmelighed.

Navn på indstilling Skriv Standardværdi Description
CLIENTID Streng Ingen Klient-id'et (app-id) for app-registreringen.
CLIENTSECRET Streng Ingen Den hemmelighed, der er knyttet til appregistreringen. Brug kun til test- og udviklingsformål.
TENANTID Streng Ingen Microsoft Entra ID-lejer-ID'et for app-registreringen.
AUTHTYPE Streng Ingen Angiv til ClientSecret.
SCOPE Streng Ingen Standardomfang for ressourcen, der bruges til at anmode om tokens, hvis det ikke angives af den, der kalder.
AUTHORITY Streng Ingen Når den er til stede, bruges som autoritet til at anmode om et token fra. Hvis ikke angivet, bruges https://login.microsoftonline.com/{TENANTID} som standard. 
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

Enkeltlejer med klienthemmelighed er den anbefalede konfiguration til lokal udvikling.

Multiprofil med klienthemmelighed

For multiprofilscenarier, der bruger en klienthemmelighed, skal du sætte autoritetsslutpunkt til botframework.com-lejer:

Navn på indstilling Skriv Standardværdi Description
CLIENTID Streng Ingen Klient-id'et (app-id) for app-registreringen.
CLIENTSECRET Streng Ingen Den hemmelighed, der er knyttet til appregistreringen. Brug kun til test- og udviklingsformål.
AUTHTYPE Streng Ingen Angiv til ClientSecret.
AUTHORITY Streng Ingen Sæt til https://login.microsoftonline.com/botframework.com for multiprofil.
SCOPE Streng Ingen Standardomfang for ressourcen, der bruges til at anmode om tokens, hvis det ikke angives af den, der kalder. 
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

Brug disse indstillinger til at konfigurere tokenindhentning med en brugertildelt administreret identitet.

Navn på indstilling Skriv Standardværdi Description
CLIENTID Streng Ingen Administreret identitet for klient-id, der skal bruges, når adgangstoken oprettes.
AUTHTYPE Streng Ingen Angiv til UserManagedIdentity.
SCOPE Streng Ingen Standardomfang for ressourcen, der bruges til at anmode om tokens, hvis det ikke angives af den, der kalder. 
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHTYPE=UserManagedIdentity
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID={managed-identity-client-id}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__SCOPE=https://api.botframework.com

Administreret id er den anbefalede konfiguration til produktionsscenarier. Du kan få mere at vide under Administrerede identiteter til Azure-ressourcer.

Bemærk!

Når du bruger administrerede identitetstyper, skal du køre din vært eller klient på en Azure-tjeneste og have konfigureret tjenesten med enten en systemtildelt eller brugertildelt administreret identitet. For at se, hvilke Azure-tjenester der understøtter administrerede identiteter, se Administrerede identiteter til Azure-ressourcer.

SystemManagedIdentity

Når du bruger godkendelsestypen SystemManagedIdentity, ignoreres klient-id'et, og den systemadministrerede identitet for tjenesten bruges.

Navn på indstilling Skriv Standardværdi Description
AUTHTYPE Streng Ingen Angiv til SystemManagedIdentity.
SCOPE Streng Ingen Standardomfang for ressourcen, der bruges til at anmode om tokens, hvis det ikke angives af den, der kalder. 
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHTYPE=SystemManagedIdentity
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__SCOPE=https://api.botframework.com

Bemærk!

Når du bruger administrerede identitetstyper, skal du køre din vært eller klient på en Azure-tjeneste og have konfigureret tjenesten med enten en systemtildelt eller brugertildelt administreret identitet. For at se, hvilke Azure-tjenester der understøtter administrerede identiteter, se Administrerede identiteter til Azure-ressourcer.

FederatedCredentials

Brug disse indstillinger til at konfigurere en enkeltlejerapp, der autentificerer via legitimationsoplysninger i organisationsnetværket.

Navn på indstilling Skriv Standardværdi Description
CLIENTID Streng Ingen Klient-id'et (app-id) for app-registreringen.
TENANTID Streng Ingen Microsoft Entra ID-lejer-ID'et for app-registreringen.
AUTHTYPE Streng Ingen Angiv til FederatedCredentials.
AUTHORITY Streng Ingen Når den er til stede, bruges som autoritet til at anmode om et token fra. Hvis ikke angivet, bruges https://login.microsoftonline.com/{TENANTID} som standard.
SCOPE Streng Ingen Standardomfang for ressourcen, der bruges til at anmode om tokens, hvis det ikke angives af den, der kalder.
FICCLIENTID Streng Ingen Klient-id'et for den administrerede identitet, der bruges til at hente det eksterne token for legitimationsoplysninger i organisationsnetværket. 
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

For yderligere information, se Godkendelse ved brug af legitimationsoplysninger i organisationsnetværket.

WorkloadIdentity

Brug disse indstillinger til at konfigurere tokenindhentning gennem Microsoft Entra-arbejdsbelastningens identitet.

Navn på indstilling Skriv Standardværdi Description
AUTHTYPE Streng Ingen Angiv til WorkloadIdentity.
CLIENTID Streng Ingen Klient-id'et (app-id) for app-registreringen.
TENANTID Streng Ingen Microsoft Entra ID-lejer-ID'et for app-registreringen.
AUTHORITY Streng Ingen Når den er til stede, bruges som autoritet til at anmode om et token fra. Hvis ikke angivet, bruges https://login.microsoftonline.com/{TENANTID} som standard.
SCOPE Streng Ingen Standardomfang for ressourcen, der bruges til at anmode om tokens, hvis det ikke angives af den, der kalder.
FEDERATEDTOKENFILE Streng Ingen Sti til tokenfilen i organisationsnetværk, der leveres af arbejdsbelastningsidentitetsmiljøet. 
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

Enkeltlejer med klientcertifikat

Brug disse indstillinger til at konfigurere en enkeltlejerforbindelse, der godkender med et klientcertifikat.

Navn på indstilling Skriv Standardværdi Description
CLIENTID Streng Ingen Klient-id'et (app-id) for app-registreringen.
TENANTID Streng Ingen Microsoft Entra ID-lejer-ID'et for app-registreringen.
AUTHTYPE Streng Ingen Angiv til Certificate.
CERTPEMFILE Streng Ingen Sti til Privacy-Enhanced Mail (PEM) certifikatfilen.
CERTKEYFILE Streng Ingen Sti til den private nøglefil for certifikatet.
SCOPE Streng Ingen Standardomfang for ressourcen, der bruges til at anmode om tokens, hvis det ikke angives af den, der kalder.
AUTHORITY Streng Ingen Når den er til stede, bruges som autoritet til at anmode om et token fra.
SENDX5C Boolesk Falsk Muliggør afsendelse af x5c-headeren under certifikatbaseret tokenindhentning. 
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

Bemærk!

JS SDK'en læser PEM-certifikatet og de private nøglefiler direkte fra disken og beregner automatisk certifikatets fingeraftryk. Nøglefilen bør ikke bruge en adgangskode.

Multiprofil med klientcertifikat

For multiprofilscenarier, der bruger klientcertifikat, skal autoritetsslutpunktet sættes til botframework.com-lejeren:

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

Bagudkompatibilitet med Azure Bot Framework SDK

For at indlæse konfigurationen ved at bruge det samme format som Azure Bot Framework SDK, skal du bruge loadPrevAuthConfigFromEnv(): AuthConfiguration.

Brug disse ældre indstillingsnavne, når du migrerer eksisterende Bot Framework SDK-konfigurationer.

Navn på indstilling Skriv Standardværdi Beskrivelse
MicrosoftAppTenantId Streng Null Microsoft Entra ID-lejer-ID (ældre Bot Framework SDK-format).
MicrosoftAppId Streng Null Klient-ID'et (app-ID) for app-registreringen (ældre Bot Framework SDK-format).
MicrosoftAppPassword Streng Null App-hemmeligheden (ældre Bot Framework SDK-format). 
MicrosoftAppTenantId={tenant-id-guid}
MicrosoftAppId={app-id-guid}
MicrosoftAppPassword={app-registration-secret}

Brugerdefineret godkendelsesudbyder

Brugere, der har behov for en brugerdefineret godkendelsesudbyder, kan implementere grænsefladen:

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

Som eksempel kan du implementere AuthProvider ved hjælp af @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
  }

For at oprette en instans af CloudAdapter ved at bruge DevTokenProvider

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

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


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

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

MSAL-pakken (Python Agents SDK Microsoft-godkendelsesbibliotek) er et værktøj, der hjælper dig med at oprette adgangstokens til agentklienter og eksterne tjenester fra en selvværtsagent i SDK til Microsoft 365-agenter.

Pakken microsoft-agents-authentication-msal indeholder klassen MsalAuth, som er den centrale godkendelsesudbyder. Du kan konfigurere den til følgende typer legitimationsoplysninger:

  • Klienthemmelighed
  • Klientcertifikat
  • Brugertildelt administreret identitet
  • Systemtildelt administreret identitet

Installer godkendelsespakken

Installer MSAL-godkendelsespakken fra PyPI:

pip install microsoft-agents-authentication-msal

Enkeltlejer versus multiprofil

Godkendelse med klienthemmelighed eller klientcertifikat understøtter både enkeltlejer- og multiprofilkonfigurationer.

Brugertildelt administreret identitet og systemtildelt administreret identitet understøtter kun enkeltlejerkonfigurationer.

Bemærk!

For multiprofil skal du konfigurere Azure Bot-instansen som multiprofil og Microsoft Entra ID-appregistreringen som konti i enhver organisationsmappe (enhver Microsoft Entra ID-lejer - multiprofil). Læs mere i Enkelt- og multiprofil-applikationer.

Konfigurere en -forbindelse

MSAL-godkendelsesbiblioteket giver dig mulighed for at oprette og bruge flere forskellige klienter med Agents Framework hosting-programmet. Hver forbindelseskonfiguration opretter en navngivet godkendelsesklient til at understøtte kommunikation med eksterne tjenester eller andre agenter.

Konfigurer via miljøvariabler, der bruger (__) dobbeltunderstregning som navngivningskonvention til indlejrede indstillinger. Klassen MsalConnectionManager læser disse variable for at konstruere AgentAuthConfiguration instanser for hver navngiven forbindelse.

Vigtigt!

Forbindelsesstyringen kræver som minimum en forbindelse med navnet SERVICE_CONNECTION.

Miljøvariabler for hver godkendelsestype

Agenten opnår MSAL-konfiguration under kørsel fra miljøvariabler med hjælpefunktionen load_configuration_from_env().

I de følgende afsnit beskrives de nødvendige konfigurationsindstillinger for hver af de understøttede godkendelsestyper, sammen med eksempler på miljøvariabler for hver type.

Enkelt lejer med klienthemmelighed

Brug disse indstillinger til at konfigurere en enkeltlejerforbindelse, der godkender med en klienthemmelighed.

Navn på indstilling Skriv Standardværdi Description
CLIENTID Streng Ingen Klient-id'et (app-id) for app-registreringen.
CLIENTSECRET Streng Ingen Den hemmelighed, der er knyttet til appregistreringen. Brug kun til test- og udviklingsformål.
TENANTID Streng Ingen Microsoft Entra ID-lejer-ID'et for app-registreringen.
AUTHTYPE Streng ClientSecret Godkendelsestypen. Angiv til ClientSecret.
SCOPES Liste med strenge Ingen Standardliste over omfang, der skal anmodes om tokens for. Bruges kun, når der ikke sendes nogen områder fra agentens forbindelsesanmodning.
AUTHORITY Streng Ingen Når den er til stede, bruges som autoritet til at anmode om et token fra. Hvis ikke angivet, bruges https://login.microsoftonline.com/{TENANTID} som standard. 
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}

Enkeltlejer med klienthemmelighed er den anbefalede konfiguration til lokal udvikling.

Multiprofil med klienthemmelighed

For multiprofilscenarier, der bruger en klienthemmelighed, skal du sætte autoritetsslutpunkt til botframework.com-lejer:

Navn på indstilling Skriv Standardværdi Description
CLIENTID Streng Ingen Klient-id'et (app-id) for app-registreringen.
CLIENTSECRET Streng Ingen Den hemmelighed, der er knyttet til appregistreringen. Brug kun til test- og udviklingsformål.
AUTHTYPE Streng ClientSecret Godkendelsestypen. Angiv til ClientSecret.
AUTHORITY Streng Ingen Sæt til https://login.microsoftonline.com/botframework.com for multiprofil.
SCOPES Liste med strenge Ingen Standardliste over omfang, der skal anmodes om tokens for. 
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

Brugertildelt administreret identitet

Brug disse indstillinger til at konfigurere tokenanskaffelse med en brugertildelt administreret identitet.

Navn på indstilling Skriv Standardværdi Description
CLIENTID Streng Ingen Administreret identitet for klient-id, der skal bruges, når adgangstoken oprettes.
AUTHTYPE Streng ClientSecret Godkendelsestypen. Angiv til UserManagedIdentity. 
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID={managed-identity-client-id}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHTYPE=UserManagedIdentity

Administreret id er den anbefalede konfiguration til produktionsscenarier. Du kan få mere at vide under Administrerede identiteter til Azure-ressourcer.

Bemærk!

Når du bruger administrerede identitetstyper, skal du køre din vært eller klient på en Azure-tjeneste og have konfigureret tjenesten med enten en systemtildelt eller brugertildelt administreret identitet. For at se, hvilke Azure-tjenester der understøtter administrerede identiteter, se Administrerede identiteter til Azure-ressourcer.

Systemtildelt administreret identitet

Når du bruger godkendelsestypen SystemManagedIdentity, ignoreres klient-id'et, og den systemadministrerede identitet for tjenesten bruges.

Navn på indstilling Skriv Standardværdi Description
AUTHTYPE Streng ClientSecret Godkendelsestypen. Angiv til SystemManagedIdentity. 
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHTYPE=SystemManagedIdentity

Bemærk!

Når du bruger administrerede identitetstyper, skal du køre din vært eller klient på en Azure-tjeneste og have konfigureret tjenesten med enten en systemtildelt eller brugertildelt administreret identitet. For at se, hvilke Azure-tjenester der understøtter administrerede identiteter, se Administrerede identiteter til Azure-ressourcer.

Enkeltlejer med klientcertifikat

Brug disse indstillinger til at konfigurere en enkeltlejerforbindelse, der godkender med et klientcertifikat.

Navn på indstilling Skriv Standardværdi Description
CLIENTID Streng Ingen Klient-id'et (app-id) for app-registreringen.
TENANTID Streng Ingen Microsoft Entra ID-lejer-ID'et for app-registreringen.
AUTHTYPE Streng ClientSecret Godkendelsestypen. Angiv til certificate.
CERTPEMFILE Streng Ingen Sti til Privacy-Enhanced Mail (PEM) certifikatfilen.
CERTKEYFILE Streng Ingen Sti til den private nøglefil for certifikatet.
SCOPES Liste med strenge Ingen Standardliste over omfang, der skal anmodes om tokens for.
AUTHORITY Streng Ingen Når den er til stede, bruges som autoritet til at anmode om et token fra. 
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}

Bemærk!

Python SDK læser PEM-certifikatet og privatnøglefilen direkte fra disken og beregner certifikatets fingeraftryk automatisk. Nøglefilen bør ikke bruge en adgangskode.

Multiprofil med klientcertifikat

For multiprofilscenarier, der bruger klientcertifikat, skal autoritetsslutpunktet sættes til botframework.com-lejeren:

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

Konfigurer forbindelsesstyring

MsalConnectionManager-klassen kan administrere flere godkendelsesforbindelser for din agent. Den læser forbindelseskonfigurationer og opretter MsalAuth instanser for hver navngiven forbindelse.

Her er et eksempel på, hvordan du indstiller forbindelsesstyringen og starter din agent:

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()
)

Se eksemplet på hurtig start af Python for et komplet eksempel på, hvordan MsalConnectionManager bruges i en Python-agent.

Brugerdefineret godkendelsesudbyder

Brugere, der kræver en tilpasset godkendelsesudbyder, kan implementere AccessTokenProviderBase-basisklassen.

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

Logføring af understøttelse af godkendelse

MSAL-godkendelsessystemet bruger det Python-standardmodulet logging under loggernavnet microsoft_agents.authentication.msal. For at muliggøre detaljeret logføring af godkendelsesflows til fejlfinding af token-indsamling, skal du konfigurere loggeren i din applikation:

import logging

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

Bedste praksis for sikkerhed

  • Opbevar hemmeligheder i Azure Key Vault eller miljøvariabler. De må aldrig defineres i kildekoden.
  • Brug administrerede identiteter, når det er muligt, da de eliminerer behovet for at administrere hemmeligheder.
  • Roter klienthemmeligheder og certifikater regelmæssigt.
  • Brug mindstprivilegier-princippet for omfang og tilladelser.
  • Last updated on