Authentication

By default, authentication is not enabled, however there are some features that are not available unless users login such as watching alerts.

Alerta supports three authentication mechanisms for the web UI (Basic Auth, OAuth and SAML) as well as API keys for direct access to the API.

The most straight-forward to implment of the three is Basic Auth.

To enforce authentication set AUTH_REQUIRED to True in the alertad.conf file and SECRET_KEY to some random string:

AUTH_REQUIRED = True
SECRET_KEY = 'UszE5hI_hx5pXKcsCP_2&1DIs&9_Ve*k'

Note

Ensure that the SECRET_KEY that is used to encode cookies is a unique, randomly generated sequence of ASCII characters. The following command generates a suitable 32-character random string on Mac or Linux:

$ LC_CTYPE=C tr -dc A-Za-z0-9_\!\@\#\$\%\^\&\*\(\)-+= < /dev/urandom | head -c 32 && echo

Basic Auth

HTTP Basic authentication is a very simple method for enforcing access control.

To use Basic Auth set the provider configuration setting in the Web UI config.js file to basic. There is no additional configuration required of the Alerta server to use Basic Auth:

'use strict';

angular.module('config', [])
  .constant('config', {
    'endpoint'    : "/api",
    'provider'    : "basic"
  })
  .constant('colors', {});

Note

HTTP Basic auth does not provide any encryption of the username or password so it is strongly advised to only use Basic auth over HTTPS.

OAuth2 Authentication

OAuth authentication is provided by Google OpenID Connect, GitHub, GitLab OAuth 2.0 or Keycloak OAuth 2.0 and configuration is more involved than the Basic Auth setup.

Note

If alerta is deployed to a publicly accessible web server it is important to configure the OAuth2 settings correctly to ensure that only authorised users can access and modify your alerts.

To use OAuth2 set the provider configuration setting in the Web UI config.js file to one of google, github, gitlab or keycloak:

'use strict';

angular.module('config', [])
  .constant('config', {
    'endpoint'    : "/api",
    'provider'    : "google",
    'client_id'   : "INSERT-CLIENT-ID-HERE" // replace with the client id for your OAuth provider
  })
  .constant('colors', {});

Next, follow the steps below for the chosen OAuth provider to create an OAuth client ID and client secret. The client ID will need to be added to the web UI config.js and both the client ID and client secret will need to be added to the alertad.conf file for the Alerta server.

Google OAuth2

To use Google as the OAuth2 provider for Alerta, login to Google Developer Console and create a new project for alerta.

  • Project Name: alerta
  • Project ID: (automatically assigned)

Go to APIs and auth -> APIs and set Google+ API to ON. Next go to APIs and auth -> Credentials and click Create New Client ID and choose Web Application.

Click Create Client ID and take note of the Client ID and Client Secret. The configuration settins for alerta server are as follows:

OAUTH2_CLIENT_ID = '379647311730-sj130ru952o3o7ig8u0ts8np2ojivr8d.apps.googleusercontent.com'
OAUTH2_CLIENT_SECRET = '8HrqJhbrYn9oDtaJqExample'

To restrict access to users with particular Google apps domains use:

ALLOWED_EMAIL_DOMAINS = ['example.org', 'mycompany.com']

Note

ALLOWED_EMAIL_DOMAINS can be an asterisk (*) to force login but not restrict who can login.

GitHub OAuth2

To use GitHub as the OAuth2 provider for Alerta, login to GitHub and go to Settings -> Applications -> Register New Application.

Note

The Authorization callback URL is the most important setting and it is nothing more than the URL domain (ie. without any path) where the alerta Web UI is being hosted.

Click Register Application and take note of the Client ID and Client Secret. Then configuration settings for alerta server are as follows:

OAUTH2_CLIENT_ID = 'f7b0c15e2b722e0e38f4'
OAUTH2_CLIENT_SECRET = '7aa9094369b72937910badab0424dc7393x8mpl3'

To restrict access to users who are members of particular GitHub organisations use:

ALLOWED_GITHUB_ORGS = ['example', 'mycompany']

Note

ALLOWED_GITHUB_ORGS can be an asterisk (*) to force login but not restrict who can login.

Important

To revoke access of your instance of alerta to your GitHub user info at any time go to Settings -> Applications -> Authorized applications, find alerta in the list of applications and click the Revoke button.

GitLab OAuth2

To use GitLab as the OAuth2 provider for Alerta, login to GitLab and go to Profile Settings -> Applications -> New Application.

Note

The Redirect URL is the most important setting and it is nothing more than the URL domain (ie. without any path) where the alerta Web UI is being hosted.

Click Submit and take note of the Application ID and Secret. Then configuration settings for alerta server are as follows (replacing the values shown below with the values generated by GitLab):

GITLAB_URL = 'https://gitlab.com'  # or your own GitLab server
OAUTH2_CLIENT_ID = 'd31e9caa131f72901b16d22289c824f423bd5cbf187a11245f402e8b2707d591'
OAUTH2_CLIENT_SECRET = '42f1de369ec706996cadda234986779eeb65c0201a6f286b9751b1f845d62c8a'

To restrict access to users who are members of particular GitLab groups use:

ALLOWED_GITLAB_GROUPS = ['group1', 'group2']

Note

ALLOWED_GITLAB_GROUPS can be an asterisk (*) to force login but not restrict who can login.

Important

To revoke access of your instance of alerta to your GitLab user info at any time go to Profile Settings -> Applications -> Authorized appliations, find alerta in the list of applications and click the Revoke button.

Keycloak OAuth2

To use Keycloak as the OAuth2 provider for Alerta, login to Keycloak admin interface, select the realm and go to Clients -> Create.

After the client is created, edit it and change the following properties:

  • Access Type: confindential

Add the following mapper under the Mappers tab:

Name: role memberships
Mapper type: User Realm Role
Token Claim Name: roles
Claim JSON type: String
Add to userinfo: ON

Now go to Installation and generate it by selecting ‘Keycloak OIDC JSON’. You should get something like this:

{
  "realm": "master",
  "auth-server-url": "https://keycloak.example.org/auth",
  "ssl-required": "external",
  "resource": "alerta-ui",
  "credentials": {
    "secret": "418bbf31-aef-33d1-a471-322a60276879"
  },
  "use-resource-role-mappings": true
}

Take note of the realm, resource and secret. Then configuration settings for alerta server are as follows (replacing the values shown below with the values generated by Keycloak):

KEYCLOAK_URL = 'https://keycloak.example.org'
KEYCLOAK_REALM = 'master'
OAUTH2_CLIENT_ID = 'alerta-ui'
OAUTH2_CLIENT_SECRET = '418bbf31-aef-33d1-a471-322a60276879'

To restrict access to users who are associated with a particular Keycloak role use:

ALLOWED_KEYCLOAK_ROLES = ['role1', 'role2']

Note

ALLOWED_KEYCLOAK_ROLES can be an asterisk (*) to force login but not restrict who can login.

Cross-Origin

If the Alerta API is not being served from the same domain as the Alerta Web UI then the CORS_ORIGINS setting needs to be updated to prevent modern browsers from blocking the cross-origin requests.

CORS_ORIGINS = [
    'http://try.alerta.io',
    'http://explorer.alerta.io',
    'chrome-extension://jplkjnjaegjgacpfafdopnpnhmobhlaf',
    'http://localhost'
]

SAML 2.0 Authentication

OAuth authentication is provided by Google OpenID Connect, GitHub, GitLab OAuth 2.0 or Keycloak OAuth 2.0 and configuration is more involved than the Basic Auth setup.

SAML 2.0

Generate private/public key pair

openssl req -utf8 -new -x509 -days 3652 -nodes -out "alerta.cert" -keyout "alerta.key"

Note

This key pair is not related to HTTPS.

Configure pysaml2

Bare-minimum config example:

SAML2_CONFIG = {
    'metadata': {
        'local': ['/path/to/federationmetadata.xml']
    },
    'key_file': '/path/to/alerta.key',
    'cert_file': '/path/to/alerta.cert'
}
metadata
IdP metadata (refer to saml2 documentation for possible ways of specifying it)
key_file, cert_file
path to aforementioned keys

Refer to pysaml2 documentation and source code if you need additional options:

Note: entityid and service provider endpoints are configured by default based on your BASE_URL value which is mandatory if you use SAML (see General Settings)

ALLOWED_SAML2_GROUPS

To restrict access to users who are members of particular group use:

ALLOWED_SAML2_GROUPS = ['alerta_ro', 'alerta_rw']

Note: you need to ensure that pysaml2 authn response identity object contains groups attribute. You can do this by writing proper attribute map which will convert your IdP-specific attribute name to groups. Example:

MAP = {
    ...
    'fro': {
        ...
        'http://schemas.xmlsoap.org/claims/group': 'groups',
        ...
    },
    'to': {
        ...
        'groups': 'http://schemas.xmlsoap.org/claims/group',
        ...
    }
}

See pysaml2 attribute-map-dir documentation. attribute-map-dir can be specified in the SAML2_CONFIG, see Configure pysaml2

SAML2_USER_NAME_FORMAT

This is a python string template which is used to generate user’s name based on attributes (make sure that attribute-map-dir is properly configured in case default does not fit). Default is '{givenName} {surname}'.

Cross-Origin

You also need to add your IdP origin to CORS headers:

CORS_ORIGINS = [
    ...
    'https://sso.example.com',
    ...
]

Add trusted Service Provider to your Identity Provider

Your metadata url is: {BASE_URL}/auth/saml/metadata.xml, pass it to your IdP administrator.

API Keys

If authentication is enforced, then an API key is needed to access the alerta API programatically or to use the alerta CLI. Keys can be easily generated from the Alerta web UI and can be read-write or read-only. They are valid for 1 year but this period is configurable using API_KEY_EXPIRE_DAYS in the server configuration.

See the example CLI config for how to set the API key for the command-line tool.

To use an API key in an API query you must set the correct HTTP Authorization header:

curl 'http://api.alerta.io/alerts' -H 'Authorization: Key demo-key' -H 'Accept: application/json'

or use the api-key GET parameter:

curl 'http://api.alerta.io/alerts?api-key=demo-key' -H 'Accept: application/json'

Note

Using the HTTP Authorization header is preferred so that API keys are not inadvertently captured in log files and accidentally exposed.

User Authorisation

Google, GitHub, GitLab OAuth, Keycloak OAuth are used for user authentication, not user authorisation. Authentication proves that you are who you say you are. Authorization says that you are allowed to access what you have requested.

To control who has access to Alerta you can restrict access to users with a certain email domain name by setting ALLOWED_EMAIL_DOMAINS when using Google OAuth2, or who belong to a particular GitHub organisation by setting ALLOWED_GITHUB_ORGS when using GitHub OAuth, or who belong to a particular GitLab group by setting ALLOWED_GITLAB_GROUPS when using GitLab OAuth2. belong to a particular Keycloak role by setting ALLOWED_KEYCLOAK_ROLES when using Keycloak OAuth2

For those situations where it is not possible to group users in this way it is possible to selectively allow access on a per-user basis. How this is done depends on whether you are using Google, GitHub, GitLab or Keycloak as OAuth2 provider for user login.

User Roles

TBC