diff --git a/configuration/configure-api-token.adoc b/configuration/configure-api-token.adoc index 1688ac9b0ff1..3efc7067da6c 100644 --- a/configuration/configure-api-token.adoc +++ b/configuration/configure-api-token.adoc @@ -7,10 +7,11 @@ include::modules/common-attributes.adoc[] toc::[] [role="_abstract"] -{rh-rhacs-first} requires API tokens for some system integrations, authentication processes, and system functions. You can configure tokens using the {product-title-short} web interface. +{rh-rhacs-first} requires API tokens for some system integrations, authentication processes, and system functions. You can configure tokens by using the {product-title-short} web interface. include::snippets/note-about-creating-tokens.adoc[] +//Creating an API token include::modules/create-api-token.adoc[leveloffset=+1] [role="_additional-resources"] @@ -19,4 +20,7 @@ include::modules/create-api-token.adoc[leveloffset=+1] * xref:../operating/manage-user-access/configure-short-lived-access.adoc#configure-short-lived-access[Configuring short-lived access] * link:https://github.com/stackrox/contributions/blob/main/guides/cloud-provider-integrations/azure-service-principal-m2m-auth.md[Using Azure Entra ID service principals for machine to machine auth with RHACS] +//About API token expiration include::modules/about-api-token-expiration.adoc[leveloffset=+1] + +include::modules/api-token-expiration-environment-variables.adoc[leveloffset=+2] diff --git a/modules/about-api-token-expiration.adoc b/modules/about-api-token-expiration.adoc index ac86d9024ef2..6911969a2e68 100644 --- a/modules/about-api-token-expiration.adoc +++ b/modules/about-api-token-expiration.adoc @@ -9,31 +9,11 @@ You use API tokens in {product-title} ({product-title-short}) for several authentication and access functions, such as API access, CLI access, and authentication. API tokens expire one year from the creation date, and {product-title-short} alerts you when a token expires soon. -{product-title-short} provides notifications in the web interface and by sending log messages to Central when a token will expire in less than one week. The log message process runs once an hour. Once a day, the process lists the tokens that are expiring and creates a log message for each one. Log messages are issued once a day and appear in Central logs. +{product-title-short} provides notifications in the web interface and by sending log messages to Central when a token will expire in less than one week. The log message process runs every hour. The process lists the tokens that are expiring and creates a log message for each one every day. {product-title-short} issues log messages daily and they appear in Central logs. Logs have the format as shown in the following example: [source,text] ---- Warn: API Token [token name] (ID [token ID]) will expire in less than X days. ----- -You can change the default settings for the log message process by configuring the environment variables shown in the following table: - -[cols="1,1,1"] -|=== - -|Environment variable |Default value |Description - -| ROX_TOKEN_EXPIRATION_NOTIFIER_INTERVAL -| 1h (1 hour) -| The frequency at which the log message background loop that lists tokens and creates the logs will run. - -| ROX_TOKEN_EXPIRATION_NOTIFIER_BACKOFF_INTERVAL -| 24h (1 day) -| The frequency at which the loop lists tokens and issues notifications. - -| ROX_TOKEN_EXPIRATION_DETECTION_WINDOW -| 168h (1 week) -| The time period before expiration of the token that will cause the notification to be generated. - -|=== \ No newline at end of file +---- \ No newline at end of file diff --git a/modules/api-token-expiration-environment-variables.adoc b/modules/api-token-expiration-environment-variables.adoc new file mode 100644 index 000000000000..76088b93737c --- /dev/null +++ b/modules/api-token-expiration-environment-variables.adoc @@ -0,0 +1,31 @@ +// Module included in the following assemblies: +// +// * configuration/configure-api-token.adoc + +:_mod-docs-content-type: REFERENCE +[id="api-token-expiration-environment-variables_{context}"] += Configuring API token expiration notification settings + +[role="_abstract"] +You can customize the API token expiration notification behavior by configuring environment variables that control the notification frequency and detection window. + +You can change the default settings for the log message process by configuring the environment variables shown in the following table: + +[cols="1,1,1"] +|=== + +|Environment variable |Default value |Description + +| ROX_TOKEN_EXPIRATION_NOTIFIER_INTERVAL +| 1h (1 hour) +| The frequency at which the log message background loop that lists tokens and creates the logs will run. + +| ROX_TOKEN_EXPIRATION_NOTIFIER_BACKOFF_INTERVAL +| 24h (1 day) +| The frequency at which the loop lists tokens and issues notifications. + +| ROX_TOKEN_EXPIRATION_DETECTION_WINDOW +| 168h (1 week) +| The time period before expiration of the token that triggers the notification. + +|=== diff --git a/modules/create-api-token.adoc b/modules/create-api-token.adoc index 4b94f658cb58..b94aa92557e4 100644 --- a/modules/create-api-token.adoc +++ b/modules/create-api-token.adoc @@ -5,6 +5,9 @@ [id="create-api-token_{context}"] = Creating an API token +[role="_abstract"] +You can create API tokens for authentication and system integrations through the {product-title-short} portal. + .Procedure . In the {product-title-short} portal, go to *Platform Configuration* -> *Integrations*. diff --git a/snippets/note-about-creating-tokens.adoc b/snippets/note-about-creating-tokens.adoc index 6ce1f686092e..78e4d9706227 100644 --- a/snippets/note-about-creating-tokens.adoc +++ b/snippets/note-about-creating-tokens.adoc @@ -12,6 +12,6 @@ * To prevent privilege escalation, when you create a new token, your role's permissions limit the permission you can assign to that token. For example, if you only have `read` permission for the Integration resource, you cannot create a token with `write` permission. * If you want a custom role to create tokens for other users to use, you must assign the required permissions to that custom role. * Use short-lived tokens for machine-to-machine communication, such as CI/CD pipelines, scripts, and other automation. Also, use the `roxctl central login` command for human-to-machine communication, such as `roxctl` CLI or API access. -* The majority of cloud service providers support OIDC identity tokens, for example, Microsoft Entra ID, Google Cloud Identity Platform, and AWS Cognito. OIDC identity tokens issued by these services can be used for {product-title-short} short-lived access. -* Third-party OIDC identity tokens can also be used directly to access the API endpoint, without an exchange, if a machine-to-machine configuration exists for the token issuer. +* The majority of cloud service providers support OIDC identity tokens, for example, Microsoft Entra ID, Google Cloud Identity Platform, and AWS Cognito. You can use OIDC identity tokens issued by these services for {product-title-short} short-lived access. +* You can also use third-party OIDC identity tokens directly to access the API endpoint, without an exchange, if a machine-to-machine configuration exists for the token issuer. ==== \ No newline at end of file