Fortinet Document Library

Version:


Table of Contents

Azure Active Directory

1.0.0
Copy Link

About the connector

Azure Active Directory is a managed multi-tenant service from Microsoft that offers identity and access capabilities for the cloud using Azure Active Directory REST API services.

This document provides information about the Azure Active Directory connector, which facilitates automated interactions, between Azure Active Directory REST API services and FortiSOAR™ playbooks. Add the Azure Active Directory connector as a step in FortiSOAR™ playbooks and perform automated operations, such as retrieving a list of users from Azure Active Directory, or disabling the account of a specific user in Azure Active Directory.

Version information

Connector Version: 1.0.0

Authored By: Fortinet

Certified: No

Installing the connector

From FortiSOAR™ 5.0.0 onwards, use the Connector Store to install the connector. For the detailed procedure to install a connector, click here.
You can also use the yum command to install connectors. Connectors provided by FortiSOAR™ are delivered using a FortiSOAR™ repository. Therefore, you must set up your FortiSOAR™ repository and run the yum command as a root user to install connectors:

yum install cyops-connector-azure-active-directory

Prerequisites to configuring the connector

  • You must have the Tenant and Client ID for your Azure Active Directory instance to which you will connect and perform automated operations and the Client secret to access that instance.
  • To access the CyOPsTM UI, ensure that port 443 is open through the firewall for the CyOPsTM instance.

Configuring the connector

For the procedure to configure a connector, click here

Configuration parameters

In FortiSOAR™, on the Connectors page, click the Azure Active Directory connector row (if you are in the Grid view on the Connectors page) and in the Configurations tab enter the required configuration details: 

Parameter Description
Directory (Tenant) ID ID of the tenant that you have been provided for your Azure Active Directory instance.
Application (Client) ID Unique API ID of the Azure Active Directory application that is used to create an authentication token required to access the API.
Application (Client) Secret Unique API Secret of the Azure Active Directory application that is used to create an authentication token required to access the API.

Actions supported by the connector

The following automated operations can be included in playbooks, and you can also use the annotations to access operations from FortiSOAR™ release 4.10.0 and onwards:

Function Description Annotation and Category
List Users Retrieves the list of users from Azure Active Directory. list_users
Investigation
Get User Details Retrieves specific information for a specific user from Azure Active Directory, based on the Object ID or User Principal Name you have specified. get_user_details
Investigation
Add User Creates a new user in Azure Active Directory, based on the User Principal Name, Display Name, Password, and other input parameters you have specified. add_user
Investigation
Enable User Enables a specific user's account in Azure Active Directory, based on the Object ID or User Principal Name you have specified. enable_user
Containment
Disable User Disables a specific user's account in Azure Active Directory, based on the Object ID or User Principal Name you have specified. disable_user
Containment
Delete User Deletes a specific user's account from Azure Active Directory, based on the Object ID or User Principal Name you have specified. delete_user
Investigation
Reset Password Resets the password for an existing Azure Active Directory user, based on the Object ID or User Principal Name, password and other input parameters you have specified. reset_password
Containment

operation: List Users

Input parameters

None.

Output

The output contains the following populated JSON schema:
{
     "value": [
         {
             "companyName": "",
             "legalAgeGroupClassification": "",
             "state": "",
             "showInAddressList": "",
             "jobTitle": "",
             "department": "",
             "signInNames": [],
             "proxyAddresses": [],
             "userPrincipalName": "",
             "passwordPolicies": "",
             "onPremisesDistinguishedName": "",
             "surname": "",
             "givenName": "",
             "physicalDeliveryOfficeName": "",
             "facsimileTelephoneNumber": "",
             "objectType": "",
             "accountEnabled": "",
             "lastDirSyncTime": "",
             "creationType": "",
             "createdDateTime": "",
             "streetAddress": "",
             "city": "",
             "isCompromised": "",
             "provisionedPlans": [
                 {
                     "service": "",
                     "provisioningStatus": "",
                     "capabilityStatus": ""
                 }
             ],
             "usageLocation": "",
             "objectId": "",
             "immutableId": "",
             "onPremisesSecurityIdentifier": "",
             "odata.type": "",
             "postalCode": "",
             "thumbnailPhoto@odata.mediaEditLink": "",
             "userType": "",
             "ageGroup": "",
             "sipProxyAddress": "",
             "userIdentities": [],
             "mailNickname": "",
             "assignedLicenses": [
                 {
                     "skuId": "",
                     "disabledPlans": []
                 }
             ],
             "country": "",
             "refreshTokensValidFromDateTime": "",
             "userState": "",
             "deletionTimestamp": "",
             "userStateChangedOn": "",
             "displayName": "",
             "preferredLanguage": "",
             "consentProvidedForMinor": "",
             "otherMails": [],
             "mail": "",
             "mobile": "",
             "employeeId": "",
             "telephoneNumber": "",
             "provisioningErrors": [],
             "dirSyncEnabled": "",
             "assignedPlans": [
                 {
                     "assignedTimestamp": "",
                     "service": "",
                     "servicePlanId": "",
                     "capabilityStatus": ""
                 }
             ],
             "passwordProfile": ""
         }
     ],
     "odata.metadata": ""
}

operation: Get User Details

Input parameters

Parameter Description
Based On Select the parameter based on which you want to retrieve details of a user from Azure Active Directory. You can choose between Object ID or User Principal Name.
  • If you choose Object ID, then in the Object ID field, you must specify the ID of the object based on which details of the user is retrieved from Azure Active Directory.
  • If you choose User Principal Name, then in the User Principal Name field, you must specify the principal name of the user whose details you want to retrieve from Azure Active Directory.

Output

The output contains the following populated JSON schema:
{
     "companyName": "",
     "legalAgeGroupClassification": "",
     "state": "",
     "showInAddressList": "",
     "jobTitle": "",
     "department": "",
     "signInNames": [],
     "proxyAddresses": [],
     "userPrincipalName": "",
     "passwordPolicies": "",
     "onPremisesDistinguishedName": "",
     "surname": "",
     "givenName": "",
     "odata.type": "",
     "facsimileTelephoneNumber": "",
     "objectType": "",
     "accountEnabled": "",
     "lastDirSyncTime": "",
     "creationType": "",
     "createdDateTime": "",
     "streetAddress": "",
     "mail": "",
     "isCompromised": "",
     "provisionedPlans": [],
     "usageLocation": "",
     "objectId": "",
     "immutableId": "",
     "onPremisesSecurityIdentifier": "",
     "physicalDeliveryOfficeName": "",
     "postalCode": "",
     "thumbnailPhoto@odata.mediaEditLink": "",
     "userType": "",
     "ageGroup": "",
     "odata.metadata": "",
     "sipProxyAddress": "",
     "userIdentities": [],
     "mailNickname": "",
     "assignedLicenses": [],
     "country": "",
     "refreshTokensValidFromDateTime": "",
     "userState": "",
     "deletionTimestamp": "",
     "userStateChangedOn": "",
     "displayName": "",
     "preferredLanguage": "",
     "consentProvidedForMinor": "",
     "otherMails": [],
     "city": "",
     "mobile": "",
     "employeeId": "",
     "telephoneNumber": "",
     "provisioningErrors": [],
     "dirSyncEnabled": "",
     "assignedPlans": [],
     "passwordProfile": {
         "password": "",
         "forceChangePasswordNextLogin": "",
         "enforceChangePasswordPolicy": ""
     }
}

operation: Add User

Input parameters

Parameter Description
Display Name Name that you want to display in the address book for the user that you are creating in Azure Active Directory.
Mail Nick Name Mail alias for the user that you are creating in Azure Active Directory.
User Principal Name Principal name of the user that you are creating in Azure Active Directory.
Password Password of the user that you are creating in Azure Active Directory.
Force Change Password Next Login If you select this option, i.e., set it to true, then the user is forced to change his password when the users next logs into Azure Active Directory.
Account Enabled If you select this option, i.e., set it to true, then the user's account is enabled on Azure Active Directory.
Additional Fields (Optional) Additional fields that you want to add to the user that you are creating in Azure Active Directory.

Output

The output contains the following populated JSON schema:
{
     "companyName": "",
     "objectId": "",
     "thumbnailPhoto@odata.mediaEditLink": "",
     "immutableId": "",
     "state": "",
     "onPremisesSecurityIdentifier": "",
     "jobTitle": "",
     "department": "",
     "provisionedPlans": [],
     "userType": "",
     "odata.metadata": "",
     "sipProxyAddress": "",
     "provisioningErrors": [],
     "userPrincipalName": "",
     "proxyAddresses": [],
     "passwordPolicies": "",
     "mailNickname": "",
     "city": "",
     "assignedLicenses": [],
     "country": "",
     "givenName": "",
     "odata.type": "",
     "deletionTimestamp": "",
     "surname": "",
     "physicalDeliveryOfficeName": "",
     "facsimileTelephoneNumber": "",
     "objectType": "",
     "accountEnabled": "",
     "lastDirSyncTime": "",
     "displayName": "",
     "preferredLanguage": "",
     "creationType": "",
     "otherMails": [],
     "postalCode": "",
     "mail": "",
     "mobile": "",
     "streetAddress": "",
     "telephoneNumber": "",
     "passwordProfile": {
         "password": "",
         "forceChangePasswordNextLogin": ""
     },
     "dirSyncEnabled": "",
     "assignedPlans": [],
     "usageLocation": ""
}

operation: Enable User

Input parameters

Parameter Description
Based On Select the parameter based on which you want to enable a user's account on Azure Active Directory. You can choose between Object ID or User Principal Name.
  • If you choose Object ID, then in the Object ID field, you must specify the ID of the object based on which user account is enabled on Azure Active Directory.
  • If you choose User Principal Name, then in the User Principal Name field, you must specify the ID of the object based on which user account is enabled on Azure Active Directory.

Output

The output contains the following populated JSON schema:
{
     "status": "",
     "result": ""
}

operation: Disable User

Input parameters

Parameter Description
Based On Select the parameter based on which you want to disable a user's account on Azure Active Directory. You can choose between Object ID or User Principal Name.
  • If you choose Object ID, then in the Object ID field, you must specify the ID of the object based on which user account is disabled on Azure Active Directory.
  • If you choose User Principal Name, then in the User Principal Name field, you must specify the ID of the object based on which user account is disabled on Azure Active Directory.

Output

The output contains the following populated JSON schema:


{
     "status": "",
     "result": ""
}

operation: Delete User

Input parameters

Parameter Description
Based On Select the parameter based on which you want to delete a user's account from Azure Active Directory. You can choose between Object ID or User Principal Name.
  • If you choose Object ID, then in the Object ID field, you must specify the ID of the object based on which user account is deleted from Azure Active Directory.
  • If you choose User Principal Name, then in the User Principal Name field, you must specify the ID of the object based on which user account is deleted from Azure Active Directory.

Output

The output contains the following populated JSON schema:
{
     "status": "",
     "result": ""
}

operation: Reset Password

Input parameters

Parameter Description
Based On Select the parameter based on which you want to retrieve details of the user, whose password you want to reset, from Azure Active Directory. You can choose between Object ID or User Principal Name.
  • If you choose Object ID, then in the Object ID field, you must specify the ID of the object based on which details of the user is retrieved from Azure Active Directory.
  • If you choose User Principal Name, then in the User Principal Name field, you must specify the principal name of the user whose details you want to retrieve from Azure Active Directory.
Password Temporary password that you want to set for the user whose password you want to rest on Azure Active Directory.
Force Change Password Next Login If you select this option, i.e., set it to true, then the user is forced to change his password when the users next logs into Azure Active Directory.

Output

The output contains the following populated JSON schema:
{
     "status": "",
     "result": ""
}

Included playbooks

The Sample - Azure-Active-Directory - 1.0.0 playbook collection comes bundled with the Azure Active Directory connector. These playbooks contain steps using which you can perform all supported actions. You can see bundled playbooks in the Automation > Playbooks section in CyOPsTM after importing the Azure Active Directory connector.

  • Add User
  • Delete User
  • Disable User
  • Enable User
  • Get User Details
  • List Users
  • Reset Password

Note: If you are planning to use any of the sample playbooks in your environment, ensure that you clone those playbooks and move them to a different collection since the sample playbook collection gets deleted during connector upgrade and delete.

About the connector

Azure Active Directory is a managed multi-tenant service from Microsoft that offers identity and access capabilities for the cloud using Azure Active Directory REST API services.

This document provides information about the Azure Active Directory connector, which facilitates automated interactions, between Azure Active Directory REST API services and FortiSOAR™ playbooks. Add the Azure Active Directory connector as a step in FortiSOAR™ playbooks and perform automated operations, such as retrieving a list of users from Azure Active Directory, or disabling the account of a specific user in Azure Active Directory.

Version information

Connector Version: 1.0.0

Authored By: Fortinet

Certified: No

Installing the connector

From FortiSOAR™ 5.0.0 onwards, use the Connector Store to install the connector. For the detailed procedure to install a connector, click here.
You can also use the yum command to install connectors. Connectors provided by FortiSOAR™ are delivered using a FortiSOAR™ repository. Therefore, you must set up your FortiSOAR™ repository and run the yum command as a root user to install connectors:

yum install cyops-connector-azure-active-directory

Prerequisites to configuring the connector

Configuring the connector

For the procedure to configure a connector, click here

Configuration parameters

In FortiSOAR™, on the Connectors page, click the Azure Active Directory connector row (if you are in the Grid view on the Connectors page) and in the Configurations tab enter the required configuration details: 

Parameter Description
Directory (Tenant) ID ID of the tenant that you have been provided for your Azure Active Directory instance.
Application (Client) ID Unique API ID of the Azure Active Directory application that is used to create an authentication token required to access the API.
Application (Client) Secret Unique API Secret of the Azure Active Directory application that is used to create an authentication token required to access the API.

Actions supported by the connector

The following automated operations can be included in playbooks, and you can also use the annotations to access operations from FortiSOAR™ release 4.10.0 and onwards:

Function Description Annotation and Category
List Users Retrieves the list of users from Azure Active Directory. list_users
Investigation
Get User Details Retrieves specific information for a specific user from Azure Active Directory, based on the Object ID or User Principal Name you have specified. get_user_details
Investigation
Add User Creates a new user in Azure Active Directory, based on the User Principal Name, Display Name, Password, and other input parameters you have specified. add_user
Investigation
Enable User Enables a specific user's account in Azure Active Directory, based on the Object ID or User Principal Name you have specified. enable_user
Containment
Disable User Disables a specific user's account in Azure Active Directory, based on the Object ID or User Principal Name you have specified. disable_user
Containment
Delete User Deletes a specific user's account from Azure Active Directory, based on the Object ID or User Principal Name you have specified. delete_user
Investigation
Reset Password Resets the password for an existing Azure Active Directory user, based on the Object ID or User Principal Name, password and other input parameters you have specified. reset_password
Containment

operation: List Users

Input parameters

None.

Output

The output contains the following populated JSON schema:
{
     "value": [
         {
             "companyName": "",
             "legalAgeGroupClassification": "",
             "state": "",
             "showInAddressList": "",
             "jobTitle": "",
             "department": "",
             "signInNames": [],
             "proxyAddresses": [],
             "userPrincipalName": "",
             "passwordPolicies": "",
             "onPremisesDistinguishedName": "",
             "surname": "",
             "givenName": "",
             "physicalDeliveryOfficeName": "",
             "facsimileTelephoneNumber": "",
             "objectType": "",
             "accountEnabled": "",
             "lastDirSyncTime": "",
             "creationType": "",
             "createdDateTime": "",
             "streetAddress": "",
             "city": "",
             "isCompromised": "",
             "provisionedPlans": [
                 {
                     "service": "",
                     "provisioningStatus": "",
                     "capabilityStatus": ""
                 }
             ],
             "usageLocation": "",
             "objectId": "",
             "immutableId": "",
             "onPremisesSecurityIdentifier": "",
             "odata.type": "",
             "postalCode": "",
             "thumbnailPhoto@odata.mediaEditLink": "",
             "userType": "",
             "ageGroup": "",
             "sipProxyAddress": "",
             "userIdentities": [],
             "mailNickname": "",
             "assignedLicenses": [
                 {
                     "skuId": "",
                     "disabledPlans": []
                 }
             ],
             "country": "",
             "refreshTokensValidFromDateTime": "",
             "userState": "",
             "deletionTimestamp": "",
             "userStateChangedOn": "",
             "displayName": "",
             "preferredLanguage": "",
             "consentProvidedForMinor": "",
             "otherMails": [],
             "mail": "",
             "mobile": "",
             "employeeId": "",
             "telephoneNumber": "",
             "provisioningErrors": [],
             "dirSyncEnabled": "",
             "assignedPlans": [
                 {
                     "assignedTimestamp": "",
                     "service": "",
                     "servicePlanId": "",
                     "capabilityStatus": ""
                 }
             ],
             "passwordProfile": ""
         }
     ],
     "odata.metadata": ""
}

operation: Get User Details

Input parameters

Parameter Description
Based On Select the parameter based on which you want to retrieve details of a user from Azure Active Directory. You can choose between Object ID or User Principal Name.
  • If you choose Object ID, then in the Object ID field, you must specify the ID of the object based on which details of the user is retrieved from Azure Active Directory.
  • If you choose User Principal Name, then in the User Principal Name field, you must specify the principal name of the user whose details you want to retrieve from Azure Active Directory.

Output

The output contains the following populated JSON schema:
{
     "companyName": "",
     "legalAgeGroupClassification": "",
     "state": "",
     "showInAddressList": "",
     "jobTitle": "",
     "department": "",
     "signInNames": [],
     "proxyAddresses": [],
     "userPrincipalName": "",
     "passwordPolicies": "",
     "onPremisesDistinguishedName": "",
     "surname": "",
     "givenName": "",
     "odata.type": "",
     "facsimileTelephoneNumber": "",
     "objectType": "",
     "accountEnabled": "",
     "lastDirSyncTime": "",
     "creationType": "",
     "createdDateTime": "",
     "streetAddress": "",
     "mail": "",
     "isCompromised": "",
     "provisionedPlans": [],
     "usageLocation": "",
     "objectId": "",
     "immutableId": "",
     "onPremisesSecurityIdentifier": "",
     "physicalDeliveryOfficeName": "",
     "postalCode": "",
     "thumbnailPhoto@odata.mediaEditLink": "",
     "userType": "",
     "ageGroup": "",
     "odata.metadata": "",
     "sipProxyAddress": "",
     "userIdentities": [],
     "mailNickname": "",
     "assignedLicenses": [],
     "country": "",
     "refreshTokensValidFromDateTime": "",
     "userState": "",
     "deletionTimestamp": "",
     "userStateChangedOn": "",
     "displayName": "",
     "preferredLanguage": "",
     "consentProvidedForMinor": "",
     "otherMails": [],
     "city": "",
     "mobile": "",
     "employeeId": "",
     "telephoneNumber": "",
     "provisioningErrors": [],
     "dirSyncEnabled": "",
     "assignedPlans": [],
     "passwordProfile": {
         "password": "",
         "forceChangePasswordNextLogin": "",
         "enforceChangePasswordPolicy": ""
     }
}

operation: Add User

Input parameters

Parameter Description
Display Name Name that you want to display in the address book for the user that you are creating in Azure Active Directory.
Mail Nick Name Mail alias for the user that you are creating in Azure Active Directory.
User Principal Name Principal name of the user that you are creating in Azure Active Directory.
Password Password of the user that you are creating in Azure Active Directory.
Force Change Password Next Login If you select this option, i.e., set it to true, then the user is forced to change his password when the users next logs into Azure Active Directory.
Account Enabled If you select this option, i.e., set it to true, then the user's account is enabled on Azure Active Directory.
Additional Fields (Optional) Additional fields that you want to add to the user that you are creating in Azure Active Directory.

Output

The output contains the following populated JSON schema:
{
     "companyName": "",
     "objectId": "",
     "thumbnailPhoto@odata.mediaEditLink": "",
     "immutableId": "",
     "state": "",
     "onPremisesSecurityIdentifier": "",
     "jobTitle": "",
     "department": "",
     "provisionedPlans": [],
     "userType": "",
     "odata.metadata": "",
     "sipProxyAddress": "",
     "provisioningErrors": [],
     "userPrincipalName": "",
     "proxyAddresses": [],
     "passwordPolicies": "",
     "mailNickname": "",
     "city": "",
     "assignedLicenses": [],
     "country": "",
     "givenName": "",
     "odata.type": "",
     "deletionTimestamp": "",
     "surname": "",
     "physicalDeliveryOfficeName": "",
     "facsimileTelephoneNumber": "",
     "objectType": "",
     "accountEnabled": "",
     "lastDirSyncTime": "",
     "displayName": "",
     "preferredLanguage": "",
     "creationType": "",
     "otherMails": [],
     "postalCode": "",
     "mail": "",
     "mobile": "",
     "streetAddress": "",
     "telephoneNumber": "",
     "passwordProfile": {
         "password": "",
         "forceChangePasswordNextLogin": ""
     },
     "dirSyncEnabled": "",
     "assignedPlans": [],
     "usageLocation": ""
}

operation: Enable User

Input parameters

Parameter Description
Based On Select the parameter based on which you want to enable a user's account on Azure Active Directory. You can choose between Object ID or User Principal Name.
  • If you choose Object ID, then in the Object ID field, you must specify the ID of the object based on which user account is enabled on Azure Active Directory.
  • If you choose User Principal Name, then in the User Principal Name field, you must specify the ID of the object based on which user account is enabled on Azure Active Directory.

Output

The output contains the following populated JSON schema:
{
     "status": "",
     "result": ""
}

operation: Disable User

Input parameters

Parameter Description
Based On Select the parameter based on which you want to disable a user's account on Azure Active Directory. You can choose between Object ID or User Principal Name.
  • If you choose Object ID, then in the Object ID field, you must specify the ID of the object based on which user account is disabled on Azure Active Directory.
  • If you choose User Principal Name, then in the User Principal Name field, you must specify the ID of the object based on which user account is disabled on Azure Active Directory.

Output

The output contains the following populated JSON schema:


{
     "status": "",
     "result": ""
}

operation: Delete User

Input parameters

Parameter Description
Based On Select the parameter based on which you want to delete a user's account from Azure Active Directory. You can choose between Object ID or User Principal Name.
  • If you choose Object ID, then in the Object ID field, you must specify the ID of the object based on which user account is deleted from Azure Active Directory.
  • If you choose User Principal Name, then in the User Principal Name field, you must specify the ID of the object based on which user account is deleted from Azure Active Directory.

Output

The output contains the following populated JSON schema:
{
     "status": "",
     "result": ""
}

operation: Reset Password

Input parameters

Parameter Description
Based On Select the parameter based on which you want to retrieve details of the user, whose password you want to reset, from Azure Active Directory. You can choose between Object ID or User Principal Name.
  • If you choose Object ID, then in the Object ID field, you must specify the ID of the object based on which details of the user is retrieved from Azure Active Directory.
  • If you choose User Principal Name, then in the User Principal Name field, you must specify the principal name of the user whose details you want to retrieve from Azure Active Directory.
Password Temporary password that you want to set for the user whose password you want to rest on Azure Active Directory.
Force Change Password Next Login If you select this option, i.e., set it to true, then the user is forced to change his password when the users next logs into Azure Active Directory.

Output

The output contains the following populated JSON schema:
{
     "status": "",
     "result": ""
}

Included playbooks

The Sample - Azure-Active-Directory - 1.0.0 playbook collection comes bundled with the Azure Active Directory connector. These playbooks contain steps using which you can perform all supported actions. You can see bundled playbooks in the Automation > Playbooks section in CyOPsTM after importing the Azure Active Directory connector.

Note: If you are planning to use any of the sample playbooks in your environment, ensure that you clone those playbooks and move them to a different collection since the sample playbook collection gets deleted during connector upgrade and delete.