Make Project For The Web Human: Build your Project bot with Power Virtual Agents (Detailed!)


If you are new to Power Virtual Agents (PVA), I recommend do a quick read at https://docs.microsoft.com/en-us/power-virtual-agents/fundamentals-get-started#create-your-first-bot to know the terms to be used in this post.

In my previous post, I gave a feel of how PVA simplified the way of managing projects!

Today, I spent 6 hours writing this post to give a complete step-by-step process of building this Project bot. So, don’t miss to read this till the end.

Bot: I am waiting!

When the user sends a message, bot matches the message with the right topic based on trigger phrases. In this case, the below topic is matched and the user is greeted with the message “Sure. I can help you. Please login to identify your projects.” . What happens next is important?

This post goes deeper into the authentication process combined with Microsoft Graph and new Project to personalize conversations.

How is this done? Read on.

PVA Bot about to be built needs to first authenticate and get consent from the user to access their details, then get profile details, email address from Microsoft Graph Web API and pull the projects from CDS to personalize the conversation.

Let’s start with end user authentication support in PVA. PVA supports any identity provider that is compliant with the OAuth2 standard. Microsoft identity is an identity provider that allow us to build applications (here it is PVA bot) that can sign in all Microsoft identities and get security tokens to call Microsoft APIs, such as Microsoft Graph.

I have divided this post into nine sections: starting from authentication basics and ending with authoring PVA bots.

  1. Create an identify for PVA Bot in Azure App Portal
  2. Request an authorization code
  3. Request an access token
  4. Access Graph API will access token
  5. License requirements
  6. Configure end user authentication in Power Virtual Agent bot
  7. Author Project Bot Topic
  8. Authenticate node
  9. Author flow called by topic

Create an identify for PVA Bot in Azure App Portal

Our PVA bot needs have permission to access Microsoft Graph Web API. Let’s create an identity for the PVA bot (this identity is called as service principal) and assign the required Graph API permission.

Remember, the redirect URI should be set to https://token.botframework.com/.auth/web/redirect. Post user authentication, Microsoft Identity redirects to this URI with authentication responses (tokens)

  1. Create an Azure AD application – https://docs.microsoft.com/en-us/azure/active-directory/develop/howto-create-service-principal-portal#create-an-azure-active-directory-application
  2. Create an application secret – https://docs.microsoft.com/en-us/azure/active-directory/develop/howto-create-service-principal-portal#certificates-and-secrets
  3. Configure API permissions: PVA Bot needs to read name and email address of signed-in user. Default permission, User.Read is sufficient – https://docs.microsoft.com/en-us/graph/permissions-reference#user-permissions . Scope name of User.Read is https://graph.microsoft.com/User.Read

Once the app identity is created, secure the below details before building PVA bots.

  1. Application (client) id
  2. Client Secret key
  3. Authorization endpoint
  4. Token endpoint
  5. Scopes

Authentication and Authorization

Before you read further, let’s get the difference between authentication and authorization right.

Authentication is process of proving you are who you say you are. Authorization specifies what data you’re allowed to access and what you can do with it.

Source: https://docs.microsoft.com/en-us/azure/active-directory/develop/authentication-scenarios

How does the App (PVA Bot) and Microsoft Identity use the app identity details for authentication and authorization?

At a high level, the entire flow looks a bit like this. App first gets the authentication code, then gets the access token for the allowed scope of Web API and finally uses the access token to talk to Web API.

Source: https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-auth-code-flow
Native App is our PVA Bot and Web API is the Microsoft Graph Web API

Request an authorization code

First, PVA bot directs the user to the /authorize end point of Microsoft Identity.

https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id={ClientId}&response_type=code&redirect_uri={RedirectUrl}&scope={Scopes}&state={State}

To this end point, the bot will send the following values as query parameters

  1. client_id must be application (client) id of the app identity.
  2. response_type must be code. As this end point must return the authorization code.
  3. redirect_uri must be https://token.botframework.com/.auth/web/redirect
  4. scope will be https://graph.microsoft.com/User.Read
  5. state will be randomly generated unique value. PVA will take care of this parameter.

At this point, the user will be asked to enter their credentials and complete the authentication. Microsoft identity platform endpoint will also ensure that the user has consented to the user profile permissions indicated in the scope parameter.

Once the user authenticates and grants consent, the Microsoft identity platform endpoint will return a response to PVA Bot at the indicated redirect_uri with authorization code in code parameter and state value sent in request in state parameter.

The only thing PVA Bot can do with the authorization code is to make a request to get an access token. Authorization codes are short lived, typically they expire after about 10 minutes.

Source: https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-auth-code-flow#request-an-authorization-code

Request an access token

Now that PVA bot has acquired the authorization code and have been granted permission by the user, the bot can redeem the code for an access token. PVA bot sends a POST request to the /token endpoint.

POST https://login.microsoftonline.com/common/oauth2/v2.0/token

Content-Type: application/x-www-form-urlencoded
code={Code}&grant_type=authorization_code&redirect_uri={RedirectUrl}&client_id={ClientId}&client_secret={ClientSecret}

To this end point, the bot will POST the below parameters as request body

  1. code is the authorization code returned by /authorize end point
  2. grant_type must be authorization_code for the authorization code flow.
  3. redirect_uri must be https://token.botframework.com/.auth/web/redirect. The same redirect_uri value that was used to acquire the authorization_code.
  4. client_id must be application (client) id of the app identity.
  5. client_secret must be the application secret that was created in the app registration portal for your app

A successful response will return access token and expiry time (in seconds). This access token also called as bearer token basically says “Give the bearer of this token access”. PVA bot can use this token to access the resource, such as a web API.

Access_tokens are short lived, and PVA Bot refreshes them after they expire to continue accessing resources.

Bot does so by submitting another POST request to the /token endpoint, this time providing the refresh_token (that is the access token received before) instead of the authorization code, redirect URI, client id and client secret.

Source: https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-auth-code-flow#use-the-access-token

Access Microsoft Graph API with access token

With the access token, the bot can call flow action with the access token as parameter and get the projects assigned to the user. Flow does a HTTP GET request for the signed-in user passing the bearer token

GET https://graph.microsoft.com/v1.0/me  
Authorization: Bearer <access token>

If the access token is valid, Graph Web API returns the below response. We can use JSON actions to parse the property values of mail and givenName.

HTTP/1.1 200 OK
Content-type: application/json
Content-length: 491

{
  "businessPhones": [
       "businessPhones-value"
   ],
   "displayName": "displayName-value",
   "givenName": "givenName-value",
   "jobTitle": "jobTitle-value",
   "mail": "mail-value",
   "mobilePhone": "mobilePhone-value",
   "officeLocation": "officeLocation-value",
   "preferredLanguage": "preferredLanguage-value",
   "surname": "surname-value",
   "userPrincipalName": "userPrincipalName-value",
   "id": "id-value"
}

License requirements

Before building the bot, the user must have the following licenses

  1. Power Virtual Agent is currently in public preview; Just signup for free PVA preview at https://powerva.microsoft.com. This action will attach “Dynamics 365 AI for Customer Service Virtual Agents Viral SKU” license to the logged-in user.
  2. Project Plan 3 (formerly Project Online Professional) or Project Plan 5 (formerly Project Online Premium).
  3. Any Microsoft Flow license

Configure end user authentication in Power Virtual Agent Bot

In Power Virtual Agents, choose the environment where the bot needs to be created. This is important. Flows called by bot should also be hosted as solutions in the same environment.

Create a bot and select Manage on the side navigation pane, and then go to the Authentication tab. This section will use details of the PVA Bot app registered in Azure App portal such as client id, client secret key, scope (API permissions).

One PVA Bot = One OAuth2 Identity Provider with multiple scopes to the same resource

Presently, one PVA bot can be configured to get authenticated by one identity provider with multiple scopes to the same resource. This means a bot cannot request for access tokens for different resources.
  1. Connection name : Friendly name for your identity provider connection . Can’t be changed later
  2. Service Provider : This defaults to OAuth2Generic and can’t be changed
  3. Client ID : Paste the application (client) id of the app identity.
  4. Client Secret : Paste the secret key that was created in the app registration portal for your app
  5. Scope : The list of scopes (API permissions) the authenticated users to have once signed in. This should match with the API permissions of PVA Bot app. This will be https://graph.microsoft.com/User.Read
  6. Scope List delimiter: Indicates the separator character for the scope list. This can’t be empty, and so set this field to , (comma)
  7. Authorization URL Template : Microsoft identity authorization end point is https://login.microsoftonline.com/common/oauth2/v2.0/authorize
  8. Authorization URL Query String Template : This field should set to the list of query parameters that will be appended to the authorization end point. Set this field to?client_id={ClientId}&response_type=code&redirect_uri={RedirectUrl}&scope={Scopes}&state={State}
  9. Token URL Template : Microsoft identity token end point to get access tokens. This field is set to https://login.microsoftonline.com/common/oauth2/v2.0/token
  10. Token URL Query String Template : Usually this is a question mark ?
  11. Token Body Template : This field is the template of the token body. This field is set to code={Code}&grant_type=authorization_code&redirect_uri={RedirectUrl}&client_id={ClientId}&client_secret={ClientSecret}
  12. Refresh URL Template : Microsoft identity token end point to refresh access tokens. This field is set to https://login.microsoftonline.com/common/oauth2/v2.0/token
  13. Refresh URL Query String Template : Usually this is a question mark ?
  14. Refresh Body Template : This field is the template of the refresh token body. This field is set to refresh_token={RefreshToken}&redirect_uri={RedirectUrl}&grant_type=refresh_token&client_id={ClientId}&client_secret={ClientSecret}

Author Project Bot Topic

A bot can handle multiple topics. A topic can handle a specific requirement. Each topic starts with trigger phrases and conversation nodes. In our topic, the conversation nodes, call an action, show an message and go to another topic is used.

Authenticate Node

After the initial greeting message, click + sign, select call an action conversation node and then select Authenticate. This node can will be available only after end-user authentication configuration is complete


Authenticate node wraps authentication flow (that is section Request an authorization code, Request an access token) and gives the bearer token and if the user has logged in. What a relief?

Adding this node will add set of child nodes for success and failure path

Author flow called by bot

Once we have the authenticate node, click + sign, select call an action. This action will allow you to choose an existing flow created by any PVA bots hosted as solutions in the same environment or create a new flow.

It is recommended to have package all flows of one bot within a single ‘container’ in Power Automate solutions.

Selecting Create a flow action will open Power Automate and you can start edit the flow. This flow is filled with set of actions like the one below

This generated flow would be changed to the one below

This flow gets triggered with the bearer token (access code). Brief details about each step is given below to guide you

  1. Get the given name and primary email address of the signed in user using Microsoft Graph . Note the authentication is Raw and value is “Bearer ” + <token>. This action returns user details as JSON (refer section) document.
  2. As we are not interested in all details about the signed-in user, schema includes only two properties – givenName and mail
  3. Lists projects with project manager’s internal email address equals to mail. Projects entity has many-to-one relationship with user. So, the Filter Query field navigates to user entity and checks internalemailaddress field equals mail. This action will be executed with defined connection; it will not be executed in the context of the signed-in user
  4. This is simple. Initialize Projects variable to store the project id and names
  5. Builds project variable with project id and project name
  6. Respond back to virtual agent with name of the project manager and projects

Hope this long post helps you to get started and build personalized no-code bots with Power Virtual Agents, Power Automate, Microsoft Graph backed with CDS.

Looking forward to hear your experience. 🙂

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s