×
Microsoft Azure AD

Overview

The Azure AD Plugin provides the functionality to manage users, manage groups, and search for sign-in information.

To allow for the necessary functionality, an OAuth2 authorization must be created with the appropriate API permissions.

Functionality

The Security Flow Azure AD Plugin exposes the ability to:

  • view and manage groups
  • view and manage users
  • search and view sign-in information

Instance Configuration Parameters

Property
Description
Instance Name

Name for the Azure AD instance.

Unique ID

A system-wide unique identifier for this plugin instance used to locate the service.

Authorization (OAuth2)

Drop down list of available OAuth2 authorization tokens to used to access Azure AD.

To allow for the necessary functionality, an OAuth2 authorization must be created with the appropriate API permissions. The Actions in the nodes below describe the permissions necessary.

Flow Node

This node provides Azure AD capabilities for managing groups. Specifically, this node allows users to be added or removed from a group as either a member or owner of that group.

If there are errors indicating the Azure AD API requests could not be performed, the messages are filtered out of the flow and the Incident timeline is updated with the errors. However, if the Azure AD API requests could be performed but there are error responses, the message is sent out of the error pathway.

The following permissions are needed for performing read-only actions:

  • Group.Read.All - Provides access to reading group information.
  • User.ReadBasic.All - Provides access to reading a user's ID.
      • The following permissions are needed for performing update actions:
      • Group.ReadWrite.All - Provides access to updating all groups.
      • User.ReadBasic.All - Provides access to reading a user's ID.

Property
Description
Name

The display name of the node within the flows.

Unique ID

System-wide unique ID of the plugin instance.

Group Name

The display name of the Azure AD group to be updated.

Action

Configuration option determining the type of operation to perform:

  • Add User to Group: Adds a user to the group
  • Remove User from Group: Removes a user from the group
  • Get Group Members: Retrieves the group members
  • Get Group Owners: Retrieves the group owners
User

The User Principal Name or the Object ID of the Azure AD user to be affected.
The following contexts are supported:

  • msg: This selects part of the incoming message as the source of the data. This is the typical choice.
  • flow: This selects part of the flow context’s saved data as the source. This information is shared with only the nodes on a given tab.
  • global: This selects part of the global context’s saved data as the source. This information is shared by all nodes regardless of tab.
  • J: expression: JSONata expression language to perform query and transform operations on the payload.
Membership Type

This section configures the group operations based on the selected Action. There are two possibilities for each Action as shown in the list below.

  • Add User to Group

    1. Add as Member
    2. Add as Owner
  • Remove User from Group

    1. Remove as Member
    2. Remove as Owner

This node provides Azure AD capabilities for retrieving information about a user or managing attributes associated with a user.

If there are errors indicating the Azure AD API requests could not be performed, the messages are filtered out of the flow and the Incident timeline is updated with the errors. However, if the Azure AD API requests could be performed but there are error responses, the message is sent out of the error pathway.

The following permissions are needed for performing read-only actions:

  • User.Read.All - Provides access to reading a user's information.
  • Directory.Read.All - Provides access to reading any data in the directory.
One of the following permissions are required to perform the user updates, the directory permission, Directory.ReadWrite.All, enables much more access.
  • User.ReadWrite.All - Provides access to managing a user's information. This permission is required to delete a user.
  • Directory.ReadWrite.All - Provides access to managing any data in the directory.

Property
Description
Name

The display name of the node within the flows.

Unique ID

System-wide unique ID of the plugin instance.

Action

Configuration option determining the type of operation to perform:

  • Get User: Retrieves the selected properties associated with the supplied User (UPN).
  • Update User: Updates properties of an existing user identified by the User (UPN).
  • Create User: Creates a new user using the User (UPN) field as the User Principal Name.
  • Delete User: Deletes the user associated with the User (UPN). User.ReadWrite.All permission is required to perform this operation.
  • Member Of: Retrieves the list of groups the User (UPN) is a direct member of.
  • List Licenses: Lists licenses associated with a User (UPN).
  • Assign Licenses: Changes the licenses assigned to a User (UPN).
  • Revoke Sign-in Sessions: Revokes all the application refresh tokens and browser session cookies associated with a User (UPN).
User (UPN)

The User Principal Name, i.e. their email address, of the user. For existing users, the user may be specified using their user ID, a GUID.

Settings

This section configures settings for a newly created user when the Action is Create User.

  • Account Enabled: The account is enabled.
  • Force Password Change on Sign In: The user must change their password on first sign-in.
  • Require MFA on Sign In: Require multi-factor authentication during sign-ins.
Password

When the Action is Create User, this field defines the initial user password.

Mail Alias

When the Action is Create User, this field defines the user’s mail alias.

Display Name

When the Action is Create User, this field defines the user’s display name.

Properties or Additional Properties

Depending on the action selected the properties represent retrieved values to retrieve (Get User), values to update (Update User), or values to create (Create User).

The Property field is seeded with a default set of standard field names. Typing or clicking twice will show the standard field names. Other fields unique to your installation can be specified manually.

Property evaluation is done based on the Data Type and Value.

Add Licenses

When the Action is Assign Licenses, this field defines the licenses to add to the user.

The License Name field is seeded with Product Name & String ID information from Microsoft. The list was last seeded on 2020/02/19. Typing or clicking twice will show the matching license name and is simply used to populate the License ID.

Remove Licenses

When the Action is Assign Licenses, this field defines the licenses to remove from the user.

The License Name field is seeded with Product Name & String ID information from Microsoft. The list was last seeded on 2020/02/19. Typing or clicking twice will show the matching license name and is simply used to populate the License ID.

This node provides Azure AD capabilities for retrieving Identity and Access information.

If there are errors indicating the Azure AD API requests could not be performed, the messages are filtered out of the flow and the Incident timeline is updated with the errors. However, if the Azure AD API requests could be performed but there are error responses, the message is sent out of the error pathway.

The following permissions are needed for performing actions:

  • AuditLog.Read.All - Provides access to reading audit logs.
  • Directory.Read.All - Provides access to reading any data in the directory.

Property
Description
Name

The display name of the node within the flows.

Unique ID

System-wide unique ID of the plugin instance.

Action

Configuration option determining the type of operation to perform:

  • List Sign-Ins: Retrieves sign-ins matching the Sign-Ins Filtering conditions.
  • Get Sign-In: Retrieves a single sign-in’s information based on it’s ID.
Mode

Defines the mode of operation when filtering.

  • Guided: Exposes an input area for defining a list of logically AND’ed filter criteria.
  • Expert: Exposes an input area for defining a complex free-form filter.
Sign-Ins Filtering

When the Action is List Sign-Ins, this field defines the filtering criteria for matching sign-ins.

In Guided mode, a list of criteria is logically AND’ed together to define the filter. The Attribute select field is seeded with information from the List Sign-Ins page from Microsoft.

In Expert mode, a free-form entry area provides a template based format for defining the filter. The expert mode filter uses variable substitution from the incoming message using a mustache format. A mustache is a set of double curly braces surrounding a variable, i.e. {{ variable }}. For example, {{payload.data}} would substitute in the value of payload.data found in the incoming message.

Size Limit

When the Action is List Sign-Ins, this limits the total number of returned results. This field is provided because returning sign-in information results is time consuming.

Sign-In ID

When the Action is Get Sign-In, this field defines the ID of the sign-in to retrieve.

Learn More

JSON Message Format

The following samples show the JSON content added to the message payload, which conform to the Node Messaging Format. The content exists within the azuread object. The following examples use azuread1 for the Unique Id of the plugin:

Add User to Group Success

The italicized, green text is inserted into the message payload upon a successful request to Azure AD.

"payload": {
  "azuread": {
    "azuread1": {
      "action": "add-user",
      "response": {
        "user": "user@domain.com",
        "group": "Test",
        "owner": "added",
        "member": "added",
        "userId": "[UUID of user]",
        "groupId": "[GUID of group]"
      }
    }
  }
}

Remove User from Group Success

The italicized, green text is inserted into the message payload upon a successful request to Azure AD.

"payload": {
  "azuread": {
    "azuread1": {
      "action": "remove-user",
      "response": {
        "user": "user@domain.com",
        "group": "Test",
        "owner": "removed",
        "member": "removed",
        "userId": "[UUID of user]",
        "groupId": "[GUID of group]"
      }
    }
  }
}

Error

The italicized, maroon text is inserted into the message payload upon a failed request. In the following example, a non-existent group called Random was tested against.

"payload": {
  "azuread": {
    "azuread1": {
      "action": "remove-user",
      "error": {
        "errorCode": 5,
        "errorMessage": "Azure AD Exception occurred.  No matching Azure AD group found for Random."
      }
    }
  }
}
Nevelex Labs, Main Office

Metro Office Park
2950 Metro Drive, Suite 104
Bloomington, MN 55425
Phone: +1 952-500-8921

©Nevelex Labs, LLC. 2018-2024, All Rights Reserved.

EULA