Einmaliges AnmeldenSingle sign on

gilt für: SDK v4APPLIES TO: SDK v4

Einmaliges Anmelden (Single Sign-On, SSO) ermöglicht es einem Client (virtueller Assistent, WebChat usw.), im Namen des Benutzers mit einem Bot oder Skill zu kommunizieren.Single Sign on (SSO) allows a client, such as virtual assistant, WebChat and so on, to communicate with a bot or skill on behalf of the user. Aktuell wird nur der Identitätsanbieter Azure AD v2 unterstützt.Currently, only the Azure AD v2 identity provider is supported.

SSO ist für folgende Szenarien relevant:SSO applies to the following scenarios:

  • Virtueller Assistent und Skill-Bot(s).Virtual assistant and one or more skill bots. Der Benutzer kann sich einmalig bei dem virtuellen Assistenten anmelden.The user can sign in once into the virtual assistant. Der Assistent ruft dann mehrere Skills im Namen des Benutzers auf.The assistant then invokes multiple skills on behalf of the user. Weitere Informationen finden Sie unter Virtueller Assistent – Übersicht.See also Virtual assistant.
  • In eine Website eingebetteter Webchat.Webchat embedded into a website. Der Benutzer meldet sich bei der Website an.The user sign in the website. Die Website ruft dann einen Bot oder Skill im Namen des Benutzers auf.The website then invokes a bot or a skill on behalf of the user.

SSO hat folgende Vorteile:SSO provides the following advantages:

  • Der Benutzer muss sich nicht erneut anmelden, wenn er bereits bei einem virtuellen Assistenten oder bei einer Website angemeldet ist.The user does not have to login over again, if already signed in a virtual assistant or website.
  • Die Benutzerberechtigungen sind dem virtuellen Assistenten bzw. der Website nicht bekannt.The virtual assistant or website do not have knowledge of user permissions.

Hinweis

SSO ist ein neues Feature in der Version 4.8 des Bot Framework SDK.SSO is a new feature in Bot Framework SDK v4.8.

Interaktion der SSO-KomponentenSSO components interaction

Die folgenden Zeitabfolgediagramme geben Aufschluss über die Interaktionen zwischen den verschiedenen SSO-Komponenten.The following time sequence diagrams show the interactions between the SSO various components.

  • Das folgende Diagramm zeigt einen normalen Ablauf bei Verwendung eines virtuellen Assistenten (Client):The following diagram shows a normal flow when using a virtual assistant client.

    Bot-SSO: virtueller Assistent

  • Das folgende Diagramm zeigt einen normalen Ablauf und einen Ausweichablauf bei Verwendung eines WebChat-Clients:The following shows a normal and a fallback flow when using a WebChat client.

    Bot-SSO: WebChat

    Im Falle eines Fehlers greift SSO auf das ursprüngliche Verhalten zurück und zeigt die OAuth-Karte an.In the case of failure, SSO falls back to the existing behavior of showing the OAuth card. Ein Fehler kann beispielsweise auftreten, wenn eine Benutzereinwilligung erforderlich ist oder der Tokenaustausch nicht erfolgreich war.The failure may be caused for example if the user consent is required or if the token exchange fails.

Sehen wir uns den Ablauf etwas genauer an.Let's analyze the flow.

  1. Der Client beginnt eine Konversation mit dem Bot und löst dadurch ein OAuth-Szenario aus.The client starts a conversation with the bot triggering an OAuth scenario.

  2. Der Bot gibt eine OAuth-Karte an den Client zurück.The bot sends back an OAuth Card to the client.

  3. Der Client fängt die OAuth-Karte ab, bevor sie dem Benutzer angezeigt wird, und überprüft, ob sie eine Eigenschaft vom Typ TokenExchangeResource enthält.The client intercepts the OAuth card before displaying it to the user and checks if it contains a TokenExchangeResource property.

  4. Ist die Eigenschaft vorhanden, sendet der Client eine Anforderung vom Typ TokenExchangeInvokeRequest an den Bot.If the property exisists, the client sends a TokenExchangeInvokeRequest to the bot. Der Client muss über ein austauschbares Token für den Benutzer verfügen. Dabei muss es sich um ein Azure AD v2-Token handeln, und die Zielgruppe muss der Eigenschaft TokenExchangeResource.Uri entsprechen.The client must have an exchangeable token for the user, which must be an Azure AD v2 token and whose audience must be the same as TokenExchangeResource.Uri property. Der Client sendet eine Aufrufaktivität (Invoke) mit dem unten gezeigten Text an den Bot.The client sends an Invoke activity to the bot with the body shown below.

    {
        "type": "Invoke",
        "name": "signin/tokenExchange",
        "value": {
            "id": "<any unique Id>",
            "connectionName": "<connection Name on the skill bot (from the OAuth Card)>",
            "token": "<exchangeable token>"
        }
    }
    
  5. Der Bot verarbeitet die Anforderung vom Typ TokenExchangeInvokeRequest und gibt eine Antwort vom Typ TokenExchangeInvokeResponse an den Client zurück.The bot processes the TokenExchangeInvokeRequest and returns a TokenExchangeInvokeResponse back to the client. Der Client muss auf die Antwort vom Typ TokenExchangeInvokeResponse warten.The client should wait till it receives the TokenExchangeInvokeResponse.

    {
        "status": "<response code>",
        "body": {
            "id":"<unique Id>",
            "connectionName": "<connection Name on the skill bot (from the OAuth Card)>",
            "failureDetail": "<failure reason if status code is not 200, null otherwise>"
        }
    }
    
  6. Wenn in der Antwort vom Typ TokenExchangeInvokeResponse als Status (status) der Wert 200 angegeben ist, wird die OAuth-Karte nicht angezeigt.If the TokenExchangeInvokeResponse has a status of 200, then the client does not show the OAuth card. Dies ist im Diagramm mit dem normalen Ablauf dargestellt.See the normal flow diagram. Sollte der Status nicht status lauten oder die Antwort vom Typ TokenExchangeInvokeResponse nicht empfangen werden, wird dem Benutzer die OAuth-Karte angezeigt.For any other status or if the TokenExchangeInvokeResponse is not received, then the client shows the OAuth card to the user. Dies ist im Diagramm mit dem Ausweichablauf dargestellt.See the fallback flow diagram. Dadurch wird sichergestellt, dass der SSO-Ablauf auf den normalen OAuthCard-Ablauf ausweicht, wenn ein Fehler auftritt oder Abhängigkeiten wie etwa die Benutzereinwilligung nicht erfüllt sind.This ensures that the SSO flow falls back to normal OAuthCard flow, in case of any errors or unmet dependencies like user consent.

Nächste SchritteNext steps