Konfigurere enkel pålogging med en generisk OAuth-leverandør

Artikkel
07/22/2024

Viktig!

Power Virtual Agents-funksjoner er nå en del av Microsoft Copilot Studio etter betydelige investeringer i generativ kunstig intelligens og forbedrede integreringer på tvers av Microsoft Copilot.

Enkelte artikler og skjermbilder kan henvise til Power Virtual Agents når vi oppdaterer dokumentasjons- og opplæringsinnhold.

Copilot Studio støtter enkel pålogging (SSO) med OAuth 2.0-kompatible godkjenningsleverandører. Med SSO kan brukere på nettstedet logge på kunder hvis de logget på siden eller appen der kopiloten er distribuert.

Forutsetning

Opprette eller bruke et egendefinert arbeidsområde som støtter den generiske SSO-flyten for OAuth-leverandør

Når godkjenningsforespørselsemnet utløses i kopiloter koblet til en generisk OAuth 2.0-leverandør, sende Copilot Studio en melding som inneholder en sikker URL-adresse, som brukes til å legge inn brukerens tilgangstoken.

Det egendefinerte lerretet eller siden der lerretet er innebygd, må implementere følgende mønster:

Hent en tilgangstoken for den påloggede brukeren fra OAuth 2.0-godkjenningsleverandøren ved hjelp av den foretrukne metoden.
Avskjær en innkommende melding fra Copilot Studio, og trekk ut den sikre URL-adressen.
Legg inn tilgangstoken til den sikre URL-adressen.

Trekke ut en sikker URL og sende tokenet

Det egendefinerte arbeidsområdet avskjærer innkommende meldinger ved hjelp av et mellomvarekonsept, som er kode som kjører i konteksten for meldinger som mottas fra Copilot Studio.

For å kunne svare på påloggingsforespørsler må det egendefinerte arbeidsområdet fange opp meldinger med vedlegg som har application/vnd.microsoft.card.oauth-innholdstype. OAuthCard-vedlegg inneholder en content.tokenPostResource.sasUrl-egenskap som den sikre URL-adressen kan trekkes ut fra. Til slutt bør det egendefinerte arbeidsområdet legge inn brukerens tilgangstoken til den sikre URL-adressen.

JavaScript-koden nedenfor er et eksempel på mellomvarekode som trekker ut den sikre URL-adressen og legger inn et token. Hvis innlegget er vellykket, returnerer mellomvaren false. Hvis innlegget ikke er mislykket, eller hvis aktiviteten ikke har application/vnd.microsoft.card.oauth-egenskapen, returnerer den 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);
  }
};

Fullstendig eksempelkode

Implementeringen av et egendefinert arbeidsområde eller en app som henter et token for en pålogget bruker, og sender tokenet til Copilot Studio, varierer avhengig av godkjenningsleverandøren din. Hvis du vil ha mer informasjon, kan du se dokumentasjonen for godkjenningsleverandøren hvis du vil ha mer informasjon om påloggingsflyter og hente tilgangstokener. Hvis du vil se et eksempel på en referanse ved hjelp av OKTA, kan du se Tredjeparts-SSO med OKTA.

Bruke tokenet i Copilot Studio

Tokener som legges inn ved hjelp av den sikre URL-adressen, fylles ut i variabelen System.User.AccessToken i Copilot Studio. Kopilotutviklere kan bruke denne systemvariabelen for å få tilgang til beskyttede API-er som er koblet til den godkjente leverandøren som genererte tokenet.

I følgende eksempel er en HTTP-samtale konfigurert med et autorisasjonshode som bruker System.User.AccessToken.

Skjermbilde som illustrerer en HTTP-samtale som har tilgang til en sikker APU.

Støttede kanaler

SSO med en generisk OAuth-godkjenningsleverandør er et egendefinert mønster som kan implementeres enten av et egendefinert arbeidsområde eller en annen klient som arbeider med Directline-API.

Del via