Azure Active Directory

Overview

Azure Active Directory is Microsoft’s cloud identity service. It holds the user accounts people sign in with, the devices joined or registered to the organization, and the groups that tie the two together and drive access to everything from Teams channels to licensed applications. In a Microsoft-centric enterprise it is the authoritative answer to who works here, what they can reach, and which machines are theirs.

The ReadyWorks Azure Active Directory connector reads that directory through the Microsoft Graph API. It obtains an OAuth access token from the Microsoft identity platform, then calls Graph endpoints and writes the responses into ReadyWorks staging tables. Six inbound job templates ship: users, devices, groups, the members of each group, the owners of each group, and one generic template for calling any other Graph endpoint.

Identity is usually the spine of a ReadyWorks data model. Device records from discovery tools carry a machine name and a serial number; they become actionable once resolved to a named person with a department, a manager and a location. That is what this connector supplies. Group membership matters just as much for transformation work, because groups are how access and licensing are actually assigned, so they determine what has to follow a user to a new machine or a new platform.

The connector is bidirectional. Three outbound job templates ship for group lifecycle management: create, update and delete.

NOTE: Microsoft renamed Azure Active Directory to Microsoft Entra ID. The connector, its description and its endpoints still use the Azure AD name, and the Graph API paths are unchanged, so nothing needs reconfiguring. Expect to see both names in Microsoft’s own documentation.

NOTE: All six inbound templates and all three outbound templates ship with Enabled set to No. Activate the ones you need after you create the connection.

Connector Properties

Authentication Methods

Two methods ship with this connector. Both are enabled, both are marked as default, and both use the json_rest_api.php driver. Both perform an OAuth client credentials exchange against the Microsoft identity platform and then send the returned token as a bearer token on every Graph call. The difference is what proves the application’s identity: a client secret, or a certificate.

NOTE: Both methods require an app registration in the tenant with application permissions granted for the Graph resources you intend to read, and admin consent recorded. The connection supplies the tenant id, the application id and the credential; it does not grant the permissions.

Method 1: MS Graph Authentication (AZURE_AD_ms_graph)

Connect to an Azure Active Directory using MS Graph API

Client secret authentication. ReadyWorks posts the application id, the client secret and a scope of .default to the tenant’s token endpoint, reads the access token out of the response, and sends it as Authorization: Bearer on every Graph call.

Connection Configuration Fields (9)

NOTE: The OAuth POST Request Full URI default contains the token %auth_value_1%, which resolves to the Tenant Id entered above. Leave it in place rather than typing the tenant id into the URL, so the two cannot drift apart.

Authentication Configuration

Headers sent on the authentication call:

Headers sent on the data calls:

Authentication request body:

cURL options:

Method 2: MS Graph Certificate Based Authentication (AZURE_AD_f56cc6b7d2)

Connect to an Azure Active Directory using MS Graph API with Certificate

Certificate authentication. Instead of a client secret, the connection stores a public certificate and its private key, both masked. This method carries an authentication flag, MS_GRAPH_JWT, which tells the engine to build and sign a JWT client assertion rather than sending a secret. Only two methods in the whole connector library carry any authentication flag: this one and Microsoft Intune’s certificate-based method, which uses the same flag. Use it where policy forbids long-lived client secrets, or where the app registration is already set up for certificate credentials.

Connection Configuration Fields (10)

NOTE: Server Temporary Working Path and API Domain both carry display order 10 in this method, so their position relative to each other in the connection form is not guaranteed. Both fields work; only their order is affected. The same collision appears on several other connectors, including Microsoft Intune, Everpure, Hitachi Vantara, Intel Redfish, Qumulo, Scality and Veeam.

Authentication Configuration

Headers are identical to Method 1: Content-Type: application/x-www-form-urlencoded on the authentication call, then Content-Type: application/json and Authorization: Bearer %auth_data% on the data calls. The cURL options are also identical. Only the request body differs.

Authentication request body:

NOTE: The certificate and key are not posted to Microsoft as they appear above. The MS_GRAPH_JWT flag intercepts them and uses them to sign a client assertion, which is what actually reaches the token endpoint.

Inbound Job Fields Enabled (44)

These are the settings the job editor shows when you create or edit an inbound job on an Azure Active Directory connection. It is the full REST form, including three levels of enumeration.

Inbound Job Templates (6)

Five templates call named Graph endpoints; the sixth is a blank starting point for any other endpoint. All five named templates read the value node and page through results using Graph’s @odata.nextLink.

Job Template Configuration

Settings Common to All Six Templates

Settings That Vary by Template

NOTE: Data Identity matches Destination Table on all six templates.

Enumeration Settings

Group Members and Group Owners both enumerate. Each first calls the enumeration endpoint to collect every group id, then calls its own endpoint once per group, substituting the id into %enum_id%.

NOTE: An enumeration field named enum_id_1 can be referenced either as %enum_id_1% or as %enum_id%. These two templates use the shorter form. Both resolve to the same value.

NOTE: These two jobs make one API call per group in the tenant. On a large tenant that is a lot of calls, and because Single Authentication defaults to No the connection re-authenticates on each loop. If either job runs long or hits Graph throttling, set Single Authentication to Yes on the connection, and consider setting Maximum API Calls and Pause Enumeration on the job.

API Data Parameters

Three templates restrict the properties Graph returns.

NOTE: The Users $select list does not include accountEnabled, so the staged user table carries no indication of whether an account is active or disabled. If you need to tell leavers from current staff, which most joiner, mover and leaver work and most migration wave planning does, add accountEnabled to the parameter before enabling the job.

Outbound Job Fields Enabled (13)

Outbound Job Templates (3)

Three templates cover the group lifecycle. Together they let a ReadyWorks process create a group for a migration wave, add or rename it as the wave changes, and remove it when the wave closes.

All three ship with Enabled set to No, Log Raw API Calls No, Body Data Sending Method and Data Sending Method both JSON Encoded Data, and Ignore Empty Outbound Fields Yes. Their orders are 10, 20 and 30.

Create Group (Template 8)

Posts a new group to Graph. Four fields are required, matching what Graph itself demands to create a group: a display name, a mail nickname, and the two flags that decide what kind of group it is. Returns the new group id, which a later Update or Delete job needs.

Return data field: Group Id from id.

NOTE: Owner Id is the one field with a pattern. ReadyWorks wraps the value you supply into the full Graph user URL shown above, so pass a bare user object id rather than a URL.

Delete Group (Template 9)

Removes a group. It takes only the group id, marked as a URI field so it substitutes into %group_id% in the endpoint path rather than being sent in the body.

Return data field: Group Id from group_id.

NOTE: Deleting a group in Entra ID is not reversible from ReadyWorks. Microsoft retains deleted Microsoft 365 groups for a recovery period, but security groups behave differently. Confirm the group type before enabling a job built on this template.

Update Group (Template 10)

Patches an existing group. Group Id is required and travels in the URI; everything else is optional, and because Ignore Empty Outbound Fields is Yes, only the fields you populate are sent. That makes it safe to use the same job to change one property without overwriting the others.

Return data field: Group Id from id.