NAV Navbar
Logo
Switch version:

Authorization Configuration

The Authorization Configuration is used to configure a connection to an LDAP/AD server. The configuration is later used by plugin to authorize a user or search for them from the LDAP/AD server. You can also configure multiple LDAP/AD servers by creating multiple authorization configurations.

  1. Login to GoCD server as admin and navigate to Admin > Security > Authorization Configuration.
  2. Click on Add to create a new authorization configuration.
  3. Provide a unique identifier for this authorization configuration and select LDAP Authorization Plugin for GoCD as Plugin Id.
  4. Url (Mandatory): Specify your ldap server URL.

    Ldap Uri
    <property>
      <key>Url</key>
      <value>ldap://ldap-server-url:10389</value>
    </property>
    
  5. StartTLS (Optional): StartTLS is a mechanism for avoiding the need to listen on a separate port for SSL connections. Enabling StartTLS would require the server certificate to be configured.

    StartTLS
    <property>
       <key>StartTLS</key>
       <value>false</value>
    </property>
    
  6. ManagerDN (Optional): The LDAP/AD manager user’s DN, used to connect to the LDAP/AD server.

    ManagerDN
    <property>
       <key>ManagerDN</key>
       <value>uid=admin,ou=system,dc=example,dc=com</value>
    </property>
    
  7. Password (Mandatory if ManagerDN provided): The LDAP/AD manager password, used to connect to the LDAP/AD server. Required only if a ManagerDN is specified.

  8. Certificate (Optional): Provide the server X.509 Certificate in PEM format if using ldaps or StartTLS is enabled. You can use keytool or openssl to generate x.509 certificate in PEM format. If a certificate is not configured, the plugin will look for server certificate in following order -

    1. Truststore defined using Java system property javax.net.ssl.trustStore.
    2. If not defined, then ${JAVA_HOME}/lib/security/jssecacerts or ${JAVA_HOME}/lib/security/cacerts.

    X.509 Certificate in PEM format

    Certificate
    <property>
       <key>Certificate</key>
       <value>
          -----BEGIN CERTIFICATE-----
          MIIDBzCCAe+...1E2mRQFQHn64AhA=
          -----END CERTIFICATE-----
       </value>
    </property>
    
  9. SearchBases (Mandatory): This field defines the location in the directory from which the LDAP search begins. You can provide multiple search bases each separated by newlines. If multiple search bases are configured the plugin would look for the user in each search base sequentially until the user is found.

    Single search base

    Single search base
    <property>
       <key>SearchBases</key>
       <value>ou=users,ou=system</value>
    </property>
    

    Multiple search base

    Multiple search bases
    <property>
       <key>SearchBases</key>
       <value>
        ou=users,ou=system
        ou=employee,ou=system
        </value>
    </property>
    
  10. UserLoginFilter (Mandatory): It is an LDAP search filter used during authentication to lookup for a user entry matching the given expression.

    • In following example, the {0} is replaced with the username provided by the user at the login screen. For an user with username bford above filter resolves to (sAMAccountName=bford).

    In the following example the filter would search for a username matching the sAMAccountName attribute.

    User login filter
    <property>
       <key>UserLoginFilter</key>
       <value>(sAMAccountName={0})</value>
    </property>
    
  11. UserNameAttribute (Mandatory): The value of this attribute will be used by GoCD as a username of the logged in user. The GoCD uses username to decide role based permissions for an logged in user.

    In the following example the UserLoginFilter uses an Or filter whereby the User can login using either of sAMAccountName, mail or uid. On successful authentication the plugin would return a User object to GoCD with the username derived from the UserNameAttribute which is sAMAccountName in this example.

    Username attribute
    <property>
       <key>UserLoginFilter</key>
       <value>(|(sAMAccountName={0})(mail={0})(uid={0}))</value>
    </property>
    <property>
       <key>UserNameAttribute</key>
       <value>sAMAccountName</value>
    </property>
    
  12. UserSearchFilter (Optional): It is an LDAP search filter used to lookup for users matching a given search term. This allows GoCD administrator to manage LDAP/AD users from User Summary Page in GoCD. Default filter used is (|(sAMAccountName=*{0}*)(uid=*{0}*)(cn=*{0}*)(mail=*{0}*)(otherMailbox=*{0}*)).

    User search filter
    <property>
       <key>UserSearchFilter</key>
       <value>(|(sAMAccountName=*{0}*)(uid=*{0}*))</value>
    </property>
    
  13. DisplayNameAttribute (Optional): The value of this attribute in the logged in user’s record in the LDAP server is used as a display name. Default attribute used is cn.

    Display name attribute
    <property>
       <key>DisplayNameAttribute</key>
       <value>displayName</value>
    </property>
    
    Display name is shown in the top right corner after loggin in -
    Display name attribute example


  14. EmailAttribute (Optional): Value of this attribute is mapped to GoCD User mail field. Default value used is mail. Once attribute is mapped, user can create custom email notification as described here

    Email attribute
    <property>
       <key>EmailAttribute</key>
       <value>mail</value>
    </property>
    
  15. SearchTimeout (Optional): Timeout in seconds for search operations, default value is 5 secs.

    Search timeout
    <property>
      <key>SearchTimeout</key>
      <value>10</value>
    </property>
    
  16. Click on Check connection to verify your configuration. The plugin will establish a connection with LDAP/AD server using the configuration and will returns the verification status.

  17. Once verify connection succeed, Click on Save to save authorization configuration.

Example authorization configuration

Authorization configuration

Alternatively, the configuration can be added directly to the GoCD config XML using the <authConfig>. It should be added under <security/> tag as described in following example -

<security>
 <authConfigs>
    <authConfig id="my-ldap" pluginId="com.thoughtworks.gocd.authorization.ldap">
      <property>
        <key>Url</key>
        <value>ldap://ldap-server-url:10389</value>
      </property>
       <property>
        <key>StartTLS</key>
        <value>false</value>
      </property>
      <property>
        <key>ManagerDN</key>
        <value>uid=admin,ou=system,dc=example,dc=com</value>
      </property>
      <property>
        <key>Password</key>
        <value>secret</value>
      </property>
      <property>
        <key>Certificate</key>
        <value>
          -----BEGIN CERTIFICATE-----
          MIIDBzCCAe+...1E2mRQFQHn64AhA=
          -----END CERTIFICATE-----
        </value>
      </property>
      <property>
        <key>SearchBases</key>
        <value>
          ou=Teams,dc=corporate,dc=example,dc=com
          ou=users,ou=system
        </value>
      </property>
      <property>
        <key>UserLoginFilter</key>
        <value>(sAMAccountName={0})</value>
      </property>
      <property>
        <key>UserNameAttribute</key>
        <value>sAMAccountName</value>
      </property>
      <property>
        <key>UserSearchFilter</key>
        <value>(|(sAMAccountName=*{0}*)(uid=*{0}*))</value>
      </property>
      <property>
        <key>DisplayNameAttribute</key>
        <value>displayName</value>
      </property>
      <property>
        <key>EmailAttribute</key>
        <value>mail</value>
      </property>
      <property>
        <key>SearchTimeout</key>
        <value>10</value>
      </property>
    </authConfig>
  </authConfigs>
</security>