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.
Connector Version: 2.0.0
FortiSOAR™ Version Tested on: 7.0.0-480
Azure Active Directory Version Tested on: Azure Cloud
Authored By: Fortinet
Certified: Yes
Following enhancements have been made to the Azure Active Directory connector in version 2.0.0:
You can get authentication tokens to access the security graph APIs using two methods:
User.ReadBasic.All
User.Read.All
User.ReadWrite.All
Directory.Read.All
Directory.ReadWrite.All
Directory.AccessAsUser.All
of type 'Delegated'.TENANT_ID
, CLIENT_ID
, and REDIRECT_URI
with your own tenant ID, client ID, and redirect URL: https://login.microsoftonline.com/TENANT_ID/oauth2/v2.0/authorize?response_type=code&scope=offline_access User.ReadBasic.All User.Read.All User.ReadWrite.All Directory.Read.All Directory.ReadWrite.All Directory.AccessAsUser.All&client_id=CLIENT_ID&redirect_uri=REDIRECT_URI
REDIRECT_URI?code=AUTH_CODE&session_state=SESSION_STATE
AUTH_CODE
(without the "code=" prefix) and paste it in your instance configuration in the 'Authorization Code' parameter.User.Read.All
User.ReadWrite.All
Directory.Read.All
Directory.ReadWrite.All
User.ManageIdentities.All
of type 'Application'.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 following yum command as a root
user to install connectors from an SSH session:
yum install cyops-connector-azure-active-directory
For the procedure to configure a connector, click here.
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 |
---|---|
Get Access Token | Select the method using which you will get authentication tokens used to access the security graph APIs. You can choose between On behalf of User – Delegate Permission or Without a User - Application Permission. For more information, see the Getting Access Tokens section. |
Server URL | The service-based URL to which you will connect and perform the automated operations. |
Client ID | Unique ID of the Azure Active Directory application that is used to create an authentication token required to access the API. |
Client Secret | Unique Client Secret of the Azure Active Directory application that is used to create an authentication token required to access the API. For information on how to get the secret key, see https://docs.microsoft.com/en-us/windows/security/threat-protection/microsoft-defender-atp/exposed-apis-create-app-webapp. |
Tenant ID | ID of the tenant that you have been provided for your Azure Active Directory instance. |
Authorization Code | (Only Applicable to On behalf of User – Delegate Permission) The authorization code that you acquired during the authorization step. For more information, see the Getting Access Tokens using the On behalf of the user – Delegate Permission method section. |
Redirect URL | (Only Applicable to On behalf of User – Delegate Permission) The redirect_uri of your app, where authentication responses can be sent and received by your app. The redirect URL that you specify here must exactly match one of the redirect_uri's you have registered in your app registration portal. |
Verify SSL | Specifies whether the SSL certificate for the server is to be verified or not. By default, this option is set as True . |
The following automated operations can be included in playbooks, and you can also use the annotations to access operations from version 4.10.0 onwards:
Function | Description | Annotation and Category |
---|---|---|
List Users | Retrieves the list of users from Azure Active Directory based on the input parameters such as the query for filtering users you have specified. | 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 |
Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criterion is applied, and an unfiltered list is returned.
Parameter | Description |
---|---|
Filter Query | Filter query based on which you want to retrieve users from Azure Active Directory. The OData's Filter query is supported on the following fields: "id", "userPrincipalName", "displayName", "givenName" and "jobTitle". For example [userPrincipalName eq 'username@fortisoar1.onmicrosoft.com'] retrieve a user which userPrincipalName is username@fortisoar1.onmicrosoft.com |
Select Query | Specify the select query to retrieve user fields from Azure Active Directory. The OData's Select query is supported on fields such as: "id", "userPrincipalName", "displayName", etc. |
Search Query | Specify the search query to retrieve user details from Azure Active Directory. The OData's Search query is supported on fields such as: "id", "userPrincipalName", "displayName", etc. |
The output contains the following populated JSON schema:
{
"@odata.context": "",
"value": [
{
"businessPhones": [],
"displayName": "",
"givenName": "",
"jobTitle": "",
"mail": "",
"mobilePhone": "",
"officeLocation": "",
"preferredLanguage": "",
"surname": "",
"userPrincipalName": "",
"id": ""
}
]
}
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.
|
The output contains the following populated JSON schema:
{
"@odata.context": "",
"businessPhones": [],
"displayName": "",
"givenName": "",
"jobTitle": "",
"mail": "",
"mobilePhone": "",
"officeLocation": "",
"preferredLanguage": "",
"surname": "",
"userPrincipalName": "",
"id": ""
}
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. |
The output contains the following populated JSON schema:
{
"@odata.context": "",
"id": "",
"businessPhones": [],
"displayName": "",
"givenName": "",
"jobTitle": "",
"mail": "",
"mobilePhone": "",
"officeLocation": "",
"preferredLanguage": "",
"surname": "",
"userPrincipalName": ""
}
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.
|
The output contains the following populated JSON schema:
{
"status": "",
"result": ""
}
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.
|
The output contains the following populated JSON schema:
{
"status": "",
"result": ""
}
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.
|
The output contains the following populated JSON schema:
{
"status": "",
"result": ""
}
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.
|
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 user next logs into Azure Active Directory. |
The output contains the following populated JSON schema:
{
"status": "",
"result": ""
}
The Sample - Azure-Active-Directory - 2.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 FortiSOAR&trade 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.
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.
Connector Version: 2.0.0
FortiSOAR™ Version Tested on: 7.0.0-480
Azure Active Directory Version Tested on: Azure Cloud
Authored By: Fortinet
Certified: Yes
Following enhancements have been made to the Azure Active Directory connector in version 2.0.0:
You can get authentication tokens to access the security graph APIs using two methods:
User.ReadBasic.All
User.Read.All
User.ReadWrite.All
Directory.Read.All
Directory.ReadWrite.All
Directory.AccessAsUser.All
of type 'Delegated'.TENANT_ID
, CLIENT_ID
, and REDIRECT_URI
with your own tenant ID, client ID, and redirect URL: https://login.microsoftonline.com/TENANT_ID/oauth2/v2.0/authorize?response_type=code&scope=offline_access User.ReadBasic.All User.Read.All User.ReadWrite.All Directory.Read.All Directory.ReadWrite.All Directory.AccessAsUser.All&client_id=CLIENT_ID&redirect_uri=REDIRECT_URI
REDIRECT_URI?code=AUTH_CODE&session_state=SESSION_STATE
AUTH_CODE
(without the "code=" prefix) and paste it in your instance configuration in the 'Authorization Code' parameter.User.Read.All
User.ReadWrite.All
Directory.Read.All
Directory.ReadWrite.All
User.ManageIdentities.All
of type 'Application'.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 following yum command as a root
user to install connectors from an SSH session:
yum install cyops-connector-azure-active-directory
For the procedure to configure a connector, click here.
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 |
---|---|
Get Access Token | Select the method using which you will get authentication tokens used to access the security graph APIs. You can choose between On behalf of User – Delegate Permission or Without a User - Application Permission. For more information, see the Getting Access Tokens section. |
Server URL | The service-based URL to which you will connect and perform the automated operations. |
Client ID | Unique ID of the Azure Active Directory application that is used to create an authentication token required to access the API. |
Client Secret | Unique Client Secret of the Azure Active Directory application that is used to create an authentication token required to access the API. For information on how to get the secret key, see https://docs.microsoft.com/en-us/windows/security/threat-protection/microsoft-defender-atp/exposed-apis-create-app-webapp. |
Tenant ID | ID of the tenant that you have been provided for your Azure Active Directory instance. |
Authorization Code | (Only Applicable to On behalf of User – Delegate Permission) The authorization code that you acquired during the authorization step. For more information, see the Getting Access Tokens using the On behalf of the user – Delegate Permission method section. |
Redirect URL | (Only Applicable to On behalf of User – Delegate Permission) The redirect_uri of your app, where authentication responses can be sent and received by your app. The redirect URL that you specify here must exactly match one of the redirect_uri's you have registered in your app registration portal. |
Verify SSL | Specifies whether the SSL certificate for the server is to be verified or not. By default, this option is set as True . |
The following automated operations can be included in playbooks, and you can also use the annotations to access operations from version 4.10.0 onwards:
Function | Description | Annotation and Category |
---|---|---|
List Users | Retrieves the list of users from Azure Active Directory based on the input parameters such as the query for filtering users you have specified. | 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 |
Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criterion is applied, and an unfiltered list is returned.
Parameter | Description |
---|---|
Filter Query | Filter query based on which you want to retrieve users from Azure Active Directory. The OData's Filter query is supported on the following fields: "id", "userPrincipalName", "displayName", "givenName" and "jobTitle". For example [userPrincipalName eq 'username@fortisoar1.onmicrosoft.com'] retrieve a user which userPrincipalName is username@fortisoar1.onmicrosoft.com |
Select Query | Specify the select query to retrieve user fields from Azure Active Directory. The OData's Select query is supported on fields such as: "id", "userPrincipalName", "displayName", etc. |
Search Query | Specify the search query to retrieve user details from Azure Active Directory. The OData's Search query is supported on fields such as: "id", "userPrincipalName", "displayName", etc. |
The output contains the following populated JSON schema:
{
"@odata.context": "",
"value": [
{
"businessPhones": [],
"displayName": "",
"givenName": "",
"jobTitle": "",
"mail": "",
"mobilePhone": "",
"officeLocation": "",
"preferredLanguage": "",
"surname": "",
"userPrincipalName": "",
"id": ""
}
]
}
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.
|
The output contains the following populated JSON schema:
{
"@odata.context": "",
"businessPhones": [],
"displayName": "",
"givenName": "",
"jobTitle": "",
"mail": "",
"mobilePhone": "",
"officeLocation": "",
"preferredLanguage": "",
"surname": "",
"userPrincipalName": "",
"id": ""
}
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. |
The output contains the following populated JSON schema:
{
"@odata.context": "",
"id": "",
"businessPhones": [],
"displayName": "",
"givenName": "",
"jobTitle": "",
"mail": "",
"mobilePhone": "",
"officeLocation": "",
"preferredLanguage": "",
"surname": "",
"userPrincipalName": ""
}
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.
|
The output contains the following populated JSON schema:
{
"status": "",
"result": ""
}
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.
|
The output contains the following populated JSON schema:
{
"status": "",
"result": ""
}
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.
|
The output contains the following populated JSON schema:
{
"status": "",
"result": ""
}
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.
|
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 user next logs into Azure Active Directory. |
The output contains the following populated JSON schema:
{
"status": "",
"result": ""
}
The Sample - Azure-Active-Directory - 2.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 FortiSOAR&trade 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.