# Configuring Microsoft Entra ID SaaS for Integration This section describes the various configurations to be performed to support the following features: ## Microsoft Graph API Microsoft recommends the use of Microsoft Graph API instead of the Azure Active Directory Graph API. Microsoft has stopped addition of new feature in the Azure Active Directory API. The Microsoft Entra ID SaaS connector has been enhanced to use the Microsoft Graph API completely. - To enable using the latest attributes and features supported by Microsoft Graph API, set the value of `useMSGraphAPI` attribute to `true`. - The default Microsoft Graph API version is "v1.0". To use another version, specify the version in the in `msgraph-api-version` attribute in the connector configuration. For example, you can set the API version by adding `msgraph-api-version` with a value of `"v1.0"`. For more information, refer to Additional Configuration Parameters. ## Generating a Refresh Token Perform the following steps to generate the Refresh Token: 1. Obtain the authorization code using the following request. This process involves user consent. ```text client_id= &response_type=code &redirect_uri= &response_mode=query &scope=offline_access%20https://graph.microsoft.com/.default &state= ``` Parameters details: | Parameter | Description | | --- | --- | | client\_id | Client ID of the registered application. | | response\_type | For authorization code the value must be code. | | redirect\_uri | This should be redirect uri configured while registering the application. This should be pointed to localhost and any unused port. | | response\_mode | To get the code to in string parameter on your redirect URI, it should be query. | | scope | Here multiple scopes can be added for defining the required API. | The default added scope is [https://graph.microsoft.com/.default](). The refreshToken parameter is also required for configuration. The **offline\_access** scope must be added. | Parameter | Description | | --- | --- | | state | This can be any random number. Same value will be returned along with authorization code. | The Response in browser address bar would be displayed as follows: `https://localhost:44320/?code=OAQABAAIAAAAm-06blBE1TpVMil8KPQ41U9-...&state=1234566&session_state=9557b1f1-0fd8-4e12-a39f-213cfcd12153` Copy the code present between **code=** and &state. > **Note** > > The received Authorization Code can be used only once and is valid for a short duration. 2. Obtain the Refresh Token as follows using the Auth Code obtained in the above step: The Auth Code received from the previous steps must be passed in the following request along with other parameters in following request: ```text POST https://login.microsoftonline.com/{{Your Domain name}}/oauth2/v2.0/token Content-Type: application/x-www-form-urlencoded client_id= &scope=offline_access%20https://graph.microsoft.com/.default &code=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq3n8b2JRLk4OxVXr... &redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F &grant_type=authorization_code &client_secret=JqQX2PNo9bpM0uEihUPzyrh ``` Following are the newly added parameters: | Parameter | Description | | --- | --- | | code | Authorization code obtained in previous steps. | | grant\_type | As you intend to redeem the Auth Code it should be **authorization\_code**. | | client\_secret | Client Secret of the registered application. | **Response**: ```text { "token_type": "Bearer", "scope": "https://graph.windows.net/Directory.Read.All https://graph.windows.net/User.Read https://graph.windows.net/.default", "expires_in": 7199, "ext_expires_in": 7199, "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6IlNzWnNCT mhaY0YzUTlTNHRycFFCVEJ5TlJSSSIsImtpZCI6IlNzWnNCTmhaY0YzUTlTNHRycFFCVEJ5TlJSSSJ9 .eyJhdWQiOiJodHRwczovL2dyYXBoLndpbmRvd3MubmV0Iiwia...", "refresh_token": "OAQABAAAAAAAm-06blBE1TpVMil8KPQ410LOG6EPVxGfgH8rHUXApUs5fPFtel9FsKTXo2oN8Rw _ngEOpKNt1hfufYyJJnG39XxfscpcW...." } ``` Copy the **Refresh Token** received in the response. ## Service Plan Management (managing Licenses) The Microsoft Entra ID SaaS connector supports assigning different Azure services licenses to the users. The connector uses individual plan to assign licenses. > [!NOTE] > > To provision the licenses or plans to user, set the user’s `usageLocation` property correctly. - **Assigning license plan**: Office 365 license pack consist of licenses for individual services. For example, Exchange Online or SharePoint Online. - The connector models the `assignedPlans` attribute from account schema as an entitlement. It can be requested as an entitlement during Create or Update operations for Identities. > **Important** > > - If you use group-based licensing, licenses are assigned or removed based on group membership. To avoid concurrency errors, do not mark the `assignedPlans` attribute in the account schema as an entitlement. > - When `assignedPlans` are managed by a group, do not use `assignedPlans` as entitlements in the account schema. Service Plan now has separate group schema attributes. For a detailed list of the attributes, refer to [Service Plan](). The following operations are supported for the Service Plan object type: - Aggregation - View details of Service Plan (like object properties, members, and so on) - Assign and Revoke access request for Service Plan (entitlement attribute: `assignedPlans`) ## Support for Provisioning Operations of `manager` Attribute The Microsoft Entra ID SaaS connector supports the `manager` attribute for the following: - **Account Aggregation** (Full and Delta): On Account Aggregation, the `manager` attribute for a user populates for a non-null (blank) value on the Microsoft Entra managed system. Add the `manager` attribute in the account schema with the string type. For more information on adding attributes to the account schema, refer to [Editing an Account Schema](). - **Provisioning**: The `manager` attribute is supported for the Add, Remove, and Set operations where the value of the manager can be set as either `objectId` or the `userPrincipalName`. Add the `manager` attribute in the Provisioning policy. The blank value in the **Set** operation is applicable to remove the `manager` value at the Microsoft Entra managed system. ## Azure Resource Filtering: Subscriptions and Management Groups The Microsoft Entra ID SaaS connector supports filtering Azure resource providing granular control over the scope of account and entitlement aggregation through Azure subscriptions and management groups. This improves performance, increases data relevance, and reduces data collection time. It also improves focus on relevant subscriptions and management groups by limiting irrelevant data. ### Impact on Aggregation - **Account Aggregation**: Filters User/Service Principal role assignments and group memberships within specific Azure subscriptions and management groups. - **Entitlement Aggregation**: Filters subscriptions, management groups, & resource groups. After these are identified, the connector filters Azure role assignments, eligible roles, and active roles based on selected subscriptions and management groups. ### Azure Resource Configuration for Filtering Add the following attributes using the SailPoint REST APIs: - `subscriptionFilter`: Provides an array of Azure Subscription IDs. - `managementGroupsFilter`: Provides an array of Azure Management Group IDs. For example, Use the SailPoint API by sending a PATCH request to the `/v3/sources/{source_id}` endpoint. `PATCH https://{orgName}.api.identitynow.com/v3/sources/:source_id` In the PATCH payload, add the attributes as shown below: ```text [{ "op": "add", "path": "/connectorAttributes/subscriptionFilter", "value": ["/subscriptions/", "/subscriptions/"] }, { "op": "add", "path": "/connectorAttributes/managementGroupsFilter", "value": ["/providers/Microsoft.Management/managementGroups/", "/providers/Microsoft.Management/managementGroups/"] }] ``` > [!NOTE] > > For more information on SailPoint's REST APIs, refer to [Best Practices: REST API Authentication]() and [REST API - Update Source (Partial)]() in the SailPoint Developer Community. #### Steps for Obtaining Azure Subscription IDs. 1. Sign in to Azure Portal. 2. Go to **Subscriptions**. 3. Select **Download** or **Export to CSV** (usually available in the top menu). This will give you a CSV file with Subscription ID. > **Note** > > When specifying a subscription in Azure resource paths, ensure the prefix `/subscriptions/` is included before the subscription ID. > > For example, > > Subscription ID only: `abcd-efgh-1234-5678-ijkl` > > Full subscription path: `/subscriptions/abcd-efgh-1234-5678-ijkl` #### Steps for Obtaining Azure Management Group IDs. 1. Sign in to Azure Portal. 2. Search for Management Groups in the top search bar. 3. Select on **Management Groups** to view the hierarchy. 4. Select **Download** or **Export to CSV** (usually available in the top menu). This will give you a CSV file with Management Group ID. > **Note** > > When specifying a management groups in Azure resource paths, ensure the prefix `/providers/Microsoft.Management/managementGroups/` is included before the Management Group ID. > > For example, `/providers/Microsoft.Management/managementGroups/Your_Management_Group_Name` ## Sponsors for Guest User (B2B) and External Member (B2B) The sponsor feature helps manage B2B users in your directory by tracking who is responsible for each guest user. While entitlement management can monitor guests from certain domains, it does not cover guests outside of these specific areas. With the sponsor feature, you can assign a person or group to every guest user, which helps track who invited them and promotes accountability. The Sponsors field on the user object identifies the person or group tasked with managing and overseeing the user's lifecycle, ensuring they have the correct access to resources. Being a sponsor does not confer administrative powers to the sponsor user or group. However, it can be utilized for approval processes in entitlement management and for custom solutions, but it provides no other built-in directory powers. ### Supported Features Aggregation and provisioning of `sponsors` for Guest User (B2B) and External Member (B2B). ### Adding Sponsors to the Source To use this feature, you must manually add the sponsor attributes to the Account Schema for the Microsoft Entra source. | Attribute | Type | Read/Write | Description | | --- | --- | --- | --- | | sponsors | String (multi-valued) | Read-only | Returns each sponsor as a JSON object containing `displayName` and `id`. Useful for display purposes. | | sponsors.users | String (multi-valued) | Read + Write | Returns and accepts the UPN of each user-type sponsor. For example, `someone@example.com`. | | sponsors.groups | String (multi-valued) | Read + Write | Returns and accepts the Object ID of each group-type sponsor. | > [!NOTE] > > To provision sponsors, use `sponsors.users` for user-type sponsors and `sponsors.groups` for group-type sponsors. The `sponsors` attribute is read-only and cannot be used for provisioning. For more information, refer to [Editing an Account Schema](). ### Provisioning When provisioning a Microsoft Entra user as a sponsor, add the `sponsors.users` attribute to the Account Schema and provide the user's User Principal Name (UPN). For example, `someone@example.com`. When provisioning a Microsoft Entra group as a sponsor, add the `sponsors.groups` attribute to the Account Schema and provide the group's Object ID. Both attributes support Add, Remove, and Set operations. A Set operation on `sponsors.users` replaces only the user-type sponsors, leaving any group sponsors intact, and vice versa for `sponsors.groups`.