Merge pull request #1629 from influxdata/chrono-basic-auth
Document Chronograf basic authpull/1746/head
pierwill
GitHub
commit
4856dc917f
|
|
@ -10,14 +10,16 @@ menu:
|
|||
---
|
||||
|
||||
To enhance security, configure Chronograf to authenticate and authorize with [OAuth 2.0](https://oauth.net/) and use TLS/HTTPS.
|
||||
(Basic authentication with username and password is also available.)
|
||||
|
||||
* [Configure OAuth 2.0](#configure-oauth-2-0)
|
||||
* [Configure Chronograf to authenticate with OAuth 2.0](#configure-chronograf-to-authenticate-with-oauth-20)
|
||||
1. [Generate a Token Secret](#generate-a-token-secret)
|
||||
2. [Set configurations for your OAuth provider](#set-configurations-for-your-oauth-provider)
|
||||
3. [Configure authentication duration](#configure-authentication-duration)
|
||||
* [Configure Chronograf to authenticate with a username and password](#configure-chronograf-to-authenticate-with-a-username-and-password)
|
||||
* [Configure TLS (Transport Layer Security) and HTTPS](#configure-tls-transport-layer-security-and-https)
|
||||
|
||||
## Configure OAuth 2.0
|
||||
## Configure Chronograf to authenticate with OAuth 2.0
|
||||
|
||||
> After configuring OAuth 2.0, the Chronograf Admin tab becomes visible.
|
||||
> You can then set up [multiple organizations](/chronograf/v1.8/administration/managing-organizations/)
|
||||
|
|
@ -33,12 +35,12 @@ 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 secret, high-entropy pseudo-random string.
|
||||
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'
|
||||
> ```
|
||||
For example, to do this with OpenSSL, run this command:
|
||||
```sh
|
||||
openssl rand -base64 256 | tr -d '\n'
|
||||
```
|
||||
|
||||
2. Set the environment variable:
|
||||
|
||||
|
|
@ -46,8 +48,10 @@ Chronograf will use this secret to generate the JWT Signature for all access tok
|
|||
TOKEN_SECRET=<mysecret>
|
||||
```
|
||||
|
||||
> ***InfluxEnterprise clusters:*** If you are running multiple Chronograf servers in a high availability configuration,
|
||||
> set the `TOKEN_SECRET` environment variable on each server to ensure that users can stay logged in.
|
||||
{{% note %}}
|
||||
***InfluxEnterprise clusters:*** If you are running multiple Chronograf servers in a high availability configuration,
|
||||
set the `TOKEN_SECRET` environment variable on each server to ensure that users can stay logged in.
|
||||
{{% /note %}}
|
||||
|
||||
### JWKS Signature Verification (optional)
|
||||
|
||||
|
|
@ -76,7 +80,7 @@ Configuration steps for the following supported authentication providers are pro
|
|||
* [Okta](#configure-okta-authentication)
|
||||
* [Gitlab](#configure-gitlab-authentication)
|
||||
* [Azure Active Directory](#configure-azure-active-directory-authentication)
|
||||
* [Configure Chronograf to use any OAuth 2.0 provider](#configure-chronograf-to-use-any-oauth-2-0-provider)
|
||||
* [Configure Chronograf to use any OAuth 2.0 provider](#configure-chronograf-to-use-any-oauth-20-provider)
|
||||
|
||||
> If you haven't already, you must first [generate a token secret](#generate-a-token-secret) before proceeding.
|
||||
|
||||
|
|
@ -417,7 +421,9 @@ JWKS_URL="https://example.com/adfs/discovery/keys"
|
|||
TOKEN_SECRET="ZNh2N9toMwUVQxTVEe2ZnnMtgkh3xqKZ"
|
||||
```
|
||||
|
||||
> _**Note:**_ Do not use special characters for the GENERIC_CLIENT_ID as AD FS will split strings here, finally resulting in an identifier mismatch.
|
||||
{{% note %}}
|
||||
Do not use special characters for the `GENERIC_CLIENT_ID` as AD FS may split strings at the special character, resulting in an identifier mismatch.
|
||||
{{% /note %}}
|
||||
|
||||
### Configure authentication duration
|
||||
|
||||
|
|
@ -441,6 +447,28 @@ 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.
|
||||
|
||||
{{% warn %}}
|
||||
[OAuth 2.0](#configure-chronograf-to-authenticate-with-oauth-20) is the preferred method for authentication.
|
||||
Only use basic authentication in cases where an OAuth 2.0 integration is not possible.
|
||||
{{% /warn %}}
|
||||
|
||||
When using basic authentication, *all users have SuperAdmin status*; Chronograf authorization rules are not enforced.
|
||||
For more information, see [Cross-organization SuperAdmin status](/chronograf/v1.8/administration/managing-chronograf-users/#cross-organization-superadmin-status).
|
||||
|
||||
To enable basic authentication, run chronograf with the `-htpasswd` flag or use the `HTPASSWD` environment variable.
|
||||
|
||||
```sh
|
||||
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](https://docs.nginx.com/nginx/admin-guide/security-controls/configuring-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.
|
||||
|
|
@ -453,7 +481,9 @@ Chronograf includes command line and environment variable options for configurin
|
|||
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.
|
||||
|
||||
> ***Note:*** Using HTTPS helps guard against nefarious agents sniffing the JWT and using it to spoof a valid user against the Chronograf server.
|
||||
{{% note %}}
|
||||
Using HTTPS helps guard against nefarious agents sniffing the JWT and using it to spoof a valid user against the Chronograf server.
|
||||
{{% /note %}}
|
||||
|
||||
### Configuring TLS for Chronograf
|
||||
|
||||
|
|
@ -468,7 +498,9 @@ All Chronograf command line options have corresponding environment variables.
|
|||
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).
|
||||
|
||||
> ***Note:*** 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).
|
||||
{{% note %}}
|
||||
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).
|
||||
{{% /note %}}
|
||||
|
||||
#### Example with CLI options
|
||||
```sh
|
||||
|
|
|
|||
|
|
@ -71,11 +71,12 @@ chronograf [flags]
|
|||
|
||||
### General authentication flags
|
||||
|
||||
| Flag | Description | Env. Variable |
|
||||
|:-----------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-----------------|
|
||||
| `-t`, `--token-secret` | Secret for signing tokens | `$TOKEN_SECRET` |
|
||||
| `--auth-duration` | Total duration, in hours, of cookie life for authentication. Default value is `720h`. | `$AUTH_DURATION` |
|
||||
| `--public-url` | Public URL required to access Chronograf using a web browser. For example, if you access Chronograf using the default URL, the public URL value would be `http://localhost:8888`. Required for Google OAuth 2.0 authentication. Used for Auth0 and some generic OAuth 2.0 authentication providers. | `$PUBLIC_URL` |
|
||||
| Flag | Description | Env. Variable |
|
||||
|:-------------------------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-----------------|
|
||||
| `-t`, `--token-secret` | Secret for signing tokens | `$TOKEN_SECRET` |
|
||||
| `--auth-duration` | Total duration, in hours, of cookie life for authentication. Default value is `720h`. | `$AUTH_DURATION` |
|
||||
| `--public-url` | Public URL required to access Chronograf using a web browser. For example, if you access Chronograf using the default URL, the public URL value would be `http://localhost:8888`. Required for Google OAuth 2.0 authentication. Used for Auth0 and some generic OAuth 2.0 authentication providers. | `$PUBLIC_URL` |
|
||||
| `—htpasswd <path to .htpasswd file>` | Password file for use with HTTP basic authentication (username and password). See [NGINX documentation](https://docs.nginx.com/nginx/admin-guide/security-controls/configuring-http-basic-authentication/) for more on password files. | `$HTPASSWD` |
|
||||
|
||||
### GitHub-specific OAuth 2.0 authentication flags
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue