Azure AD support in Atlassian Crowd v3.x
Azure AD support in Atlassian Crowd v3.x
On August 17th 2017, Atlassian released Crowd 3.0
with native support for Microsoft Azure Active Directory. Please check our comparison table
for feature differences between Crowd's native Azure AD connector and the ODCC plugin.
Cleito ODCC is a simple plugin that you install on the Crowd server to which your Atlassian applications (e.g. Jira, Confluence, HipChat, Bamboo, Bitbucket) are connected.
The configuration consists in three easy steps:
- First of all, you will need to create an API key in Office 365. That key will be used by the ODCC plugin to browse your Office 365 instance and get its users and groups.
- Then you will configure the ODCC plugin in Crowd administration console. In this step, you will obviously enter the credentials of the previously created API key. You will also have the opportunity to set other options such as whether you want to fetch Office 365 profile pictures as Crowd user avatars.
- Finally you will need to configure your applications so that they use the Crowd server as a User Directory.
Please note that for security reasons the connection to Office 365 is read-only
. The ODCC plugin cannot create, update nor delete any object in Office 365.
Office 365 uses the cloud-based user authentication service Azure Active Directory to manage users. This implies the following prerequisites for the use of the ODCC plugin:
- If your organization manages users on-premises, please make sure that password synchronization has been enabled. For more information about implementing password synchronization with Azure AD Connect, please see Microsoft's documentation.
- Please also make sure that your organization has access to its Azure AD administration center. Ask your Office 365 administrator to log into the Office 365 administration portal and to select Admin centers > Azure AD. If the Azure AD admin center is not accessible, then your organization needs to register its free Azure Active Directory subscription. Please see Microsoft's documentation for more details.
- Finally, as Cleito ODCC uses the Exchange Web Services (EWS) API for the authentication of users with Azure AD Multi-Factor Authentication (MFA) enabled, such users will need a valid Office 365 Exchange Online mailbox.
- Atlassian Crowd 2.9.x, 2.10.x, 2.11.x, 2.12.x, 3.0.x and 3.1.x are supported
Firewall and proxy rules
Your Crowd server must be able to connect to any URL of the following web sites, either directly or through a proxy.
Azure Global Datacenters
Azure Germany Datacenters
In addition, if you choose IMAPS over HTTPS as the protocol used by Crowd for user authentication on Office 365, you will need to allow outgoing TCP connections to outlook.office365.com
(Azure Global Datacenters) or outlook.office.de
(Azure Germany Datacenters) on port 993.
Step 1 - Office 365 configuration
- Log into Microsoft Azure portal (or Microsoft Azure Germany portal). You do not have to be an administrator, any Office 365 account in your organization will work.
Click on Azure Active Directory > Properties in the left pane and note down the Directory ID as you will need it in the rest of the configuration process.
- Now, click on Azure Active Directory > App registrations and then click Add.
Give the app a name, select Web app / API as the application type, enter the Crowd server URL in the sign-on URL field and finally click on Create.
- Click on the display name of the app you have just created.
Note down the Application ID as you will need it in the rest of the configuration process. Then click on All settings.
- Click on Keys.
Then enter a description, select an expiration time and click on Save.
Note down the key value / application secret as you will need it in the rest of the configuration process.
- Click on Required permissions.
Then click on Windows Azure Active Directory.
Check Read directory data in Application Permissions.
Make sure that Sign in and read user profile is already checked in Delegated Permissions.
Finally click on Save.
- These permissions must now be validated by an Office 365 / Azure AD administrator. Ask your Office 365 / Azure AD administrator to open a browser to the following address.
Azure Global Datacenters
Azure Germany Datacenters
Once logged in, your Office 365 administrator will see the following page:
After clicking on Accept, your Office 365 administrator will be automatically redirected to:
Please note that it does not matter if the <SIGN_ON_URL> is not resolvable nor accessible to your Office 365 administrator. For instance, you might have previously entered http://localhost:8095/crowd as the sign-on URL of your app, in which case your Office 365 administrator will get a 404 - Not Found error when redirected to that URL.
Step 2 - Crowd configuration
- Download and unzip the CLEITO ODCC archive somewhere on your Crowd server.
- Copy the content of the lib directory to the crowd-webapp/WEB-INF/lib directory of your Crowd server.
- If you are running Atlassian Crowd v2.10.2, v2.10.3, v2.11.x or v2.12.x, please also copy the content of the extra-libs directory to the crowd-webapp/WEB-INF/lib directory of your Crowd server.
- Edit crowd-webapp/WEB-INF/classes/log4j.properties and add the following lines at the end of the file:
### CLEITO ODCC ###
- Restart Crowd.
- Log into Crowd administration console, click on Directories and then on Add directory
Select Custom for the directory type and click on Next.
- Give the connector a name and a description, and enter com.cleito.odcc.directory.Office365RemoteDirectory in the Implementation class field. Then click on Continue.
- Click on the Attributes tab and add each of the following attribute-value pairs:
Finally click on Update.
|The Directory ID of your Office 365 instance
|The ID of the application that you created in Step 1
|The value of the secret key that you created in Step 1
If your Office 365 instance resides in Azure Germany, please also set the following attribute-value pairs:
- Now click on Users or Groups. You should see all the identities of your Office 365 instance.
If you don't, go back to the Attributes tab of your Office 365 Directory Connector and click on Update after adding the odcc.log.level attribute and setting its value to FINE. Then click again on Users and take a look at the catalina.out file in the apache-tomcat/logs directory of your Crowd server.
- You might have noticed in the previous example that the default Crowd usernames are in the form firstname.lastname@example.org. The ODCC plugin actually uses the Office 365 userPrincipalName attribute as the username attribute for Crowd users.
If you want Crowd to use the shortusername part, you will need to set the value of the odcc.remove.domain.in.username attribute to true and the value of the ms.client_domain attribute to the domain name part of your users UPN (e.g. yourdomain.com or yourdomain.onmicrosoft.com).
The following table lists all the available configuration options of the ODCC plugin:
||Available since version
||Either true or false
When set to true, the username in Crowd will be the short username part of the userPrincipalName in Office 365. Please note that the ms.client_domain attribute must also be set.
||The domain name part of your users UPN in Office 365, e.g. yourdomain.com or yourdomain.onmicrosoft.com
||Either true or false
When set to true, the ODCC plugin will use the Office 365 profile photo as the Crowd user avatar. Please note that this can have a huge impact on performance especially when listing users in Crowd administration console.
Please note that starting from Crowd 3.1.0, you will also need to add the following option to JAVA_OPTS in apache-tomcat/bin/setenv.sh (Linux, Mac OS) or apache-tomcat/bin/setenv.bat (Windows):
||A list of comma separated Office 365 groups, e.g. Paris_Users, London_Users
If this property is set, the ODCC plugin will only fetch Office 365 users who belong to those groups. If this property is not set, all Office 365 users will be returned.
||A list of comma separated Office 365 groups, e.g. jira-software-users, confluence-users
If this property is set, the ODCC plugin will only fetch Office 365 groups whose names match the specified terms. If this property is not set, all Office 365 groups will be returned.
||Either true or false
When set to false, search restrictions on users will be included as query parameters in the HTTPS request to Office 365. Otherwise search restrictions will be applied locally.
||Either true or false
When set to false, search restrictions on groups will be included as query parameters in the HTTPS request to Office 365. Otherwise search restrictions will be applied locally.
||Either https or imaps
When set to imaps, the ODCC plugin will use the IMAPS protocol to authenticate end-users on Office 365. This requires that ALL users have a valid Office 365 Exchange Online mailbox.
||When set to ews, the ODCC plugin will use the Exchange Web Services (EWS) API for the authentication of ALL users, not just users with Azure AD Multi-Factor Authentication (MFA) enabled. This requires that ALL users have a valid Office 365 Exchange Online mailbox. Please note that this was the default behavior prior to ODCC v1.3.
||The maximum number of HTTP connections in the connection pool when requesting Office 365
||The HTTP connection timeout (in milliseconds) when requesting Office 365
||The server name of the proxy server used to request Office 365, e.g. internal-proxy.cleito.com
||The port of the proxy server used to request Office 365, e.g. 3128
||The username used to authenticate with the proxy server. This can only be used with TLS/SSL termination proxies.
||The password used to authenticate with the proxy server. This can only be used with TLS/SSL termination proxies.
||The IMAPS connection timeout (in milliseconds) when requesting Office 365
||Either INFO or FINE
The log level used by the ODCC plugin
||The commercial license key to be entered after purchasing the product
- Now click on the Applications tab of Crowd administration console and add the Office 365 Directory to the list of directories of each of the applications that you want to integrate with Cleito ODCC.
If your application is not listed, please, see Atlassian's documentation for details on adding an application to Crowd.
You must also add the Office 365 groups whose members are allowed to authenticate in the Groups tab of each of your applications.
Step 3 - Application configuration
You must now add the Crowd server to the list of user directories that your application (e.g. Jira) will rely on.
Log into your application as an administrator, select User management in the Administration pane and click on User Directories. Then click on Add Directory, select Atlassian Crowd and click on Next.
- Fill in the required fields in Server Settings
- Select Read Only in Crowd Permissions. Then select Enable Nested Groups and uncheck Enable Incremental Synchronisation. Finally click on Test Settings and then on Save and Test.
- Click on Synchronise.
Once the synchronisation is over, you should see all your Office 365 users and groups in the User Management pane.
- Finally you should disable the built-in User Management in your application as detailed in Atlassian's documentation. If you don't, users will still see the Forgot Password link on your application's login form and will also see the link to reset their password in their profile pane. They should not see these links anymore as their account is now managed in Office 365.
About users with Multi-Factor Authentication (MFA) enabled
Some of your users might have enabled Azure AD Multi-Factor Authentication (MFA) on their Office 365 account. These users will have to create an app password
for Crowd in their Office 365 account. This app password
must then be used in each Atlassian application's login form to authenticate. Please see Microsoft's documentation
for details on creating an app password in Office 365.
Please note that users with Azure AD Multi-Factor Authentication (MFA) enabled MUST have a valid Office 365 Exchange Online mailbox to login.
If you have enabled Crowd SSO, your users will log into a first application with their Office 365 account and then they will be able to browse from one application to another without reauthenticating.
However, if you configured the Cleito ODCC plugin with the odcc.remove.domain.in.username
option, your users will have to use their short username (e.g. firstname.lastname
) when logging in first. As a matter of fact, if the odcc.remove.domain.in.username
option is enabled and your users authenticate with their full userPrincipalName
), then Single Sign-On won't work and your users will have to authenticate again.
About newly created users
Newly created (or recently unlocked) users in Office 365 / Azure AD might have to log into their Office 365 account and change their password before they can log onto your Atlassian applications.
Users with Azure AD Multi-Factor Authentication (MFA) enabled might also encounter an issue if there is a delayed synchronization between Active Directory Domain Services and the Microsoft Exchange Information Store service. Please see Microsoft's documentation
for more details about these synchronization issues.
If you need to upgrade CLEITO ODCC, replace CLEITO-ODCC-1.x.jar
in the crowd-webapp/WEB-INF/lib
directory of your Crowd server. Then restart Crowd.
Entering license key
Go to the Attributes
tab of your Office 365 Directory Connector in Crowd administration console, enter your license key in the value field of the odcc.license
attribute, click on Add
and then on Update
Uninstall / Emergency
The ODCC plugin does not store anything locally. All your users and groups are stored in Office 365 / Azure Active Directory and only there. They are not replicated in Crowd's database. Therefore, if you want to stop using the ODCC plugin (for instance because your organization has decided to migrate away from Office 365) you will need to export your users and groups from Azure AD and import them into another Crowd's directory. You might also want to migrate your Office 365 Cloud accounts to Crowd local accounts in an emergency situation where your Crowd server has lost connectivity to Office 365 / Azure AD.
In such cases, please follow the next instructions:
- On your Windows workstation, install the PowerShell Azure AD module as detailed in Microsoft's documentation
- Download and unzip ExportOffice365UsersAndGroups.zip
- Edit the ExportOffice365UsersAndGroups.ps1 script and modify the ODCC options so as to match your configuration
- Then run the script in a PowerShell or command line prompt
You will be prompted a username and password. You can use any Office 365 / Azure AD account here, this does not have to be an Administrator account.
Once the script has finished running, you will find two CSV files on your local path:
Please note that the passwords included in users_file.csv have been randomly generated by the script. These are not the users' passwords in Office 365 since the users' credentials cannot be extracted from Azure AD.
- Now go to Crowd administration console and follow Atlassian's instructions to import the CSV files in any of your Crowd directories (e.g. Internal, LDAP). Please note that Crowd's CSV importer does not support nested groups so you will have to manually add groups as other groups' members when the import is over.
- For each of your applications (e.g. Jira, Confluence), add the directory in which you imported your users and groups to the list of authorized directories (in first position). Please also make sure to add the required groups to the list of authorized groups for your applications.
- Finally, make sure that your users can log onto your applications using the passwords that were randomly generated by the script. Then remove the ODCC directory from the list of authorized directories for your applications.
Troubleshooting and problem resolution
Whatever your problem is, please go to the Attributes
tab of your Office 365 Directory Connector in Crowd administration console, then set the value of the odcc.log.level
attribute to FINE
ODCC events will be logged into the apache-tomcat/logs/catalina.out
file of your Crowd server. They are all prefixed by the [ODCC]
string so you can easily parse the generated log file.
When you have solved your problem, you can turn back the log level to INFO
Please note that if you do not get any ODCC event in the logs
, that is most probably because you forgot to edit the log4j.properties
file as detailed at the beginning of Step 2
Do not remain stuck with a configuration issue
Feel free to contact us at email@example.com