From e884fbe8c490e67b3b035051ed11b0848a478954 Mon Sep 17 00:00:00 2001 From: Vita Alhambra Date: Wed, 21 Aug 2024 10:22:34 -0400 Subject: [PATCH] Add some more description to access token environment variables #6656 --- source/reference/modules/studio/security.rst | 38 ++++++++++++++++++-- 1 file changed, 35 insertions(+), 3 deletions(-) diff --git a/source/reference/modules/studio/security.rst b/source/reference/modules/studio/security.rst index caae49208..247a62dc4 100644 --- a/source/reference/modules/studio/security.rst +++ b/source/reference/modules/studio/security.rst @@ -1,5 +1,5 @@ :is-up-to-date: True -:last-updated: 4.1.4 +:last-updated: 4.1.6 .. index:: Studio Security @@ -891,7 +891,12 @@ Access Tokens :label: Since :version: 4.0.0 -The following section of Studio's configuration overrides allows you to configure settings for the Studio access tokens. Access tokens can then be used to invoke `Crafter Studio's REST APIs <../../../_static/api/studio.html>`_, or used in :ref:`crafter-cli` to perform operations on Studio. +The following section of Studio's configuration overrides allows you to configure settings for the Studio access tokens. +Access tokens can then be used to invoke `Crafter Studio's REST APIs <../../../_static/api/studio.html>`_ from the out +of the box UI as well as any customized JavaScript, CURL commands, or used in :ref:`crafter-cli` to perform operations on Studio. + +Studio access tokens uses JWT tokens for authentication. The following environment variables are used to customize the +default behavior of the JWT token that is used. .. code-block:: yaml :caption: *CRAFTER_HOME/bin/apache-tomcat/shared/classes/crafter/studio/extension/studio-config-override.yaml* @@ -920,6 +925,33 @@ The following section of Studio's configuration overrides allows you to configur # Indicates if the refresh token cookie should be secure (should be true for production environments behind HTTPS) studio.security.token.cookie.secure: ${env:STUDIO_REFRESH_TOKEN_SECURE} -| +where: + +- ``STUDIO_TOKEN_ISSUER``, ``STUDIO_TOKEN_VALID_ISSUERS``, ``STUDIO_TOKEN_AUDIENCE`` |br| + These variables are used in the JWT claims set. See https://datatracker.ietf.org/doc/html/rfc7519#section-4.1 for more + information on JWT claims set. + +- ``STUDIO_TOKEN_TIMEOUT`` |br| + This variable sets the expiration of the JWT token in minutes (default is 5 minutes). The expiration value is also + injected into the JWT claims when a token is published. This cannot be changed after the token is published. + After the expiration time, the token is invalid and a new token must be published to use for API calls. (This can be + done automatically with the ``refresh_token`` in the UI) + +- ``STUDIO_TOKEN_SIGN_PASSWORD`` |br| + This variable is used for the Signature part of the JWT token. The signature is used to verify the message wasn't + changed along the way, and, in the case of tokens signed with a private key, it can also verify that the sender of + the JWT is who it says it is. For Studio, we use HMAC_SHA512 algorithm for the signature. + +- ``STUDIO_TOKEN_ENCRYPT_PASSWORD`` |br| + This variable is used for encrypting the JWT token itself so that it won't be decrypted without a password. + +- ``STUDIO_REFRESH_TOKEN_NAME``, ``STUDIO_REFRESH_TOKEN_MAX_AGE``, ``STUDIO_REFRESH_TOKEN_SECURE`` |br| + These variables are used for customizing the refresh token cookie. JWT token is short lived in general and we use a + refresh token to exchange for a new JWT token when the old one is expired. By default the cookie name is ``refresh_token``. + When creating a new access token, the backend will validate if the refresh token cookie is valid. You should find + this from the cookies in the browser while logging in with Studio. + +For more information on JWT tokens in general, see https://jwt.io/introduction. +For information on creating access tokens in Studio, see :ref:`here `. |hr|