How to: integrate Power Virtual Agents with Teams using SSO and how to retrieve user information

Power Virtual Agents are a great platform that allows organization to create powerful chatbots in a very short amount of time. And yes, they are easy to install into Teams as well. Let’s assume you have a some kind of Power Virtual Agent bot (PVA bot) ready and you want to bring that bot into Teams.

Since Docs. Microsoft.Com has an excellent article how you can enable Teams channel AND how to create the app manifest that actually materializes your bot into Teams I am not going to re-write it. Instead I urge you to read that guide, it is very simple: https://docs.microsoft.com/en-us/power-virtual-agents/publication-add-bot-to-microsoft-teams

Something that is really easy to miss, especially if you do that several times without a checklist, are Valid domains. Remember to add token.botframework.com to valid domains or your Login button does nothing. #speakingfromtheexperience

In the future there will be even an easier way to add your bot to Teams. There will be just a button Publish to Teams that will take care of the manifest part and install the bot. It won’t be much more easier after that!

Adding Authentication

Now that we got that covered, you soon notice that your bot is not really authenticated into Office 365. If you are running Power Automates you notice that you don’t know who the user typing into the bot really is.

For this there is also a superb Docs.Microsoft.Com article that will help you to get your AAD Authentication in place. Yes, you need to do a App Registration in the Azure but otherwise it is just making sure you add every detail onto it’s right place.

https://docs.microsoft.com/en-us/power-virtual-agents/configuration-end-user-authentication

Follow the instruction and check that you put the correct content to each of the fields. I have included a table with those values for a bit of help.

Label	Value
Token URL Template	https://login.microsoftonline.com/common/oauth2/v2.0/token
ClientID	This is your registered Azure AD Application ID
Token Body Template	code={Code}&grant_type=authorization_code&redirect_uri={RedirectUrl}&client_id={ClientId}&client_secret={ClientSecret}
Client Secret	This is your registered Azure AD Application Client Secret
Refresh URL Template	https://login.microsoftonline.com/common/oauth2/v2.0/token
Authorization URL Template	https://login.microsoftonline.com/common/oauth2/v2.0/authorize
Refresh Body Template	refresh_token={RefreshToken}&redirect_uri={RedirectUrl}&grant_type=refresh_token&client_id={ClientId}&client_secret={ClientSecret}
Authorization URL Query String Template	?client_id={ClientId}&response_type=code&redirect_uri={RedirectUrl}&scope={Scopes}&state={State}

What I didn’t mention yet was the Token exchange URL (required for SSO). This can be done using following. Open Azure AD and navigate to your PVA service and open Expose an API. Use +Add a scope (if you don’t have application ID URL yet it will be created now) and type in your scope name and add some appropriate text to Admin/User logins. I have a demo environments so I didn’t really pay attention to those texts.

Copy the Scope URL after creation (it starts with api://) and paste it into Token Exchange URL in PVA Authentication settings.

This procedure is also quite described in Docs: https://docs.microsoft.com/en-us/power-virtual-agents/configure-sso

Logging in and Getting User Information

Now that we have authentication enabled we need to enable login. For that I have created a topic in PVA called “authenticate me” that also can be used to test this.

For this topic you need to add a Call to action named “Authenticate” to let PVA manage the authentication. You will get two variables out of that: isLoggedIn and AuthToken.

Once user logs in, you will have his Authentication token. But your bot still does not know who the user really is. For that you need to add a another Call to Action and create a Flow to retrieve user information based on that token.

You will set those return values later, but when you set them up remember to check variable properties (click on variable name) and choose Usage: Bot to make them usable in all topics.

To get started with the creation of Flow you can check this guide. https://docs.microsoft.com/en-us/power-virtual-agents/advanced-flow

However note that the Flow you are creating for this is different in inside. In the essence: you choose to add a Call to Action, Choose Create a Flow, Build the Flow contents, Rename it, Save it, Get back to PVA editor and add Call to Action and this time choose your Flow you just created.

Important steps here

• AuthToken value comes as input from your PVA bot
• Add premium HTTP connector. Yes, the user who creates this needs to have a premium Power Automate licensing in place.
• Method: GET
• URI: https://graph.microsoft.com/v1.0/me/
• Headers key: Authorization
• Headers value: Bearer and add dynamic value AuthToken. There is a space between Bearer and AuthToken.

You will get a JSON reply, which you need to parse with Parse JSON action. Choose Content as the Body from HTTP call.

The final step is to link Parse JSON outputs (userPrincipalName and displayName) to appropriate outputs. Just +Add an output to add more.

Here is the Schema I used.

{
    "type": "object",
    "properties": {
        "@@odata.context": {
            "type": "string"
        },
        "businessPhones": {
            "type": "array",
            "items": {
                "type": [
                    "string",
                    "null"
                ]
            }
        },
        "displayName": {
            "type": "string"
        },
        "givenName": {
            "type": [
                "string",
                "null"
            ]
        },
        "jobTitle": {
            "type": [
                "string",
                "null"
            ]
        },
        "mail": {
            "type": [
                "string",
                "null"
            ]
        },
        "mobilePhone": {
            "type": [
                "string",
                "null"
            ]
        },
        "officeLocation": {
            "type": [
                "string",
                "null"
            ]
        },
        "preferredLanguage": {
            "type": [
                "string",
                "null"
            ]
        },
        "surname": {
            "type": [
                "string",
                "null"
            ]
        },
        "userPrincipalName": {
            "type": "string"
        },
        "id": {
            "type": "string"
        }
    }
}

Now we know who the user is and we can reuse his account (userPrincipalName) in other flows! The Authenticate me is a great test here to see everything worked.

Tip: If you encounter errors start debugging them by opening the Flow connected to “Authenticate me” topic and see it’s run history.

Reusing the user id in real topics

No, you don’t need to go through the “Authenticate me” step in every topic. Since those values can be reused in other topics AND Power Virtual Agents are really smart it will ask for the authenticate when you need to pass the username to another Flow. You just add the Username bot variable to other Flow’s input and PVA takes care of the rest.