Overview

ODCC Overview

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:

  1. First of all, you will need to create an application account in Office 365. That account will be used by the ODCC plugin to browse your Office 365 instance and get its users and groups.
  2. Then you will configure the ODCC plugin in Crowd administration console. In this step, you will obviously enter the credentials of the previously created application account. 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.
  3. 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.


Prerequisites

Office 365 uses the cloud-based user authentication service Azure Active Directory to manage users. This implies two prerequisites for the use of the ODCC plugin:

  1. 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.
  2. 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.
Besides, as Cleito ODCC uses the Exchange Web Services (EWS) API for user authentication, your users will need a valid Office 365 Outlook (mail) account.


System requirements

Crowd server

  • Atlassian Crowd 2.9.x, 2.10.x, 2.11.x and 2.12.0 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:
  • https://graph.microsoft.com
  • https://graph.windows.net
  • https://login.microsoftonline.com
  • https://outlook.office365.com
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 on port 993.


Step 1 - Office 365 configuration

  1. Log into Microsoft Azure 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.

    Directory ID
  2. Now, click on Azure Active Directory > App registrations and then click Add.

    App registrations
    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.

    Create app registration
  3. Click on the display name of the app you have just created.

    App display name
    Note down the Application ID as you will need it in the rest of the configuration process. Then click on All settings.

    Application ID
  4. Click on Keys.

    Keys
    Then enter a description, select an expiration time and click on Save.

    Key fields
    Note down the key value / application secret as you will need it in the rest of the configuration process.

    Key value
  5. Click on Required permissions.

    Required permissions
    Then click on Windows Azure Active Directory.

    Windows Azure Active Directory permissions
    Check Read directory data in Application Permissions and click on Save.

    Read directory data
  6. These permissions must now be validated by an Office 365 / Azure Active Directory administrator. Ask you Office 365 administrator to open a browser to the following address:
    https://login.microsoftonline.com/<DIRECTORY_ID>/adminconsent?client_id=<APPLICATION_ID>&state=12345&redirect_uri=<SIGN_ON_URL>
    For instance:
    https://login.microsoftonline.com/23c5****-****-****-****-************/adminconsent?client_id=7a6*****-****-****-****-************&state=12345&redirect_uri=http://crowd.cleito.com:8095/crowd
    Once logged in, your Office 365 administrator will see the following page:

    Admin validation
    After clicking on Accept, your Office 365 administrator will be automatically redirected to:
    <SIGN_ON_URL>?admin_consent=True&tenant=<DIRECTORY_ID>&state=12345
    For instance:
    http://crowd.cleito.com:8095/crowd?admin_consent=True&tenant=23c5****-****-****-****-************&state=12345
    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

  1. Download and unzip the CLEITO ODCC archive somewhere on your Crowd server.

  2. Copy the content of the lib directory to the crowd-webapp/WEB-INF/lib directory of your Crowd server.

  3. If you are running Atlassian Crowd v2.10.2 or later, please also copy the content of the extra-libs directory to the crowd-webapp/WEB-INF/lib directory of your Crowd server.

  4. Edit crowd-webapp/WEB-INF/classes/log4j.properties and add the following lines at the end of the file:

    ### CLEITO ODCC ###

    log4j.logger.com.cleito=ALL

    log4j.logger.javax.mail=WARN

    log4j.logger.com.sun.mail.imap=WARN
  5. Restart Crowd.

  6. Log into Crowd administration console, click on Directories and then on Add directory

    Select Custom for the directory type and click on Next.

    Select directory type
  7. Give the connector a name and a description, and enter com.cleito.odcc.directory.Office365RemoteDirectory in the Implementation class field. Then click on Continue.

    Create custom connector
  8. Click on the Attributes tab and add each of the following attribute-value pair:

    Attribute Value Description
    ms.tenant_id <DIRECTORY_ID> The Directory ID of your Office 365 instance
    ms.client_id <APPLICATION_ID> The ID of the application that you created in Step 1
    ms.client_secret <SECRET_KEY> The value of the secret key that you created in Step 1
    Finally click on Update.

    Directory attributes
  9. Now click on Users or Groups. You should see all the identities of your Office 365 instance.
    Office 365 identities 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.

  10. You might have noticed in the previous example that the default Crowd usernames are in the form shortusername@yourdomain.com. 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:

    Attribute Description Default Value Available since version
    odcc.remove.domain.in.username 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.
    false 1.0
    ms.client_domain The domain name part of your users UPN in Office 365, e.g. yourdomain.com or yourdomain.onmicrosoft.com 1.0
    odcc.get.user.avatar 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.
    false 1.0
    odcc.fetch.users.from.groups 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.
    1.1
    odcc.limit.groups 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.
    1.0
    odcc.users.search.restriction.local 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.
    true 1.1
    odcc.groups.search.restriction.local 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.
    false 1.1
    odcc.authentication.protocol Either https or imaps

    When set to imaps, the ODCC plugin will use the IMAPS protocol to authenticate end-users on Office 365.
    https 1.0
    http.max.connections The maximum number of HTTP connections in the connection pool when requesting Office 365 20 1.0
    http.timeout The HTTP connection timeout (in milliseconds) when requesting Office 365 20000 1.0
    http.proxy.host The server name of the proxy server used to request Office 365, e.g. internal-proxy.cleito.com 1.0
    http.proxy.port The port of the proxy server used to request Office 365, e.g. 3128 1.0
    http.proxy.username The username used to authenticate with the proxy server. This can only be used with TLS/SSL termination proxies. 1.0
    http.proxy.password The password used to authenticate with the proxy server. This can only be used with TLS/SSL termination proxies. 1.0
    imaps.timeout The IMAPS connection timeout (in milliseconds) when requesting Office 365 10000 1.0
    odcc.log.level Either INFO or FINE

    The log level used by the ODCC plugin
    INFO 1.0
    odcc.license The commercial license key to be entered after purchasing the product 1.0
  11. 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.

    ODCC App Directories
    You must also add the Office 365 groups whose members are allowed to authenticate in the Groups tab of each of your applications.

    ODCC App Groups


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.

  1. 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.

    Add directory
  2. Fill in the required fields in Server Settings

    Crowd Server Settings
  3. 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.

    Crowd Advanced Settings
  4. Click on Synchronise.

    Crowd Synchronisation
    Once the synchronisation is over, you should see all your Office 365 users and groups in the User Management pane.

  5. 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 2-step verification users

Some of your users might have enabled 2-step verification on their Office 365 account. As of today, Crowd does not support two-factor authentication nor two-step verification. Thus 2-step verification users have to create an app password for your Atlassian Stack in their Office 365 account. This app password must then be used in the Atlassian application (e.g. Jira) login form to authenticate. Please see Microsoft's documentation for details on creating an app password in Office 365.


About SSO

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 (e.g. firstname.lastname@yourdomain.com), 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 will have to log once into their Office 365 Outlook (mail) account before they can authenticate to your Atlassian applications. The ODCC plugin actually uses the Exchange Web Services (EWS) API for user authentication and thus requires a valid and working Office 365 Outlook (mail) account. There might also be 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.


Upgrading

If you need to upgrade CLEITO ODCC, replace CLEITO-ODCC-1.x.jar with CLEITO-ODCC-1.1.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.

ODCC license


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:

  1. On your Windows workstation, install the PowerShell Azure AD module as detailed in Microsoft's documentation
    Install-Module AzureAD
  2. Download and unzip ExportOffice365UsersAndGroups.zip

  3. Edit the ExportOffice365UsersAndGroups.ps1 script and modify the ODCC options so as to match your configuration

  4. Then run the script in a PowerShell or command line prompt
    powershell ./ExportOffice365UsersAndGroups.ps1
    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. Export script authentication
    Once the script has finished running, you will find two CSV files on your local path:
    • users_file.csv
    • group_memberships_file.csv

    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.

    Export script command prompt
  5. 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.

  6. 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.

  7. 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 FINE log level
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. ODCC logs 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