From d1533d2d18e804ee75dfd82b5cb2521a0a2abb17 Mon Sep 17 00:00:00 2001 From: glasstiger <94906625+glasstiger@users.noreply.github.com> Date: Wed, 4 Dec 2024 18:43:44 +0000 Subject: [PATCH] ACL config doc, updated OIDC config (#99) - added ACL config doc - updated OIDC config doc --------- Co-authored-by: goodroot <9484709+goodroot@users.noreply.github.com> --- .../configuration-utils/_iam.config.json | 86 +++++++++++++++++++ .../configuration-utils/_oidc.config.json | 44 +++++++--- documentation/configuration.md | 37 ++++++-- 3 files changed, 148 insertions(+), 19 deletions(-) create mode 100644 documentation/configuration-utils/_iam.config.json diff --git a/documentation/configuration-utils/_iam.config.json b/documentation/configuration-utils/_iam.config.json new file mode 100644 index 00000000..54bdbd5d --- /dev/null +++ b/documentation/configuration-utils/_iam.config.json @@ -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." + } +} diff --git a/documentation/configuration-utils/_oidc.config.json b/documentation/configuration-utils/_oidc.config.json index d6bfae7c..c57d0985 100644 --- a/documentation/configuration-utils/_oidc.config.json +++ b/documentation/configuration-utils/_oidc.config.json @@ -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": { @@ -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`)." @@ -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." @@ -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, diff --git a/documentation/configuration.md b/documentation/configuration.md index 20de4120..5a485e43 100644 --- a/documentation/configuration.md +++ b/documentation/configuration.md @@ -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" @@ -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. @@ -207,7 +208,7 @@ PostgresSQL wire protocol. ### InfluxDB Line Protocol (ILP) This section describes ingestion settings for incoming messages using InfluxDB -line protocol. +Line Protocol. | Property | Default | Description | | ------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -215,6 +216,8 @@ line protocol. #### 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. | @@ -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/). ::: @@ -258,6 +260,23 @@ For a tuning guide see... the +### 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). + + + ### OpenID Connect (OIDC) :::note @@ -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).