HelloID-Conn-Prov-Target-Azure-Guest-Account

ℹ️ Information
This repository contains the connector and configuration code only. The implementer is responsible to acquire the connection details such as username, password, certificate, etc. You might even need to sign a contract or agreement with the supplier before implementing this connector. Please contact the client's application manager to coordinate the connector requirements.

Versioning

Version	Description	Date
1.1.0	Updated with new logging and checks for existing accounts and missing aRef or account mapping	2023/02/02
1.0.0	Initial release	2020/07/17

Table of Contents

• HelloID-Conn-Prov-Target-Azure-Guest-Account
  • Versioning
  • Table of Contents
  • Introduction
  • Getting the Azure AD graph API access
    • Application Registration
    • Configuring App Permissions
    • Authentication and Authorization
    • Connection settings
  • Getting help
  • HelloID Docs

Introduction

The interface to communicate with Microsoft Azure AD is through the Microsoft Graph API. GetConnectors are based on a pre-defined 'data collection', which is an existing view based on the data inside the Profit database.

• For this connector we can create the Azure AD Guest accounts by sending an invitation, this way they can log on with their invited email address.

  If you want to create Azure AD Guest accounts directly (with a logon name of the tenant domain itself), please use the built-in Microsoft Azure Active Directory target system. By specifying the userType 'Guest' in the mapping you can create Guest accounts with a logon name of the tenant domain.

• If you want to create regular Azure AD accounts, please use the built-in Microsoft Azure Active Directory target system.

• We can also correlate to an existing Azure AD account and manage this account (enable,disable,update and delete).
• Additionally we have the option to provision groupmemberships.

  Currently only Microsoft 365 and Security groups are supported by the Microsoft Graph API

Getting the Azure AD graph API access

Application Registration

The first step to connect to Graph API and make requests, is to register a new Azure Active Directory Application. The application is used to connect to the API and to manage permissions.

• Navigate to App Registrations in Azure, and select “New Registration” (Azure Portal > Azure Active Directory > App Registration > New Application Registration).
• Next, give the application a name. In this example we are using “HelloID PowerShell” as application name.
• Specify who can use this application (Accounts in this organizational directory only).
• Specify the Redirect URI. You can enter any url as a redirect URI value. In this example we used http://localhost because it doesn't have to resolve.
• Click the “Register” button to finally create your new application.

Some key items regarding the application are the Application ID (which is the Client ID), the Directory ID (which is the Tenant ID) and Client Secret.

Configuring App Permissions

The Microsoft Graph documentation provides details on which permission are required for each permission type.

To assign your application the right permissions, navigate to Azure Portal > Azure Active Directory >App Registrations. Select the application we created before, and select “API Permissions” or “View API Permissions”. To assign a new permission to your application, click the “Add a permission” button. From the “Request API Permissions” screen click “Microsoft Graph”. For this connector the following permissions are used as Application permissions:

• Read and Write all user’s full profiles by using User.ReadWrite.All
• Read and Write all groups in an organization’s directory by using Group.ReadWrite.All
• Read and Write data to an organization’s directory by using Directory.ReadWrite.All
• Invite Guests by using User.Invite.All

Some high-privilege permissions can be set to admin-restricted and require an administrators consent to be granted.

To grant admin consent to our application press the “Grant admin consent for TENANT” button.

Authentication and Authorization

There are multiple ways to authenticate to the Graph API with each has its own pros and cons, in this example we are using the Authorization Code grant type.

• First we need to get the Client ID, go to the Azure Portal > Azure Active Directory > App Registrations.
• Select your application and copy the Application (client) ID value.
• After we have the Client ID we also have to create a Client Secret.
• From the Azure Portal, go to Azure Active Directory > App Registrations.
• Select the application we have created before, and select "Certificates and Secrets".
• Under “Client Secrets” click on the “New Client Secret” button to create a new secret.
• Provide a logical name for your secret in the Description field, and select the expiration date for your secret.
• It's IMPORTANT to copy the newly generated client secret, because you cannot see the value anymore after you close the page.
• At last we need to get the Tenant ID. This can be found in the Azure Portal by going to Azure Active Directory > Overview.

Connection settings

The following settings are required to connect to the API.

Setting	Description
Azure AD Tenant ID	Id of the Azure tenant
Azure AD App ID	Id of the Azure app
Azure AD App Secret	Secret of the Azure app

Getting help

For more information on how to configure a HelloID PowerShell connector, please refer to our documentation pages

If you need help, feel free to ask questions on our forum

• For any remarks about this connector, please use the Connector specific forum post

HelloID Docs

The official HelloID documentation can be found at: https://docs.helloid.com/