Go User Documentation

Authentication

Go was built from the bottom up with security in mind. Go server provides both an http service and an https service by default. The http service listens on port 8153 and the https service listens on port 8154.

By default, Go does not require users to authenticate. However we provide two mechanisms for you to force users to authenticate if you wish to. You can create a password file (in standard Apache htpasswd syntax) to authenticate log in requests. Alternatively Go can authenticate against LDAP or ActiveDirectory servers.

You can use both password file and LDAP/ActiveDirectory authentication at the same time. In this case Go will first try and authenticate you against the password file. If it cannot find your username, or if it finds that your username and password do not match, it will try LDAP/AD next. This can be very useful if you need a read-only user that can be used by scripts, and you do not want to add this user to your LDAP.

File Based Authentication

The simplest way to authenticate people is to create a password file for Go to use. This is just a plain text file with the following format:

[username]:[password hashed with SHA1 and encoded with base 64]

If your SHA1 algorithm and base 64 encoding works properly, the password "badger" should come out as "ThmbShxAtJepX80c2JY1FzOEmUk=".

You can put as many username/hashed password pairs as you like -- use a new line for each one.

To configure Go to use a password file for authentication:

Login to Go as an admin
Navigate to the "Admin" section
Click on the "Server Configuration" tab
Fill out the "Password File Settings" field under the "User Management" section

Go should pick up this change immediately and start authenticating new users (note that anybody already using Go will be required to re-authenticate).

The file format for the password file is the standard one for Java Properties, which means that spaces, the equals sign, and the colon are special characters in the username and must be escaped with a backslash.

Generating passwords using htpasswd

You can use the htpasswd program from Apache to manage your password file. You must use the -s option with htpasswd to force it to use SHA1 encoding for the password. So for example, you can use the following command to create a password file called "passwd" and put the password for the user "user" in it:

htpasswd -c -s passwd user

htpasswd on Windows

htpasswd is not available on windows, but there are plenty of websites that perform the encryption for free. Make sure you use the SHA1 algorithm.

htpasswd on Mac OSX

htpasswd is already installed by default on Mac OSX.

htpasswd on Linux

Debian based distributions (e.g. Ubuntu) htpasswd can be installed from the apache2-utils

$ apt-get install apache2-utils

Generating passwords using python

Another option is to use the following command (assumes python is installed on your system)

$ python -c "import sha;from base64 import b64encode;print b64encode(sha.new('my-password').digest())"

LDAP/ActiveDirectory Authentication

Go can authenticate against an LDAP or Active Directory (AD) server. Go uses the standard JNDI APIs to access LDAP/AD, using the well known Acegi Security framework. Go uses "bind" authentication to authenticate directly to the LDAP/AD server.

Note that LDAP/AD Authentication can be complex to configure. We highly recommend that you work with your network administration staff to configure this feature.

To configure Go to use LDAP/AD for authentication:

Login to Go as an admin
Navigate to the "Admin" section
Click on the "Server Configuration" tab
Fill out the "LDAP Settings" under the "User Management" section

The Manager DN is the LDAP/AD manager user's DN, used to connect to the LDAP/AD server.

The Manager Password is the LDAP/AD manager password, used to connect to the LDAP/AD server. Use the 'change password' checkbox to edit the password.

The Search Base is the name of the context or object to search in for the user record. If you have more than one search base, please separate each of them with a new line.

The Search Filter is the expression used in the user search. It is an LDAP search filter as defined in RFC 2254 with optional parameters -- in this case, the username is the only parameter. An example might be:

(uid={0})

which would search for a username match on the uid attribute, or

(sAMAccountName={0})

which would search for a username match on the sAMAccountName attribute (for ActiveDirectory users)

Click on Check LDAP button to check if your LDAP configuration is correct. This will bind to the LDAP server using the credentials provided in Manager DN and Manager Password.

Check LDAP will report an error if Search Base contains invalid dc information. However, it will not detect invalid ou

The authentication operation has two steps: firstly, Go uses the Manager DN and Manager Password supplied to search for the user using the searchBase and searchFilter attributes. Go will search subtrees and time out after five seconds. Go then uses the DN returned to attempt to bind to LDAP/AD using the username and password supplied by the user.

Note that Go doesn't retrieve any further information from LDAP/AD such as roles, groups or email address. It simply gets the user's CN.

If multiple search bases are configured, Go server will look for the specified user in each search base, one after the other. It will stop searching when it finds the information in a search base. In case any of the search bases are invalid, Go server will log this information in the server log, but continue searching in the remaining search bases.

Controlling User Access

Once a user is authenticated, Go checks to see if he is an existing user or a new user (logging in for the first time). If a new user, there are two behaviors Go can operate under:

Automatically register the new user in Go and continue with the login process. This option has implications on licensing because auto-registering any new user who is in LDAP might cause you to run over your license limit. So keep that in mind when using this option.
Deny access to the user if not already a registered Go user. New users will have to be explicitly added by an admin.

To switch the mode in which the Go Server operates:

Login to Go as an admin
Navigate to the "Admin" section
Click on the "Server Configuration" tab
Set the "Allow users that exist in LDAP or in the password file to log into Go, even if they haven't been explicitly added to Go" checkbox

Common errors

Below are few of the common errors you might encounter while integrating with an authentication provider

Bad credentials

Invalid username/password combination. Please check if the combination is valid and try again.

User [username] not found in directory

A user with [username] is not found in LDAP. Please check with your LDAP administrator to verify if the user exists.
Check with your Go Administrator to verify that the user with [username] exists in the LDAP search base configured in Go.

Empty username not allowed

The user has supplied an empty username. Please enter a valid username in the field.

Failed to authenticate with your authentication provider. Please check if your authentication provider is up and available to serve requests.

Your LDAP server could not be reached by Go Server. Please check with your LDAP Administrator to resolve connectivity issues, if one exists, between Go Server and LDAP.
Please check with your Go Administrator to verify that the LDAP configuration is correct. Also check the Go Server logs for errors.

User license limit exceeded, please contact the administrator

This error is displayed when the number of users logged into Go has exceeded the number permited by the license. This typically happens when an existing license expires. It can also happen if a license which allowed certain number of users has been replaced by another which allows a lesser number of users.

Your account has been disabled by the administrator

This error is displayed when the user trying to log into Go has been disabled by the administrator. Please check with your Go Administrator.