Creating the Microsoft App
The setup does not need to be performed by an administrator in Azure. Any account can create the required app. However, the app should be added to a long-living account, or given shared ownership with other users to ensure it doesn't get deleted on accident when an account is removed from Azure.
This step will guide you through creating an application on Microsoft Azure that can access the resources needed for your Microsoft Graph connector to work. Make sure to complete the Microsoft App setup in a new tab or window - you will need information from this page to finish setting up on Blackbox.
Making the Application
Login to Microsoft Azure and go to the portal homepage. Once there, select Microsoft Entra ID or search for it.
If you already have an exiting app, you do not have to create a new one. You can update API scopes for the application to fit your changing needs.
Once on the Entra ID page, select App Registrations from the left hand menu, then click New Registration.
Once on the Register an application page, enter a name for your new application. It is recommend you call this application something similar to Blackbox Connector, and not Demo App as this guide uses.
Leave the other settings alone, we will make changes later when needed. Finally, click Register.
You should be automatically be redirected to the Application page upon registration.
Configuring API Permissions
Blackbox connector API permissions require Administrator consent before they are enabled. You can continue with setup, but your connector wont work until those permissions have been approved.
Once created, your application needs API scopes in order to function correctly. Click API Permissions from the side menu, then click Add a permission. This will open a menu on your left. Select Microsoft Graph from the top of this menu.
Microsoft Graph workflows will never use Delegate Permissions because Blackbox signs into the application as another app, not as a Microsoft user.
Select Application Permissions. This will open a menu of scopes you can select. Each scope is searchable by its name. To find the names of the scopes you need, specific go to the workflow folder in this directory and find the list of scopes in the README.md file for that workflow.
In the search box, search for the scope that you need. Then, expand the dropdown containing the scope and click the checkbox for the scope you wish to add. You can do this for as many scopes as you need, before finally hitting the Add permissions button.
By default, the
User.Read.Allscope is needed to test the connection. This scope is used because it is extremely common in Microsoft Graph workflows.
Once the permission have been requested, you will see them on the API permissions page. Permissions that require admin consent will have a warning next to them until admin consent has been provided. Contact your Azure administrator to get these approved.
Once consent has been granted, the API permission will have a message that that looks like this instead of a warning:
Creating a Client Secret
To prevent accidental loss of a client secret, you may wish to come back to this step when asked for a client secret in Microsoft Identity Platform Setup.
In order to Blackbox to connect to your Entra ID App, Blackbox needs a client secret. Go to Certificates and Secrets on the left menu in your App Page. Ensure you are on Client secrets, then select New client secret. In the new menu that opens, enter a name for your secret. Your name should be indicative of what this secret is used for. Set a lifetime for your secret. The shorter the lifetime, the more frequently you will have to update Blackbox with a new client secret. Click Add to add your new secret.
Do not leave or refresh the page after clicking Add.
When your new secret is created, you must copy it and save it somewhere secure. You will not be able to copy the secret again. As soon as you leave the page, the secret will be hidden. If you loose the secret, you will have to create a new one.
Click the copy icon next to the Value field, and save the secret somewhere secure. You will need this later.
Setting Up An Instance
Now that you have an Azure Entra ID Application created, you are ready to setup your Microsoft Graph Instance in Blackbox. Head back to Blackbox, but do not close your App Registration page, we will need information from that to complete the connector setup.
Connector Instance Creation
Now that there is a product assigned to your user, you can create a new instance for it. Go to My Connectors > Microsoft Graph and click on the New... instance button.
A popup will show that has options for creating your new instance. Input a name for your instance, select/deselect the product features as needed, and click Add.
You should have a new connector instance on the Microsoft Graph page now.
Microsoft Identity Platform Datasource Setup
Select the datasources button (the chain icon) to go to the datasources page. Once there, make sure Microsoft Identity Platform is selected. The datasource instance should be New Datasource... by default. If you wish to, change the label for your new datasource. Finally, make sure the Authentication Type is set to Microsoft Identity Platform. Leave all the other fields as is.
If you have different scopes or a different endpoint that you wish to use for testing, you can change it by modifying the
TestConnectionPathfield.
To start filling in the datasource values, open Blackbox and your Azure Entra ID App registration side by side. On Azure, select the Overview page from the left menu. On Azure, copy the field called Application (client) ID and paste it in the client_id field in Blackbox.
Then, taking the Client Secret you created in Creating a Client Secret, paste the secret into the client_secret field in Blackbox. Finally, on Azure, select the Endpoints button.
On the Endpoints screen, copy the OAuth 2.0 authorization endpoint (v2) link and paste it in the getauthorizationcodeurl field in Blackbox. Next, copy the OAuth 2.0 token endpoint and paste it in the getaccesstokenurl field in Blackbox. Close the Endpoints menu.
At the bottom of the datasource screen in Blackbox, click the Create button.
At the bottom of the datasource page, underneath the Redirect URI field, there should now be two buttons. In order to test your configuration, click Authenticate and Get Token. Assuming everything has been set up correctly, you should see a page that tells you the token has successfully been retrieved. Once you have a token, you can press the Test Connection button. When this succeeds, your Microsoft Graph instance has successfully been setup!
If Test Connection errors with an error code similar to the following:
(Forbidden) {"error":{"code":"AccessDenied","message":"Either scp or roles claim need to be present in the token.","innerError":{"date":"2024-01-12T21:28:18","request-id":"efae55ec-b77d-4194-9760-40f7e0446328","client-request-id":"efae55ec-b77d-4194-9760-40f7e0446328"}}}
it means you are either missing the correct API scopes (the default scope needed for testing is User.Read.All) or your Azure Administrator has not approved the requested scopes. Please see Configuring API Permissions for more information about setting up API scopes.