Set up LDAP authentication

You can manage and authenticate ALM Octane users using your organization's LDAP system.

Caution: Once you set up LDAP authentication, you cannot continue using ALM Octane built-in, native, internal user management. You cannot have a mix of users created with ALM Octane internal user management and users imported from LDAP.

Overview

This topic provides a workflow and overview for setting up ALM Octane for LDAP user authentication.

Workflow

Configure Define LDAP settings in the octane.yml file either during installation or any time after. For details, see how to configure other settings in the ALM Octane Installation Guide.
Restart

Restart the ALM Octane server. The LDAP settings defined in the octane.yml file take effect each time you restart the ALM Octane server. For details on restarting the server, see the ALM Octane Installation Guide.

Note: After restarting the server, any previously-defined native ALM Octane users (both admins and regular) can no longer access the ALM Octane server. Only the AdminDN user defined in the octane.yml file has access. The AdminDN logs in using the specified email (not using the name defined in octane.yml).

Export users from LDAP system Export users using your LDAP configuration tool. For details, see Export and import users.
Import LDAP users into ALM Octane Import LDAP users using the ALM Octane Settings area. LDAP users can be imported the shared space or the workspace. You need shared space admin or workspace admin permissions, respectively. See Export and import users.
Update (optional)  Over time, update LDAP users or the LDAP server properties as necessary. For details, see Update LDAP user or LDAP server properties.

How ALM Octane adds LDAP users

New and existing users are added into ALM Octane differently:

  • New, unique users are assigned to the default workspace with the team member role. Users are considered unique if either their logonName or their email (as defined in the octane.yml file) does not match the mapped attributes of the imported LDAP users.

  • If both the logonName or email of an existing, native ALM Octane user matches the details of an imported user, ALM Octane updates the details of the existing, native user to reflect that the existing user is an LDAP user.

  • Existing, native ALM Octane users that do not match details of imported users are not updated. These users are unable to log in to ALM Octane after the import. We recommend you manually deactivate these users, because they cannot log into ALM Octane. For details on deactivating users, see Activate or deactivate a user.

Back to top

Using the REST API to create an LDAP user

You can create LDAP users using the REST API by posting the user with certain LDAP attributes.

You cannot use the REST API to import existing LDAP users.

For details, see the details about creating users in the ALM Octane Developer Guide.

Back to top

Export and import users

  1. If you are using LDAP over SSL:

    • Retrieve the certificate of the authority that issued the LDAP server certificate.

    • Install the certificate on the ALM Octane JRE keystore.

  2. In your LDAP configuration tool, export user details to a .csv file. If you have more than one LDAP server, create a separate .csv file for each one.

    Caution: After exporting to the .csv file, do not open the file in Microsoft Excel, even just for viewing purposes. This is because opening a .csv file in Microsoft Excel can change the file to a non-csv format. ALM Octane supports only the csv file format.

    If you want to view the .csv file, for example, to make sure it contains all headers, open the file with a simple text editor like Notepad. Do not make any changes to the file.

    When you export user details, you must use the exact attributes listed in the octane.yml file, and in the exact order the attributes are listed there.

    Your .csv file should have the following:

    • A header file containing the attributes in the octane.yml file.

    • Lines for each user, containing the values for the attributes included in the header.

    Example:
    dn,givenName,sn,cn,uid,mail,telephoneNumber,homePhone
    "uid=stark@default.com,ou=People,o=default.com","Tony","Stark","Tony Stark","stark@default.com","stark@default.com","+000 00 11111222","+000 00 11111222",
    "uid=c@default.com,ou=People,o=default.com","Chris","C","Chris C","c@default.com","c@default.com","+000 00 11111222",,
    "uid=g@default.com,ou=People,o=default.com","Greg","G","Greg G","g@default.com","g@default.com","+000 00 11111223","+000 00 11111233",
    "uid=k@default.com,ou=People,o=default.com","Kenny","K","Kenny K","k@default.com","k@default.com","+000 00 11111225",,
    "uid=m@default.com,ou=People,o=default.com","Maria","M","Maria M","m@default.com","m@default.com","+000 00 11111224","+000 00 11111288",
    "uid=p@default.com,ou=People,o=default.com","Peter","P","Peter P","p@default.com","p@default.com|palias@default.com","+000 00 11111333",,
    "uid=s@default.com,ou=People,o=default.com","Susan","S","Susan S","s@default.com","s@default.com","+000 00 11111444",,
    "uid=v@default.com,ou=People,o=default.com","Mark","V","Mark V","v@default.com","v@default.com","+000 00 11111555","+000 00 11111666",
    "uid=a@default.com,ou=People,o=default.com","Tony","A","Tony A","a@default.com","a@default.com","+000 00 11111277","+000 00 11111888"
    

    For an example of how to do this, see the following KB.

  3. Log in to ALM Octane using the login name for the AdminDn user in the octane.yml.

  4. In Settings, choose Shared Space, or select a workspace. This determines the context in which you import the users.

    Shared space

    Creates or updates shared space users.

    New users are assigned to the default workspace with the team member role, which is the default role for all new users until other roles are assigned.

    Workspace

    Creates or updates a workspace user.

    The users are assigned with the role selected in the import dialog.

  5. Choose the Users tab.

  6. In the toolbar, click Import.

  7. In the import dialog, select:

    • The relevant .csv file.

      Note: If you have more than one LDAP server, import each file separately.

    • The LDAP server from which the .csv file was exported.

    • The role to assign to all imported LDAP users.

    Click OK to import.

  8. Check the response that is returned after the import.

    This includes the number of users successfully imported, and errors for each user that did not import successfully.

    The error report can be found in the server logs by the correlation ID.

    The errors report specifically which users in the .csv file were not imported successfully. Users are identified by index of the line number in the .csv file.

    If there are errors, resolve them in your LDAP user configuration tools or in the .csv file. Then reimport the .csv file.

Back to top

Update LDAP user or LDAP server properties

When using ALM Octane with LDAP, ALM Octane does not manage user details other than the user avatar. Instead, user details are managed by your LDAP server.

Here are some scenarios which would necessitate that you make LDAP updates, and how to make the updates.

User attribute changes

These changes include changes to a specific user attribute, such as the user's last name.

These changes do not include changes to the attributes that are mapped to the ALM Octane logonName or the email (as defined in the octane.yml file) as these are unique identifiers.

To update user details:

  1. Update the details in the LDAP configuration tool.

  2. Re-export the users using a new .csv file, making sure the attributes are in the exact order as in the octane.yml file.

  3. Re-import the .csv file to ALM Octane.

LDAP server changes

These changes include changes to a specific LDAP server attribute, such as the LDAP server's ID or IP address.

If you update the LDAP server ID, you must also update your users in ALM Octane. This is because the LDAP server details are included in the details for each of the LDAP users.

To update LDAP server details:

  1. Using your LDAP configuration tool on the new LDAP server, export the users to a .csv file.

    When you export user details, you must use the exact attributes listed in the octane.yml file, and in the exact order the attributes are listed in the file.

  2. In the octane.yml file, modify the details for the LDAP server. For details, see the ALM Octane Installation Guide.

  3. Restart your ALM Octane server. For details on how to restart your server, see the ALM Octane Installation Guide.

  4. In ALM Octane, re-import the .csv file. In the Import dialog, select the name of the new LDAP server.

The details are updated for the users, including the server details.

User logon name or email changes

Each ALM Octane user is uniquely identified by their name and their email (logonName and email, as defined in the octane.yml file).

If a user's email or logon name changes in LDAP, ALM Octane recognizes that user as a new user.

To update these unique identifying attributes, without creating new users, contact ALM Octane customer support.

Back to top