Skip to main content

Azure Get API Token Activity

Overview​

The Azure Get API Token (azure_get_api_token) Activity can be used in Automations to retrieve Microsoft Graph or Exchange Online Token from the list of available tokens 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 SmartForms User Offboarding Automation. In this package, the activity is used to retrieve the available Microsoft Graph and Exchange Online tokens. These tokens are then used by Pia during package execution to modify the behavior of the selected user in Microsoft Azure or Exchange Online.

The Azure Get API Token Activity Activity can be located by simply searching for "Azure: Get API Token" in the list of activities in the package editor:

Here is a basic example of a package where the Azure Get API Token Activity can been used:

# Pia Automation Package
conditions:
- name: 'client_filter'
optMode: 'OptOut'
category: 'Hello World'
lockTo: '2'

- name: 'chat'
option_button: 'Azure Get API Token'
option_text: 'Text which is displayed in the Pia Chatbot'
option_category: 'Pia Chatbot Category'

steps:
- task: azure_get_api_token
alias: 'graph_token'
continue_on_error: 'true'
inputs:
Scope: "https://graph.microsoft.com"

- task: inline_powershell
inputs:
token: =azure_get_api_token.Token
script: |
Write-Host $token

Activity Behavior​

The primary purpose of this activity is to retrieve Microsoft Graph or Exchange Online Token which is then passed along to the package so that the package can perform specific tasks in Microsoft 365 or Exchange Online 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 Azure Get API 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 Azure Get API 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: Tenant Id
Property Required: Yes
Property Description: Id of Azure Tenant to retrieve token for

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 client that is linked to Pia. When you set the mode to 'Client', the activity will lookup the scope or upn for the current client that the Package is running for.

Property Name: Scope
Property Required: Yes
Property Description: When the scopes are defined, the activity will retrieve token(s) with restricted access scope. Scopes can be provided for Graph API or Exchange Online.

Example Scopes:
  Microsoft Graph - "https://graph.microsoft.com"
  Exchange Online - "https://outlook.office365.com"

Output Properties​

There is a single output property available for this activity.

Property Name: Token
Property Required: This is the token retrieved by the Azure Get API Token activity.