README.md

Configuring Microsoft Azure AD Outbound Provisioning Connector

This document provides instructions on how to provision users to a Azure Active Directory (Azure AD) from the WSO2 Identity Server (WSO2 IS). Follow the instructions given in the sections below to set this up.

This connector allows the users to be:

• provisioned to the Azure AD

• deprovisioned from the Azure AD

• assigned to groups in the Azure AD

Prerequisites

Before you begin:

• Register a new application using the Microsoft App Registration Portal. For instructions on how to do this, see Registering an application in the Microsoft documentation.

  Click to view vital information about registering the application

  When registering the application, note the following mandatory configurations.

  1. Under the Platforms section, select Allow Implicit flow and configure the redirect and logout URLs.

  2. Under the Microsoft Graph Permissions section, add the following permissions.

     1. Delegated permissions:

        • User.Read
        • User.ReadBasic.All
        • User.ReadWrite
        • User.Invite.All (Admin Only)
        • User.Read.All (Admin Only)
        • User.ReadWrite.All (Admin Only)

     2. Application permissions:

        • Directory.Read.All (Admin Only)
        • Domain.ReadWrite.All (Admin Only)
        • User.Read.All (Admin Only)
        • User.ReadWrite.All (Admin Only)

  3. Application permissions needs to be consented by an administrator . Construct and access the following URL on a browser window to provide consent for the application permissions.

     Request URL Format

     https://login.microsoftonline.com/{tenant}/adminconsent?client_id={application-is}&state=12345&redirect_uri={application-redirect-url}

     Sample URL

     https://login.microsoftonline.com/wso2sl.onmicrosoft.com/adminconsent?client_id=1b0c61c1-3af9-41f6-a7a7-e5f1e4ac1023&state=12345&redirect_uri=https://localhost/myapp

• Add a new domain to Office 365 using the Office 365 Admin Portal. For instructions on how to do this, see Add A Domain to Office 365 in the Microsoft documentation.

Installing the connector

1. Download the Office365 connector from the WSO2 Connectors Store.

2. Copy the org.wso2.carbon.identity.outbound.provisioning.connector.office365-x.x.x.jar file to the <IS_HOME>/repository/components/dropins folder.

3. Restart the server.

Configuring the identity provider

First you must configure an identity provider to accept the provisioning request from WSO2 Identity Server. Follow the instructions given below to create a new identity provider for Office365 provisioning in WSO2 IS.

1. Log in to the management console using your username and password or admin/admin credentials.

2. Click Add under Identity Providers on the Main menu.

3. Enter a name for the identity provider.

4. Expand Outbound Provisioning Connectors and then expand Office365 Provisioning Configuration.

5. Configure the following fields.

   

   Field	Description	Sample Value
   Enable	Select the checkbox to enable Office365 identity provisioning. Unselect the checkbox to disable it.	Selected
   Client ID	The application ID used to register the app in the Microsoft App Registration Portal (see the prerequisites for more information).	7d7d8f46-7184-4dc7-a198-4554dadc1197
   Client Secret	The application secret used to register the app in the Microsoft App Registration Portal (see the prerequisites for more information).
   Office365 Tenant Name	The organization name used to signup for Office 365.	wso2office.onmicrosoft.com
   Office365 Domain Name	The domain name registered in Office365 (see the prerequisites for more information).	wso2.ml
   Immutable ID	A valid claim which acts as the unique identifier of the user in the Azure AD. 📋Note: The claim URI for the Immutable ID should match the Subject Claim URI given under the Claim Configuration section when creating a service provider.	http://wso2.org/claims/objectguid
   User Principal Name	A valid claim which will be the Internet-style login name for the user.	http://wso2.org/claims/username
   Append Domain Name to UPN	If this is set to true, the domain name is appended to the UPN if it is not already there.	true (E.g., if the username is "john" and the domain name is "foo.com", the UPN will be " [email protected] ")
   Display Name	A valid claim which is the name displayed for the user in the address book of the Azure AD.	http://wso2.org/claims/displayName
   Email Nickname	A valid claim as the mail alias for the user in the Azure AD.	http://wso2.org/claims/username
   Dynamic Membership Rule Attribute	The Azure AD user attribute considered during the execution of the dynamic membership query (see prerequisites for more information). 📋Note: This is an optional configuration and can be used when dynamically assigning users into groups for provisioning in the Azure AD. The attribute must be equal to the attribute name given to the dynamic membership rule.	department
   Dynamic Membership Rule Value	The claim mapped to the attribute (see prerequisites for more information). 📋Note: This is an optional configuration and can be used when dynamically assigning users into groups for provisioning in the Azure AD. However, if the attribute has been set and this value has not been set, http://wso2.org/claims/role is considered as the default value.	http://wso2.org/claims/role

   ℹ️ All the fields that are marked as mandatory * must have a value in order to succesfully provision the users. For more information about user attributes in the Azure AD, see the user properties in the Microsoft documentation.

6. Optional step - you can provision users based on the roles they are assigned to. To do this, configure the following.
   For more information, see Role Based Provisioning .

   1. Expand Role Configuration section.

   2. Enter the provisioning roles.
      

7. Click Register to save the changes.

Configuring the resident service provider

In this scenario, WSO2 Identity Server is the provisioning party. WSO2 IS initiates the request to Office365 and acts as the identity provider. Therefore the outbound provisioning identity provider must be configured against the resident service provider in order to the provision the user to the Azure AD.

1. Log in to the management console using the username and password (admin/admin).

2. Click Resident under Service Providers on the Main menu.

3. In the resulting screen, expand the Outbound Provisioning Configuration section.

4. Select the identity provider you created for Office365 outbound provisioning from the drop down menu. Click [+] to add it as a service provider.
   

5. Click Update to save changes.

Try it out

The sample scenario in this tutorial demonstrates the use of the outbound provisioning connector for:

• Provisioning users based on the user role. Users are not provisioned to the Azure AD until they are assigned to the office365Role role.
• Assigning users into groups using dynamic membership allocation rules.
• Permanently de-provisioning users from the Azure AD by un-assigning the role from the user.

Follow the instructions below to try out this scenario.

Enable Claims

1. Log in to the management console and click List under Claims .

2. Click on the http://wso2.org/claims claim dialect.

3. Click Edit on the Display Name claim and select Supported By Default to enable the claim.
   

4. Click Update to save.

5. Similarly, enable all the claims that you configured in the outbound provisioning configuration of the office365 identity provider.
   For this scenario, enable the User ID and Username claims.

Create User

1. Click Add under Users and Roles on the Main tab of the management console.

2. Click Add New User and create a user with the username 'john’.

   

3. Click Finish. You will see the user you just created listed on the screen.

4. Click User Profile to edit John's user profile and add claim values for the claims you configured in the Office365 connector IdP configurations.

   ℹ️ In this scenario, Username, Display Name, and User ID are mandatory attributes for user provisioning and group assigning.

   

5. Click Update to save the changes.

Create a user group in the Azure AD

1. Create a group in the Azure AD. For more information, see Create a dynamic group and check status in the Microsoft documentation.

   ℹ️When creating groups in the Azure AD, rules can be applied to determine the membership based on user properties. All the dynamic group rules are evaluated in all additions/removals to the group. Dynamic group membership reduces the administrative overhead of adding and removing users.

2. Select Dynamic Use r as the Membership type when creating the group.

   ℹ️You need to have a Azure AD Premium P1 license to add dynamic membership rules in Azure AD.

3. Add a Dynamic Membership Rule as shown below. This rule specifies that any users that belong to the Engineering should be provisioned directly to the Engineering user group.
   

Assign the role

1. Login to the WSO2 IS management console.
2. Click Add under Users and Roles and then click Create New Role.
3. Create two new roles named office365role and Engineering.
   
4. Assign login permissions to the roles.
5. Assign the user 'john' to the roles ' office365role ' and ' Engineering .
   

When the role is assigned to the user, the user is provisioned to the AzureAD. This may take a few seconds.

Access the Azure AD portal. You will see that the user John has been succesfully provisioned to the Azure AD. Since John is assigned to the ' office365role ' and ' Engineering' roles, the dynamic membership rule is satisfied. Therefore, John is directly added to the ' Engineering ' group at the point of provisioning.