Azure AD User Provisioning

1. About this document

This document provides step-by-step instructions to configure Azure AD User Provisioning in SAFE.

2. Introduction

The integration of SAFE with Azure AD User Provisioning streamlines the user management under the people attack surface in SAFE and ensures up-to-date user information within the system.

The key highlights of this integration include the following:

1. Seamless User Sync (Add/Remove User): With Azure AD User Provisioning, syncing users between SAFE and Azure AD becomes effortless. As individuals join or leave the organization, their user information is automatically updated in SAFE, eliminating manual data entry and reducing administrative overhead.
2. Attribute Synchronization:  Keep user attributes such as Department, Location, Designation, Email, and custom-created tags consistent and synchronized across SAFE and Azure AD. This ensures accurate user information throughout your organization's systems.

3. Prerequisites

1. SAFE access with an admin role.
2. Azure portal access with an admin role.

4. Configure Azure AD User Provisioning

4.1. Generate connector details (API Endpoint URL and Secret Token) in SAFE

Follow the below steps to generate the connector details:

1. Navigate to the SAFE Hooks.
2. Click the Azure AD User Provisioning card.
3. Enter the Expiry period in days. The default value is set to 90 days. 
4. This represents the maximum duration for which the generated secret token remains valid. After the token expires, it is necessary to set up a new token. Setting the token expiry is crucial for data security. Rotating the token before it expires is recommended to prevent application quarantine.
5. Click the Generate Token button. The system displays the API Endpoint URL and SecretToken.
6. Copy and save the generated API Endpoint URL and SecretToken to be used while setting up user provisioning in Azure.

4.2. Set up an application in Azure

1. Login to Azure Portal and click the Azure Active Directory from the Azure services list.
   
2. Click on Enterprise Application from the left navigation.
   
3. Click the New Application to create a new enterprise application.
   
4. Click the Createyour own application button.
   
5. Enter a name for the application.
   Example: "SAFE - Azure Ad User Provisioning"
6. Select the option Integrate any other application you don't find in the gallery (Non-gallery).
   
7. Click the Create button. Once the application is created, you will be redirected to the application's home page. 
8. Click the Users and groups from the left navigation.
   
9. Click the Add user/groups button.
   
10. Select the users/groups you want to add.
    
11. Click the Assign button. Only users assigned to the application will be eligible for provisioning.
    
12. The system displays the list of users and groups that are assigned. These users and groups are now eligible to be synced with SAFE with their details.
    
13. Click Provisioning from the left navigation.
14. Click the Get Started button.
    
15. Select the ProvisioningMode as Automatic.
16. Under Admin Credentials,  enter the Tenant URL (API Endpoint URL) and SecretToken generated in step 4.1.
    
17. Click the Test Connection button. Once the connection is verified, click the Save button.
    If you encounter an error message, please double-check the URL and ensure that the token entered is the most recent one.
    
18. Go to the Mapping, where there are two types of mappings: Provision Azure Active Directory Groups and Provision Azure Active Directory Users, both enabled by default.
    
19. Click the Provision Azure Active Directory Groups, toggle Enabled to No, and Save the configuration.
    
20. Go back to Provision Azure Active Directory Users, keep Enabled toggled to Yes, and keep all Target Object Actions checked, i.e., Create, Update, and Delete.
21. Go to the Attribute Mapping section and make sure only the supported attributes in SAFE are selected with the exact mapping. Remove any mapping from defaults that is not in the below list by clicking the Delete button corresponding to the mapping. Refer to the table below.
    
22. Make sure that the Matching precedence of the mail attribute is set to 1, and for all other attributes, it is set to No.

4.3. Set the Matching precedence of the mail attribute

1. On the Attribute Mapping page, click on mail.
2. Set the "Match objects using this attribute" to Yes.
3. Set the Matching precedence to 2.
   
4. Navigate back to Attribute Mapping.
5. Click on userPrincipalName.
6. Set the "Match objects using this attribute" to No.
   
7. Navigate back to Attribute Mapping.
8. Click on mail.
9. Set the "Matching precedence for mail" to 1, and click the Ok button.
   

4.4. Supported Custom Fields

4.3.1. Prerequisites

To synchronize a custom field in the SAFE Application with an Azure AD Attribute, the custom field needs to be present in SAFE. The custom field should be of type "Any," and the relevant input vector should be selected as "Technology & People.” For instance, you can create a custom field named "postalCode" in SAFE with the specified configuration.

4.3.2. Steps to be performed in Azure AD User Provisioning Application

1. Navigate to Azure AD Portal > Provisioning > Attribute Mapping. 
2. On the Attribute Mapping page, click the Show Advanced Options available at the bottom left of the page.
   
3. Click on Edit Attribute List for customappsso.
4. Add an attribute with the format urn:ietf:params:scim:schemas:extension:CustomExtensionName:2.0:User:<custom-field-name-created-in-SAFE>
   For example, if the custom field created in SAFE is of the name postalCode, the attribute will be urn:ietf:params:scim:schemas:extension:CustomExtensionName:2.0:User:postalCode
   
5. Click the Save button.
6. Navigate back to Attribute Mapping.
7. Click the AddNew Mapping.
8. Select postalCode from the sourceAttribute.
   
9. Select urn:ietf:params:scim:schemas:extension:CustomExtensionName:2.0:User:postalCode from the Target Attribute.
   
10. Click the OK button.
    
11. Once done, click Save and then Yes.
12. Go to Settings.
13. Enable the "Send an email notification when a failure occurs" checkbox and provide the email address. In the event of a failure, an Azure AD User Provisioning application may enter a quarantine state (for more details, refer to FAQ Point 4). By selecting this checkbox, you will receive prompt notifications for any such failures.
14. Email notifications will be sent within 24 hours of the job entering the quarantine state on the provided email.
    
15. On the Provisioning screen, turn the toggle for Provisioning Status to On and click SaveandConfirm.
    
16. Now the setup is done, and the provision cycle should start in some time. Initially, on the provisioning screen, there should be a message indicating that the initial cycle has not run, and clicking on View Provisioning Logs will show empty logs.
17. After the provisioning cycle gets completed, there should be a message on the Provisioning Screen - Initial Cycle Completed.
    
18. On clicking View Provisioning Logs, it should show the users that got created/updated and check for any failures.
    

5. FAQs

Q: What could cause a user to be skipped during provisioning with the reason "UnprocessableEntry"?

Please verify if the email information is empty for that specific user.

Q: How often does provisioning occur?

Provisioning is automatically triggered at a default interval of 40 minutes.

Q. Can the provisioning be stopped?

At any point in time, you can Start and Stop Provisioning. You can also Restart Provisioning, which will start the process all over again and create the users in the Target Application. If some users already exist in the target application with the same username/id, they will be skipped.

Q. What are the potential causes for the Azure AD User Provisioning Application entering quarantine mode?

1. The secret token generated for the Azure AD User Provisioning Application has expired.
2. A considerable number of failures occurred during the process of fetching, updating, or creating users. Please review Step 20 to examine the provisioning logs.

For further information on why the application enters quarantine mode and the necessary steps to resolve it. Refer to Azure Active Directory documentation.

Q. Is on-demand provisioning supported?

The Provision on Demand option is only available for individual users and not supported for groups.

Q.I had a previous version of Azure AD User Provisioning token configured. Will that work?

No, the previous token will not work. You will need to generate a new token using the provided steps.

Q. What custom field types are supported by SAFE for Azure AD User Provisioning?

SAFE only supports Custom fields of type “Any” for this integration.

Q. Valid credentials in Azure AD User Provisioning are giving Invalid credentials. What can be the reasons?

SAFE might be under load at the time when the user is trying to test the connection. Due to this, rate-limiting will come into effect. In such a scenario, please try after some time.

8. SAFE's Outgoing IP Addresses

SAFE's Outgoing IP Addresses: Here, you can find the outgoing IP addresses of SAFE. All traffic to any integrations in SAFE will see one IP address as the source IP of the incoming connection.