Start Building for Free


3 months ago3 min read
Server v2.x
Server Admin
On This Page

This document describes the various ways users of your CircleCI server v2.x installation can get access and authenticate their accounts. CircleCI server v2.x supports OAuth and LDAP as authentication methods.

OAuth with GitHub/GitHub Enterprise

The default method for user account authentication in CircleCI server is through Enterprise OAuth.

After your installation is up and running, provide users with a link to access the application - for example <your-circleci-hostname>.com – and it will prompt them to set up an account by running through the GitHub/GitHub Enterprise OAuth flow. The application will then redirect them to the CircleCI login screen.

Server Login
Figure 1. CircleCI Server v2.x Login Screen


As an alternative to the OAuth/GitHub option, you can choose LDAP authentication. Many organizations use a LDAP server to centralize all their identity information in a single place. This section describes how to enable, configure, and test CircleCI to authenticate users with OpenLDAP or Active Directory credentials.


  • Install and configure your OpenLDAP server or Active Directory.

  • Configure GitHub Enterprise or to be the source of organizations and projects to which users have access.

  • Install a new instance of CircleCI server v2.x with no existing users.

Configure LDAP Authentication

This section provides information to configure LDAP. Below is an example configuration to give an idea of the information types required. The example shows OpenLDAP in use but the settings for Active Directory are comparable:

LDAP Example
Figure 2. LDAP Config Example

These are the steps to configure LDAP in the CircleCI server v2.x management console:

  1. Verify access over the LDAP/AD ports to your LDAP/AD servers.

  2. Log in as administrator to the Management Console for your newly installed CircleCI instance.

  3. Navigate to the Settings page (for example <your-circleci-hostname>.com:8800) and scroll down to check the Enable LDAP-only Authentication button. Select either OpenLDAP or Active Directory.

  4. Fill in your LDAP instance Hostname and port number.

  5. Select the encryption type (plain text is insecure and thus not recommended).

  6. Fill in the Search user field with the Fully Distinguished Name for a user you authorize to perform search queries over a LDAP database. Example: cn=<admin>,dc=<example>,dc=<org>.

  7. Fill in the Search password field with the LDAP password for a user from the previous step.

  8. Fill in the Base DN field with a Distinguished Name for a point in the directory from where CircleCI will be looking for users/groups. Example: ou=company,dc=example,dc=org

  9. Fill in the User search DN field with a Relative Distinguished Name for a point in a directory where CircleCI will find users. Should be relative to the Base DN provided above. Example: ou=users.

  10. Fill in the Username field with a name of an attribute that is the source of usernames for Logging In. Example: uid (in this case users will have to use their UID for logging in) or mail (in this case users will be using emails for logging in).

  11. Fill in the Email field with the name of an attribute that is the source of a user email. Example: mail

  12. Fill in the Group Membership field with a name of an attribute that is the user membership in a particular group. Example: uniqueMember.

  13. Fill in the Group Object Class field with a name of an Object Class that will identify DN as a group. Example: groupOfUniqueNames

  14. (Optional) Fill in the Test username and Test password fields with a test email and password for an LDAP user you want to test. This is a 3rd party infrastructure and this test option is not always reliable.

  15. Save the settings.

Known Issue: Grant Admin Access to User

If you are using LDAP authentication, use one of the following methods to grant admin privileges to a user. Admin privileges should be automatically granted to the first user accessing a project, but currently there is a known issue preventing this from happening when LDAP authentication is in use.

For a given user by LDAP user name (prior to GitHub account connection, or if they have no GitHub account):

(-> (circle.repl.mongo/fetch :users :domain-model :where {:login "the-ldap-username" :first_vcs_authorized_client_id nil} :limit 1)
    (circle.model.user/set-fields! {:admin "all"})

By GitHub user name (after GitHub account connection, which replaces prior :login value):

(-> (circle.repl.mongo/fetch :users :domain-model :where {:login "the-github-username"} :limit 1)
    (circle.model.user/set-fields! {:admin "all"})

By analytics ID

(-> (circle.model.user/find-one-by-analytics-id "3b35037c-6eb3-4e41-88e2-3913b2f43d96")
    (circle.model.user/set-fields! {:admin "all"})

User Interaction

After setting up LDAP, a user who logs in to CircleCI will be redirected to the Accounts page with a Connect button that they must use to connect their GitHub account. After they click Connect, an LDAP section with their user information (for example, their email) on the page will appear and they will be directed to authenticate their GitHub account. After authenticating their GitHub account users are directed to the Job page to use CircleCI.


Troubleshoot LDAP server settings with LDAP search as follows:

ldapsearch -x LLL -h <ldap_address_server>

Help make this document better

This guide, as well as the rest of our docs, are open source and available on GitHub. We welcome your contributions.

Need support?

Our support engineers are available to help with service issues, billing, or account related questions, and can help troubleshoot build configurations. Contact our support engineers by opening a ticket.

You can also visit our support site to find support articles, community forums, and training resources.