Azure AD Plugin for User Risk Exchange

This document explains how to configure the Azure AD plugin with the User Risk Exchange module in the Netskope Cloud Exchange platform. The Microsoft Azure AD plugin fetches Risky users and their respective scores from Microsoft Azure AD. It also supports add to group, remove from group, and confirm compromised actions on users. The users are pulled from Home > Risky Users in the Microsoft Azure AD platform.

Prerequisites

To complete this configuration, you need:

CE Version Compatibility

Netskope CE v4.2.0, v5.0.0

Azure AD Plugin Support

The Microsoft Azure AD URE plugin fetches users and their respective score. This plugin also performs actions.

Type of data pulled	Users
Types of Action Supported	Add to Group, Remove from Group, Confirm Compromise, No actions

Mappings

Fields Pulled

Microsoft Azure AD Fields	Netskope CE Fields
userPrincipalName	email
riskLevel	score

Score Mappings

Default Netskope Score	Default Netskope Score Range
Critical	0-250
High	251-500
Medium	501-750
Low	751-1000

Microsoft Azure AD Scores	Netskope CE URE Scores
none hidden unknownFutureValue	None
low	875
medium	625
high	375

Permissions

Refer to Get your Azure AD Credentials for details about obtaining and providing necessary permissions.

API Details

List of APIs Used

API Endpoint	Method	Use Case
<tenant_id>/oauth2/token	GET	Get OAuth2 token
/identityProtection/riskyUsers	GET	Fetch Users and Scores
/groups	GET	Get all groups
/groups	POST	Create a new group
/groups/{group-id}/members/$ref	POST	Add member to group
/groups/{group-id}/members/{member-id}/$ref	DELETE	Remove member from group
/identityProtection/riskyUsers/confirmCompromised	POST	Confirm a user as compromised
/users/{user-mail}	GET	Get user by email

Get Auth Token

API Endpoint: <Base URL>/<tenant_id>/oauth2/token
Method: GET
Body:

{
     grant_type": "client_credentials",
     client_id": client_id,
     client_secret": client_secret,
     resource": "https://graph.microsoft.com"
}

Sample API Response:

{
    "token_type": "Bearer",
    "expires_in": "3599",
    "ext_expires_in": "3599",
    "expires_on": "1666161987",
    "not_before": "1666158087",
    "resource": "https://graph.microsoft.com",
    "access_token": "eyJ0eXAiOiJKV1Q...."
}

Fetch Users and Scores

API Endpoint: <Base URL>/identityProtection/riskyUsers
Method: GET
Headers:

Key	Value
Content-Type	application/json
Accept	*/*
Authorization	Bearer <auth_token>

Sample API Response:

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#identityProtection/riskyUsers",
    "@odata.nextLink": "https://graph.microsoft.com/v1.0/identityProtection/riskyUsers?$top=1&$skiptoken=*****cbe5460********************4f1442c63a7b211674hdb2850a4421048fc_1",
    "@microsoft.graph.tips": "Use $select to choose only the properties your app needs, as this can lead to performance improvements. For example: GET identityProtection/riskyUsers?$select=isDeleted,isProcessing",
    "value": [
        {
            "id": "f8c8dcb2-21b7-4e20-985c-52**603300d",
            "isDeleted": false,
            "isProcessing": false,
            "riskLevel": "high",
            "riskState": "confirmedCompromised",
            "riskDetail": "adminConfirmedUserCompromised",
            "riskLastUpdatedDateTime": "2024-03-14T09:59:29.085289Z",
            "userDisplayName": "User",
            "userPrincipalName": "user@onmicrosoft.com"
        }
    ]
}

Get All Groups

API Endpoint: <Base URL>/groups
Method: GET
Headers:

Key	Value
Content-Type	application/json
Accept	*/*
Authorization	Bearer <auth_token>

Parameters:

Key	Value
$filter	not groupTypes/any(s:s eq ‘DynamicMembership’)
$top	999
$orderby	displayName
$select	id,displayName,groupTypes
$count	true

Sample API Response:

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#groups(id,displayName,groupTypes)",
    "@odata.nextLink": "https://graph.microsoft.com/v1.0/groups?$filter=groupTypes%2fany(s%3as+eq+%27DynamicMembership%27)&$top=1&$select=id%2cdisplayName%2cgroupTypes&$count=true&$skiptoken=RFNwdAoAAQAAAA",
    "value": [
        {
            "id": "826e5e6c-f533-4a93-8420-fc9592ae3ca0",
            "displayName": "TestDynamic",
            "groupTypes": [
                "DynamicMembership"
            ]
        }
    ]
}

Create a New Group

API Endpoint: <Base URL>/groups
Method: POST
Headers:

Key	Value
Content-Type	application/json
Accept	*/*
Authorization	Bearer <auth_token>

Body:

{
    "description": "Created group from Netskope Cloud Exchange via Microsoft Azure AD User Risk Exchange plugin.",
    "displayName": "Group Name",
    "mailEnabled": true,
    "mailNickname": "groupname",
    "securityEnabled": false,
    "groupTypes": [
        "Unified"
    ]
}

Sample API Response:

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#groups/$entity",
    "id": "6999bb7****************05b4e04155",
    "deletedDateTime": null,
    "classification": null,
    "createdDateTime": "2024-03-16T11:01:45Z",
    "creationOptions": [],
    "description": "Created group from Netskope Cloud Exchange via Microsoft Azure AD User Risk Exchange plugin.",
    "displayName": "Group Name",
    "expirationDateTime": null,
    "groupTypes": [
        "Unified"
    ],
    "isAssignableToRole": null,
    "mail": "groupname@netskopebd.onmicrosoft.com",
    "mailEnabled": true,
    "mailNickname": "groupname",
    "membershipRule": null,
    "membershipRuleProcessingState": null,
    "onPremisesDomainName": null,
    "onPremisesLastSyncDateTime": null,
    "onPremisesNetBiosName": null,
    "onPremisesSamAccountName": null,
    "onPremisesSecurityIdentifier": null,
    "onPremisesSyncEnabled": null,
    "preferredDataLocation": null,
    "preferredLanguage": null,
    "proxyAddresses": [
        "SMTP:groupname@netskopebd.onmicrosoft.com"
    ],
    "renewedDateTime": "2024-03-16T11:01:45Z",
    "resourceBehaviorOptions": [],
    "resourceProvisioningOptions": [],
    "securityEnabled": false,
    "securityIdentifier": "S-1-12-1-1771682685-1286044974-90333062-1430380724",
    "theme": null,
    "uniqueName": null,
    "visibility": "Public",
    "onPremisesProvisioningErrors": [],
    "serviceProvisioningErrors": []
}

Add a Member to a Group

API Endpoint: <Base URL>/groups/{group-id}/members/$ref
Method: POST
Headers:

Key	Value
Content-Type	application/json
Accept	*/*
Authorization	Bearer <auth_token>

Body:

{
    "@odata.id": "https://graph.microsoft.com/v1.0/directoryObjects/{id}"
}

Sample API Response: (Status Code 204)

{}

Remove a Member from a Group

API Endpoint: <Base URL>/groups/{group-id}/members/{member-id}/$ref
Method: DELETE
Headers:

Key	Value
Content-Type	application/json
Accept	*/*
Authorization	Bearer <auth_token>

Sample API Response: (Status Code 204)

{}

Confirm a User as Compromised

API endpoint: <Base URL>/identityProtection/riskyUsers/confirmCompromised
Method: POST
Headers:

Key	Value
Content-Type	application/json
Accept	*/*
Authorization	Bearer <auth_token>

Body:

{
    "userIds": [
        "targeted-userId-1"
    ]
}

Sample API Response: (Status Code 204)

{}

Fetch Users and Scores

API endpoint: <Base URL>/users/{user-mail}
Method: GET
Headers:

Key	Value
Content-Type	application/json
Accept	*/*
Authorization	Bearer <auth_token>

Sample API Response:

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users/$entity",
    "@microsoft.graph.tips": "This request only returns a subset of the resource's properties. Your app will need to use $select to return non-default properties. To find out what other properties are available for this resource see https://learn.microsoft.com/graph/api/resources/user",
    "businessPhones": [],
    "displayName": "Crest",
    "givenName": null,
    "jobTitle": null,
    "mail": "user@netskopebd.onmicrosoft.com",
    "mobilePhone": null,
    "officeLocation": null,
    "preferredLanguage": "en-US",
    "surname": null,
    "userPrincipalName": "user@netskopebd.onmicrosoft.com",
    "id": "e0ae0b3b-**********7-cb84372efc52"
}

Performance Matrix

The performance readings are conducted on a Large CE Stack with these VM specifications by pulling 500K Users and their respective risk scores in a plugin cycle.

Stack details	Size: Large RAM: 32 GB CPU: 16 Cores
User Risk scores fetched from Microsoft Azure AD	500K
Time Taken	~120 mins

User Agent

netskope-ce-5.0.0-ure-microsoft-azure-ad-v1.2.1

Workflow

Click play to watch a video.

Configure Actions for the Azure AD Plugin

 

The Microsoft Azure AD plugin supports:

• Add to Group action will add a user to a selected group.
• Remove from Group action will remove a user from a selected group.
• Confirm Compromised action will confirm that the user that is added to risky used is actually a risky user and change the Risk State of that user to “Confirm Compromised”.
• No Action will not perform any action on users.

To configure these actions, follow the below steps.

Add to Group

1. Go to Actions in User Risk Exchange and click Add Action Configuration.
2. Select a Business rule, a Configuration, and select the name of your configured plugin.
3. On the Actions dropdown, select Add to Group.
4. On the Group dropdown, select Create new group and enter a Group Name to create a new group in Microsoft Azure AD.
5. Click Save.
   
6. Click Sync to perform the action manually. Enter the days, and click Fetch to see the number of users that will be affected by this action. Click Sync to perform actions.

Remove from Group

1. Go to Actions in User Risk Exchange and click Add Action Configuration.
2. Select a Business Rule, a Configuration, and select the name of your configured plugin.
3. On the Actions dropdown, select Remove from Group.
4. On the Group dropdown, select the group to remove.
   
5. Click Save and then Sync. Enter the days, and click Fetch to see the number of users that will be affected by this action. Click Sync to perform actions.

Confirm Compromised

1. Go to Actions in User Risk Exchange and click Add Action Configuration.
2. Select a Business Rule, a Configuration, and select the name of your configured plugin.
3. On the Actions dropdown, select Confirm Compromised.
4. Click Save and then Sync. Enter the days, and click Fetch to see the number of users that will be affected by this action. Click Sync to perform actions.

No Action

1. Go to Actions in User Risk Exchange and click Add Action Configuration.
2. Select a Business Rule, a Configuration, and select the name of your configured plugin.
3. On the Actions dropdown, select No Action, and then enable Generate Alerts toggle.
4. Click Save and then Sync. Enter the days, and click Fetch to see the number of users that will be affected by this action. Click Sync to perform actions.
   

Validate the Azure AD Plugin

Validate the Pull

In the Microsoft Azure AD platform, the users are shown at Home > Risky Users.

In User Risk Exchange, go to Users and check the users pulled from the Microsoft Azure AD plugin.
Also, you can go to Logging and search the logs for pulling users from the Microsoft Azure AD platform.

Use a filter like this.

Validate the Action

To validate the actions performed in Cloud Exchange, go to Logging and search for logs related to Microsoft Azure AD plugin.




In Microsoft Azure AD, look for the Add to group and Remove from group action. 

1. Go to Home > Azure Active Directory. Click Groups on the left-hand panel.
2. Search and select the name of your group. For example, Netskope in this case. Click Members on the left-hand panel.
   
   
3. Verify the members in the group according to the action you performed.

Confirm Compromised Action

1. Log in to Microsoft Azure platform and search for Microsoft Azure AD Risky Users.
2.  You’ll see Risk State. Initially when a user is added to Risky Users, then its risk state is At Risk, and after the action is performed, then its risk state should be changed to confirm compromised, as shown here.
   

    

   Note: It might take a few minutes after the action “Confirm Compromised” is performed for the status of a user to change on the Azure platform.

Troubleshooting

Group ID is displayed instead of Group name in action configuration post plugin update

After upgrading the Plugin from v1.1.2 to the latest version, the user will get the Group ID displayed in the Action instead of Group Display Name:

267******************-878e6f460a1c

What to do: Edit the Action and select the Group according to the previously saved group.

Group ID and name is displayed in the action if the group is deleted from platform

If the group or group name is Updated/Deleted from the Microsoft Azure AD, then the Group name will be displayed as below in the action configuration and the user will receive an error while trying to perform the action Add to Group or Remove from Group:

{"id": "26739fd0-bba6-4eb7-b761-878e6f460a1c", "displayName": "Netskope CE Azure AD Demo", "display_name": "Netskope CE Azure AD Demo (Security)", "group_type": "Security"}

What to do: Check if the group exists else create the group with the same name on the Azure platform, or use a different group in the action configuration.

Receiving warning log: Unable to add/remove user in/from a group

When an action, Add to Group, is performed on a user whose already present in a group, below warning log will be received. The same behavior will be noticed when an action Remove from group is performed on a user who is not present in the group.

URE Microsoft Azure AD [Microsoft Azure AD]: Unable to add user with email 'crest@netskopebd.onmicrosoft.com' to group named 'Netskope' and ID '5bbe2369-24b4-44a2-b37c-778b9a77f7a3'. This error may occur if user already exist in group. Error: {'code': 'Request_BadRequest', 'message': "One or more added object references already exist for the following modified properties: 'members'.", 'innerError': {'date': '2024-03-18T06:31:08', 'request-id': '33b52b75-ffee-4ff5-95d2-6250205947ee', 'client-request-id': '33b52b75-ffee-4ff5-95d2-6250205947ee'}}

What to do: Check if the user is already present in the group or not. If the user is already present, this log will be received.