cc-backend/docs/dev-authentication.md

Overview

The authentication is implemented in internal/auth/. In auth.go an interface is defined that any authentication provider must fulfill. It also acts as a dispatcher to delegate the calls to the available authentication providers.

Two authentication types are available:

• JWT authentication for the REST API that does not create a session cookie
• Session based authentication using a session cookie

The most important routines in auth are:

• Login() Handle POST request to login user and start a new session
• Auth() Authenticate user and put User Object in context of the request

The http router calls auth in the following cases:

• r.Handle("/login", authentication.Login( ... )).Methods(http.MethodPost): The POST request on the /login route will call the Login callback.
• r.Handle("/jwt-login", authentication.Login( ... )): Any request on the /jwt-login route will call the Login callback. Intended for use for the JWT token based authenticators.
• Any route in the secured subrouter will always call Auth(), on success it will call the next handler in the chain, on failure it will render the login template.

secured.Use(func(next http.Handler) http.Handler {
	return authentication.Auth(
		// On success;
		next,

		// On failure:
		func(rw http.ResponseWriter, r *http.Request, err error) {
               // Render login form
		})
})

A JWT token can be used to initiate an authenticated user session. This can either happen by calling the login route with a token provided in a header or via a special cookie containing the JWT token. For API routes the access is authenticated on every request using the JWT token and no session is initiated.

Login

The Login function (located in auth.go):

• Extracts the user name and gets the user from the user database table. In case the user is not found the user object is set to nil.
• Iterates over all authenticators and:
  • Calls its CanLogin function which checks if the authentication method is supported for this user.
  • Calls its Login function to authenticate the user. On success a valid user object is returned.
  • Creates a new session object, stores the user attributes in the session and saves the session.
  • Starts the onSuccess http handler

Local authenticator

This authenticator is applied if

return user != nil && user.AuthSource == AuthViaLocalPassword

Compares the password provided by the login form to the password hash stored in the user database table:

if e := bcrypt.CompareHashAndPassword([]byte(user.Password), []byte(r.FormValue("password"))); e != nil {
	log.Errorf("AUTH/LOCAL > Authentication for user %s failed!", user.Username)
	return nil, fmt.Errorf("Authentication failed")
}

LDAP authenticator

This authenticator is applied if the user was found in the database and its AuthSource is LDAP:

if user != nil {
	if user.AuthSource == schema.AuthViaLDAP {
		return user, true
	}
} 

If the option SyncUserOnLogin is set it tried to sync the user from the LDAP directory. In case this succeeds the user is persisted to the database and can login.

Gets the LDAP connection and tries a bind with the provided credentials:

if err := l.Bind(userDn, r.FormValue("password")); err != nil {
	log.Errorf("AUTH/LDAP > Authentication for user %s failed: %v", user.Username, err)
	return nil, fmt.Errorf("Authentication failed")
}

JWT Session authenticator

Login via JWT token will create a session without password. For login the X-Auth-Token header is not supported. This authenticator is applied if the Authorization header or query parameter login-token is present:

	return user, r.Header.Get("Authorization") != "" ||
		r.URL.Query().Get("login-token") != ""

The Login function:

• Parses the token and checks if it is expired
• Check if the signing method is EdDSA or HS256 or HS512
• Check if claims are valid and extracts the claims
• The following claims have to be present:
  • sub: The subject, in this case this is the username
  • exp: Expiration in Unix epoch time
  • roles: String array with roles of user
• In case user does not exist in the database and the option SyncUserOnLogin is set add user to user database table with AuthViaToken AuthSource.
• Return valid user object

JWT Cookie Session authenticator

Login via JWT cookie token will create a session without password. It is first checked if the required configuration options are set:

• trustedIssuer
• CookieName

and optionally the environment variable CROSS_LOGIN_JWT_PUBLIC_KEY is set.

This authenticator is applied if the configured cookie is present:

	jwtCookie, err := r.Cookie(cookieName)

	if err == nil && jwtCookie.Value != "" {
		return true
	}

The Login function:

• Extracts and parses the token
• Checks if signing method is Ed25519/EdDSA
• In case publicKeyCrossLogin is configured:
  • Check if iss issuer claim matched trusted issuer from configuration
  • Return public cross login key
  • Otherwise return standard public key
• Check if claims are valid
• Depending on the option validateUser the roles are extracted from JWT token or taken from user object fetched from database
• Ask browser to delete the JWT cookie
• In case user does not exist in the database and the option SyncUserOnLogin is set add user to user database table with AuthViaToken AuthSource.
• Return valid user object

Auth

The Auth function (located in auth.go):

• Returns a new http handler function that is defined right away
• This handler tries two methods to authenticate a user:
  • Via a JWT API token in AuthViaJWT()
  • Via a valid session in AuthViaSession()
• If err is not nil and the user object is valid it puts the user object in the request context and starts the onSuccess http handler
• Otherwise it calls the onFailure handler

AuthViaJWT

Implemented in JWTAuthenticator:

• Extract token either from header X-Auth-Token or Authorization with Bearer prefix
• Parse token and check if it is valid. The Parse routine will also check if the token is expired.
• If the option validateUser is set it will ensure the user object exists in the database and takes the roles from the database user
• Otherwise the roles are extracted from the roles claim
• Returns a valid user object with AuthType set to AuthToken

AuthViaSession

• Extracts session
• Get values username, projects, and roles from session
• Returns a valid user object with AuthType set to AuthSession