Get Microsoft Graph Delegated Token Activity
Overview
The Microsoft Graph API allows you to delegate permissions from a user account to Pia. Before using this activity, you must configure any users you wish to impersonate in the Microsoft Graph Delegate Consent screen on the client dashboard. If you want to write an automation which performs an action on behalf of a user across multiple clients, you must do this configuration for each client. For more information refer to this article.
The MS Graph Delegated Token Activity (msgraph_delegated_token) is one of the built in activities available in the Pia Package Editor. This activity retrieves a single token from the list of available tokens for the client which is then used by the package to make changes in Microsoft 365 on behalf of the Signed In user. This activity is used in Cloud Only, Cloud Hybrid and Semi-Hybrid packages.
An example scenario where this activity is currently used in Pia is the Setup Mail Forwarding Package. In this package, the activity is used to retrieve the available graph delegated token with a "Mail.Send" scope. This token is then used by Pia during package execution to modify mail flow functionality for the selected user.
The MS Graph Delegated Token Activity can be located by simply searching for "MS Graph" in the list of activities in the package editor:
Here is a basic example of a package where the MS Graph Delegated Token Activity has been used:
# Pia Automation Package
conditions:
- name: 'client_filter'
optMode: 'OptOut'
category: 'Hello World'
lockTo: '2'
- name: 'chat'
option_button: 'MS Graph'
option_text: 'Text which is displayed in the Pia Chatbot'
option_category: 'Pia Chatbot Category'
steps:
- task: msgraph_delegated_token
inputs:
scopes: 'Mail.Send'
- task: chat_interaction
inputs:
text: 'Please type in your message'
form_name: 'email_submission_form'
form_display_mode: 'Embed'
- task: inline_powershell
inputs:
token: =msgraph_delegated_token.Token
receivers: =chat_interaction.form.receivers
message: =chat_interaction.form.message
subject: =chat_interaction.form.subject
script: |
$params = @{
message = @{subject = $subject
body = @{contentType = "Text"; content = $message;}
toRecipients = @(
@{emailAddress = @{ address = $receivers;}}
)
}
}
$request = [System.Net.HttpWebRequest]::Create("https://graph.microsoft.com/v1.0/me/sendMail")
$request.Method = "POST";
$request.ContentType = "application/json";
$request.Accept = "application/json";
$request.Headers["Authorization"] = "Bearer $token";
$jsonBody = $(ConvertTo-Json $params -Depth 10)
$requestWriter = New-Object System.IO.StreamWriter $request.GetRequestStream();
$requestWriter.Write($jsonBody);
$requestWriter.Flush();
$requestWriter.Close();
$response = $request.GetResponse();
$response.Dispose();
- task: chat_interaction
inputs:
text: 'Email has been sent.'
for the above example, a form has been created with the name 'email_submission_form'. The form has three form fields:
Receivers: Text field to ass email address of the receiver (Reference Name: receivers).
Subject: Text field to add subject of the email (Reference Name: subject).
Message: multi-line Text field to add the body of the email (Reference Name: message).
When the package runs, Pia will present you with a form to add the receiver's email address, subject of the email and body. Once the form is filled, an email will be sent using the Microsoft Graph Token retrieved by the MS Graph Delegated Token Activity.
Activity Behavior
The primary purpose of this activity is to retrieve Microsoft Delegated token which is then passed along to the package so that the package can perform specific tasks in Microsoft 365 on behalf of the Signed In user.
The activity can only retrieve a single token at once that is available for the client. You will need to define the scope of the token in the input property of the activity to retrieve the required token. The default behavior of the activity is that it will fail the package execution if the token could not be obtained. However, you can modify this behavior by setting a 'continue_on_error' property on the activity.
You can set the 'continue_on_error' property on the MS Graph Delegated Token Activity as shown below:
If the value of the property is 'true', the activity will not fail when the token could not be retrieved. If the value of the property is 'false', the activity will fail causing the package execution to error when the token is not obtained.
The MS Graph Delegated Token Activity can be used in all types of package executions. This includes packages which have been initiated via the Pia Chatbot or via Ticketing System Event.
Input Properties
Use properties to modify the behavior of the activity.
Property Name: upn
Property Required: No
Property Description: This is the UPN of the user to retrieve delegated Token token for. Example: 'john.smith@domain_name.com'
Property Name: scopes
Property Required: No
Property Description: When the scopes are defined, the activity will retrieve token(s) with restricted access scope.
Property Name: client_id
Property Required: Yes
Property Description: The internal Client ID - defaults to the client id for the ticket associated with this package execution.
Property Name: mode
Property Required: Yes
Property Options: 'Client' or 'Pia'
Property Description: When you set the mode to 'Pia', the activity will lookup the scope or upn from the active client. When you set the mode to 'Client', the activity will lookup the scope or upn for another client.
Output Properties
There is a single output property available for this activity.
Property Name: Token
Property Required: This is the token retrieved by the MS Graph Delegated Token activity.