Email Server and Authentication

Configure and Test Mail Server

When identity is added, an email is sent with randomly generated password to the user. When a user wants to change the email or password, a verification is sent via email as well. If you have not set up an email server, the default behaviour is to store the emails in the “/mail” folder within the software. This is usually for diagnosis or debugging purposes. It is recommended to set up a mail server at the start. Below are two examples of how to set up a mail server. Example 1: Uses Gmail

  1. Gmail allows only OAuth2 authentication without weakening security. Visit https://console.developers.google.com/apis/credentials to set up a “clientID” and “clientSecret”. Use these to generate a “refreshToken”.

  2. In the software root folder, navigate to the “/etc” folder. Open the application.conf file using a text editor. In the “elixir.mail” section, edit the following with the information obtained earlier accordingly.

    elixir.mail {
smtp = "gmail"
gmail {
host = "smtp.gmail.com"
port = 587
debug = true
oauth2 {
userName = "xxx@gmail.com"
clientId = "XXXX"
clientSecret = "YYYY"
refreshToken = "ZZZZ"
}
}
}

  3. After the above is edited in the application.conf file, start the software server and go to Identities module to create a user with a valid email address.

Example 2: Uses AWS

  1. In the software root folder, navigate to the “/etc” folder. Open the application.conf file using a text editor. In the “elixir.mail” section, edit the following:

    elixir.mail {
smtp = "aws"
aws {
from = "<user@example.com>"
host = "<hostname>"
dnsResolver = ""
port = 465
user = "XXXX"
password = "YYYY"
connectionTimeout = 30000
tls = true
ssl = true
authMechanism = ""
debug = false
}
}

  2. After the above is edited in the application.conf file, start the software server and go to Identities module to create a user with a valid email address.

Use GitLab As Authentication

The Identities module in the software provides a simple mechanism for authentication (determining who is logging in). If you already have an authentication system, such as an SSO, LDAP or Active Directory, then it is possible to use that as the authentication mechanism. This identity management system is built upon OAuth2, which is what makes it possible to plug in alternate authentication providers. If an external authentication system is used, the Identities module is not needed and should be removed to avoid confusion. This section describes the steps to set up GitLab as the authentication method to log into the software. The steps are as follows:

  1. Create an account in GitLab.

  2. In GitLab, add Ambience software as an application under your user.

    Note that URL callback should be http://hostname:1740/authclient for Ambience. Use port 1730 for Repertoire. This is consistent with the setting in application.conf file.

  3. Change the hostname on your machine to point to the proper endpoint (i.e., the added application).

  4. Add the user into Users module with the same name that was created in the GitLab server.

  5. Go to the software root directory and go to the “/etc” folder. Open the application.conf file using a text editor.

  6. Make the following changes in the “elixir.sso.client” section.

    elixir.sso.client {
cookie-name = "elx-amb"
cookie-same-site = "Lax"
openid-field = "name"
openid-scope = "openid email"
service-definition {
elxsso {
authorization = "https://<gitlab-host>/oauth/authorize"
token = "https://<gitlab-host>/oauth/token"
userinfo = "https://<gitlab-host>/oauth/userinfo"
logout = ${sso-server-baseurl}"/simple-sso/logout"
debug = false
client {
id = "[Your Application ID]"
secret = "[Your secret]"
endpoint = ${sso-client-baseurl}"/authclient"
}
}
}
}

  7. Save the application.conf file.

  8. Restart the software server. Open a browser and key in “localhost:1740” in the address bar and hit the enter key.

    For Repertoire, key in “localhost:1730” in the address bar.

  9. Log into the software with your GitLab account.

Two-factor Authentication

Ambience/Repertoire software supports Time-based One-time Password (TOTP) Two-factor Authentication (2FA). By default, 2FA is disabled in the application.conf file. To enable 2FA, edit the application.conf file in two areas:

  1. Under the simple-server section, change show-totp = false to true. This is to allow the login dialog to include 2FA.

    simple-server {
clients {
ambience {
secret = "171ccf22-670a-43c2-ac79-05c44bf305e3"
redirect = ${sso-client-baseurl}"/authclient"
#login-page = "" # set resource file here to use a custom login page for this client
landing-page = "http://"${host}":"${port}"/"
name = "Elixir Ambience"
show-totp = true
}
}
}

  2. Add a new line in the application.conf file. This will allow User Settings module to include 2FA setup, in which users can set up their own 2FA.

    ambience.user-settings.enable-panel.totp = true

Next: Configure Ambience