Authentication

There are two possible sources of credentials for users in an ACE installation: LDAP and a *NIX-like password file. At least one of the sources have to be configured for ACE to start correctly.

It's also possible to use both sources at the same time; users from both sources will then be used.

NOTE: In addition to being present in one of the configured authentication sources, a user must also have a user role definition in order to be able to authenticate. See UserRoles for more information.

Password file

The ACE security service will by default try to read user credentials through a password file located at /opt/ace/passwd inside the Content Service. There is no default password file shipped with ACE.

The password file is on the same format as *NIX /etc/passwd files:

# System users

user1:$1$SALT$YQNBYRN9kIvLkQIp4SpsO0
user2:$1$OTHERSAL$HWbaC1l6oscA8my7Tq0bi0

The hashedPassword part of each password file entry is on the format $1$salt$hashedPassword and can be generated using any standard *NIX toolchain such as openssl or perl / python. For example, the following will generate a new password entry string using openssl and MD5:

[user@host ~]# openssl passwd -1 -salt SALT PASSWORD
$1$SALT$YQNBYRN9kIvLkQIp4SpsO0

Any standard hashing algorithm (MD5, SHA-256, SHA-512 etc) is supported.

In order to add a custom password file, simply mount a new file onto /opt/ace/password in the Content Service container.

Configuration files such as the password file contains sensitive information. Always make sure to store such files securely and limit access to trusted staff. When mounting the password file inside Docker or Docker Swarm, it's advisable to use Docker Secrets.

LDAP

In addition to a password file, ACE can also authenticate using LDAP. However, only simple authentication is supported at this time. We recommend communicating with the LDAP server using SSL (ldaps).

Please see the Content Service configuration for more information.

Amazon Cognito

As a more cloud-friendly alternative to the direct LDAP connection or password file, ACE supports using Amazon Cognito for authentication.

AWS IAM user

All Cognito authentication communication from ACE is handled using a configured AWS IAM user. The user is required to have the following permissions:

• cognito-idp:AdminInitiateAuth
• cognito-idp:ListUsers

The user credentials of the IAM user are configured in either Content Service configuration or in the Docker mounted /opt/ace/cognito-credentials.json file.

/opt/ace/cognito-credentials.json example:

{
  "accessKey": "...",
  "secretKey": "..."
}

Content Service configuration example:

  cognito:
    ...
    # Location of the file containing the Cognito IAM credentials. Don't change
    # this setting, use Docker secrets instead.
    credentialsFile: file:/opt/ace/cognito-credentials.json
    # IAM access key to be used for user verification with cognito
    accessKey: ${COGNITO_ACCESS_KEY!""}
    # IAM secret key to be used for user verification with cognito
    secretKey: ${COGNITO_SECRET_KEY!""}
    ...

NOTE: any credentials details configured using environment variables will have precedence over Content Service configuration.

A full configuration example for Amazon Cognito can be found in the Content Service configuration.

Notes

ACE system users

IMPORTANT: ACE need access to a system user in run-time to function properly. If your LDAP server cannot be guaranteed to have a consistent up time, this user should be kept in an ACE password file (see above) instead.

The system user is called admin: this user is the default administrative user shipped with ACE. You can set any custom password for it.

Credentials source precedence

ACE will always try to locate user credentials using the ACE password file before attempting any configured Amazon Cognito or LDAP authentication sources. Please note, however, that if a user is defined in both sources, but with conflicting passwords, any authentication attempts for such a user using the password defined in LDAP will be seen as an authentication FAILURE.