Manage Chronograf security

To enhance security, configure Chronograf to authenticate and authorize with OAuth 2.0 and use TLS/HTTPS. (Basic authentication with username and password is also available.)

• Configure Chronograf to authenticate with OAuth 2.0
  1. Generate a Token Secret
  2. Set configurations for your OAuth provider
  3. Configure authentication duration
• Configure Chronograf to authenticate with a username and password
• Configure TLS (Transport Layer Security) and HTTPS

Configure Chronograf to authenticate with OAuth 2.0

Configure Chronograf to use an OAuth 2.0 provider and JWT (JSON Web Token) to authenticate users and enable role-based access controls.

(For more details on OAuth and JWT, see RFC 6749 and RFC 7519.)

Generate a Token Secret

To configure any of the supported OAuth 2.0 providers to work with Chronograf, you must configure the TOKEN_SECRET environment variable (or command line option). Chronograf will use this secret to generate the JWT Signature for all access tokens.

1. Generate a high-entropy pseudo-random string.

   For example, to do this with OpenSSL, run this command:

   openssl rand -base64 256 | tr -d '\n'

2. Set the environment variable:

   TOKEN_SECRET=<mysecret>

JWKS Signature Verification (optional)

If the OAuth provider implements OpenID Connect with RS256 signatures, you need to enable this feature with the USE_ID_TOKEN variable and provide a JSON Web Key Set (JWKS) document (holding the certificate chain) to validate the RSA signatures against. This certificate chain is regularly rolled over (when the certificates expire), so it is fetched from the JWKS_URL on demand.

Example:

export USE_ID_TOKEN=true
export JWKS_URL=https://example.com/adfs/discovery/keys

Set configurations for your OAuth provider

To enable OAuth 2.0 authorization and authentication in Chronograf, you must set configuration options that are specific for the OAuth 2.0 authentication provider you want to use.

Configuration steps for the following supported authentication providers are provided in these sections below:

• GitHub
• Google
• Auth0
• Heroku
• Okta
• Gitlab
• Azure Active Directory
• Bitbucket
• Configure Chronograf to use any OAuth 2.0 provider

Configure GitHub authentication

1. Follow the steps to Register a new OAuth application on GitHub to obtain your Client ID and Client Secret. On the GitHub application registration page, enter the following values:

   • Homepage URL: the full Chronograf server name and port. For example, to run the application locally with default settings, set the this URL to http://localhost:8888.
   • Authorization callback URL: the Homepage URL plus the callback URL path /oauth/github/callback (for example, http://localhost:8888/oauth/github/callback).

2. Set the Chronograf environment variables with the credentials provided by GitHub:

   export GH_CLIENT_ID=<github-client-id>
   export GH_CLIENT_SECRET=<github-client-secret>
   
   # If using Github Enterprise
   export GH_URL=https://github.custom-domain.com

3. If you haven’t already, set the Chronograf environment with your token secret:

   export TOKEN_SECRET=Super5uperUdn3verGu355!

Alternatively, set environment variables using the equivalent command line options:

• --github-url
• --github-client-id
• --github-client-secret
• --token_secret=

For details on the command line options and environment variables, see GitHub OAuth 2.0 authentication options.

GitHub organizations (optional)

To require GitHub organization membership for authenticating users, set the GH_ORGS environment variable with the name of your organization.

export GH_ORGS=biffs-gang

If the user is not a member of the specified GitHub organization, then the user will not be granted access. To support multiple organizations, use a comma-delimited list.

export GH_ORGS=hill-valley-preservation-sociey,the-pinheads

Example GitHub OAuth configuration

# Github Enterprise base URL
export GH_URL=https://github.mydomain.com

# GitHub Client ID
export GH_CLIENT_ID=b339dd4fddd95abec9aa

# GitHub Client Secret
export GH_CLIENT_SECRET=260041897d3252c146ece6b46ba39bc1e54416dc

# Secret used to generate JWT tokens
export TOKEN_SECRET=Super5uperUdn3verGu355!

# Restrict to specific GitHub organizations
export GH_ORGS=biffs-gang

Configure Google authentication

1. Follow the steps in Obtain OAuth 2.0 credentials to obtain the required Google OAuth 2.0 credentials, including a Google Client ID and Client Secret, by

2. Verify that Chronograf is publicly accessible using a fully-qualified domain name so that Google can properly redirect users back to the application.

3. Set the Chronograf environment variables for the Google OAuth 2.0 credentials and Public URL used to access Chronograf:

   export GOOGLE_CLIENT_ID=812760930421-kj6rnscmlbv49pmkgr1jq5autblc49kr.apps.googleusercontent.com
   export GOOGLE_CLIENT_SECRET=wwo0m29iLirM6LzHJWE84GRD
   export PUBLIC_URL=http://localhost:8888

4. If you haven’t already, set the Chronograf environment with your token secret:

   export TOKEN_SECRET=Super5uperUdn3verGu355!

Alternatively, the environment variables discussed above can be set using their corresponding command line options:

• --google-client-id=
• --google-client-secret=
• --public-url=
• --token_secret=

For details on Chronograf command line options and environment variables, see Google OAuth 2.0 authentication options.

Optional Google domains

Configure Google authentication to restrict access to Chronograf to specific domains. Set the GOOGLE_DOMAINS environment variable or the --google-domains command line option. Separate multiple domains using commas. For example, to permit access only from biffspleasurepalace.com and savetheclocktower.com, set the environment variable as follows:

export GOOGLE_DOMAINS=biffspleasurepalace.com,savetheclocktower.com

Configure Auth0 authentication

See OAuth 2.0 for details about the Auth0 implementation.

1. Set up your Auth0 account to obtain the necessary credentials.

   1. From the Auth0 user dashboard, click Create Application.
   2. Choose Regular Web Applications as the type of application and click Create.
   3. In the Settings tab, set Token Endpoint Authentication to None.
   4. Set Allowed Callback URLs to https://www.example.com/oauth/auth0/callback (substituting example.com with the PUBLIC_URL of your Chronograf instance)
   5. Set Allowed Logout URLs to https://www.example.com (substituting example.com with the PUBLIC_URL of your Chronograf instance)

2. Set the Chronograf environment variables based on your Auth0 client credentials:

   • AUTH0_DOMAIN (Auth0 domain)
   • AUTH0_CLIENT_ID (Auth0 Client ID)
   • AUTH0_CLIENT_SECRET (Auth0 client Secret)
   • PUBLIC_URL (Public URL, used in callback URL and logout URL above)

3. If you haven’t already, set the Chronograf environment with your token secret:

   export TOKEN_SECRET=Super5uperUdn3verGu355!

Alternatively, the environment variables discussed above can be set using their corresponding command line options:

• --auth0-domain
• --auth0-client-id
• --auth0-client-secret
• --public-url

Auth0 organizations (optional)

Auth0 can be customized to the operator’s requirements, so it has no official concept of an “organization.” Organizations are supported in Chronograf using a lightweight app_metadata key that can be inserted into Auth0 user profiles automatically or manually.

To assign a user to an organization, add an organization key to the user app_metadata field with the value corresponding to the user’s organization. For example, you can assign the user Marty McFly to the “time-travelers” organization by setting app_metadata to {"organization": "time-travelers"}. This can be done either manually by an operator or automatically through the use of an Auth0 Rule or a pre-user registration Auth0 Hook.

Next, you will need to set the Chronograf AUTH0_ORGS environment variable to a comma-separated list of the allowed organizations. For example, if you have one group of users with an organization key set to biffs-gang and another group with an organization key set to time-travelers, you can permit access to both with this environment variable: AUTH0_ORGS=biffs-gang,time-travelers.

An --auth0-organizations command line option is also available, but it is limited to a single organization and does not accept a comma-separated list like its environment variable equivalent.

Configure Heroku authentication

1. Obtain a client ID and application secret for Heroku by following the guide posted here.

2. Set the Chronograf environment variables based on your Heroku client credentials:

   export HEROKU_CLIENT_ID=<client-id-from-heroku>
   export HEROKU_SECRET=<client-secret-from-heroku>

3. If you haven’t already, set the Chronograf environment with your token secret:

   export TOKEN_SECRET=Super5uperUdn3verGu355!

Heroku organizations (optional)

To restrict access to members of specific Heroku organizations, use the HEROKU_ORGS environment variable (or associated command line option). Multiple values must be comma-separated.

For example, to permit access from the hill-valley-preservation-society organization and the-pinheads organization, use the following environment variable:

export HEROKU_ORGS=hill-valley-preservation-sociey,the-pinheads

Configure Okta authentication

1. Create an Okta web application by following the steps in the Okta documentation: Implement the Authorization Code Flow.

2. In the General Settings section, find the Allowed grant types listing and select only the Client acting on behalf of a user: Authorization Code option.

3. In the LOGIN section, set the *Login redirect URIs and Initiate login URI to http://localhost:8888/oauth/okta/callback (the default callback URL for Chronograf).

4. Set the following Chronograf environment variables:

   GENERIC_NAME=okta
   
   # The client ID is provided in the "Client Credentials" section of the Okta dashboard.
   GENERIC_CLIENT_ID=<okta_client_ID>
   
   # The client secret is in the "Client Credentials" section of the Okta dashboard.
   GENERIC_CLIENT_SECRET=<okta_client_secret>
   
   GENERIC_AUTH_URL=https://dev-553212.oktapreview.com/oauth2/default/v1/authorize
   GENERIC_TOKEN_URL=https://dev-553212.oktapreview.com/oauth2/default/v1/token
   GENERIC_API_URL=https://dev-553212.oktapreview.com/oauth2/default/v1/userinfo
   PUBLIC_URL=http://localhost:8888
   TOKEN_SECRET=secretsecretsecret
   GENERIC_SCOPES=openid,profile,email

5. If you haven’t already, set the Chronograf environment with your token secret:

   export TOKEN_SECRET=Super5uperUdn3verGu355!

Configure GitLab authentication

1. In your GitLab profile, create a new OAuth2 authentication service.

   1. Provide a name for your application, then enter your publicly accessible Chronograf URL with the /oauth/gitlab/callback path as your GitLab callback URL. (For example, http://<your_chronograf_server>:8888/oauth/gitlab/callback.)
   2. Click Submit to save the service details.
   3. Make sure your application has openid and read_user scopes.

2. Copy the provided Application Id and Secret and set the following environment variables:

   In the examples below, note the use of gitlab-server-example.com and chronograf-server-example.com in urls. These should be replaced by the actual URLs used to access each service.

   GENERIC_NAME="gitlab"
   GENERIC_CLIENT_ID=<gitlab_application_id>
   GENERIC_CLIENT_SECRET=<gitlab_secret>
   GENERIC_AUTH_URL="https://gitlab.com/oauth/authorize"
   GENERIC_TOKEN_URL="https://gitlab.com/oauth/token"
   TOKEN_SECRET=<mytokensecret>
   GENERIC_SCOPES="api,openid,read_user"
   PUBLIC_URL="http://<chronograf-host>:8888"
   GENERIC_API_URL="https://gitlab.com/api/v3/user"

   The equivalent command line options are:

   --generic-name=gitlab
   --generic-client-id=<gitlab_application_id>
   --generic-client-secret=<gitlab_secret>
   --generic-auth-url=https://gitlab.com/oauth/authorize
   --generic-token-url=https://gitlab.com/oauth/token
   --token-secret=<mytokensecret>
   --generic-scopes=openid,read_user
   --generic-api-url=https://gitlab.com/api/v3/user
   --public-url=http://<chronograf-host>:8888/

Configure Azure Active Directory authentication

1. Create an Azure Active Directory application. Note the following information: <APPLICATION-ID>, <TENANT-ID>, and <APPLICATION-KEY>. You’ll need these to define your Chronograf environment.

2. Be sure to register a reply URL in your Azure application settings. This should match the calling URL from Chronograf. Otherwise, you will get an error stating no reply address is registered for the application. For example, if Chronograf is configured with a GENERIC_NAME value of AzureAD, the reply URL would be http://localhost:8888/oauth/AzureAD/callback.

3. After completing the application provisioning within Azure AD, you can now complete the configuration with Chronograf. Using the metadata from your Azure AD instance, proceed to export the following environment variables:

   Set the following environment variables in /etc/default/chronograf:

   GENERIC_TOKEN_URL=https://login.microsoftonline.com/<<TENANT-ID>>/oauth2/token
   TENANT=<<TENANT-ID>>
   GENERIC_NAME=AzureAD
   GENERIC_API_KEY=userPrincipalName
   GENERIC_SCOPES=openid
   GENERIC_CLIENT_ID=<<APPLICATION-ID>>
   GENERIC_AUTH_URL=https://login.microsoftonline.com/<<TENANT-ID>>/oauth2/authorize?resource=https://graph.windows.net
   GENERIC_CLIENT_SECRET=<<APPLICATION-KEY>>
   TOKEN_SECRET=secret
   GENERIC_API_URL=https://graph.windows.net/<<TENANT-ID>>/me?api-version=1.6
   PUBLIC_URL=http://localhost:8888

   Note: If you’ve configured TLS/SSL, modify the PUBLIC_URL to ensure you’re using HTTPS.

Configure Bitbucket authentication

1. Complete the instructions to Use OAuth on Bitbucket Cloud, and include the following information:

• Callback URL: http://localhost:8888/oauth/bitbucket/callback
• Permissions: Account read, email

2. Run the following command to set Chronograf environment variables for Bitbucket in /etc/default/chronograf:

   export TOKEN_SECRET=...
   export GENERIC_CLIENT_ID=...
   export GENERIC_CLIENT_SECRET=...
   export GENERIC_AUTH_URL=https://bitbucket.org/site/oauth2/authorize
   export GENERIC_TOKEN_URL=https://bitbucket.org/site/oauth2/access_token
   export GENERIC_API_URL=https://api.bitbucket.org/2.0/user
   export GENERIC_SCOPES=account
   export PUBLIC_URL=http://localhost:8888
   export GENERIC_NAME=bitbucket

Configure Chronograf to use any OAuth 2.0 provider

Chronograf can be configured to work with any OAuth 2.0 provider, including those defined above, by using the generic configuration options below. Additionally, the generic provider implements OpenID Connect (OIDC) as implemented by Active Directory Federation Services (AD FS).

When using the generic configuration, some or all of the following environment variables (or corresponding command line options) are required (depending on your OAuth 2.0 provider):

• GENERIC_CLIENT_ID: Application client identifier issued by the provider
• GENERIC_CLIENT_SECRET: Application client secret issued by the provider
• GENERIC_AUTH_URL: Provider’s authorization endpoint URL
• GENERIC_TOKEN_URL: Provider’s token endpoint URL used by the Chronograf client to obtain an access token
• USE_ID_TOKEN: Enable OpenID id_token processing
• JWKS_URL: Provider’s JWKS endpoint used by the client to validate RSA signatures
• GENERIC_API_URL: Provider’s OpenID UserInfo endpoint URL used by Chronograf to request user data
• GENERIC_API_KEY: JSON lookup key for OpenID UserInfo (known to be required for Microsoft Azure, with the value userPrincipalName)
• GENERIC_SCOPES: Scopes of user data required for your instance of Chronograf, such as user email and OAuth provider organization
  • Multiple values must be space-delimited, e.g. user:email read:org
  • These may vary by OAuth 2.0 provider
  • Default value: user:email
• PUBLIC_URL: Full public URL used to access Chronograf from a web browser, i.e. where Chronograf is hosted
  • Used by Chronograf, for example, to construct the callback URL
• TOKEN_SECRET: Used to validate OAuth state response. (see above)

Optional environment variables

The following environment variables (and corresponding command line options) are also available for optional use:

• GENERIC_DOMAINS: Email domain where email address must include.
• GENERIC_NAME: Value used in the callback URL in conjunction with PUBLIC_URL, e.g. <PUBLIC_URL>/oauth/<GENERIC_NAME>/callback
  • This value is also used in the text for the Chronograf Login button
  • Default value is generic
  • So, for example, if PUBLIC_URL is https://localhost:8888 and GENERIC_NAME is its default value, then the callback URL would be https://localhost:8888/oauth/generic/callback, and the Chronograf Login button would read Log in with Generic
  • While using Chronograf, this value should be supplied in the Provider field when adding a user or creating an organization mapping.

Example: OIDC with AD FS

See Enabling OpenID Connect with AD FS 2016 for a walk through of the server configuration.

Exports for Chronograf (e.g. in /etc/default/chronograf):

PUBLIC_URL="https://example.com:8888"
GENERIC_CLIENT_ID="chronograf"
GENERIC_CLIENT_SECRET="KW-TkvH7vzYeJMAKj-3T1PdHx5bxrZnoNck2KlX8"
GENERIC_AUTH_URL="https://example.com/adfs/oauth2/authorize"
GENERIC_TOKEN_URL="https://example.com/adfs/oauth2/token"
GENERIC_SCOPES="openid"
GENERIC_API_KEY="upn"
USE_ID_TOKEN="true"
JWKS_URL="https://example.com/adfs/discovery/keys"
TOKEN_SECRET="ZNh2N9toMwUVQxTVEe2ZnnMtgkh3xqKZ"

ERRO[0053] Unable to get OAuth Group malformed email address, expected "..." to contain @ symbol

Configure authentication duration

By default, user authentication remains valid for 30 days using a cookie stored in the web browser. To configure a different authorization duration, set a duration using the AUTH_DURATION environment variable.

Example:

To set the authentication duration to 1 hour, use the following shell command:

export AUTH_DURATION=1h

The duration uses the Go (golang) time duration format, so the largest time unit is h (hours). So to change it to 45 days, use:

export AUTH_DURATION=1080h

To require re-authentication every time the browser is closed, set AUTH_DURATION to 0. This makes the cookie transient (aka “in-memory”).

Configure Chronograf to authenticate with a username and password

Chronograf can be configured to authenticate users by username and password (“basic authentication”). Turn on basic authentication access to restrict HTTP requests to Chronograf to selected users.

When using basic authentication, all users have SuperAdmin status; Chronograf authorization rules are not enforced. For more information, see Cross-organization SuperAdmin status.

To enable basic authentication, run chronograf with the --htpasswd flag or use the HTPASSWD environment variable.

chronograf --htpasswd <path to .htpasswd file>

The .htpasswd file contains users and their passwords, and should be created with a password file utility tool such as apache2-utils. For more information about how to restrict access with basic authentication, see NGINX documentation on Restricting Access with HTTP Basic Authentication.

Configure TLS (Transport Layer Security) and HTTPS

The TLS (Transport Layer Security) cryptographic protocol is supported in Chronograf to provides server authentication, data confidentiality, and data integrity. Using TLS secures traffic between a server and web browser and enables the use of HTTPS.

InfluxData recommends using HTTPS to communicate securely with Chronograf applications. If you are not using a TLS termination proxy, you can run your Chronograf server with TLS connections.

Chronograf includes command line and environment variable options for configuring TLS (Transport Layer Security) certificates and key files. Use of the TLS cryptographic protocol provides server authentication, data confidentiality, and data integrity. When configured, users can use HTTPS to securely communicate with your Chronograf applications.

Configure TLS for Chronograf

Chronograf server has command line and environment variable options to specify the certificate and key files. The server reads and parses a public/private key pair from these files. The files must contain PEM-encoded data.

All Chronograf command line options have corresponding environment variables.

To configure Chronograf to support TLS, do the following:

1. Specify the certificate file using the TLS_CERTIFICATE environment variable or the --cert CLI option.

2. Specify the key file using the TLS_PRIVATE_KEY environment variable or --key CLI option.

   If both the TLS certificate and key are in the same file, specify them using the TLS_CERTIFICATE environment variable (or the --cert CLI option).

3. (Optional) To specify which TLS cipher suites to allow, use the TLS_CIPHERS environment variable or the --tls-ciphers CLI option. Chronograf supports all cipher suites in the Go crypto/tls package and, by default, allows them all.

4. (Optional) To specify the minimum and maximum TLS versions to allow, use the TLS_MIN_VERSION and TLS_MAX_VERSION environment variables or the --tls-min-version and --tls-max-version CLI options. By default, the minimum TLS version allowed is tls1.2 and the maximum version is unlimited.

Example with CLI options

chronograf \
  --cert=my.crt \
  --key=my.key \
  --tls-ciphers=TLS_RSA_WITH_AES_256_CBC_SHA,TLS_AES_128_GCM_SHA256 \
  --tls-min-version=tls1.2 \
  --tls-max-version=tls1.3

Example with environment variables

TLS_CERTIFICATE=my.crt \
TLS_PRIVATE_KEY=my.key \
TLS_CIPHERS=TLS_RSA_WITH_AES_256_CBC_SHA,TLS_AES_128_GCM_SHA256 \
TLS_MIN_VERSION=tls1.2 \
TLS_MAX_VERSION=tls1.3 \
chronograf

Docker example with environment variables

docker run \
  -v /host/path/to/certs:/certs \
  -e TLS_CERTIFICATE=/certs/my.crt \
  -e TLS_PRIVATE_KEY=/certs/my.key \
  -e TLS_CIPHERS=TLS_RSA_WITH_AES_256_CBC_SHA,TLS_AES_128_GCM_SHA256 \
  -e TLS_MIN_VERSION=tls1.2 \
  -e TLS_MAX_VERSION=tls1.3 \
  chronograf:1.10

Test with self-signed certificates

To test your setup, you can use a self-signed certificate.

To create a certificate and key in one file with OpenSSL:

openssl req -x509 -newkey rsa:4096 -sha256 -nodes -keyout testing.pem -out testing.pem -subj "/CN=localhost" -days 365

Next, set the environment variable TLS_CERTIFICATE:

export TLS_CERTIFICATE=$PWD/testing.pem

Run Chronograf:

./chronograf
INFO[0000] Serving chronograf at https://[::]:8888       component=server

In the first log message you should see https rather than http.