Kertakirjautumisen määrittäminen yleisen OAuth-palvelun avulla

Artikkeli
12/31/2024

Copilot Studio tukee kertakirjautumista (SSO) OAuth 2.0 -yhteensopivien todentamispalveluiden kanssa. SSO:n avulla verkkosivuston agentit voivat kirjata asiakkaat sisään, jos he kirjautuivat sivulle tai sovellukseen, jossa agentti on otettu käyttöön.

edellytykset

Mukautetun pohjan luominen tai käyttö, joka tukee yleisen OAuth-palvelun SSO-työnkulkua

Kun todentamisen aihe käynnistyy yleiseen OAuth 2.0 -palveluntarjoajaan yhdistetyissä agenteissa, Copilot Studio lähettää viestin, joka sisältää suojatun URL-osoitteen, jonka avulla lähetetään käyttäjän käyttöoikeustietue.

Mukautetun pohjan tai sivun, johon pohja on upotettu, on toteutettava seuraava kaava:

Hanki käyttöoikeustietue kirjautuneelle käyttäjälle OAuth 2.0 -todennuspalvelusta käyttämällä haluamaasi menetelmää.
Sieppaa Copilot Studiosta saapuva viesti ja pura suojattu URL-osoite.
Lähetä käyttöoikeustietue suojattuun URL-osoitteeseen.

Pura suojattu URL-osoite ja lähetä käyttöoikeustietue

Mukautettu pohja sieppaa saapuvat viestit käyttämällä väliohjelmistokonseptia, joka on koodi, joka suoritetaan viestien Copilot Studiosta vastaanottamisen kontekstissa.

Jos haluat vastata kirjautumispyyntöihin, mukautetun pohjan on siepattava viestit, joissa on liitteitä, joiden sisältötyyppi on application/vnd.microsoft.card.oauth. OAuthCard-liitteet sisältävät content.tokenPostResource.sasUrl-ominaisuuden, josta suojatun URL-osoitteen voi poimia. Lopuksi mukautetun pohjan on lähetettävä käyttäjän käyttöoikeustietue suojattuun URL-osoitteeseen.

Seuraava JavaScript-koodi on esimerkki väliohjelmistokoodista, joka poimii suojatun URL-osoitteen ja lähettää käyttöoikeustietueen. Jos lähetys onnistuu, väliohjelmisto palauttaa false. Jos lähetys epäonnistuu tai aktiviteetilla ei ole application/vnd.microsoft.card.oauth-ominaisuutta, se palauttaa 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);
  }
};

Täysi näytekoodi

Mukautetun pohjan tai sovelluksen toteutus, joka hankkii tunnuksen kirjautuneelle käyttäjälle ja lähettää tunnuksen Copilot Studioon, vaihtelee todentamispalvelun mukaan. Lisätietoja kirjautumisvirroista ja käyttöoikeustietueiden hankkimisesta on todentamispalvelusi dokumentaatiossa. Viite-esimerkki OKTA-palvelua käytettäessä: Kolmannen osapuolen kertakirjautuminen OKTA:n avulla.

Tunnuksen käyttäminen Copilot Studiossa

Suojatulla URL-osoitteella julkaistut tunnukset täytetään System.User.AccessToken-muuttujaan kohteessa Copilot Studiossa. Agentin tekijät voivat tämän järjestelmämuuttujan avulla käyttää suojattuja ohjelmointirajapintoja, jotka on yhdistetty todennettuun palveluun, joka loi tunnuksen.

Seuraavassa esimerkissä HTTP-kutsu määritetään käyttämällä valtuutustietojen otsikkoa, joka käyttää kohdetta System.User.AccessToken.

Näyttökuva suojattua ohjelmointirajapintaa käyttävästä HTTP-kutsusta.

Tuetut kanavat

Kertakirjautuminen yleisen OAuth-todennuspalvelun avulla on mukautettu malli, joka voidaan toteuttaa mukautetussa pohjassa tai jossain muussa Directline-ohjelmointirajapintaa käyttävässä asiakasohjelmassa.

Jaa