Skip to content

Commit

Permalink
ACL config doc, updated OIDC config (#99)
Browse files Browse the repository at this point in the history
- added ACL config doc
- updated OIDC config doc

---------

Co-authored-by: goodroot <[email protected]>
  • Loading branch information
glasstiger and goodroot authored Dec 4, 2024
1 parent 335a9ac commit d1533d2
Show file tree
Hide file tree
Showing 3 changed files with 148 additions and 19 deletions.
86 changes: 86 additions & 0 deletions documentation/configuration-utils/_iam.config.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,86 @@
{
"acl.enabled": {
"default": "true",
"description": "Enables/disables Identity and Access Management."
},
"acl.admin.user.enabled": {
"default": "true",
"description": "Enables/disables the built-in admin user."
},
"acl.admin.user": {
"default": "admin",
"description": "Name of the built-in admin user."
},
"acl.admin.password": {
"default": "quest",
"description": "The password of the built-in admin user."
},
"acl.basic.auth.realm.enabled": {
"default": "false",
"description": "When enabled the browser's basic auth popup window is used instead of the Web Console's login screen. Only present for backwards compatibility."
},
"acl.entity.name.max.length": {
"default": "255",
"description": "Maximum length of user, group and service account names."
},
"acl.password.hash.iteration.count": {
"default": "100000",
"description": "QuestDB Enterprise never stores passwords in plain text, it stores password hashes only. This is the number of hash iterations used in password hashing. Higher means safer, almost never should be changed."
},
"acl.rest.token.refresh.threshold": {
"default": "10",
"description": "When a REST token is created in REFRESH mode, its TTL is extended on every successful authentication, unless the last successful authentication was within this threshold. This setting removes unnecessary overhead of continuously refreshing REST tokens if they are used often. The value is expressed in seconds."
},
"tls.enabled": {
"default": "false",
"description": "Enables/disables TLS encryption globally for all QuestDB interfaces (HTTP endpoints, ILP over TCP)."
},
"tls.cert.path": {
"default": "",
"description": "Path to certificate used for TLS encryption globally. The certificate should be DER-encoded and saved in PEM format."
},
"tls.private.key.path": {
"default": "",
"description": "Path to private key used for TLS encryption globally."
},
"http.tls.enabled": {
"default": "false",
"description": "Enables/disables TLS encryption for the HTTP server only."
},
"http.tls.cert.path": {
"default": "",
"description": "Path to certificate used for TLS encryption for the HTTP server only. The certificate should be DER-encoded and saved in PEM format."
},
"http.tls.private.key.path": {
"default": "",
"description": "Path to private key used for TLS encryption for the HTTP server only."
},
"http.min.tls.enabled": {
"default": "false",
"description": "Enables/disables TLS encryption for the minimal HTTP server only."
},
"http.min.tls.cert.path": {
"default": "",
"description": "Path to certificate used for TLS encryption for the minimal HTTP server only. The certificate should be DER-encoded and saved in PEM format."
},
"http.min.tls.private.key.path": {
"default": "",
"description": "Path to private key used for TLS encryption for the minimal HTTP server only."
},
"line.tcp.tls.enabled": {
"default": "false",
"description": "Enables/disables TLS encryption for ILP over TCP only."
},
"line.tcp.tls.cert.path": {
"default": "",
"description": "Path to certificate used for TLS encryption for ILP over TCP only. The certificate should be DER-encoded and saved in PEM format."
},
"line.tcp.tls.private.key.path": {
"default": "",
"description": "Path to private key used for TLS encryption for ILP over TCP only."
},
"line.tcp.acl.enabled": {
"default": "true",
"description": "Enables/disables authentication for the ILP over TCP endpoint only."
}
}
44 changes: 34 additions & 10 deletions documentation/configuration-utils/_oidc.config.json
Original file line number Diff line number Diff line change
@@ -1,26 +1,34 @@
{
"acl.oidc.enabled": {
"default": false,
"default": "false",
"description": "Enables/disables OIDC authentication. When enabled, few other configuration options must also be set."
},
"acl.oidc.pkce.enabled": {
"default": "true",
"description": "Enables/disables PKCE for the Authorization Code Flow. This should always be enabled in a production environment, the Web Console is not fully secure without it."
},
"acl.oidc.ropc.flow.enabled": {
"default": false,
"description": "Enables/disables Resource Owner Password Credentials flow."
"default": "false",
"description": "Enables/disables Resource Owner Password Credentials flow. When enabled, this flow also has to be configured in the OIDC Provider."
},
"acl.oidc.configuration.url": {
"default": "",
"description": "URL where the OpenID Provider's configuration information cna be loaded in json format, should always end with `/.well-known/openid-configuration`."
},
"acl.oidc.host": {
"default": "",
"description": "OIDC provider hostname, required when OIDC is enabled."
"description": "OIDC provider hostname. Required when OIDC is enabled, unless the OIDC configuration URL is set."
},
"acl.oidc.port": {
"default": 443,
"description": "OIDC provider port number, required when OIDC is enabled."
"description": "OIDC provider port number."
},
"acl.oidc.tls.enabled": {
"default": true,
"description": "Whether the OIDC provider requires a secure connection or not. It is highly unlikely, but if the User Info Endpoint does not require a secure connection, this option can be set to `false`."
"default": "true",
"description": "Whether the OIDC provider requires a secure connection or not. It is highly unlikely in a production environment, but if the OpenID Provider endpoints do not require a secure connection, this option can be set to `false`."
},
"acl.oidc.tls.validation.enabled": {
"default": true,
"default": "true",
"description": "Enables/disables TLS certificate validation. If you are working with self-signed certificates that you would like QuestDB to trust, disable this option. Validation is strongly recommended in production environments. QuestDB will check that the certificate is valid, and that it is issued for the server to which it connects."
},
"acl.oidc.tls.keystore.path": {
Expand All @@ -39,6 +47,10 @@
"default": "",
"description": "Client name assigned to QuestDB in the OIDC server, required when OIDC is enabled."
},
"acl.oidc.audience": {
"default": "",
"description": "OAuth2 audience as set on the tokens issued by the OIDC Provider, defaults to the client id."
},
"acl.oidc.redirect.uri": {
"default": "",
"description": "The redirect URI tells the OIDC server where to redirect the user after successful authentication. If not set, the Web Console defaults it to the location where it was loaded from (`window.location.href`)."
Expand All @@ -47,6 +59,10 @@
"default": "openid",
"description": "The OIDC server should ask consent for the list of scopes provided in this property. The scope `openid` is mandatory, and always should be included."
},
"acl.oidc.public.keys.endpoint": {
"default": "/pf/JWKS",
"description": "JSON Web Key Set (JWKS) Endpoint, the default value should work for the Ping Identity Platform. This endpoint provides the list of public keys can be used to decode and validate ID tokens issued by the OIDC Provider."
},
"acl.oidc.authorization.endpoint": {
"default": "/as/authorization.oauth2",
"description": "OIDC Authorization Endpoint, the default value should work for the Ping Identity Platform."
Expand All @@ -57,11 +73,19 @@
},
"acl.oidc.userinfo.endpoint": {
"default": "/idp/userinfo.openid",
"description": "OIDC User Info Endpoint, the default value should work for the Ping Identity Platform."
"description": "OIDC User Info Endpoint, the default value should work for the Ping Identity Platform. Used to retrieve additional user information which contains the user's group memberships."
},
"acl.oidc.groups.encoded.in.token": {
"default": "false",
"description": "Should be set to false, if the OIDC Provider is configured to encode the group memberships of the user into the id token. When set to true, QuestDB will look for the groups in the token instead of calling the User Info endpoint."
},
"acl.oidc.sub.claim": {
"default": "sub",
"description": "The name of the claim in the user information, which contains the name of the user. Could be a username, the user's full name or email. It will be displayed in the Web Console, and logged for audit purposes."
},
"acl.oidc.groups.claim": {
"default": "groups",
"description": "The name of the custom claim inside the user info response object, which contains the group memberships of the user."
"description": "The name of the custom claim in the user information, which contains the group memberships of the user."
},
"acl.oidc.cache.ttl": {
"default": 30000,
Expand Down
37 changes: 28 additions & 9 deletions documentation/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ import postgresConfig from "./configuration-utils/\_postgres.config.json"
import tcpConfig from "./configuration-utils/\_tcp.config.json"
import udpConfig from "./configuration-utils/\_udp.config.json"
import replicationConfig from "./configuration-utils/\_replication.config.json"
import iamConfig from "./configuration-utils/\_iam.config.json"
import oidcConfig from "./configuration-utils/\_oidc.config.json"
import logConfig from "./configuration-utils/\_log.config.json"

Expand Down Expand Up @@ -192,8 +193,8 @@ It is important that the two path are identical

### Parallel SQL execution

This section describes settings that can affect parallelism level of SQL
execution and therefore performance.
This section describes settings that can affect the level of parallelism during
SQL execution, and therefore can also have an impact on performance.

<ConfigTable rows={parallelSqlConfig} />

Expand All @@ -207,14 +208,16 @@ PostgresSQL wire protocol.
### InfluxDB Line Protocol (ILP)

This section describes ingestion settings for incoming messages using InfluxDB
line protocol.
Line Protocol.

| Property | Default | Description |
| ------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| line.default.partition.by | DAY | Table partition strategy to be used with tables that are created automatically by InfluxDB Line Protocol. Possible values are: `HOUR`, `DAY`, `WEEK`, `MONTH`, and `YEAR`. |

#### HTTP specific settings

ILP over HTTP is the preferred way of ingesting data.

| Property | Default | Description |
| ---------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| line.http.enabled | true | Enable ILP over HTTP. Default port is 9000. Enabled by default within open source versions, defaults to false and must be enabled for Enterprise. |
Expand All @@ -229,9 +232,8 @@ line protocol.

:::note

The UDP receiver is deprecated since QuestDB version 6.5.2. We recommend the
[InfluxDB Line Protocol TCP receiver](/docs/reference/api/ilp/overview/)
instead.
The UDP receiver is deprecated since QuestDB version 6.5.2. We recommend ILP over
HTTP instead, or less frequently [ILP over TCP](/docs/reference/api/ilp/overview/).

:::

Expand All @@ -258,6 +260,23 @@ For a tuning guide see... the

<ConfigTable rows={replicationConfig} />

### Identity and Access Management (IAM)

:::note

Identity and Access Management is available within [QuestDB Enterprise](/enterprise/).

:::

Identity and Access Management (IAM) ensures that data can be accessed only
by authorized users. The below configuration properties relate to various
authentication and authorization features.

For a full explanation of IAM, see the
[Identity and Access Management (IAM) documentation](/docs/operations/rbac).

<ConfigTable rows={iamConfig} />

### OpenID Connect (OIDC)

:::note
Expand All @@ -266,10 +285,10 @@ OpenID Connect is [Enterprise](/enterprise/) and [Cloud](/cloud/) only.

:::

Integrate with OpenID Connect (OIDC) to sync QuestDB with an Identity Provider
(IdP).
OpenID Connect (OIDC) support is part of QuestDB's Identity and Access Management.
The database can be integrated with any OAuth2/OIDC Identity Provider (IdP).

For a full explanation of OIDC, see the
For detailed information about OIDC, see the
[OpenID Connect (OIDC) integration guide](/docs/operations/openid-connect-oidc-integration).

<ConfigTable rows={oidcConfig} />
Expand Down

0 comments on commit d1533d2

Please sign in to comment.