Konfigurere enkelt logon med en generisk OAuth-udbyder

Copilot Studio understøtter enkeltlogon (SSO) med godkendelsesudbydere, der er kompatible med OAuth 2.0. SSO gør det muligt for agenter på dit websted at logge kunder på, hvis de er logget på den side eller app, hvor agenten er installeret.

Forudsætninger

Oprette eller bruge et brugerdefineret lærred, der understøtter det generiske OAuth-provider-SSO-flow

Når godkendelsesemnet starter i agenter, der er koblet til en generisk OAuth 2.0-udbyder, sender Copilot Studio en besked, der indeholder en sikker URL, som bruges til at overføre brugerens adgangstoken.

Det brugerdefinerede lærred eller en side, hvor lærredet er integreret, skal implementere følgende mønster:

  1. Få en adgangstoken for den bruger, der er logget på, fra din OAuth 2.0-godkendelsesudbyder ved hjælp af din foretrukne metode.

  2. Opfang en indgående besked fra Copilot Studio, og udtræk den sikre URL-adresse.

  3. Send adgangstoken til den sikre webadresse.

Udtræk den sikre URL-adresse og send token

Det brugerdefinerede lærred opfanger indgående beskeder ved hjælp af et middleware-koncept, hvilket er kode, der afvikles i forbindelse med modtagelse af beskeder fra Copilot Studio.

For at kunne reagere på logonanmodninger skal det brugerdefinerede lærred sende meddelelser med vedhæftede filer, der har indholdstypen application/vnd.microsoft.card.oauth. Vedhæftede filer i OAuthCard indeholder en content.tokenPostResource.sasUrl egenskab, som den sikre URL-adresse kan udtrækkes fra. Til sidst skal det brugerdefinerede lærred sende brugerens adgangstoken til den sikre URL-adresse.

Følgende JavaScript-kode er et eksempel på middleware-kode, der udtrækker den sikre webadresse og sender en token. Hvis indlægget lykkes, returnerer middleware false. Hvis opslaget ikke lykkes, eller hvis aktiviteten ikke har application/vnd.microsoft.card.oauth-egenskaben, returneres 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);
  }
};

Komplet eksempelkode

Implementeringen af en brugerdefineret lærred eller app, der henter et token for en bruger, der er logget ind, og sender dette token til Copilot Studio, varierer afhængigt af din godkendelsesudbyder. Du kan finde flere oplysninger i dokumentationen til godkendelsesudbyderen for at få flere oplysninger om logonforløb og om indhentning af adgangstokener. Du kan se et referenceeksempel ved hjælp af OKTA i Tredjeparts-SSO med OKTA.

Sådan bruger du et token i Copilot Studio

Tokens, der sendes via den sikre URL, placeres i variablen System.User.AccessToken i Copilot Studio. Agentudviklere kan bruge denne systemvariabel til at få adgang til beskyttede API'er, der er forbundet med den godkendte udbyder, der genererede tokenet.

I følgende eksempel konfigureres et HTTP-opkald med et godkendelsesheader, der bruger System.User.AccessToken.

Skærmbillede, der illustrerer et HTTP-opkald, der har adgang til en sikker API.

Understøttede kanaler

SSO med en generisk OAuth-godkendelsesudbyder er et brugerdefineret mønster, der enten kan implementeres af et brugerdefineret lærred eller en hvilken som helst anden klient, der arbejder med Directline-API'en.

  • Last updated on