From 051f3118f28fedf7d2b13d03bcf8e3bd9f056ba8 Mon Sep 17 00:00:00 2001 From: arbulu89 Date: Mon, 7 Oct 2024 14:50:30 +0200 Subject: [PATCH 01/20] Add trento sso integration docs --- trento/migration/sso-integration.md | 387 ++++++++++++++ trento/xml/article_sap_trento.xml | 1 + trento/xml/sso-integration.xml | 762 ++++++++++++++++++++++++++++ 3 files changed, 1150 insertions(+) create mode 100644 trento/migration/sso-integration.md create mode 100644 trento/xml/sso-integration.xml diff --git a/trento/migration/sso-integration.md b/trento/migration/sso-integration.md new file mode 100644 index 00000000..434e7a16 --- /dev/null +++ b/trento/migration/sso-integration.md @@ -0,0 +1,387 @@ +# Single Sign-On integration + +Trento can be integrated with an identity provider (IDP) that uses different Single sign-on (SSO) protocols like OpenID Connect (OIDC) and Open Authorization 2.0 (OAuth 2). + +> [!NOTE] +> Trento cannot start with multiple SSO options together, so only one can be chosen. + +## Available protocols + +- OpenID Connect (OIDC) +- Open Authorization 2.0 (OAuth 2) +- Security Assertion Markup Language (SAML) + +## User Roles and Authentication + +User authentication is entirely managed by the IDP, which is responsible for maintaining user accounts. +A user, who does not exist on the IDP, is unable to access the Trento web console. +During the installation process, a default admin user is defined using the `ADMIN_USER` variable, which defaults to `admin`. If the authenticated user’s IDP username matches this admin user's username, that user is automatically granted `all:all` permissions within Trento. +User permissions are entirely managed by Trento, they are not imported from the IDP. The abilities must be granted by some user with `all:all` or `all:users` abilities (**admin user initially**). This means that only basic user information is retrieved from the external IDP. + +## OIDC + +Trento integrates with an IDP that uses the OIDC protocol to authenticate users accessing the Trento web console. + +### Enabling OIDC + +OIDC authentication is **disabled by default**. + +#### Enabling OIDC when using RPM packages + +Provide the following environment variables to trento-web configuration, which is stored at `/etc/trento/trento-web` and restart the application to enable OIDC integration. + +``` +# Required: +ENABLE_OIDC=true +OIDC_CLIENT_ID=<> +OIDC_CLIENT_SECRET=<> +OIDC_BASE_URL=<> + +# Optional: +OIDC_CALLBACK_URL=<> +``` +#### Enabling OIDC when using Docker images + +Provide the following environment variables to the docker container and restart the application to enable OIDC integration. + +```bash +docker run -d \ +-p 4000:4000 \ +--name trento-web \ +--network trento-net \ +--add-host "host.docker.internal:host-gateway" \ + +...[other settings]... + +# Required: +-e ENABLE_OIDC=true \ +-e OIDC_CLIENT_ID=<> \ +-e OIDC_CLIENT_SECRET=<> \ +-e OIDC_BASE_URL=<> \ + +# Optional: +-e OIDC_CALLBACK_URL=<> \ + +...[other settings]... +``` + +### Available variables + +OIDC_CLIENT_ID + +: OIDC client id + +OIDC_CLIENT_SECRET + +: OIDC client secret + +OIDC_BASE_URL + +: OIDC base url + +OIDC_CALLBACK_URL + +: OIDC callback url where the IDP is redirecting once the authentication is completed (default value: `https://#{TRENTO_WEB_ORIGIN}/auth/oidc_callback`) + +## OAuth 2.0 + +Trento integrates with an IDP that uses the OAuth 2 protocol to authenticate users accessing the Trento web console. + +### Enabling OAuth 2.0 + +OAuth 2.0 authentication is **disabled by default**. + +#### Enabling OAuth 2.0 when using RPM packages + +Provide the following environment variables to trento-web configuration, which is stored at `/etc/trento/trento-web` and restart the application to enable OAuth 2.0 integration. + +``` +# Required: +ENABLE_OAUTH2=true +OAUTH2_CLIENT_ID=<> +OAUTH2_CLIENT_SECRET=<> +OAUTH2_BASE_URL=<> +OAUTH2_AUTHORIZE_URL=<> +OAUTH2_TOKEN_URL=<> +OAUTH2_USER_URL=<> + +# Optional: +OAUTH2_SCOPES=<> +OAUTH2_CALLBACK_URL=<> +``` + +> **Note:** OAUTH2_SCOPES is an optional variable with the default value `openid profile email`. OAUTH2_SCOPES must be adjusted depending on IDP provider requirements. + +#### Enabling OAuth 2.0 when using Docker images + +Provide the following environment variables to the docker container and restart the application to enable OAuth 2.0 integration. + +```bash +docker run -d \ +-p 4000:4000 \ +--name trento-web \ +--network trento-net \ +--add-host "host.docker.internal:host-gateway" \ + +...[other settings]... + +-e ENABLE_OAUTH2=true \ +-e OAUTH2_CLIENT_ID=<> \ +-e OAUTH2_CLIENT_SECRET=<> \ +-e OAUTH2_BASE_URL=<> \ +-e OAUTH2_AUTHORIZE_URL=<> \ +-e OAUTH2_TOKEN_URL=<> \ +-e OAUTH2_USER_URL=<> \ + +# Optional: +-e OAUTH2_SCOPES=<> \ +-e OAUTH2_CALLBACK_URL=<> \ + +...[other settings]... +``` + +### Available variables + +OAUTH2_CLIENT_ID + +: OAUTH2 client id + +OAUTH2_CLIENT_SECRET + +: OAUTH2 client secret + +OAUTH2_BASE_URL + +: OAUTH2 base url + +OAUTH2_AUTHORIZE_URL + +: OAUTH2 authorization url + +OAUTH2_TOKEN_URL + +: OAUTH2 token url + +OAUTH2_USER_URL + +: OAUTH2 token url + +OAUTH2_SCOPES + +: OAUTH2 scopes, used to define the user values sent to the SP (default value: `openid profile email`) + +OAUTH2_CALLBACK_URL + +: OAUTH2 callback url where the IDP is redirecting once the authentication is completed (default value: `https://#{TRENTO_WEB_ORIGIN}/auth/oauth2_callback`) + +## SAML + +Trento integrates with an IDP that uses the SAML protocol to authenticate users accessing the Trento web console. + +In order to use an existing SAML IDP, some requirements must be met, configuring the IDP and starting Trento in a specific way. Follow the next instructions to properly setup both. + +### SAML IDP setup + +Configure the existing IDP with the next minimum options to be able to connect with Trento's Service Provider (SP). + +#### SAML user profile + +Users provided by the SAML installation must have some few mandatory attributes in order to login in Trento. All of them are mandatory, even though their name is configurable. +The user profile must include attributes for: username, email, first name and last name. +This attributes must be mapped for all users wanting to connect to Trento. + +By default, Trento expects the `username`, `email`, `firstName` and `lastName` attribute names. All these 4 attribute names are configurable using the next environment variables, following the same order: `SAML_USERNAME_ATTR_NAME`, `SAML_EMAIL_ATTR_NAME`, `SAML_FIRSTNAME_ATTR_NAME` and `SAML_LASTNAME_ATTR_NAME`. +So for example, if the IDP user profile username is defined as `attr:username`, `SAML_USERNAME_ATTR_NAME=attr:username` should be used. + +#### Signing keys + +Commonly, SAML protocol messages are signed with SSL. This is optional using Trento, and the signing is not required (even though it is recommended). +If the IDP signs the messages, and expect signed messages back, certificates used by the SP (Trento in this case) must be provided to the IDP, the Certificate file in this case. + +For this reason, Trento already provides a certificates set created during the installation. When Trento is installed the first time (does not matter the installation mode) the certificates are created, and the public certificate file content is available in the `http://localhost:4000/api/public_keys` route. + +```bash +curl http://localhost:4000/api/public_keys +``` + +Copy the content of the certificate from there, and provide it to the IDP. This way, the IDP will sign and verify the messages sent by both ends. + +When this certificate is used, and provided to the IDP, the IDP recreates its own `metadata.xml` file. This file defines which certificate is used to sign the messages by both sides. At this point, Trento Web must be restarted to use the new `metadata.xml` content. + +If the `SAML_METDATA_CONTENT` option is being used, the content of this variable must be updated with the new metadata. In the other hand, if `SAML_METADATA_URL` is used, the new metadata is automatically fetched. If neither of these steps are completed, communication will fail because the message signatures will not be recognized + +**This restart must be done manually, by the admin. If the installation is done by a `RPM`, restarting the `systemd` daemon. If the installation is done using `Docker`, the container must be restarted.** + +``` +# RPM +systemctl restart trento-web + +# Docker +# Get container ID +docker container ps +# Restart +docker restart container-id +``` + +#### SAML redirect URI + +Once the login is done succesfully, the IDP redirects the session back to Trento. This redirection is done to `https://trento.example.com/sso/sp/consume/saml`, so this URI must be set as valid in the IDP. + +### Enabling SAML + +SAML authentication is **disabled by default**. + +#### Enabling SAML when using RPM packages + +Provide the following environment variables to trento-web configuration, which is stored at `/etc/trento/trento-web` and restart the application to enable SAML integration. + +``` +# Required: +ENABLE_SAML=true +SAML_IDP_ID=<> +SAML_SP_ID=<> +# Only SAML_METADATA_URL or SAML_METADATA_CONTENT must by provided +SAML_METADATA_URL=<> +SAML_METADATA_CONTENT=<> + +# Optional: +SAML_IDP_NAMEID_FORMAT=<> +SAML_SP_DIR=<> +SAML_SP_ENTITY_ID=<> +SAML_SP_CONTACT_NAME=<> +SAML_SP_CONTACT_EMAIL=<> +SAML_SP_ORG_NAME=<> +SAML_SP_ORG_DISPLAYNAME=<> +SAML_SP_ORG_URL=<> +SAML_USERNAME_ATTR_NAME=<> +SAML_EMAIL_ATTR_NAME=<> +SAML_FIRSTNAME_ATTR_NAME=<> +SAML_LASTNAME_ATTR_NAME=<> +SAML_SIGN_REQUESTS=<> +SAML_SIGN_METADATA=<> +SAML_SIGNED_ASSERTION=<> +SAML_SIGNED_ENVELOPES=<> +``` + +#### Enabling SAML when using Docker images + +Provide the following environment variables to the docker container and restart the application to enable SAML integration. + +```bash +docker run -d \ +-p 4000:4000 \ +--name trento-web \ +--network trento-net \ +--add-host "host.docker.internal:host-gateway" \ + +...[other settings]... + +-e ENABLE_SAML=true +-e SAML_IDP_ID=<> \ +-e SAML_SP_ID=<> \ +# Only SAML_METADATA_URL or SAML_METADATA_CONTENT must by provided +-e SAML_METADATA_URL=<> \ +-e SAML_METADATA_CONTENT=<> \ + +# Optional: +-e SAML_IDP_NAMEID_FORMAT=<> \ +-e SAML_SP_DIR=<> \ +-e SAML_SP_ENTITY_ID=<> \ +-e SAML_SP_CONTACT_NAME=<> \ +-e SAML_SP_CONTACT_EMAIL=<> \ +-e SAML_SP_ORG_NAME=<> \ +-e SAML_SP_ORG_DISPLAYNAME=<> \ +-e SAML_SP_ORG_URL=<> \ +-e SAML_USERNAME_ATTR_NAME=<> \ +-e SAML_EMAIL_ATTR_NAME=<> \ +-e SAML_FIRSTNAME_ATTR_NAME=<> \ +-e SAML_LASTNAME_ATTR_NAME=<> \ +-e SAML_SIGN_REQUESTS=<> \ +-e SAML_SIGN_METADATA=<> \ +-e SAML_SIGNED_ASSERTION=<> \ +-e SAML_SIGNED_ENVELOPES=<> \ + +...[other settings]... +``` + +### Available variables + +SAML_IDP_ID + +: SAML IDP id + +SAML_SP_ID + +: SAML SP id + +SAML_METADATA_URL + +: URL to retrieve the SAML metadata xml file. One of `SAML_METADATA_URL` or `SAML_METADATA_CONTENT` is required + +SAML_METADATA_CONTENT + +: One line string containing the SAML metadata xml file content (`SAML_METADATA_URL` has precedence over this) + +SAML_IDP_NAMEID_FORMAT + +: SAML IDP name id format, used to interpret the attribute name. Whole urn string must be used (default value: `SAML IDP name id format, used to interpret the attribute name. Whole urn string must be used`) + +SAML_SP_DIR + +: SAML SP directory, where SP specific required files (such as certificates and metadata file) are placed (default value: `/etc/trento/trento-web/saml`) + +SAML_SP_ENTITY_ID + +: SAML SP entity id. If it is not given, value from the metadata.xml file is used + +SAML_SP_CONTACT_NAME + +: SAML SP contact name (default value: `Trento SP Admin`) + +SAML_SP_CONTACT_EMAIL + +: SAML SP contact email (default value: `admin@trento.suse.com`) + +SAML_SP_ORG_NAME + +: SAML SP organization name (default value: `Trento SP`) + +SAML_SP_ORG_DISPLAYNAME + +: SAML SP organization display name (default value: `SAML SP build with Trento`) + +SAML_SP_ORG_URL + +: SAML SP organization url (default value: `https://www.trento-project.io/`) + +SAML_USERNAME_ATTR_NAME + +: SAML user profile "username" attribute field name. This attribute must exist in the IDP user (default value: `username`) + +SAML_EMAIL_ATTR_NAME + +: SAML user profile "email" attribute field name. This attribute must exist in the IDP user (default value: `email`) + +SAML_FIRSTNAME_ATTR_NAME + +: SAML user profile "first name" attribute field name. This attribute must exist in the IDP user (default value: `firstName`) + +SAML_LASTNAME_ATTR_NAME + +: SAML user profile "last name" attribute field name. This attribute must exist in the IDP user (default value: `lastName`) + +SAML_SIGN_REQUESTS + +: Sign SAML requests in the SP side (default value: `true`) + +SAML_SIGN_METADATA + +: Sign SAML metadata documents in the SP side (default value: `true`) + +SAML_SIGNED_ASSERTION + +: Require to receive SAML assertion signed from the IDP. Set to false if the IDP doesn't sign the assertion (default value: `true`) + +SAML_SIGNED_ENVELOPES + +: Require to receive SAML envelopes signed from the IDP. Set to false if the IDP doesn't sign the envelopes (default value: `true`) \ No newline at end of file diff --git a/trento/xml/article_sap_trento.xml b/trento/xml/article_sap_trento.xml index ebdf188c..8f908cad 100644 --- a/trento/xml/article_sap_trento.xml +++ b/trento/xml/article_sap_trento.xml @@ -671,6 +671,7 @@ As agreed on https://confluence.suse.com/x/DAEcN on our Trento doc kick off +
diff --git a/trento/xml/sso-integration.xml b/trento/xml/sso-integration.xml new file mode 100644 index 00000000..52065dfd --- /dev/null +++ b/trento/xml/sso-integration.xml @@ -0,0 +1,762 @@ +
+ Single Sign-On integration + + Trento can be integrated with an identity provider (IDP) that uses + different Single sign-on (SSO) protocols like OpenID Connect (OIDC) + and Open Authorization 2.0 (OAuth 2). + +
+[!NOTE] +Trento cannot start with multiple SSO options together, so only one can be chosen. +
+
+ Available protocols + + + + OpenID Connect (OIDC) + + + + + Open Authorization 2.0 (OAuth 2) + + + + + Security Assertion Markup Language (SAML) + + + +
+
+ User Roles and Authentication + + User authentication is entirely managed by the IDP, which is + responsible for maintaining user accounts. A user, who does not + exist on the IDP, is unable to access the Trento web console. + During the installation process, a default admin user is defined + using the ADMIN_USER variable, which defaults + to admin. If the authenticated user’s IDP + username matches this admin user's username, that user is + automatically granted all:all permissions + within Trento. User permissions are entirely managed by Trento, + they are not imported from the IDP. The abilities must be granted + by some user with all:all or + all:users abilities + (admin user initially). This + means that only basic user information is retrieved from the + external IDP. + +
+
+ OIDC + + Trento integrates with an IDP that uses the OIDC protocol to + authenticate users accessing the Trento web console. + +
+ Enabling OIDC + + OIDC authentication is disabled by + default. + +
+ Enabling OIDC when using RPM packages + + Provide the following environment variables to trento-web + configuration, which is stored at + /etc/trento/trento-web and restart the + application to enable OIDC integration. + + +# Required: +ENABLE_OIDC=true +OIDC_CLIENT_ID=<<OIDC_CLIENT_ID>> +OIDC_CLIENT_SECRET=<<OIDC_CLIENT_SECRET>> +OIDC_BASE_URL=<<OIDC_BASE_URL>> + +# Optional: +OIDC_CALLBACK_URL=<<OIDC_CALLBACK_URL>> + +
+
+ Enabling OIDC when using Docker images + + Provide the following environment variables to the docker + container and restart the application to enable OIDC + integration. + + +docker run -d \ +-p 4000:4000 \ +--name trento-web \ +--network trento-net \ +--add-host "host.docker.internal:host-gateway" \ + +...[other settings]... + +# Required: +-e ENABLE_OIDC=true \ +-e OIDC_CLIENT_ID=<<OIDC_CLIENT_ID>> \ +-e OIDC_CLIENT_SECRET=<<OIDC_CLIENT_SECRET>> \ +-e OIDC_BASE_URL=<<OIDC_BASE_URL>> \ + +# Optional: +-e OIDC_CALLBACK_URL=<<OIDC_CALLBACK_URL>> \ + +...[other settings]... + +
+
+
+ Available variables + + + + OIDC_CLIENT_ID + + + + OIDC client id + + + + + + OIDC_CLIENT_SECRET + + + + OIDC client secret + + + + + + OIDC_BASE_URL + + + + OIDC base url + + + + + + OIDC_CALLBACK_URL + + + + OIDC callback url where the IDP is redirecting once the + authentication is completed (default value: + https://#{TRENTO_WEB_ORIGIN}/auth/oidc_callback) + + + + +
+
+
+ OAuth 2.0 + + Trento integrates with an IDP that uses the OAuth 2 protocol to + authenticate users accessing the Trento web console. + +
+ Enabling OAuth 2.0 + + OAuth 2.0 authentication is disabled by + default. + +
+ Enabling OAuth 2.0 when using RPM packages + + Provide the following environment variables to trento-web + configuration, which is stored at + /etc/trento/trento-web and restart the + application to enable OAuth 2.0 integration. + + +# Required: +ENABLE_OAUTH2=true +OAUTH2_CLIENT_ID=<<OAUTH2_CLIENT_ID>> +OAUTH2_CLIENT_SECRET=<<OAUTH2_CLIENT_SECRET>> +OAUTH2_BASE_URL=<<OAUTH2_BASE_URL>> +OAUTH2_AUTHORIZE_URL=<<OAUTH2_AUTHORIZE_URL>> +OAUTH2_TOKEN_URL=<<OAUTH2_TOKEN_URL>> +OAUTH2_USER_URL=<<OAUTH2_USER_URL>> + +# Optional: +OAUTH2_SCOPES=<<OAUTH2_SCOPES>> +OAUTH2_CALLBACK_URL=<<OAUTH2_CALLBACK_URL>> + +
+ + Note: OAUTH2_SCOPES is an + optional variable with the default value + openid profile email. OAUTH2_SCOPES must + be adjusted depending on IDP provider requirements. + +
+
+
+ Enabling OAuth 2.0 when using Docker images + + Provide the following environment variables to the docker + container and restart the application to enable OAuth 2.0 + integration. + + +docker run -d \ +-p 4000:4000 \ +--name trento-web \ +--network trento-net \ +--add-host "host.docker.internal:host-gateway" \ + +...[other settings]... + +-e ENABLE_OAUTH2=true \ +-e OAUTH2_CLIENT_ID=<<OAUTH2_CLIENT_ID>> \ +-e OAUTH2_CLIENT_SECRET=<<OAUTH2_CLIENT_SECRET>> \ +-e OAUTH2_BASE_URL=<<OAUTH2_BASE_URL>> \ +-e OAUTH2_AUTHORIZE_URL=<<OAUTH2_AUTHORIZE_URL>> \ +-e OAUTH2_TOKEN_URL=<<OAUTH2_TOKEN_URL>> \ +-e OAUTH2_USER_URL=<<OAUTH2_USER_URL>> \ + +# Optional: +-e OAUTH2_SCOPES=<<OAUTH2_SCOPES>> \ +-e OAUTH2_CALLBACK_URL=<<OAUTH2_CALLBACK_URL>> \ + +...[other settings]... + +
+
+
+ Available variables + + + + OAUTH2_CLIENT_ID + + + + OAUTH2 client id + + + + + + OAUTH2_CLIENT_SECRET + + + + OAUTH2 client secret + + + + + + OAUTH2_BASE_URL + + + + OAUTH2 base url + + + + + + OAUTH2_AUTHORIZE_URL + + + + OAUTH2 authorization url + + + + + + OAUTH2_TOKEN_URL + + + + OAUTH2 token url + + + + + + OAUTH2_USER_URL + + + + OAUTH2 token url + + + + + + OAUTH2_SCOPES + + + + OAUTH2 scopes, used to define the user values sent to the + SP (default value: + openid profile email) + + + + + + OAUTH2_CALLBACK_URL + + + + OAUTH2 callback url where the IDP is redirecting once the + authentication is completed (default value: + https://#{TRENTO_WEB_ORIGIN}/auth/oauth2_callback) + + + + +
+
+
+ SAML + + Trento integrates with an IDP that uses the SAML protocol to + authenticate users accessing the Trento web console. + + + In order to use an existing SAML IDP, some requirements must be + met, configuring the IDP and starting Trento in a specific way. + Follow the next instructions to properly setup both. + +
+ SAML IDP setup + + Configure the existing IDP with the next minimum options to be + able to connect with Trento's Service Provider (SP). + +
+ SAML user profile + + Users provided by the SAML installation must have some few + mandatory attributes in order to login in Trento. All of them + are mandatory, even though their name is configurable. The + user profile must include attributes for: username, email, + first name and last name. This attributes must be mapped for + all users wanting to connect to Trento. + + + By default, Trento expects the username, + email, firstName and + lastName attribute names. All these 4 + attribute names are configurable using the next environment + variables, following the same order: + SAML_USERNAME_ATTR_NAME, + SAML_EMAIL_ATTR_NAME, + SAML_FIRSTNAME_ATTR_NAME and + SAML_LASTNAME_ATTR_NAME. So for example, if + the IDP user profile username is defined as + attr:username, + SAML_USERNAME_ATTR_NAME=attr:username + should be used. + +
+
+ Signing keys + + Commonly, SAML protocol messages are signed with SSL. This is + optional using Trento, and the signing is not required (even + though it is recommended). If the IDP signs the messages, and + expect signed messages back, certificates used by the SP + (Trento in this case) must be provided to the IDP, the + Certificate file in this case. + + + For this reason, Trento already provides a certificates set + created during the installation. When Trento is installed the + first time (does not matter the installation mode) the + certificates are created, and the public certificate file + content is available in the + http://localhost:4000/api/public_keys + route. + + +curl http://localhost:4000/api/public_keys + + + Copy the content of the certificate from there, and provide it + to the IDP. This way, the IDP will sign and verify the + messages sent by both ends. + + + When this certificate is used, and provided to the IDP, the + IDP recreates its own metadata.xml file. + This file defines which certificate is used to sign the + messages by both sides. At this point, Trento Web must be + restarted to use the new metadata.xml + content. + + + If the SAML_METDATA_CONTENT option is being + used, the content of this variable must be updated with the + new metadata. In the other hand, if + SAML_METADATA_URL is used, the new metadata + is automatically fetched. If neither of these steps are + completed, communication will fail because the message + signatures will not be recognized + + + This restart must be done manually, by + the admin. If the installation is done by a + RPM, restarting the + systemd daemon. If the installation is done + using Docker, the container must be + restarted. + + +# RPM +systemctl restart trento-web + +# Docker +# Get container ID +docker container ps +# Restart +docker restart container-id + +
+
+ SAML redirect URI + + Once the login is done succesfully, the IDP redirects the + session back to Trento. This redirection is done to + https://trento.example.com/sso/sp/consume/saml, + so this URI must be set as valid in the IDP. + +
+
+
+ Enabling SAML + + SAML authentication is disabled by + default. + +
+ Enabling SAML when using RPM packages + + Provide the following environment variables to trento-web + configuration, which is stored at + /etc/trento/trento-web and restart the + application to enable SAML integration. + + +# Required: +ENABLE_SAML=true +SAML_IDP_ID=<<SAML_IDP_ID>> +SAML_SP_ID=<<SAML_SP_ID>> +# Only SAML_METADATA_URL or SAML_METADATA_CONTENT must by provided +SAML_METADATA_URL=<<SAML_METADATA_URL>> +SAML_METADATA_CONTENT=<<SAML_METADATA_CONTENT>> + +# Optional: +SAML_IDP_NAMEID_FORMAT=<<SAML_IDP_NAMEID_FORMAT>> +SAML_SP_DIR=<<SAML_SP_DIR>> +SAML_SP_ENTITY_ID=<<SAML_SP_ENTITY_ID>> +SAML_SP_CONTACT_NAME=<<SAML_SP_CONTACT_NAME>> +SAML_SP_CONTACT_EMAIL=<<SAML_SP_CONTACT_EMAIL>> +SAML_SP_ORG_NAME=<<SAML_SP_ORG_NAME>> +SAML_SP_ORG_DISPLAYNAME=<<SAML_SP_ORG_DISPLAYNAME>> +SAML_SP_ORG_URL=<<SAML_SP_ORG_URL>> +SAML_USERNAME_ATTR_NAME=<<SAML_USERNAME_ATTR_NAME>> +SAML_EMAIL_ATTR_NAME=<<SAML_EMAIL_ATTR_NAME>> +SAML_FIRSTNAME_ATTR_NAME=<<SAML_FIRSTNAME_ATTR_NAME>> +SAML_LASTNAME_ATTR_NAME=<<SAML_LASTNAME_ATTR_NAME>> +SAML_SIGN_REQUESTS=<<SAML_SIGN_REQUESTS>> +SAML_SIGN_METADATA=<<SAML_SIGN_METADATA>> +SAML_SIGNED_ASSERTION=<<SAML_SIGNED_ASSERTION>> +SAML_SIGNED_ENVELOPES=<<SAML_SIGNED_ENVELOPES>> + +
+
+ Enabling SAML when using Docker images + + Provide the following environment variables to the docker + container and restart the application to enable SAML + integration. + + +docker run -d \ +-p 4000:4000 \ +--name trento-web \ +--network trento-net \ +--add-host "host.docker.internal:host-gateway" \ + +...[other settings]... + +-e ENABLE_SAML=true +-e SAML_IDP_ID=<<SAML_IDP_ID>> \ +-e SAML_SP_ID=<<SAML_SP_ID>> \ +# Only SAML_METADATA_URL or SAML_METADATA_CONTENT must by provided +-e SAML_METADATA_URL=<<SAML_METADATA_URL>> \ +-e SAML_METADATA_CONTENT=<<SAML_METADATA_CONTENT>> \ + +# Optional: +-e SAML_IDP_NAMEID_FORMAT=<<SAML_IDP_NAMEID_FORMAT>> \ +-e SAML_SP_DIR=<<SAML_SP_DIR>> \ +-e SAML_SP_ENTITY_ID=<<SAML_SP_ENTITY_ID>> \ +-e SAML_SP_CONTACT_NAME=<<SAML_SP_CONTACT_NAME>> \ +-e SAML_SP_CONTACT_EMAIL=<<SAML_SP_CONTACT_EMAIL>> \ +-e SAML_SP_ORG_NAME=<<SAML_SP_ORG_NAME>> \ +-e SAML_SP_ORG_DISPLAYNAME=<<SAML_SP_ORG_DISPLAYNAME>> \ +-e SAML_SP_ORG_URL=<<SAML_SP_ORG_URL>> \ +-e SAML_USERNAME_ATTR_NAME=<<SAML_USERNAME_ATTR_NAME>> \ +-e SAML_EMAIL_ATTR_NAME=<<SAML_EMAIL_ATTR_NAME>> \ +-e SAML_FIRSTNAME_ATTR_NAME=<<SAML_FIRSTNAME_ATTR_NAME>> \ +-e SAML_LASTNAME_ATTR_NAME=<<SAML_LASTNAME_ATTR_NAME>> \ +-e SAML_SIGN_REQUESTS=<<SAML_SIGN_REQUESTS>> \ +-e SAML_SIGN_METADATA=<<SAML_SIGN_METADATA>> \ +-e SAML_SIGNED_ASSERTION=<<SAML_SIGNED_ASSERTION>> \ +-e SAML_SIGNED_ENVELOPES=<<SAML_SIGNED_ENVELOPES>> \ + +...[other settings]... + +
+
+
+ Available variables + + + + SAML_IDP_ID + + + + SAML IDP id + + + + + + SAML_SP_ID + + + + SAML SP id + + + + + + SAML_METADATA_URL + + + + URL to retrieve the SAML metadata xml file. One of + SAML_METADATA_URL or + SAML_METADATA_CONTENT is required + + + + + + SAML_METADATA_CONTENT + + + + One line string containing the SAML metadata xml file + content (SAML_METADATA_URL has + precedence over this) + + + + + + SAML_IDP_NAMEID_FORMAT + + + + SAML IDP name id format, used to interpret the attribute + name. Whole urn string must be used (default value: + SAML IDP name id format, used to interpret the attribute name. Whole urn string must be used) + + + + + + SAML_SP_DIR + + + + SAML SP directory, where SP specific required files (such + as certificates and metadata file) are placed (default + value: /etc/trento/trento-web/saml) + + + + + + SAML_SP_ENTITY_ID + + + + SAML SP entity id. If it is not given, value from the + metadata.xml file is used + + + + + + SAML_SP_CONTACT_NAME + + + + SAML SP contact name (default value: + Trento SP Admin) + + + + + + SAML_SP_CONTACT_EMAIL + + + + SAML SP contact email (default value: + admin@trento.suse.com) + + + + + + SAML_SP_ORG_NAME + + + + SAML SP organization name (default value: + Trento SP) + + + + + + SAML_SP_ORG_DISPLAYNAME + + + + SAML SP organization display name (default value: + SAML SP build with Trento) + + + + + + SAML_SP_ORG_URL + + + + SAML SP organization url (default value: + https://www.trento-project.io/) + + + + + + SAML_USERNAME_ATTR_NAME + + + + SAML user profile "username" attribute field + name. This attribute must exist in the IDP user (default + value: username) + + + + + + SAML_EMAIL_ATTR_NAME + + + + SAML user profile "email" attribute field name. + This attribute must exist in the IDP user (default value: + email) + + + + + + SAML_FIRSTNAME_ATTR_NAME + + + + SAML user profile "first name" attribute field + name. This attribute must exist in the IDP user (default + value: firstName) + + + + + + SAML_LASTNAME_ATTR_NAME + + + + SAML user profile "last name" attribute field + name. This attribute must exist in the IDP user (default + value: lastName) + + + + + + SAML_SIGN_REQUESTS + + + + Sign SAML requests in the SP side (default value: + true) + + + + + + SAML_SIGN_METADATA + + + + Sign SAML metadata documents in the SP side (default + value: true) + + + + + + SAML_SIGNED_ASSERTION + + + + Require to receive SAML assertion signed from the IDP. Set + to false if the IDP doesn't sign the assertion (default + value: true) + + + + + + SAML_SIGNED_ENVELOPES + + + + Require to receive SAML envelopes signed from the IDP. Set + to false if the IDP doesn't sign the envelopes (default + value: true) + + + + +
+
+
From e09204cf22024fc0ae788a5055156a05809c550a Mon Sep 17 00:00:00 2001 From: arbulu89 Date: Mon, 7 Oct 2024 16:54:27 +0200 Subject: [PATCH 02/20] Apply xml improvements --- trento/migration/sso-integration.md | 31 +++++++++++--------- trento/xml/sso-integration.xml | 45 ++++++++++++----------------- 2 files changed, 35 insertions(+), 41 deletions(-) diff --git a/trento/migration/sso-integration.md b/trento/migration/sso-integration.md index 434e7a16..3a21f6f0 100644 --- a/trento/migration/sso-integration.md +++ b/trento/migration/sso-integration.md @@ -2,13 +2,18 @@ Trento can be integrated with an identity provider (IDP) that uses different Single sign-on (SSO) protocols like OpenID Connect (OIDC) and Open Authorization 2.0 (OAuth 2). -> [!NOTE] -> Trento cannot start with multiple SSO options together, so only one can be chosen. +```{=docbook} + + Trento cannot start with multiple SSO options together, so only one can be chosen. + +``` ## Available protocols - OpenID Connect (OIDC) + - Open Authorization 2.0 (OAuth 2) + - Security Assertion Markup Language (SAML) ## User Roles and Authentication @@ -28,7 +33,7 @@ OIDC authentication is **disabled by default**. #### Enabling OIDC when using RPM packages -Provide the following environment variables to trento-web configuration, which is stored at `/etc/trento/trento-web` and restart the application to enable OIDC integration. +Provide the following environment variables to trento-web configuration, which is stored at /etc/trento/trento-web and restart the application to enable OIDC integration. ``` # Required: @@ -81,7 +86,7 @@ OIDC_BASE_URL OIDC_CALLBACK_URL -: OIDC callback url where the IDP is redirecting once the authentication is completed (default value: `https://#{TRENTO_WEB_ORIGIN}/auth/oidc_callback`) +: OIDC callback url where the IDP is redirecting once the authentication is completed (default value: https://#{TRENTO_WEB_ORIGIN}/auth/oidc_callback) ## OAuth 2.0 @@ -93,7 +98,7 @@ OAuth 2.0 authentication is **disabled by default**. #### Enabling OAuth 2.0 when using RPM packages -Provide the following environment variables to trento-web configuration, which is stored at `/etc/trento/trento-web` and restart the application to enable OAuth 2.0 integration. +Provide the following environment variables to trento-web configuration, which is stored at /etc/trento/trento-web and restart the application to enable OAuth 2.0 integration. ``` # Required: @@ -110,8 +115,6 @@ OAUTH2_SCOPES=<> OAUTH2_CALLBACK_URL=<> ``` -> **Note:** OAUTH2_SCOPES is an optional variable with the default value `openid profile email`. OAUTH2_SCOPES must be adjusted depending on IDP provider requirements. - #### Enabling OAuth 2.0 when using Docker images Provide the following environment variables to the docker container and restart the application to enable OAuth 2.0 integration. @@ -168,7 +171,7 @@ OAUTH2_USER_URL OAUTH2_SCOPES -: OAUTH2 scopes, used to define the user values sent to the SP (default value: `openid profile email`) +: OAUTH2 scopes, used to define the user values sent to the SP. It must be adjusted depending on IDP provider requirements (default value: `openid profile email`) OAUTH2_CALLBACK_URL @@ -198,7 +201,7 @@ So for example, if the IDP user profile username is defined as `attr:username`, Commonly, SAML protocol messages are signed with SSL. This is optional using Trento, and the signing is not required (even though it is recommended). If the IDP signs the messages, and expect signed messages back, certificates used by the SP (Trento in this case) must be provided to the IDP, the Certificate file in this case. -For this reason, Trento already provides a certificates set created during the installation. When Trento is installed the first time (does not matter the installation mode) the certificates are created, and the public certificate file content is available in the `http://localhost:4000/api/public_keys` route. +For this reason, Trento already provides a certificates set created during the installation. When Trento is installed the first time (does not matter the installation mode) the certificates are created, and the public certificate file content is available in the http://localhost:4000/api/public_keys route. ```bash curl http://localhost:4000/api/public_keys @@ -206,11 +209,11 @@ curl http://localhost:4000/api/public_keys Copy the content of the certificate from there, and provide it to the IDP. This way, the IDP will sign and verify the messages sent by both ends. -When this certificate is used, and provided to the IDP, the IDP recreates its own `metadata.xml` file. This file defines which certificate is used to sign the messages by both sides. At this point, Trento Web must be restarted to use the new `metadata.xml` content. +When this certificate is used, and provided to the IDP, the IDP recreates its own metadata.xml file. This file defines which certificate is used to sign the messages by both sides. At this point, Trento Web must be restarted to use the new metadata.xml content. -If the `SAML_METDATA_CONTENT` option is being used, the content of this variable must be updated with the new metadata. In the other hand, if `SAML_METADATA_URL` is used, the new metadata is automatically fetched. If neither of these steps are completed, communication will fail because the message signatures will not be recognized +If the option is being used, the content of this variable must be updated with the new metadata. In the other hand, if is used, the new metadata is automatically fetched. If neither of these steps are completed, communication will fail because the message signatures will not be recognized -**This restart must be done manually, by the admin. If the installation is done by a `RPM`, restarting the `systemd` daemon. If the installation is done using `Docker`, the container must be restarted.** +**This restart must be done manually, by the admin.** If the installation is done by a `RPM`, restarting the `systemd` daemon. If the installation is done using `Docker`, the container must be restarted. ``` # RPM @@ -324,11 +327,11 @@ SAML_METADATA_CONTENT SAML_IDP_NAMEID_FORMAT -: SAML IDP name id format, used to interpret the attribute name. Whole urn string must be used (default value: `SAML IDP name id format, used to interpret the attribute name. Whole urn string must be used`) +: SAML IDP name id format, used to interpret the attribute name. Whole urn string must be used (default value: `urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified`) SAML_SP_DIR -: SAML SP directory, where SP specific required files (such as certificates and metadata file) are placed (default value: `/etc/trento/trento-web/saml`) +: SAML SP directory, where SP specific required files (such as certificates and metadata file) are placed (default value: /etc/trento/trento-web/saml) SAML_SP_ENTITY_ID diff --git a/trento/xml/sso-integration.xml b/trento/xml/sso-integration.xml index 52065dfd..99794af6 100644 --- a/trento/xml/sso-integration.xml +++ b/trento/xml/sso-integration.xml @@ -5,13 +5,12 @@ different Single sign-on (SSO) protocols like OpenID Connect (OIDC) and Open Authorization 2.0 (OAuth 2). -
-[!NOTE] -Trento cannot start with multiple SSO options together, so only one can be chosen. -
+ + Trento cannot start with multiple SSO options together, so only one can be chosen. +
Available protocols - + OpenID Connect (OIDC) @@ -66,7 +65,7 @@ Trento cannot start with multiple SSO options together, so only one can be chose Provide the following environment variables to trento-web configuration, which is stored at - /etc/trento/trento-web and restart the + /etc/trento/trento-web and restart the application to enable OIDC integration. @@ -150,7 +149,7 @@ docker run -d \ OIDC callback url where the IDP is redirecting once the authentication is completed (default value: - https://#{TRENTO_WEB_ORIGIN}/auth/oidc_callback) + https://#{TRENTO_WEB_ORIGIN}/auth/oidc_callback) @@ -174,7 +173,7 @@ docker run -d \ Provide the following environment variables to trento-web configuration, which is stored at - /etc/trento/trento-web and restart the + /etc/trento/trento-web and restart the application to enable OAuth 2.0 integration. @@ -191,14 +190,6 @@ OAUTH2_USER_URL=<<OAUTH2_USER_URL>> OAUTH2_SCOPES=<<OAUTH2_SCOPES>> OAUTH2_CALLBACK_URL=<<OAUTH2_CALLBACK_URL>> -
- - Note: OAUTH2_SCOPES is an - optional variable with the default value - openid profile email. OAUTH2_SCOPES must - be adjusted depending on IDP provider requirements. - -
Enabling OAuth 2.0 when using Docker images @@ -302,7 +293,8 @@ docker run -d \ OAUTH2 scopes, used to define the user values sent to the - SP (default value: + SP. It must be adjusted depending on IDP provider + requirements (default value: openid profile email) @@ -381,8 +373,7 @@ docker run -d \ first time (does not matter the installation mode) the certificates are created, and the public certificate file content is available in the - http://localhost:4000/api/public_keys - route. + http://localhost:4000/api/public_keys route. curl http://localhost:4000/api/public_keys @@ -394,28 +385,28 @@ curl http://localhost:4000/api/public_keys When this certificate is used, and provided to the IDP, the - IDP recreates its own metadata.xml file. + IDP recreates its own metadata.xml file. This file defines which certificate is used to sign the messages by both sides. At this point, Trento Web must be - restarted to use the new metadata.xml + restarted to use the new metadata.xml content. - If the SAML_METDATA_CONTENT option is being + If the option is being used, the content of this variable must be updated with the new metadata. In the other hand, if - SAML_METADATA_URL is used, the new metadata + is used, the new metadata is automatically fetched. If neither of these steps are completed, communication will fail because the message signatures will not be recognized This restart must be done manually, by - the admin. If the installation is done by a + the admin. If the installation is done by a RPM, restarting the systemd daemon. If the installation is done using Docker, the container must be - restarted. + restarted. # RPM @@ -580,7 +571,7 @@ docker run -d \ SAML IDP name id format, used to interpret the attribute name. Whole urn string must be used (default value: - SAML IDP name id format, used to interpret the attribute name. Whole urn string must be used) + urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified) @@ -592,7 +583,7 @@ docker run -d \ SAML SP directory, where SP specific required files (such as certificates and metadata file) are placed (default - value: /etc/trento/trento-web/saml) + value: /etc/trento/trento-web/saml) From 783dfed071f86d970d249f2d0af45ac73fb470f1 Mon Sep 17 00:00:00 2001 From: Tom Schraitle Date: Wed, 9 Oct 2024 10:29:28 +0200 Subject: [PATCH 03/20] First draft of restructure into tasks + concepts * Try to use procedures (step-by-step instructions) * Add comments in // * Still needs some additions from my suggestions at GitHub --- trento/migration/sso-integration.md | 191 ++++++++++++++++------------ 1 file changed, 113 insertions(+), 78 deletions(-) diff --git a/trento/migration/sso-integration.md b/trento/migration/sso-integration.md index 3a21f6f0..5a0b2554 100644 --- a/trento/migration/sso-integration.md +++ b/trento/migration/sso-integration.md @@ -1,4 +1,4 @@ -# Single Sign-On integration +# Integrating Single Sign-On Trento can be integrated with an identity provider (IDP) that uses different Single sign-on (SSO) protocols like OpenID Connect (OIDC) and Open Authorization 2.0 (OAuth 2). @@ -8,7 +8,7 @@ Trento can be integrated with an identity provider (IDP) that uses different Sin ``` -## Available protocols +Available protocols are: - OpenID Connect (OIDC) @@ -20,57 +20,75 @@ Trento can be integrated with an identity provider (IDP) that uses different Sin User authentication is entirely managed by the IDP, which is responsible for maintaining user accounts. A user, who does not exist on the IDP, is unable to access the Trento web console. + During the installation process, a default admin user is defined using the `ADMIN_USER` variable, which defaults to `admin`. If the authenticated user’s IDP username matches this admin user's username, that user is automatically granted `all:all` permissions within Trento. -User permissions are entirely managed by Trento, they are not imported from the IDP. The abilities must be granted by some user with `all:all` or `all:users` abilities (**admin user initially**). This means that only basic user information is retrieved from the external IDP. +User permissions are entirely managed by Trento, they are not imported from the IDP. The abilities must be granted by some user with `all:all` or `all:users` abilities (admin user initially). This means that only basic user information is retrieved from the external IDP. + -## OIDC +## Using OpenID Connect Trento integrates with an IDP that uses the OIDC protocol to authenticate users accessing the Trento web console. -### Enabling OIDC +By default, OIDC is disabled. You can enable OIDC when using RPM packages or using Docker images. -OIDC authentication is **disabled by default**. -#### Enabling OIDC when using RPM packages +### Enabling OpenID Connect when using RPM packages -Provide the following environment variables to trento-web configuration, which is stored at /etc/trento/trento-web and restart the application to enable OIDC integration. +To enable OIDC when using RPM packages, proceed as follows: -``` -# Required: -ENABLE_OIDC=true -OIDC_CLIENT_ID=<> -OIDC_CLIENT_SECRET=<> -OIDC_BASE_URL=<> +1. Open the file /etc/trento/trento-web. +1. Add the following environment variables to this file. + Required variables are: -# Optional: -OIDC_CALLBACK_URL=<> -``` -#### Enabling OIDC when using Docker images + ``` + ENABLE_OIDC=true + OIDC_CLIENT_ID= + OIDC_CLIENT_SECRET= + OIDC_BASE_URL= + ``` -Provide the following environment variables to the docker container and restart the application to enable OIDC integration. +1. Optionally, add the OIDC callback URL to the configuration: + // reason why you would need that? -```bash -docker run -d \ --p 4000:4000 \ ---name trento-web \ ---network trento-net \ ---add-host "host.docker.internal:host-gateway" \ + ``` + OIDC_CALLBACK_URL= + ``` -...[other settings]... +1. Restart the application. -# Required: --e ENABLE_OIDC=true \ --e OIDC_CLIENT_ID=<> \ --e OIDC_CLIENT_SECRET=<> \ --e OIDC_BASE_URL=<> \ -# Optional: --e OIDC_CALLBACK_URL=<> \ +### Enabling OpenID Connect when using Docker images -...[other settings]... -``` +To enable OIDC when using Docker images, proceed as follows: + +1. Provide the following environment variables to the Docker container via + the `-e` option: + + ```bash + docker run -d \ + -p 4000:4000 \ + --name trento-web \ + --network trento-net \ + --add-host "host.docker.internal:host-gateway" \ + + ...[other settings]... + + # Required: + -e ENABLE_OIDC=true \ + -e OIDC_CLIENT_ID= \ + -e OIDC_CLIENT_SECRET= \ + -e OIDC_BASE_URL= \ + + # Optional: + -e OIDC_CALLBACK_URL= \ + + ...[other settings]... + ``` + +1. Restart the application. -### Available variables + +### Available variables for OpenID Connect OIDC_CLIENT_ID @@ -88,62 +106,72 @@ OIDC_CALLBACK_URL : OIDC callback url where the IDP is redirecting once the authentication is completed (default value: https://#{TRENTO_WEB_ORIGIN}/auth/oidc_callback) -## OAuth 2.0 +## Using OAuth 2.0 Trento integrates with an IDP that uses the OAuth 2 protocol to authenticate users accessing the Trento web console. -### Enabling OAuth 2.0 +By default, OAuth 2.0 is disabled. You can enable OIDC when using RPM packages or using Docker images. -OAuth 2.0 authentication is **disabled by default**. -#### Enabling OAuth 2.0 when using RPM packages +### Enabling OAuth 2.0 when using RPM packages -Provide the following environment variables to trento-web configuration, which is stored at /etc/trento/trento-web and restart the application to enable OAuth 2.0 integration. +To enable OAuth 2.0 when using RPM packages, proceed as follows: -``` -# Required: -ENABLE_OAUTH2=true -OAUTH2_CLIENT_ID=<> -OAUTH2_CLIENT_SECRET=<> -OAUTH2_BASE_URL=<> -OAUTH2_AUTHORIZE_URL=<> -OAUTH2_TOKEN_URL=<> -OAUTH2_USER_URL=<> +1. Open the file /etc/trento/trento-web. +1. Add the following environment variables to this file. + Required variables are: -# Optional: -OAUTH2_SCOPES=<> -OAUTH2_CALLBACK_URL=<> -``` + ``` + # Required: + ENABLE_OAUTH2=true + OAUTH2_CLIENT_ID= + OAUTH2_CLIENT_SECRET= + OAUTH2_BASE_URL= + OAUTH2_AUTHORIZE_URL= + OAUTH2_TOKEN_URL= + OAUTH2_USER_URL= -#### Enabling OAuth 2.0 when using Docker images + # Optional: + OAUTH2_SCOPES= + OAUTH2_CALLBACK_URL= + ``` -Provide the following environment variables to the docker container and restart the application to enable OAuth 2.0 integration. +1. Restart the application. -```bash -docker run -d \ --p 4000:4000 \ ---name trento-web \ ---network trento-net \ ---add-host "host.docker.internal:host-gateway" \ -...[other settings]... --e ENABLE_OAUTH2=true \ --e OAUTH2_CLIENT_ID=<> \ --e OAUTH2_CLIENT_SECRET=<> \ --e OAUTH2_BASE_URL=<> \ --e OAUTH2_AUTHORIZE_URL=<> \ --e OAUTH2_TOKEN_URL=<> \ --e OAUTH2_USER_URL=<> \ +### Enabling OAuth 2.0 when using Docker images -# Optional: --e OAUTH2_SCOPES=<> \ --e OAUTH2_CALLBACK_URL=<> \ +To enable OAuth 2.0 when using Docker images, proceed as follows: -...[other settings]... -``` +1. Use the following environment variables to the Docker container via + the `-e` option: -### Available variables + ```bash + docker run -d \ + -p 4000:4000 \ + --name trento-web \ + --network trento-net \ + --add-host "host.docker.internal:host-gateway" \ + + ...[other settings]... + + -e ENABLE_OAUTH2=true \ + -e OAUTH2_CLIENT_ID= \ + -e OAUTH2_CLIENT_SECRET= \ + -e OAUTH2_BASE_URL= \ + -e OAUTH2_AUTHORIZE_URL= \ + -e OAUTH2_TOKEN_URL= \ + -e OAUTH2_USER_URL= \ + + # Optional: + -e OAUTH2_SCOPES= \ + -e OAUTH2_CALLBACK_URL= \ + + ...[other settings]... + ``` + +### Available variables for OAuth OAUTH2_CLIENT_ID @@ -177,18 +205,22 @@ OAUTH2_CALLBACK_URL : OAUTH2 callback url where the IDP is redirecting once the authentication is completed (default value: `https://#{TRENTO_WEB_ORIGIN}/auth/oauth2_callback`) -## SAML + +## Using SAML Trento integrates with an IDP that uses the SAML protocol to authenticate users accessing the Trento web console. In order to use an existing SAML IDP, some requirements must be met, configuring the IDP and starting Trento in a specific way. Follow the next instructions to properly setup both. -### SAML IDP setup +### Requirements for SAML IDP setup Configure the existing IDP with the next minimum options to be able to connect with Trento's Service Provider (SP). #### SAML user profile +// Is this background information or does the admin need to check this +// somehow (=task)? + Users provided by the SAML installation must have some few mandatory attributes in order to login in Trento. All of them are mandatory, even though their name is configurable. The user profile must include attributes for: username, email, first name and last name. This attributes must be mapped for all users wanting to connect to Trento. @@ -198,6 +230,9 @@ So for example, if the IDP user profile username is defined as `attr:username`, #### Signing keys +// Is this background information or does the admin need to check this +// somehow (=task)? + Commonly, SAML protocol messages are signed with SSL. This is optional using Trento, and the signing is not required (even though it is recommended). If the IDP signs the messages, and expect signed messages back, certificates used by the SP (Trento in this case) must be provided to the IDP, the Certificate file in this case. From 8ad269dcc9d6152a465f5722b4cffaa1a236e8a3 Mon Sep 17 00:00:00 2001 From: arbulu89 Date: Wed, 9 Oct 2024 12:10:13 +0200 Subject: [PATCH 04/20] Apply some suggestions and improve SAML content --- trento/migration/sso-integration.md | 170 ++++---- trento/xml/sso-integration.xml | 612 ++++++++++++++++------------ 2 files changed, 453 insertions(+), 329 deletions(-) diff --git a/trento/migration/sso-integration.md b/trento/migration/sso-integration.md index 5a0b2554..e8f07ec0 100644 --- a/trento/migration/sso-integration.md +++ b/trento/migration/sso-integration.md @@ -22,6 +22,7 @@ User authentication is entirely managed by the IDP, which is responsible for mai A user, who does not exist on the IDP, is unable to access the Trento web console. During the installation process, a default admin user is defined using the `ADMIN_USER` variable, which defaults to `admin`. If the authenticated user’s IDP username matches this admin user's username, that user is automatically granted `all:all` permissions within Trento. + User permissions are entirely managed by Trento, they are not imported from the IDP. The abilities must be granted by some user with `all:all` or `all:users` abilities (admin user initially). This means that only basic user information is retrieved from the external IDP. @@ -47,8 +48,7 @@ To enable OIDC when using RPM packages, proceed as follows: OIDC_BASE_URL= ``` -1. Optionally, add the OIDC callback URL to the configuration: - // reason why you would need that? +1. Optionally, add the OIDC callback URL to the configuration. This can be useful if for some reason the default callback URL cannot be used, for example, if `http` is used instead of `https`. Use the next variable for that: ``` OIDC_CALLBACK_URL= @@ -171,7 +171,7 @@ To enable OAuth 2.0 when using Docker images, proceed as follows: ...[other settings]... ``` -### Available variables for OAuth +### Available variables for OAuth 2.0 OAUTH2_CLIENT_ID @@ -208,35 +208,40 @@ OAUTH2_CALLBACK_URL ## Using SAML -Trento integrates with an IDP that uses the SAML protocol to authenticate users accessing the Trento web console. +Trento integrates with an IDP that uses the SAML protocol to authenticate users accessing the Trento web console. Trento will behave as a Service Provider (SP) in this case. + +Commonly, SAML protocol messages are signed with SSL. This is optional using Trento, and the signing is not required (even though it is recommended). +If the IDP signs the messages, and expect signed messages back, certificates used by the SP (Trento in this case) must be provided to the IDP, the public certificate file in this case. + +To use an existing SAML IDP, follow the next instrunctions to met the specific requirements. You need: -In order to use an existing SAML IDP, some requirements must be met, configuring the IDP and starting Trento in a specific way. Follow the next instructions to properly setup both. +* Configure SAML IDP and user profiles +* Start Trento to generate the certificates and download them +* Provide the generated certificate to the IDP +* Restart Trento -### Requirements for SAML IDP setup +### Configuring SAML IDP setup Configure the existing IDP with the next minimum options to be able to connect with Trento's Service Provider (SP). #### SAML user profile -// Is this background information or does the admin need to check this -// somehow (=task)? - -Users provided by the SAML installation must have some few mandatory attributes in order to login in Trento. All of them are mandatory, even though their name is configurable. +Users provided by the SAML installation must have some few mandatory attributes to login in Trento. All of them are mandatory, even though their name is configurable. The user profile must include attributes for: username, email, first name and last name. This attributes must be mapped for all users wanting to connect to Trento. By default, Trento expects the `username`, `email`, `firstName` and `lastName` attribute names. All these 4 attribute names are configurable using the next environment variables, following the same order: `SAML_USERNAME_ATTR_NAME`, `SAML_EMAIL_ATTR_NAME`, `SAML_FIRSTNAME_ATTR_NAME` and `SAML_LASTNAME_ATTR_NAME`. So for example, if the IDP user profile username is defined as `attr:username`, `SAML_USERNAME_ATTR_NAME=attr:username` should be used. -#### Signing keys +#### SAML redirect URI -// Is this background information or does the admin need to check this -// somehow (=task)? +Once the login is done succesfully, the IDP redirects the session back to Trento. This redirection is done to `https://trento.example.com/sso/sp/consume/saml`, so this URI must be set as valid in the IDP. -Commonly, SAML protocol messages are signed with SSL. This is optional using Trento, and the signing is not required (even though it is recommended). -If the IDP signs the messages, and expect signed messages back, certificates used by the SP (Trento in this case) must be provided to the IDP, the Certificate file in this case. +### Get certificates from Trento -For this reason, Trento already provides a certificates set created during the installation. When Trento is installed the first time (does not matter the installation mode) the certificates are created, and the public certificate file content is available in the http://localhost:4000/api/public_keys route. +Trento provides a certificates set created during the installation. When Trento is installed the first time (does not matter the installation mode) the certificates are created, and the public certificate file content is available in the http://localhost:4000/api/public_keys route. + +Use the following command to download the certificate: ```bash curl http://localhost:4000/api/public_keys @@ -244,66 +249,77 @@ curl http://localhost:4000/api/public_keys Copy the content of the certificate from there, and provide it to the IDP. This way, the IDP will sign and verify the messages sent by both ends. -When this certificate is used, and provided to the IDP, the IDP recreates its own metadata.xml file. This file defines which certificate is used to sign the messages by both sides. At this point, Trento Web must be restarted to use the new metadata.xml content. +### Restart Trento -If the option is being used, the content of this variable must be updated with the new metadata. In the other hand, if is used, the new metadata is automatically fetched. If neither of these steps are completed, communication will fail because the message signatures will not be recognized +Once the certificate is provided to the IDP, the IDP recreates its own metadata.xml file. This file defines which certificate is used to sign the messages by both sides. At this point, Trento Web must be restarted to use the new metadata.xml content. -**This restart must be done manually, by the admin.** If the installation is done by a `RPM`, restarting the `systemd` daemon. If the installation is done using `Docker`, the container must be restarted. +If the option is being used, the content of this variable must be updated with the new metadata. In the other hand, if is used, the new metadata is automatically fetched. If neither of these steps are completed, communication will fail because the message signatures will not be recognized -``` -# RPM -systemctl restart trento-web - -# Docker -# Get container ID -docker container ps -# Restart -docker restart container-id +```{=docbook} + + This restart must be done manually, by the admin. + ``` -#### SAML redirect URI +Follow the next instrucionts to restart with the configured options: -Once the login is done succesfully, the IDP redirects the session back to Trento. This redirection is done to `https://trento.example.com/sso/sp/consume/saml`, so this URI must be set as valid in the IDP. +1. Open the file /etc/trento/trento-web. +1. Add the following environment variables to this file. + Required variables are: -### Enabling SAML + ``` + # Other SAML options + SAML_METADATA_URL= + # Or + SAML_METDATA_CONTENT= + ``` + +1. Restart the application. -SAML authentication is **disabled by default**. -#### Enabling SAML when using RPM packages +### Enabling SAML when using RPM packages -Provide the following environment variables to trento-web configuration, which is stored at `/etc/trento/trento-web` and restart the application to enable SAML integration. +To enable SAML when using RPM packages, proceed as follows: + +1. Open the file /etc/trento/trento-web. +1. Add the following environment variables to this file. + Required variables are: ``` # Required: ENABLE_SAML=true -SAML_IDP_ID=<> -SAML_SP_ID=<> +SAML_IDP_ID= +SAML_SP_ID= # Only SAML_METADATA_URL or SAML_METADATA_CONTENT must by provided -SAML_METADATA_URL=<> -SAML_METADATA_CONTENT=<> +SAML_METADATA_URL= +SAML_METADATA_CONTENT= # Optional: -SAML_IDP_NAMEID_FORMAT=<> -SAML_SP_DIR=<> -SAML_SP_ENTITY_ID=<> -SAML_SP_CONTACT_NAME=<> -SAML_SP_CONTACT_EMAIL=<> -SAML_SP_ORG_NAME=<> -SAML_SP_ORG_DISPLAYNAME=<> -SAML_SP_ORG_URL=<> -SAML_USERNAME_ATTR_NAME=<> -SAML_EMAIL_ATTR_NAME=<> -SAML_FIRSTNAME_ATTR_NAME=<> -SAML_LASTNAME_ATTR_NAME=<> -SAML_SIGN_REQUESTS=<> -SAML_SIGN_METADATA=<> -SAML_SIGNED_ASSERTION=<> -SAML_SIGNED_ENVELOPES=<> +SAML_IDP_NAMEID_FORMAT= +SAML_SP_DIR= +SAML_SP_ENTITY_ID= +SAML_SP_CONTACT_NAME= +SAML_SP_CONTACT_EMAIL= +SAML_SP_ORG_NAME= +SAML_SP_ORG_DISPLAYNAME= +SAML_SP_ORG_URL= +SAML_USERNAME_ATTR_NAME= +SAML_EMAIL_ATTR_NAME= +SAML_FIRSTNAME_ATTR_NAME= +SAML_LASTNAME_ATTR_NAME= +SAML_SIGN_REQUESTS= +SAML_SIGN_METADATA= +SAML_SIGNED_ASSERTION= +SAML_SIGNED_ENVELOPES= ``` -#### Enabling SAML when using Docker images +1. Restart the application. + +### Enabling SAML when using Docker images + +To enable SAML when using Docker images, proceed as follows: -Provide the following environment variables to the docker container and restart the application to enable SAML integration. +1. Use the following environment variables to the Docker container via the `-e` option: ```bash docker run -d \ @@ -315,34 +331,34 @@ docker run -d \ ...[other settings]... -e ENABLE_SAML=true --e SAML_IDP_ID=<> \ --e SAML_SP_ID=<> \ +-e SAML_IDP_ID= \ +-e SAML_SP_ID= \ # Only SAML_METADATA_URL or SAML_METADATA_CONTENT must by provided --e SAML_METADATA_URL=<> \ --e SAML_METADATA_CONTENT=<> \ +-e SAML_METADATA_URL= \ +-e SAML_METADATA_CONTENT= \ # Optional: --e SAML_IDP_NAMEID_FORMAT=<> \ --e SAML_SP_DIR=<> \ --e SAML_SP_ENTITY_ID=<> \ --e SAML_SP_CONTACT_NAME=<> \ --e SAML_SP_CONTACT_EMAIL=<> \ --e SAML_SP_ORG_NAME=<> \ --e SAML_SP_ORG_DISPLAYNAME=<> \ --e SAML_SP_ORG_URL=<> \ --e SAML_USERNAME_ATTR_NAME=<> \ --e SAML_EMAIL_ATTR_NAME=<> \ --e SAML_FIRSTNAME_ATTR_NAME=<> \ --e SAML_LASTNAME_ATTR_NAME=<> \ --e SAML_SIGN_REQUESTS=<> \ --e SAML_SIGN_METADATA=<> \ --e SAML_SIGNED_ASSERTION=<> \ --e SAML_SIGNED_ENVELOPES=<> \ +-e SAML_IDP_NAMEID_FORMAT= \ +-e SAML_SP_DIR= \ +-e SAML_SP_ENTITY_ID= \ +-e SAML_SP_CONTACT_NAME= \ +-e SAML_SP_CONTACT_EMAIL= \ +-e SAML_SP_ORG_NAME= \ +-e SAML_SP_ORG_DISPLAYNAME= \ +-e SAML_SP_ORG_URL= \ +-e SAML_USERNAME_ATTR_NAME= \ +-e SAML_EMAIL_ATTR_NAME= \ +-e SAML_FIRSTNAME_ATTR_NAME= \ +-e SAML_LASTNAME_ATTR_NAME= \ +-e SAML_SIGN_REQUESTS= \ +-e SAML_SIGN_METADATA= \ +-e SAML_SIGNED_ASSERTION= \ +-e SAML_SIGNED_ENVELOPES= \ ...[other settings]... ``` -### Available variables +### Available variables for SAML SAML_IDP_ID diff --git a/trento/xml/sso-integration.xml b/trento/xml/sso-integration.xml index 99794af6..3797696d 100644 --- a/trento/xml/sso-integration.xml +++ b/trento/xml/sso-integration.xml @@ -1,5 +1,5 @@ -
- Single Sign-On integration +
+ Integrating Single Sign-On Trento can be integrated with an identity provider (IDP) that uses different Single sign-on (SSO) protocols like OpenID Connect (OIDC) @@ -8,85 +8,113 @@ Trento cannot start with multiple SSO options together, so only one can be chosen. -
- Available protocols - - - - OpenID Connect (OIDC) - - - - - Open Authorization 2.0 (OAuth 2) - - - - - Security Assertion Markup Language (SAML) - - - -
+ + Available protocols are: + + + + + OpenID Connect (OIDC) + + + + + Open Authorization 2.0 (OAuth 2) + + + + + Security Assertion Markup Language (SAML) + + +
User Roles and Authentication User authentication is entirely managed by the IDP, which is responsible for maintaining user accounts. A user, who does not exist on the IDP, is unable to access the Trento web console. + + During the installation process, a default admin user is defined using the ADMIN_USER variable, which defaults to admin. If the authenticated user’s IDP username matches this admin user's username, that user is automatically granted all:all permissions - within Trento. User permissions are entirely managed by Trento, - they are not imported from the IDP. The abilities must be granted - by some user with all:all or - all:users abilities - (admin user initially). This - means that only basic user information is retrieved from the - external IDP. + within Trento. + + + User permissions are entirely managed by Trento, they are not + imported from the IDP. The abilities must be granted by some user + with all:all or all:users + abilities (admin user initially). This means that only basic user + information is retrieved from the external IDP.
-
- OIDC +
+ Using OpenID Connect Trento integrates with an IDP that uses the OIDC protocol to authenticate users accessing the Trento web console. -
- Enabling OIDC + + By default, OIDC is disabled. You can enable OIDC when using RPM + packages or using Docker images. + +
+ Enabling OpenID Connect when using RPM packages - OIDC authentication is disabled by - default. + To enable OIDC when using RPM packages, proceed as follows: -
- Enabling OIDC when using RPM packages - - Provide the following environment variables to trento-web - configuration, which is stored at - /etc/trento/trento-web and restart the - application to enable OIDC integration. - - -# Required: + + + + Open the file /etc/trento/trento-web. + + + + + Add the following environment variables to this file. + Required variables are: + + ENABLE_OIDC=true -OIDC_CLIENT_ID=<<OIDC_CLIENT_ID>> -OIDC_CLIENT_SECRET=<<OIDC_CLIENT_SECRET>> -OIDC_BASE_URL=<<OIDC_BASE_URL>> - -# Optional: -OIDC_CALLBACK_URL=<<OIDC_CALLBACK_URL>> +OIDC_CLIENT_ID=<OIDC_CLIENT_ID> +OIDC_CLIENT_SECRET=<OIDC_CLIENT_SECRET> +OIDC_BASE_URL=<OIDC_BASE_URL> -
-
- Enabling OIDC when using Docker images - - Provide the following environment variables to the docker - container and restart the application to enable OIDC - integration. - - + + + + Optionally, add the OIDC callback URL to the configuration. + This can be useful if for some reason the default callback + URL cannot be used, for example, if http + is used instead of https. Use the next + variable for that: + + +OIDC_CALLBACK_URL=<OIDC_CALLBACK_URL> + + + + + Restart the application. + + + +
+
+ Enabling OpenID Connect when using Docker images + + To enable OIDC when using Docker images, proceed as follows: + + + + + Provide the following environment variables to the Docker + container via the -e option: + + docker run -d \ -p 4000:4000 \ --name trento-web \ @@ -96,20 +124,26 @@ docker run -d \ ...[other settings]... # Required: --e ENABLE_OIDC=true \ --e OIDC_CLIENT_ID=<<OIDC_CLIENT_ID>> \ --e OIDC_CLIENT_SECRET=<<OIDC_CLIENT_SECRET>> \ --e OIDC_BASE_URL=<<OIDC_BASE_URL>> \ +-e ENABLE_OIDC=true \ +-e OIDC_CLIENT_ID=<OIDC_CLIENT_ID> \ +-e OIDC_CLIENT_SECRET=<OIDC_CLIENT_SECRET> \ +-e OIDC_BASE_URL=<OIDC_BASE_URL> \ # Optional: --e OIDC_CALLBACK_URL=<<OIDC_CALLBACK_URL>> \ +-e OIDC_CALLBACK_URL=<OIDC_CALLBACK_URL> \ ...[other settings]... -
+ + + + Restart the application. + + +
-
- Available variables +
+ Available variables for OpenID Connect @@ -156,49 +190,67 @@ docker run -d \
-
- OAuth 2.0 +
+ Using OAuth 2.0 Trento integrates with an IDP that uses the OAuth 2 protocol to authenticate users accessing the Trento web console. -
- Enabling OAuth 2.0 + + By default, OAuth 2.0 is disabled. You can enable OIDC when using + RPM packages or using Docker images. + +
+ Enabling OAuth 2.0 when using RPM packages - OAuth 2.0 authentication is disabled by - default. + To enable OAuth 2.0 when using RPM packages, proceed as follows: -
- Enabling OAuth 2.0 when using RPM packages - - Provide the following environment variables to trento-web - configuration, which is stored at - /etc/trento/trento-web and restart the - application to enable OAuth 2.0 integration. - - + + + + Open the file /etc/trento/trento-web. + + + + + Add the following environment variables to this file. + Required variables are: + + # Required: ENABLE_OAUTH2=true -OAUTH2_CLIENT_ID=<<OAUTH2_CLIENT_ID>> -OAUTH2_CLIENT_SECRET=<<OAUTH2_CLIENT_SECRET>> -OAUTH2_BASE_URL=<<OAUTH2_BASE_URL>> -OAUTH2_AUTHORIZE_URL=<<OAUTH2_AUTHORIZE_URL>> -OAUTH2_TOKEN_URL=<<OAUTH2_TOKEN_URL>> -OAUTH2_USER_URL=<<OAUTH2_USER_URL>> +OAUTH2_CLIENT_ID=<OAUTH2_CLIENT_ID> +OAUTH2_CLIENT_SECRET=<OAUTH2_CLIENT_SECRET> +OAUTH2_BASE_URL=<OAUTH2_BASE_URL> +OAUTH2_AUTHORIZE_URL=<OAUTH2_AUTHORIZE_URL> +OAUTH2_TOKEN_URL=<OAUTH2_TOKEN_URL> +OAUTH2_USER_URL=<OAUTH2_USER_URL> # Optional: -OAUTH2_SCOPES=<<OAUTH2_SCOPES>> -OAUTH2_CALLBACK_URL=<<OAUTH2_CALLBACK_URL>> +OAUTH2_SCOPES=<OAUTH2_SCOPES> +OAUTH2_CALLBACK_URL=<OAUTH2_CALLBACK_URL> -
-
- Enabling OAuth 2.0 when using Docker images - - Provide the following environment variables to the docker - container and restart the application to enable OAuth 2.0 - integration. - - + + + + Restart the application. + + + +
+
+ Enabling OAuth 2.0 when using Docker images + + To enable OAuth 2.0 when using Docker images, proceed as + follows: + + + + + Use the following environment variables to the Docker + container via the -e option: + + docker run -d \ -p 4000:4000 \ --name trento-web \ @@ -207,24 +259,25 @@ docker run -d \ ...[other settings]... --e ENABLE_OAUTH2=true \ --e OAUTH2_CLIENT_ID=<<OAUTH2_CLIENT_ID>> \ --e OAUTH2_CLIENT_SECRET=<<OAUTH2_CLIENT_SECRET>> \ --e OAUTH2_BASE_URL=<<OAUTH2_BASE_URL>> \ --e OAUTH2_AUTHORIZE_URL=<<OAUTH2_AUTHORIZE_URL>> \ --e OAUTH2_TOKEN_URL=<<OAUTH2_TOKEN_URL>> \ --e OAUTH2_USER_URL=<<OAUTH2_USER_URL>> \ +-e ENABLE_OAUTH2=true \ +-e OAUTH2_CLIENT_ID=<OAUTH2_CLIENT_ID> \ +-e OAUTH2_CLIENT_SECRET=<OAUTH2_CLIENT_SECRET> \ +-e OAUTH2_BASE_URL=<OAUTH2_BASE_URL> \ +-e OAUTH2_AUTHORIZE_URL=<OAUTH2_AUTHORIZE_URL> \ +-e OAUTH2_TOKEN_URL=<OAUTH2_TOKEN_URL> \ +-e OAUTH2_USER_URL=<OAUTH2_USER_URL> \ # Optional: --e OAUTH2_SCOPES=<<OAUTH2_SCOPES>> \ --e OAUTH2_CALLBACK_URL=<<OAUTH2_CALLBACK_URL>> \ +-e OAUTH2_SCOPES=<OAUTH2_SCOPES> \ +-e OAUTH2_CALLBACK_URL=<OAUTH2_CALLBACK_URL> \ ...[other settings]... -
+ +
-
- Available variables +
+ Available variables for OAuth 2.0 @@ -314,19 +367,49 @@ docker run -d \
-
- SAML +
+ Using SAML Trento integrates with an IDP that uses the SAML protocol to - authenticate users accessing the Trento web console. + authenticate users accessing the Trento web console. Trento will + behave as a Service Provider (SP) in this case. + + + Commonly, SAML protocol messages are signed with SSL. This is + optional using Trento, and the signing is not required (even + though it is recommended). If the IDP signs the messages, and + expect signed messages back, certificates used by the SP (Trento + in this case) must be provided to the IDP, the public certificate + file in this case. - In order to use an existing SAML IDP, some requirements must be - met, configuring the IDP and starting Trento in a specific way. - Follow the next instructions to properly setup both. + To use an existing SAML IDP, follow the next instrunctions to met + the specific requirements. You need: -
- SAML IDP setup + + + + Configure SAML IDP and user profiles + + + + + Start Trento to generate the certificates and download them + + + + + Provide the generated certificate to the IDP + + + + + Restart Trento + + + +
+ Configuring SAML IDP setup Configure the existing IDP with the next minimum options to be able to connect with Trento's Service Provider (SP). @@ -335,11 +418,11 @@ docker run -d \ SAML user profile Users provided by the SAML installation must have some few - mandatory attributes in order to login in Trento. All of them - are mandatory, even though their name is configurable. The - user profile must include attributes for: username, email, - first name and last name. This attributes must be mapped for - all users wanting to connect to Trento. + mandatory attributes to login in Trento. All of them are + mandatory, even though their name is configurable. The user + profile must include attributes for: username, email, first + name and last name. This attributes must be mapped for all + users wanting to connect to Trento. By default, Trento expects the username, @@ -357,68 +440,6 @@ docker run -d \ should be used.
-
- Signing keys - - Commonly, SAML protocol messages are signed with SSL. This is - optional using Trento, and the signing is not required (even - though it is recommended). If the IDP signs the messages, and - expect signed messages back, certificates used by the SP - (Trento in this case) must be provided to the IDP, the - Certificate file in this case. - - - For this reason, Trento already provides a certificates set - created during the installation. When Trento is installed the - first time (does not matter the installation mode) the - certificates are created, and the public certificate file - content is available in the - http://localhost:4000/api/public_keys route. - - -curl http://localhost:4000/api/public_keys - - - Copy the content of the certificate from there, and provide it - to the IDP. This way, the IDP will sign and verify the - messages sent by both ends. - - - When this certificate is used, and provided to the IDP, the - IDP recreates its own metadata.xml file. - This file defines which certificate is used to sign the - messages by both sides. At this point, Trento Web must be - restarted to use the new metadata.xml - content. - - - If the option is being - used, the content of this variable must be updated with the - new metadata. In the other hand, if - is used, the new metadata - is automatically fetched. If neither of these steps are - completed, communication will fail because the message - signatures will not be recognized - - - This restart must be done manually, by - the admin. If the installation is done by a - RPM, restarting the - systemd daemon. If the installation is done - using Docker, the container must be - restarted. - - -# RPM -systemctl restart trento-web - -# Docker -# Get container ID -docker container ps -# Restart -docker restart container-id - -
SAML redirect URI @@ -429,56 +450,144 @@ docker restart container-id
-
- Enabling SAML +
+ Get certificates from Trento - SAML authentication is disabled by - default. + Trento provides a certificates set created during the + installation. When Trento is installed the first time (does not + matter the installation mode) the certificates are created, and + the public certificate file content is available in the + http://localhost:4000/api/public_keys route. -
- Enabling SAML when using RPM packages - - Provide the following environment variables to trento-web - configuration, which is stored at - /etc/trento/trento-web and restart the - application to enable SAML integration. - - + + Use the following command to download the certificate: + + +curl http://localhost:4000/api/public_keys + + + Copy the content of the certificate from there, and provide it + to the IDP. This way, the IDP will sign and verify the messages + sent by both ends. + +
+
+ Restart Trento + + Once the certificate is provided to the IDP, the IDP recreates + its own metadata.xml file. This file + defines which certificate is used to sign the messages by both + sides. At this point, Trento Web must be restarted to use the + new metadata.xml content. + + + If the option is being + used, the content of this variable must be updated with the new + metadata. In the other hand, if + is used, the new metadata is + automatically fetched. If neither of these steps are completed, + communication will fail because the message signatures will not + be recognized + + + This restart must be done manually, by the admin. + + + Follow the next instrucionts to restart with the configured + options: + + + + + Open the file /etc/trento/trento-web. + + + + + Add the following environment variables to this file. + Required variables are: + + +# Other SAML options +SAML_METADATA_URL=<SAML_METADATA_URL> +# Or +SAML_METDATA_CONTENT=<SAML_METADATA_CONTENT> + + + + + Restart the application. + + + +
+
+ Enabling SAML when using RPM packages + + To enable SAML when using RPM packages, proceed as follows: + + + + + Open the file /etc/trento/trento-web. + + + + + Add the following environment variables to this file. + Required variables are: + + + + # Required: ENABLE_SAML=true -SAML_IDP_ID=<<SAML_IDP_ID>> -SAML_SP_ID=<<SAML_SP_ID>> +SAML_IDP_ID=<SAML_IDP_ID> +SAML_SP_ID=<SAML_SP_ID> # Only SAML_METADATA_URL or SAML_METADATA_CONTENT must by provided -SAML_METADATA_URL=<<SAML_METADATA_URL>> -SAML_METADATA_CONTENT=<<SAML_METADATA_CONTENT>> +SAML_METADATA_URL=<SAML_METADATA_URL> +SAML_METADATA_CONTENT=<SAML_METADATA_CONTENT> # Optional: -SAML_IDP_NAMEID_FORMAT=<<SAML_IDP_NAMEID_FORMAT>> -SAML_SP_DIR=<<SAML_SP_DIR>> -SAML_SP_ENTITY_ID=<<SAML_SP_ENTITY_ID>> -SAML_SP_CONTACT_NAME=<<SAML_SP_CONTACT_NAME>> -SAML_SP_CONTACT_EMAIL=<<SAML_SP_CONTACT_EMAIL>> -SAML_SP_ORG_NAME=<<SAML_SP_ORG_NAME>> -SAML_SP_ORG_DISPLAYNAME=<<SAML_SP_ORG_DISPLAYNAME>> -SAML_SP_ORG_URL=<<SAML_SP_ORG_URL>> -SAML_USERNAME_ATTR_NAME=<<SAML_USERNAME_ATTR_NAME>> -SAML_EMAIL_ATTR_NAME=<<SAML_EMAIL_ATTR_NAME>> -SAML_FIRSTNAME_ATTR_NAME=<<SAML_FIRSTNAME_ATTR_NAME>> -SAML_LASTNAME_ATTR_NAME=<<SAML_LASTNAME_ATTR_NAME>> -SAML_SIGN_REQUESTS=<<SAML_SIGN_REQUESTS>> -SAML_SIGN_METADATA=<<SAML_SIGN_METADATA>> -SAML_SIGNED_ASSERTION=<<SAML_SIGNED_ASSERTION>> -SAML_SIGNED_ENVELOPES=<<SAML_SIGNED_ENVELOPES>> +SAML_IDP_NAMEID_FORMAT=<SAML_IDP_NAMEID_FORMAT> +SAML_SP_DIR=<SAML_SP_DIR> +SAML_SP_ENTITY_ID=<SAML_SP_ENTITY_ID> +SAML_SP_CONTACT_NAME=<SAML_SP_CONTACT_NAME> +SAML_SP_CONTACT_EMAIL=<SAML_SP_CONTACT_EMAIL> +SAML_SP_ORG_NAME=<SAML_SP_ORG_NAME> +SAML_SP_ORG_DISPLAYNAME=<SAML_SP_ORG_DISPLAYNAME> +SAML_SP_ORG_URL=<SAML_SP_ORG_URL> +SAML_USERNAME_ATTR_NAME=<SAML_USERNAME_ATTR_NAME> +SAML_EMAIL_ATTR_NAME=<SAML_EMAIL_ATTR_NAME> +SAML_FIRSTNAME_ATTR_NAME=<SAML_FIRSTNAME_ATTR_NAME> +SAML_LASTNAME_ATTR_NAME=<SAML_LASTNAME_ATTR_NAME> +SAML_SIGN_REQUESTS=<SAML_SIGN_REQUESTS> +SAML_SIGN_METADATA=<SAML_SIGN_METADATA> +SAML_SIGNED_ASSERTION=<SAML_SIGNED_ASSERTION> +SAML_SIGNED_ENVELOPES=<SAML_SIGNED_ENVELOPES> -
-
- Enabling SAML when using Docker images - - Provide the following environment variables to the docker - container and restart the application to enable SAML - integration. - - + + + + Restart the application. + + + +
+
+ Enabling SAML when using Docker images + + To enable SAML when using Docker images, proceed as follows: + + + + + Use the following environment variables to the Docker + container via the -e option: + + + + docker run -d \ -p 4000:4000 \ --name trento-web \ @@ -488,36 +597,35 @@ docker run -d \ ...[other settings]... -e ENABLE_SAML=true --e SAML_IDP_ID=<<SAML_IDP_ID>> \ --e SAML_SP_ID=<<SAML_SP_ID>> \ +-e SAML_IDP_ID=<SAML_IDP_ID> \ +-e SAML_SP_ID=<SAML_SP_ID> \ # Only SAML_METADATA_URL or SAML_METADATA_CONTENT must by provided --e SAML_METADATA_URL=<<SAML_METADATA_URL>> \ --e SAML_METADATA_CONTENT=<<SAML_METADATA_CONTENT>> \ +-e SAML_METADATA_URL=<SAML_METADATA_URL> \ +-e SAML_METADATA_CONTENT=<SAML_METADATA_CONTENT> \ # Optional: --e SAML_IDP_NAMEID_FORMAT=<<SAML_IDP_NAMEID_FORMAT>> \ --e SAML_SP_DIR=<<SAML_SP_DIR>> \ --e SAML_SP_ENTITY_ID=<<SAML_SP_ENTITY_ID>> \ --e SAML_SP_CONTACT_NAME=<<SAML_SP_CONTACT_NAME>> \ --e SAML_SP_CONTACT_EMAIL=<<SAML_SP_CONTACT_EMAIL>> \ --e SAML_SP_ORG_NAME=<<SAML_SP_ORG_NAME>> \ --e SAML_SP_ORG_DISPLAYNAME=<<SAML_SP_ORG_DISPLAYNAME>> \ --e SAML_SP_ORG_URL=<<SAML_SP_ORG_URL>> \ --e SAML_USERNAME_ATTR_NAME=<<SAML_USERNAME_ATTR_NAME>> \ --e SAML_EMAIL_ATTR_NAME=<<SAML_EMAIL_ATTR_NAME>> \ --e SAML_FIRSTNAME_ATTR_NAME=<<SAML_FIRSTNAME_ATTR_NAME>> \ --e SAML_LASTNAME_ATTR_NAME=<<SAML_LASTNAME_ATTR_NAME>> \ --e SAML_SIGN_REQUESTS=<<SAML_SIGN_REQUESTS>> \ --e SAML_SIGN_METADATA=<<SAML_SIGN_METADATA>> \ --e SAML_SIGNED_ASSERTION=<<SAML_SIGNED_ASSERTION>> \ --e SAML_SIGNED_ENVELOPES=<<SAML_SIGNED_ENVELOPES>> \ +-e SAML_IDP_NAMEID_FORMAT=<SAML_IDP_NAMEID_FORMAT> \ +-e SAML_SP_DIR=<SAML_SP_DIR> \ +-e SAML_SP_ENTITY_ID=<SAML_SP_ENTITY_ID> \ +-e SAML_SP_CONTACT_NAME=<SAML_SP_CONTACT_NAME> \ +-e SAML_SP_CONTACT_EMAIL=<SAML_SP_CONTACT_EMAIL> \ +-e SAML_SP_ORG_NAME=<SAML_SP_ORG_NAME> \ +-e SAML_SP_ORG_DISPLAYNAME=<SAML_SP_ORG_DISPLAYNAME> \ +-e SAML_SP_ORG_URL=<SAML_SP_ORG_URL> \ +-e SAML_USERNAME_ATTR_NAME=<SAML_USERNAME_ATTR_NAME> \ +-e SAML_EMAIL_ATTR_NAME=<SAML_EMAIL_ATTR_NAME> \ +-e SAML_FIRSTNAME_ATTR_NAME=<SAML_FIRSTNAME_ATTR_NAME> \ +-e SAML_LASTNAME_ATTR_NAME=<SAML_LASTNAME_ATTR_NAME> \ +-e SAML_SIGN_REQUESTS=<SAML_SIGN_REQUESTS> \ +-e SAML_SIGN_METADATA=<SAML_SIGN_METADATA> \ +-e SAML_SIGNED_ASSERTION=<SAML_SIGNED_ASSERTION> \ +-e SAML_SIGNED_ENVELOPES=<SAML_SIGNED_ENVELOPES> \ ...[other settings]... -
-
- Available variables +
+ Available variables for SAML From c677c9f42413b3388445d67a5574305565a554dc Mon Sep 17 00:00:00 2001 From: arbulu89 Date: Thu, 10 Oct 2024 09:20:05 +0200 Subject: [PATCH 05/20] Improve SAML usage chapter content --- trento/migration/sso-integration.md | 168 ++++++++++++++-------------- trento/xml/sso-integration.xml | 108 +++++++++++------- 2 files changed, 156 insertions(+), 120 deletions(-) diff --git a/trento/migration/sso-integration.md b/trento/migration/sso-integration.md index e8f07ec0..5fab2fcf 100644 --- a/trento/migration/sso-integration.md +++ b/trento/migration/sso-integration.md @@ -139,7 +139,6 @@ To enable OAuth 2.0 when using RPM packages, proceed as follows: 1. Restart the application. - ### Enabling OAuth 2.0 when using Docker images To enable OAuth 2.0 when using Docker images, proceed as follows: @@ -215,45 +214,52 @@ If the IDP signs the messages, and expect signed messages back, certificates use To use an existing SAML IDP, follow the next instrunctions to met the specific requirements. You need: -* Configure SAML IDP and user profiles -* Start Trento to generate the certificates and download them -* Provide the generated certificate to the IDP -* Restart Trento +1. Configure SAML IDP and user profiles +1. Start Trento to generate the certificates and download them +1. Provide the generated certificate to the IDP +1. Restart Trento + +See the following subsections for details. ### Configuring SAML IDP setup -Configure the existing IDP with the next minimum options to be able to connect with Trento's Service Provider (SP). +Configure the existing IDP with the next minimum options to be able to connect with Trento as a Service Provider (SP). -#### SAML user profile +#### Configuring SAML user profile -Users provided by the SAML installation must have some few mandatory attributes to login in Trento. All of them are mandatory, even though their name is configurable. -The user profile must include attributes for: username, email, first name and last name. -This attributes must be mapped for all users wanting to connect to Trento. +Users provided by the SAML installation must have some few mandatory attributes to login in Trento. The required attributes are: username, email, first name and last name. All of them are mandatory, even though their field name is configurable. By default, Trento expects the `username`, `email`, `firstName` and `lastName` attribute names. All these 4 attribute names are configurable using the next environment variables, following the same order: `SAML_USERNAME_ATTR_NAME`, `SAML_EMAIL_ATTR_NAME`, `SAML_FIRSTNAME_ATTR_NAME` and `SAML_LASTNAME_ATTR_NAME`. -So for example, if the IDP user profile username is defined as `attr:username`, `SAML_USERNAME_ATTR_NAME=attr:username` should be used. -#### SAML redirect URI +So both the IDP and Trento must know how these 4 fields are mapped. For that, follow the next instruction: + +1. Add the attributes if they don't exist in the IDP user profile. If they already exist, they name doesn't need to be changed, so the current values can continue being used. + +1. Configure Trento to use the IDP attribute field names. For that, set the `SAML_USERNAME_ATTR_NAME`, `SAML_EMAIL_ATTR_NAME`, `SAML_FIRSTNAME_ATTR_NAME` and `SAML_LASTNAME_ATTR_NAME` environment values with the values configured in the IDP. For example, if the IDP user profile username is defined as `attr:username`, `SAML_USERNAME_ATTR_NAME=attr:username` should be used. + +#### Checking SAML redirect URI Once the login is done succesfully, the IDP redirects the session back to Trento. This redirection is done to `https://trento.example.com/sso/sp/consume/saml`, so this URI must be set as valid in the IDP. -### Get certificates from Trento +### Getting certificates from Trento -Trento provides a certificates set created during the installation. When Trento is installed the first time (does not matter the installation mode) the certificates are created, and the public certificate file content is available in the http://localhost:4000/api/public_keys route. +Trento provides a certificates set created during the installation. Regardless of the installation mode, when Trento is installed the first time the certificates are created and the public certificate file content is available in the http://localhost:4000/api/public_keys route. -Use the following command to download the certificate: +Use the following command to get the certificate content: ```bash curl http://localhost:4000/api/public_keys ``` -Copy the content of the certificate from there, and provide it to the IDP. This way, the IDP will sign and verify the messages sent by both ends. +Copy the content of the certificate from there and provide it to the IDP. This way, the IDP will sign its messages and verify the messages received from Trento. -### Restart Trento +### Restarting Trento Once the certificate is provided to the IDP, the IDP recreates its own metadata.xml file. This file defines which certificate is used to sign the messages by both sides. At this point, Trento Web must be restarted to use the new metadata.xml content. -If the option is being used, the content of this variable must be updated with the new metadata. In the other hand, if is used, the new metadata is automatically fetched. If neither of these steps are completed, communication will fail because the message signatures will not be recognized +If the option is being used, the content of this variable must be updated with the new metadata, as single line string. In the other hand, if is used, the new metadata is automatically fetched. If neither of these steps are completed, communication will fail because the message signatures will not be recognized. + +If the used IDP has the endpoint to provide the metadata.xml file content, the usage of is preferred, as further changes in the IDP will be fetched automatically by Trento when it is restarted. ```{=docbook} @@ -285,33 +291,33 @@ To enable SAML when using RPM packages, proceed as follows: 1. Add the following environment variables to this file. Required variables are: -``` -# Required: -ENABLE_SAML=true -SAML_IDP_ID= -SAML_SP_ID= -# Only SAML_METADATA_URL or SAML_METADATA_CONTENT must by provided -SAML_METADATA_URL= -SAML_METADATA_CONTENT= - -# Optional: -SAML_IDP_NAMEID_FORMAT= -SAML_SP_DIR= -SAML_SP_ENTITY_ID= -SAML_SP_CONTACT_NAME= -SAML_SP_CONTACT_EMAIL= -SAML_SP_ORG_NAME= -SAML_SP_ORG_DISPLAYNAME= -SAML_SP_ORG_URL= -SAML_USERNAME_ATTR_NAME= -SAML_EMAIL_ATTR_NAME= -SAML_FIRSTNAME_ATTR_NAME= -SAML_LASTNAME_ATTR_NAME= -SAML_SIGN_REQUESTS= -SAML_SIGN_METADATA= -SAML_SIGNED_ASSERTION= -SAML_SIGNED_ENVELOPES= -``` + ``` + # Required: + ENABLE_SAML=true + SAML_IDP_ID= + SAML_SP_ID= + # Only SAML_METADATA_URL or SAML_METADATA_CONTENT must by provided + SAML_METADATA_URL= + SAML_METADATA_CONTENT= + + # Optional: + SAML_IDP_NAMEID_FORMAT= + SAML_SP_DIR= + SAML_SP_ENTITY_ID= + SAML_SP_CONTACT_NAME= + SAML_SP_CONTACT_EMAIL= + SAML_SP_ORG_NAME= + SAML_SP_ORG_DISPLAYNAME= + SAML_SP_ORG_URL= + SAML_USERNAME_ATTR_NAME= + SAML_EMAIL_ATTR_NAME= + SAML_FIRSTNAME_ATTR_NAME= + SAML_LASTNAME_ATTR_NAME= + SAML_SIGN_REQUESTS= + SAML_SIGN_METADATA= + SAML_SIGNED_ASSERTION= + SAML_SIGNED_ENVELOPES= + ``` 1. Restart the application. @@ -321,42 +327,42 @@ To enable SAML when using Docker images, proceed as follows: 1. Use the following environment variables to the Docker container via the `-e` option: -```bash -docker run -d \ --p 4000:4000 \ ---name trento-web \ ---network trento-net \ ---add-host "host.docker.internal:host-gateway" \ - -...[other settings]... - --e ENABLE_SAML=true --e SAML_IDP_ID= \ --e SAML_SP_ID= \ -# Only SAML_METADATA_URL or SAML_METADATA_CONTENT must by provided --e SAML_METADATA_URL= \ --e SAML_METADATA_CONTENT= \ - -# Optional: --e SAML_IDP_NAMEID_FORMAT= \ --e SAML_SP_DIR= \ --e SAML_SP_ENTITY_ID= \ --e SAML_SP_CONTACT_NAME= \ --e SAML_SP_CONTACT_EMAIL= \ --e SAML_SP_ORG_NAME= \ --e SAML_SP_ORG_DISPLAYNAME= \ --e SAML_SP_ORG_URL= \ --e SAML_USERNAME_ATTR_NAME= \ --e SAML_EMAIL_ATTR_NAME= \ --e SAML_FIRSTNAME_ATTR_NAME= \ --e SAML_LASTNAME_ATTR_NAME= \ --e SAML_SIGN_REQUESTS= \ --e SAML_SIGN_METADATA= \ --e SAML_SIGNED_ASSERTION= \ --e SAML_SIGNED_ENVELOPES= \ - -...[other settings]... -``` + ```bash + docker run -d \ + -p 4000:4000 \ + --name trento-web \ + --network trento-net \ + --add-host "host.docker.internal:host-gateway" \ + + ...[other settings]... + + -e ENABLE_SAML=true + -e SAML_IDP_ID= \ + -e SAML_SP_ID= \ + # Only SAML_METADATA_URL or SAML_METADATA_CONTENT must by provided + -e SAML_METADATA_URL= \ + -e SAML_METADATA_CONTENT= \ + + # Optional: + -e SAML_IDP_NAMEID_FORMAT= \ + -e SAML_SP_DIR= \ + -e SAML_SP_ENTITY_ID= \ + -e SAML_SP_CONTACT_NAME= \ + -e SAML_SP_CONTACT_EMAIL= \ + -e SAML_SP_ORG_NAME= \ + -e SAML_SP_ORG_DISPLAYNAME= \ + -e SAML_SP_ORG_URL= \ + -e SAML_USERNAME_ATTR_NAME= \ + -e SAML_EMAIL_ATTR_NAME= \ + -e SAML_FIRSTNAME_ATTR_NAME= \ + -e SAML_LASTNAME_ATTR_NAME= \ + -e SAML_SIGN_REQUESTS= \ + -e SAML_SIGN_METADATA= \ + -e SAML_SIGNED_ASSERTION= \ + -e SAML_SIGNED_ENVELOPES= \ + + ...[other settings]... + ``` ### Available variables for SAML diff --git a/trento/xml/sso-integration.xml b/trento/xml/sso-integration.xml index 3797696d..7f4d5254 100644 --- a/trento/xml/sso-integration.xml +++ b/trento/xml/sso-integration.xml @@ -386,7 +386,7 @@ docker run -d \ To use an existing SAML IDP, follow the next instrunctions to met the specific requirements. You need: - + Configure SAML IDP and user profiles @@ -407,22 +407,24 @@ docker run -d \ Restart Trento - + + + See the following subsections for details. +
Configuring SAML IDP setup Configure the existing IDP with the next minimum options to be - able to connect with Trento's Service Provider (SP). + able to connect with Trento as a Service Provider (SP). -
- SAML user profile +
+ Configuring SAML user profile Users provided by the SAML installation must have some few - mandatory attributes to login in Trento. All of them are - mandatory, even though their name is configurable. The user - profile must include attributes for: username, email, first - name and last name. This attributes must be mapped for all - users wanting to connect to Trento. + mandatory attributes to login in Trento. The required + attributes are: username, email, first name and last name. All + of them are mandatory, even though their field name is + configurable. By default, Trento expects the username, @@ -433,15 +435,38 @@ docker run -d \ SAML_USERNAME_ATTR_NAME, SAML_EMAIL_ATTR_NAME, SAML_FIRSTNAME_ATTR_NAME and - SAML_LASTNAME_ATTR_NAME. So for example, if - the IDP user profile username is defined as - attr:username, - SAML_USERNAME_ATTR_NAME=attr:username - should be used. + SAML_LASTNAME_ATTR_NAME. + + + So both the IDP and Trento must know how these 4 fields are + mapped. For that, follow the next instruction: + + + + Add the attributes if they don't exist in the IDP user + profile. If they already exist, they name doesn't need to + be changed, so the current values can continue being used. + + + + + Configure Trento to use the IDP attribute field names. For + that, set the SAML_USERNAME_ATTR_NAME, + SAML_EMAIL_ATTR_NAME, + SAML_FIRSTNAME_ATTR_NAME and + SAML_LASTNAME_ATTR_NAME environment + values with the values configured in the IDP. For example, + if the IDP user profile username is defined as + attr:username, + SAML_USERNAME_ATTR_NAME=attr:username + should be used. + + +
-
- SAML redirect URI +
+ Checking SAML redirect URI Once the login is done succesfully, the IDP redirects the session back to Trento. This redirection is done to @@ -450,29 +475,29 @@ docker run -d \
-
- Get certificates from Trento +
+ Getting certificates from Trento Trento provides a certificates set created during the - installation. When Trento is installed the first time (does not - matter the installation mode) the certificates are created, and - the public certificate file content is available in the + installation. Regardless of the installation mode, when Trento + is installed the first time the certificates are created and the + public certificate file content is available in the http://localhost:4000/api/public_keys route. - Use the following command to download the certificate: + Use the following command to get the certificate content: curl http://localhost:4000/api/public_keys - Copy the content of the certificate from there, and provide it - to the IDP. This way, the IDP will sign and verify the messages - sent by both ends. + Copy the content of the certificate from there and provide it to + the IDP. This way, the IDP will sign its messages and verify the + messages received from Trento.
-
- Restart Trento +
+ Restarting Trento Once the certificate is provided to the IDP, the IDP recreates its own metadata.xml file. This file @@ -483,11 +508,18 @@ curl http://localhost:4000/api/public_keys If the option is being used, the content of this variable must be updated with the new - metadata. In the other hand, if + metadata, as single line string. In the other hand, if is used, the new metadata is automatically fetched. If neither of these steps are completed, communication will fail because the message signatures will not - be recognized + be recognized. + + + If the used IDP has the endpoint to provide the + metadata.xml file content, the usage of + is preferred, as further + changes in the IDP will be fetched automatically by Trento when + it is restarted. This restart must be done manually, by the admin. @@ -526,7 +558,7 @@ SAML_METDATA_CONTENT=<SAML_METADATA_CONTENT> To enable SAML when using RPM packages, proceed as follows: - + Open the file /etc/trento/trento-web. @@ -537,9 +569,7 @@ SAML_METDATA_CONTENT=<SAML_METADATA_CONTENT> Add the following environment variables to this file. Required variables are: - - - + # Required: ENABLE_SAML=true SAML_IDP_ID=<SAML_IDP_ID> @@ -566,7 +596,7 @@ SAML_SIGN_METADATA=<SAML_SIGN_METADATA> SAML_SIGNED_ASSERTION=<SAML_SIGNED_ASSERTION> SAML_SIGNED_ENVELOPES=<SAML_SIGNED_ENVELOPES> - + Restart the application. @@ -579,15 +609,13 @@ SAML_SIGNED_ENVELOPES=<SAML_SIGNED_ENVELOPES> To enable SAML when using Docker images, proceed as follows: - + Use the following environment variables to the Docker container via the -e option: - - - + docker run -d \ -p 4000:4000 \ --name trento-web \ @@ -623,6 +651,8 @@ docker run -d \ ...[other settings]... + +
Available variables for SAML From 154ba8d1411eeb3eb5ff825f305524cf40cb1b70 Mon Sep 17 00:00:00 2001 From: arbulu89 Date: Thu, 10 Oct 2024 13:55:06 +0200 Subject: [PATCH 06/20] Change order in SAML installation steps --- trento/migration/sso-integration.md | 32 +++++++++------- trento/xml/sso-integration.xml | 59 +++++++++++++++++------------ 2 files changed, 53 insertions(+), 38 deletions(-) diff --git a/trento/migration/sso-integration.md b/trento/migration/sso-integration.md index 5fab2fcf..c0dead6e 100644 --- a/trento/migration/sso-integration.md +++ b/trento/migration/sso-integration.md @@ -214,17 +214,33 @@ If the IDP signs the messages, and expect signed messages back, certificates use To use an existing SAML IDP, follow the next instrunctions to met the specific requirements. You need: -1. Configure SAML IDP and user profiles -1. Start Trento to generate the certificates and download them +1. Start Trento to generate the certificates and get them 1. Provide the generated certificate to the IDP +1. Configure SAML IDP and user profiles 1. Restart Trento See the following subsections for details. +### Getting certificates from Trento + +Trento provides a certificates set created during the installation. Regardless of the installation mode, when Trento is installed the first time the certificates are created and the public certificate file content is available in the http://localhost:4000/api/public_keys route. + +Use the following command to get the certificate content: + +```bash +curl http://localhost:4000/api/public_keys +``` + +Copy the content of the certificate from there and provide it to the IDP. This way, the IDP will sign its messages and verify the messages received from Trento. + ### Configuring SAML IDP setup Configure the existing IDP with the next minimum options to be able to connect with Trento as a Service Provider (SP). +#### Providing certificates + +As commented previously, a set of certificates is needed to enable signed communication. Provide the certificate generated by Trento to the IDP (each IDP has a different way to do this). Make sure that the provided certificate is available in the SAML metadata.xml file and has preference over other uploaded certificates. + #### Configuring SAML user profile Users provided by the SAML installation must have some few mandatory attributes to login in Trento. The required attributes are: username, email, first name and last name. All of them are mandatory, even though their field name is configurable. @@ -241,18 +257,6 @@ So both the IDP and Trento must know how these 4 fields are mapped. For that, fo Once the login is done succesfully, the IDP redirects the session back to Trento. This redirection is done to `https://trento.example.com/sso/sp/consume/saml`, so this URI must be set as valid in the IDP. -### Getting certificates from Trento - -Trento provides a certificates set created during the installation. Regardless of the installation mode, when Trento is installed the first time the certificates are created and the public certificate file content is available in the http://localhost:4000/api/public_keys route. - -Use the following command to get the certificate content: - -```bash -curl http://localhost:4000/api/public_keys -``` - -Copy the content of the certificate from there and provide it to the IDP. This way, the IDP will sign its messages and verify the messages received from Trento. - ### Restarting Trento Once the certificate is provided to the IDP, the IDP recreates its own metadata.xml file. This file defines which certificate is used to sign the messages by both sides. At this point, Trento Web must be restarted to use the new metadata.xml content. diff --git a/trento/xml/sso-integration.xml b/trento/xml/sso-integration.xml index 7f4d5254..75b81a15 100644 --- a/trento/xml/sso-integration.xml +++ b/trento/xml/sso-integration.xml @@ -389,17 +389,17 @@ docker run -d \ - Configure SAML IDP and user profiles + Start Trento to generate the certificates and get them - Start Trento to generate the certificates and download them + Provide the generated certificate to the IDP - Provide the generated certificate to the IDP + Configure SAML IDP and user profiles @@ -411,12 +411,44 @@ docker run -d \ See the following subsections for details. +
+ Getting certificates from Trento + + Trento provides a certificates set created during the + installation. Regardless of the installation mode, when Trento + is installed the first time the certificates are created and the + public certificate file content is available in the + http://localhost:4000/api/public_keys route. + + + Use the following command to get the certificate content: + + +curl http://localhost:4000/api/public_keys + + + Copy the content of the certificate from there and provide it to + the IDP. This way, the IDP will sign its messages and verify the + messages received from Trento. + +
Configuring SAML IDP setup Configure the existing IDP with the next minimum options to be able to connect with Trento as a Service Provider (SP). +
+ Providing certificates + + As commented previously, a set of certificates is needed to + enable signed communication. Provide the certificate generated + by Trento to the IDP (each IDP has a different way to do + this). Make sure that the provided certificate is available in + the SAML metadata.xml file and has + preference over other uploaded certificates. + +
Configuring SAML user profile @@ -475,27 +507,6 @@ docker run -d \
-
- Getting certificates from Trento - - Trento provides a certificates set created during the - installation. Regardless of the installation mode, when Trento - is installed the first time the certificates are created and the - public certificate file content is available in the - http://localhost:4000/api/public_keys route. - - - Use the following command to get the certificate content: - - -curl http://localhost:4000/api/public_keys - - - Copy the content of the certificate from there and provide it to - the IDP. This way, the IDP will sign its messages and verify the - messages received from Trento. - -
Restarting Trento From f748c2d4520852cd8fce024d21713d9fd0db4b80 Mon Sep 17 00:00:00 2001 From: arbulu89 Date: Thu, 10 Oct 2024 15:48:13 +0200 Subject: [PATCH 07/20] Apply more improvements and fix typos --- trento/migration/sso-integration.md | 16 ++++++------ trento/xml/sso-integration.xml | 40 ++++++++++++++--------------- 2 files changed, 28 insertions(+), 28 deletions(-) diff --git a/trento/migration/sso-integration.md b/trento/migration/sso-integration.md index c0dead6e..15bb7955 100644 --- a/trento/migration/sso-integration.md +++ b/trento/migration/sso-integration.md @@ -243,27 +243,27 @@ As commented previously, a set of certificates is needed to enable signed commun #### Configuring SAML user profile -Users provided by the SAML installation must have some few mandatory attributes to login in Trento. The required attributes are: username, email, first name and last name. All of them are mandatory, even though their field name is configurable. +Users provided by the SAML installation must have some few mandatory attributes to login in Trento. The required attributes are: username, email, first name and last name. All of them are mandatory, even though their field names are configurable. By default, Trento expects the `username`, `email`, `firstName` and `lastName` attribute names. All these 4 attribute names are configurable using the next environment variables, following the same order: `SAML_USERNAME_ATTR_NAME`, `SAML_EMAIL_ATTR_NAME`, `SAML_FIRSTNAME_ATTR_NAME` and `SAML_LASTNAME_ATTR_NAME`. -So both the IDP and Trento must know how these 4 fields are mapped. For that, follow the next instruction: +Both IDP and Trento must know how these 4 fields are mapped. To do this, follow the next instructions: -1. Add the attributes if they don't exist in the IDP user profile. If they already exist, they name doesn't need to be changed, so the current values can continue being used. +1. Add the attributes if they don't exist in the IDP user profile. If they already exist, don't change the attributes and keep their original values. -1. Configure Trento to use the IDP attribute field names. For that, set the `SAML_USERNAME_ATTR_NAME`, `SAML_EMAIL_ATTR_NAME`, `SAML_FIRSTNAME_ATTR_NAME` and `SAML_LASTNAME_ATTR_NAME` environment values with the values configured in the IDP. For example, if the IDP user profile username is defined as `attr:username`, `SAML_USERNAME_ATTR_NAME=attr:username` should be used. +1. Configure Trento to use the IDP attribute field names. To do this, set the `SAML_USERNAME_ATTR_NAME`, `SAML_EMAIL_ATTR_NAME`, `SAML_FIRSTNAME_ATTR_NAME` and `SAML_LASTNAME_ATTR_NAME` environment values with the values configured in the IDP. For example, if the IDP user profile username is defined as `attr:username` use `SAML_USERNAME_ATTR_NAME=attr:username`. #### Checking SAML redirect URI -Once the login is done succesfully, the IDP redirects the session back to Trento. This redirection is done to `https://trento.example.com/sso/sp/consume/saml`, so this URI must be set as valid in the IDP. +After a successful login, the IDP redirects the user's session back to Trento and redirected at https://trento.example.com/sso/sp/consume/saml. To ensure seamless SSO, this URI must be configured as valid within the IDP. ### Restarting Trento Once the certificate is provided to the IDP, the IDP recreates its own metadata.xml file. This file defines which certificate is used to sign the messages by both sides. At this point, Trento Web must be restarted to use the new metadata.xml content. -If the option is being used, the content of this variable must be updated with the new metadata, as single line string. In the other hand, if is used, the new metadata is automatically fetched. If neither of these steps are completed, communication will fail because the message signatures will not be recognized. +If the option is being used, the content of this variable must be updated with the new metadata as single line string. On the other hand, if is used, the new metadata is automatically fetched. If neither of these steps are completed, communication will fail because the message signatures will not be recognized. -If the used IDP has the endpoint to provide the metadata.xml file content, the usage of is preferred, as further changes in the IDP will be fetched automatically by Trento when it is restarted. +If the used IDP has the endpoint to provide the metadata.xml file content, prefer the variable . Trento will automatically fetch metadata when restarted. ```{=docbook} @@ -271,7 +271,7 @@ If the used IDP has the endpoint to provide the metadata.xml ``` -Follow the next instrucionts to restart with the configured options: +Follow the next instructions to restart with the configured options: 1. Open the file /etc/trento/trento-web. 1. Add the following environment variables to this file. diff --git a/trento/xml/sso-integration.xml b/trento/xml/sso-integration.xml index 75b81a15..533a180f 100644 --- a/trento/xml/sso-integration.xml +++ b/trento/xml/sso-integration.xml @@ -455,7 +455,7 @@ curl http://localhost:4000/api/public_keys Users provided by the SAML installation must have some few mandatory attributes to login in Trento. The required attributes are: username, email, first name and last name. All - of them are mandatory, even though their field name is + of them are mandatory, even though their field names are configurable. @@ -470,29 +470,29 @@ curl http://localhost:4000/api/public_keys SAML_LASTNAME_ATTR_NAME. - So both the IDP and Trento must know how these 4 fields are - mapped. For that, follow the next instruction: + Both IDP and Trento must know how these 4 fields are mapped. + To do this, follow the next instructions: Add the attributes if they don't exist in the IDP user - profile. If they already exist, they name doesn't need to - be changed, so the current values can continue being used. + profile. If they already exist, don't change the + attributes and keep their original values. - Configure Trento to use the IDP attribute field names. For - that, set the SAML_USERNAME_ATTR_NAME, + Configure Trento to use the IDP attribute field names. To + do this, set the + SAML_USERNAME_ATTR_NAME, SAML_EMAIL_ATTR_NAME, SAML_FIRSTNAME_ATTR_NAME and SAML_LASTNAME_ATTR_NAME environment values with the values configured in the IDP. For example, if the IDP user profile username is defined as - attr:username, - SAML_USERNAME_ATTR_NAME=attr:username - should be used. + attr:username use + SAML_USERNAME_ATTR_NAME=attr:username. @@ -500,10 +500,11 @@ curl http://localhost:4000/api/public_keys
Checking SAML redirect URI - Once the login is done succesfully, the IDP redirects the - session back to Trento. This redirection is done to - https://trento.example.com/sso/sp/consume/saml, - so this URI must be set as valid in the IDP. + After a successful login, the IDP redirects the user's session + back to Trento and redirected at + https://trento.example.com/sso/sp/consume/saml. + To ensure seamless SSO, this URI must be configured as valid + within the IDP.
@@ -519,7 +520,7 @@ curl http://localhost:4000/api/public_keys If the option is being used, the content of this variable must be updated with the new - metadata, as single line string. In the other hand, if + metadata as single line string. On the other hand, if is used, the new metadata is automatically fetched. If neither of these steps are completed, communication will fail because the message signatures will not @@ -527,16 +528,15 @@ curl http://localhost:4000/api/public_keys If the used IDP has the endpoint to provide the - metadata.xml file content, the usage of - is preferred, as further - changes in the IDP will be fetched automatically by Trento when - it is restarted. + metadata.xml file content, prefer the + variable . Trento will + automatically fetch metadata when restarted. This restart must be done manually, by the admin. - Follow the next instrucionts to restart with the configured + Follow the next instructions to restart with the configured options: From c7ad4dda30ad583f271c49dc72f4d66b5692cfcc Mon Sep 17 00:00:00 2001 From: arbulu89 Date: Mon, 14 Oct 2024 09:35:30 +0200 Subject: [PATCH 08/20] Add kubernetes installation chapters --- trento/migration/sso-integration.md | 48 +++++++++++++++++++- trento/xml/sso-integration.xml | 70 ++++++++++++++++++++++++++++- 2 files changed, 116 insertions(+), 2 deletions(-) diff --git a/trento/migration/sso-integration.md b/trento/migration/sso-integration.md index 15bb7955..f3193903 100644 --- a/trento/migration/sso-integration.md +++ b/trento/migration/sso-integration.md @@ -32,6 +32,16 @@ Trento integrates with an IDP that uses the OIDC protocol to authenticate users By default, OIDC is disabled. You can enable OIDC when using RPM packages or using Docker images. +### Enabling OpenID Connect when using kubernetes deployment + +To enable OIDC when using kubernetes deployment with helm, proceed as follows: + +1. Add the following variables to the previously documented helm installation command: + + ``` + HELM_EXPERIMENTAL_OCI=1 helm ... --set trento-web.oidc.enabled=true --set trento-web.oidc.cliendId= --set trento-web.oidc.clientSecret= --set trento-web.oidc.baseUrl= + ``` + ### Enabling OpenID Connect when using RPM packages @@ -113,6 +123,19 @@ Trento integrates with an IDP that uses the OAuth 2 protocol to authenticate use By default, OAuth 2.0 is disabled. You can enable OIDC when using RPM packages or using Docker images. +### Enabling OAuth 2.0 when using kubernetes deployment + +To enable OAuth 2.0 when using kubernetes deployment with helm, proceed as follows: + +1. Add the following variables to the previously documented helm installation command: + + ``` + HELM_EXPERIMENTAL_OCI=1 helm ... --set trento-web.oauth2.enabled=true --set trento-web.oauth2.cliendId= --set trento-web.ouath2.clientSecret= --set trento-web.oauth2.baseUrl= --set trento-web.oauth2.authorizeUrl= --set trento-web.oauth2.tokenUrl= --set trento-web.oauth2.userUrl= --set trento-web.oauth2.scopes= + ``` + + variable is optional with `profile email` as default value. + + ### Enabling OAuth 2.0 when using RPM packages To enable OAuth 2.0 when using RPM packages, proceed as follows: @@ -263,7 +286,7 @@ Once the certificate is provided to the IDP, the IDP recreates its own SAML_METDATA_CONTENT option is being used, the content of this variable must be updated with the new metadata as single line string. On the other hand, if is used, the new metadata is automatically fetched. If neither of these steps are completed, communication will fail because the message signatures will not be recognized. -If the used IDP has the endpoint to provide the metadata.xml file content, prefer the variable . Trento will automatically fetch metadata when restarted. +If the used IDP has the endpoint to provide the metadata.xml file content, prefer the variable . Trento will automatically fetch metadata when restarted. ```{=docbook} @@ -287,6 +310,29 @@ Follow the next instructions to restart with the configured options: 1. Restart the application. +### Enabling SAML when using kubernetes deployment + +To enable SAML when using kubernetes deployment with helm, proceed as follows: + +1. Add the following variables to the previously documented helm installation command: + + ``` + HELM_EXPERIMENTAL_OCI=1 helm ... --set trento-web.saml.enabled=true --set trento-web.saml.idpId= --set trento-web.saml.spId= --set trento-web.saml.metadataUrl= + ``` + + To use the option rather than use: + + ``` + HELM_EXPERIMENTAL_OCI=1 helm ... --set trento-web.saml.enabled=true --set trento-web.saml.idpId= --set trento-web.saml.spId= --set trento-web.saml.metadataContent= + ``` + + Additionally, the following optional values are available: + + ``` + HELM_EXPERIMENTAL_OCI=1 helm ... --set trento-web.saml.enabled=true --set trento-web.saml.idpId= --set trento-web.saml.spId= --set trento-web.saml.metadataUrl= --set trento-web.saml.idpNameIdFormat= --set trento-web.saml.spDir= --set trento-web.saml.spEntityId= --set trento-web.saml.spContactName= --set trento-web.saml.spContactEmail= --set trento-web.saml.spOrgName= --set trento-web.saml.spOrgDisplayName= --set trento-web.saml.spOrgUrl= --set trento-web.saml.usernameAttrName= --set trento-web.saml.emailAttrName= --set trento-web.saml.firstNameAttrName= --set trento-web.saml.lastNameAttrName= --set trento-web.saml.signRequests= --set trento-web.saml.signMetadata= --set trento-web.saml.signedAssertion= --set trento-web.saml.signedEnvelopes= + ``` + + ### Enabling SAML when using RPM packages To enable SAML when using RPM packages, proceed as follows: diff --git a/trento/xml/sso-integration.xml b/trento/xml/sso-integration.xml index 533a180f..58188f0b 100644 --- a/trento/xml/sso-integration.xml +++ b/trento/xml/sso-integration.xml @@ -61,6 +61,25 @@ By default, OIDC is disabled. You can enable OIDC when using RPM packages or using Docker images. +
+ Enabling OpenID Connect when using kubernetes + deployment + + To enable OIDC when using kubernetes deployment with helm, + proceed as follows: + + + + + Add the following variables to the previously documented + helm installation command: + + +HELM_EXPERIMENTAL_OCI=1 helm ... --set trento-web.oidc.enabled=true --set trento-web.oidc.cliendId=<OIDC_CLIENT_ID> --set trento-web.oidc.clientSecret=<OIDC_CLIENT_SECRET> --set trento-web.oidc.baseUrl=<OIDC_BASE_URL> + + + +
Enabling OpenID Connect when using RPM packages @@ -200,6 +219,24 @@ docker run -d \ By default, OAuth 2.0 is disabled. You can enable OIDC when using RPM packages or using Docker images. +
+ Enabling OAuth 2.0 when using kubernetes deployment + + To enable OAuth 2.0 when using kubernetes deployment with helm, + proceed as follows: + + + + + Add the following variables to the previously documented + helm installation command: + + +HELM_EXPERIMENTAL_OCI=1 helm ... --set trento-web.oauth2.enabled=true --set trento-web.oauth2.cliendId=<OAUTH2_CLIENT_ID> --set trento-web.ouath2.clientSecret=<OAUTH2_CLIENT_SECRET> --set trento-web.oauth2.baseUrl=<OAUTH2_BASE_URL> --set trento-web.oauth2.authorizeUrl=<OAUTH2_AUTHORIZE_URL> --set trento-web.oauth2.tokenUrl=<OAUTH2_TOKEN_URL> --set trento-web.oauth2.userUrl=<OAUTH2_USER_URL> --set trento-web.oauth2.scopes=<OAUTH2_SCOPES> + + + +
Enabling OAuth 2.0 when using RPM packages @@ -529,7 +566,7 @@ curl http://localhost:4000/api/public_keys If the used IDP has the endpoint to provide the metadata.xml file content, prefer the - variable . Trento will + variable . Trento will automatically fetch metadata when restarted. @@ -564,6 +601,37 @@ SAML_METDATA_CONTENT=<SAML_METADATA_CONTENT>
+
+ Enabling SAML when using kubernetes deployment + + To enable SAML when using kubernetes deployment with helm, + proceed as follows: + + + + + Add the following variables to the previously documented + helm installation command: + + +HELM_EXPERIMENTAL_OCI=1 helm ... --set trento-web.saml.enabled=true --set trento-web.saml.idpId=<SAML_IDP_ID> --set trento-web.saml.spId=<SAML_SP_ID> --set trento-web.saml.metadataUrl=<SAML_METADATA_URL> + + + To use the option + rather than use: + + +HELM_EXPERIMENTAL_OCI=1 helm ... --set trento-web.saml.enabled=true --set trento-web.saml.idpId=<SAML_IDP_ID> --set trento-web.saml.spId=<SAML_SP_ID> --set trento-web.saml.metadataContent=<SAML_METADATA_CONTENT> + + + Additionally, the following optional values are available: + + +HELM_EXPERIMENTAL_OCI=1 helm ... --set trento-web.saml.enabled=true --set trento-web.saml.idpId=<SAML_IDP_ID> --set trento-web.saml.spId=<SAML_SP_ID> --set trento-web.saml.metadataUrl=<SAML_METADATA_URL> --set trento-web.saml.idpNameIdFormat=<SAML_IDP_NAMEID_FORMAT> --set trento-web.saml.spDir=<SAML_SP_DIR> --set trento-web.saml.spEntityId=<SAML_SP_ENTITY_ID> --set trento-web.saml.spContactName=<SAML_SP_CONTACT_NAME> --set trento-web.saml.spContactEmail=<SAML_SP_CONTACT_EMAIL> --set trento-web.saml.spOrgName=<SAML_SP_ORG_NAME> --set trento-web.saml.spOrgDisplayName=<SAML_SP_ORG_DISPLAYNAME> --set trento-web.saml.spOrgUrl=<SAML_SP_ORG_URL> --set trento-web.saml.usernameAttrName=<SAML_USERNAME_ATTR_NAME> --set trento-web.saml.emailAttrName=<SAML_EMAIL_ATTR_NAME> --set trento-web.saml.firstNameAttrName=<SAML_FIRSTNAME_ATTR_NAME> --set trento-web.saml.lastNameAttrName=<SAML_LASTNAME_ATTR_NAME> --set trento-web.saml.signRequests=<SAML_SIGN_REQUESTS> --set trento-web.saml.signMetadata=<SAML_SIGN_METADATA> --set trento-web.saml.signedAssertion=<SAML_SIGNED_ASSERTION> --set trento-web.saml.signedEnvelopes=<SAML_SIGNED_ENVELOPES> + + + +
Enabling SAML when using RPM packages From 672e6ef45924358c800f2dc1032c376989256efe Mon Sep 17 00:00:00 2001 From: arbulu89 Date: Mon, 14 Oct 2024 12:04:58 +0200 Subject: [PATCH 09/20] Ident helm commands with new lines --- trento/migration/sso-integration.md | 50 ++++++++++++++++++++++++++--- trento/xml/sso-integration.xml | 50 ++++++++++++++++++++++++++--- 2 files changed, 90 insertions(+), 10 deletions(-) diff --git a/trento/migration/sso-integration.md b/trento/migration/sso-integration.md index f3193903..83fcb794 100644 --- a/trento/migration/sso-integration.md +++ b/trento/migration/sso-integration.md @@ -39,7 +39,11 @@ To enable OIDC when using kubernetes deployment with helm, proceed as follows: 1. Add the following variables to the previously documented helm installation command: ``` - HELM_EXPERIMENTAL_OCI=1 helm ... --set trento-web.oidc.enabled=true --set trento-web.oidc.cliendId= --set trento-web.oidc.clientSecret= --set trento-web.oidc.baseUrl= + HELM_EXPERIMENTAL_OCI=1 helm ... \ + --set trento-web.oidc.enabled=true \ + --set trento-web.oidc.cliendId= \ + --set trento-web.oidc.clientSecret= \ + --set trento-web.oidc.baseUrl= ``` @@ -130,7 +134,15 @@ To enable OAuth 2.0 when using kubernetes deployment with helm, proceed as follo 1. Add the following variables to the previously documented helm installation command: ``` - HELM_EXPERIMENTAL_OCI=1 helm ... --set trento-web.oauth2.enabled=true --set trento-web.oauth2.cliendId= --set trento-web.ouath2.clientSecret= --set trento-web.oauth2.baseUrl= --set trento-web.oauth2.authorizeUrl= --set trento-web.oauth2.tokenUrl= --set trento-web.oauth2.userUrl= --set trento-web.oauth2.scopes= + HELM_EXPERIMENTAL_OCI=1 helm ... \ + --set trento-web.oauth2.enabled=true \ + --set trento-web.oauth2.cliendId= \ + --set trento-web.ouath2.clientSecret= \ + --set trento-web.oauth2.baseUrl= \ + --set trento-web.oauth2.authorizeUrl= \ + --set trento-web.oauth2.tokenUrl= \ + --set trento-web.oauth2.userUrl= \ + --set trento-web.oauth2.scopes= ``` variable is optional with `profile email` as default value. @@ -317,19 +329,47 @@ To enable SAML when using kubernetes deployment with helm, proceed as follows: 1. Add the following variables to the previously documented helm installation command: ``` - HELM_EXPERIMENTAL_OCI=1 helm ... --set trento-web.saml.enabled=true --set trento-web.saml.idpId= --set trento-web.saml.spId= --set trento-web.saml.metadataUrl= + HELM_EXPERIMENTAL_OCI=1 helm ... \ + --set trento-web.saml.enabled=true \ + --set trento-web.saml.idpId= \ + --set trento-web.saml.spId= \ + --set trento-web.saml.metadataUrl= ``` To use the option rather than use: ``` - HELM_EXPERIMENTAL_OCI=1 helm ... --set trento-web.saml.enabled=true --set trento-web.saml.idpId= --set trento-web.saml.spId= --set trento-web.saml.metadataContent= + HELM_EXPERIMENTAL_OCI=1 helm ... \ + --set trento-web.saml.enabled=true \ + --set trento-web.saml.idpId= \ + --set trento-web.saml.spId= \ + --set trento-web.saml.metadataContent= ``` Additionally, the following optional values are available: ``` - HELM_EXPERIMENTAL_OCI=1 helm ... --set trento-web.saml.enabled=true --set trento-web.saml.idpId= --set trento-web.saml.spId= --set trento-web.saml.metadataUrl= --set trento-web.saml.idpNameIdFormat= --set trento-web.saml.spDir= --set trento-web.saml.spEntityId= --set trento-web.saml.spContactName= --set trento-web.saml.spContactEmail= --set trento-web.saml.spOrgName= --set trento-web.saml.spOrgDisplayName= --set trento-web.saml.spOrgUrl= --set trento-web.saml.usernameAttrName= --set trento-web.saml.emailAttrName= --set trento-web.saml.firstNameAttrName= --set trento-web.saml.lastNameAttrName= --set trento-web.saml.signRequests= --set trento-web.saml.signMetadata= --set trento-web.saml.signedAssertion= --set trento-web.saml.signedEnvelopes= + HELM_EXPERIMENTAL_OCI=1 helm ... \ + --set trento-web.saml.enabled=true \ + --set trento-web.saml.idpId= \ + --set trento-web.saml.spId= \ + --set trento-web.saml.metadataUrl= \ + --set trento-web.saml.idpNameIdFormat= \ + --set trento-web.saml.spDir= \ + --set trento-web.saml.spEntityId= \ + --set trento-web.saml.spContactName= \ + --set trento-web.saml.spContactEmail= \ + --set trento-web.saml.spOrgName= \ + --set trento-web.saml.spOrgDisplayName= \ + --set trento-web.saml.spOrgUrl= \ + --set trento-web.saml.usernameAttrName= \ + --set trento-web.saml.emailAttrName= \ + --set trento-web.saml.firstNameAttrName= \ + --set trento-web.saml.lastNameAttrName= \ + --set trento-web.saml.signRequests= \ + --set trento-web.saml.signMetadata= \ + --set trento-web.saml.signedAssertion= \ + --set trento-web.saml.signedEnvelopes= ``` diff --git a/trento/xml/sso-integration.xml b/trento/xml/sso-integration.xml index 58188f0b..3c5bbdea 100644 --- a/trento/xml/sso-integration.xml +++ b/trento/xml/sso-integration.xml @@ -75,7 +75,11 @@ helm installation command: -HELM_EXPERIMENTAL_OCI=1 helm ... --set trento-web.oidc.enabled=true --set trento-web.oidc.cliendId=<OIDC_CLIENT_ID> --set trento-web.oidc.clientSecret=<OIDC_CLIENT_SECRET> --set trento-web.oidc.baseUrl=<OIDC_BASE_URL> +HELM_EXPERIMENTAL_OCI=1 helm ... \ + --set trento-web.oidc.enabled=true \ + --set trento-web.oidc.cliendId=<OIDC_CLIENT_ID> \ + --set trento-web.oidc.clientSecret=<OIDC_CLIENT_SECRET> \ + --set trento-web.oidc.baseUrl=<OIDC_BASE_URL> @@ -232,7 +236,15 @@ docker run -d \ helm installation command: -HELM_EXPERIMENTAL_OCI=1 helm ... --set trento-web.oauth2.enabled=true --set trento-web.oauth2.cliendId=<OAUTH2_CLIENT_ID> --set trento-web.ouath2.clientSecret=<OAUTH2_CLIENT_SECRET> --set trento-web.oauth2.baseUrl=<OAUTH2_BASE_URL> --set trento-web.oauth2.authorizeUrl=<OAUTH2_AUTHORIZE_URL> --set trento-web.oauth2.tokenUrl=<OAUTH2_TOKEN_URL> --set trento-web.oauth2.userUrl=<OAUTH2_USER_URL> --set trento-web.oauth2.scopes=<OAUTH2_SCOPES> +HELM_EXPERIMENTAL_OCI=1 helm ... \ + --set trento-web.oauth2.enabled=true \ + --set trento-web.oauth2.cliendId=<OAUTH2_CLIENT_ID> \ + --set trento-web.ouath2.clientSecret=<OAUTH2_CLIENT_SECRET> \ + --set trento-web.oauth2.baseUrl=<OAUTH2_BASE_URL> \ + --set trento-web.oauth2.authorizeUrl=<OAUTH2_AUTHORIZE_URL> \ + --set trento-web.oauth2.tokenUrl=<OAUTH2_TOKEN_URL> \ + --set trento-web.oauth2.userUrl=<OAUTH2_USER_URL> \ + --set trento-web.oauth2.scopes=<OAUTH2_SCOPES> @@ -614,20 +626,48 @@ SAML_METDATA_CONTENT=<SAML_METADATA_CONTENT> helm installation command: -HELM_EXPERIMENTAL_OCI=1 helm ... --set trento-web.saml.enabled=true --set trento-web.saml.idpId=<SAML_IDP_ID> --set trento-web.saml.spId=<SAML_SP_ID> --set trento-web.saml.metadataUrl=<SAML_METADATA_URL> +HELM_EXPERIMENTAL_OCI=1 helm ... \ + --set trento-web.saml.enabled=true \ + --set trento-web.saml.idpId=<SAML_IDP_ID> \ + --set trento-web.saml.spId=<SAML_SP_ID> \ + --set trento-web.saml.metadataUrl=<SAML_METADATA_URL> To use the option rather than use: -HELM_EXPERIMENTAL_OCI=1 helm ... --set trento-web.saml.enabled=true --set trento-web.saml.idpId=<SAML_IDP_ID> --set trento-web.saml.spId=<SAML_SP_ID> --set trento-web.saml.metadataContent=<SAML_METADATA_CONTENT> +HELM_EXPERIMENTAL_OCI=1 helm ... \ + --set trento-web.saml.enabled=true \ + --set trento-web.saml.idpId=<SAML_IDP_ID> \ + --set trento-web.saml.spId=<SAML_SP_ID> \ + --set trento-web.saml.metadataContent=<SAML_METADATA_CONTENT> Additionally, the following optional values are available: -HELM_EXPERIMENTAL_OCI=1 helm ... --set trento-web.saml.enabled=true --set trento-web.saml.idpId=<SAML_IDP_ID> --set trento-web.saml.spId=<SAML_SP_ID> --set trento-web.saml.metadataUrl=<SAML_METADATA_URL> --set trento-web.saml.idpNameIdFormat=<SAML_IDP_NAMEID_FORMAT> --set trento-web.saml.spDir=<SAML_SP_DIR> --set trento-web.saml.spEntityId=<SAML_SP_ENTITY_ID> --set trento-web.saml.spContactName=<SAML_SP_CONTACT_NAME> --set trento-web.saml.spContactEmail=<SAML_SP_CONTACT_EMAIL> --set trento-web.saml.spOrgName=<SAML_SP_ORG_NAME> --set trento-web.saml.spOrgDisplayName=<SAML_SP_ORG_DISPLAYNAME> --set trento-web.saml.spOrgUrl=<SAML_SP_ORG_URL> --set trento-web.saml.usernameAttrName=<SAML_USERNAME_ATTR_NAME> --set trento-web.saml.emailAttrName=<SAML_EMAIL_ATTR_NAME> --set trento-web.saml.firstNameAttrName=<SAML_FIRSTNAME_ATTR_NAME> --set trento-web.saml.lastNameAttrName=<SAML_LASTNAME_ATTR_NAME> --set trento-web.saml.signRequests=<SAML_SIGN_REQUESTS> --set trento-web.saml.signMetadata=<SAML_SIGN_METADATA> --set trento-web.saml.signedAssertion=<SAML_SIGNED_ASSERTION> --set trento-web.saml.signedEnvelopes=<SAML_SIGNED_ENVELOPES> +HELM_EXPERIMENTAL_OCI=1 helm ... \ + --set trento-web.saml.enabled=true \ + --set trento-web.saml.idpId=<SAML_IDP_ID> \ + --set trento-web.saml.spId=<SAML_SP_ID> \ + --set trento-web.saml.metadataUrl=<SAML_METADATA_URL> \ + --set trento-web.saml.idpNameIdFormat=<SAML_IDP_NAMEID_FORMAT> \ + --set trento-web.saml.spDir=<SAML_SP_DIR> \ + --set trento-web.saml.spEntityId=<SAML_SP_ENTITY_ID> \ + --set trento-web.saml.spContactName=<SAML_SP_CONTACT_NAME> \ + --set trento-web.saml.spContactEmail=<SAML_SP_CONTACT_EMAIL> \ + --set trento-web.saml.spOrgName=<SAML_SP_ORG_NAME> \ + --set trento-web.saml.spOrgDisplayName=<SAML_SP_ORG_DISPLAYNAME> \ + --set trento-web.saml.spOrgUrl=<SAML_SP_ORG_URL> \ + --set trento-web.saml.usernameAttrName=<SAML_USERNAME_ATTR_NAME> \ + --set trento-web.saml.emailAttrName=<SAML_EMAIL_ATTR_NAME> \ + --set trento-web.saml.firstNameAttrName=<SAML_FIRSTNAME_ATTR_NAME> \ + --set trento-web.saml.lastNameAttrName=<SAML_LASTNAME_ATTR_NAME> \ + --set trento-web.saml.signRequests=<SAML_SIGN_REQUESTS> \ + --set trento-web.saml.signMetadata=<SAML_SIGN_METADATA> \ + --set trento-web.saml.signedAssertion=<SAML_SIGNED_ASSERTION> \ + --set trento-web.saml.signedEnvelopes=<SAML_SIGNED_ENVELOPES> From be5095ef46111e960fd5f00737195bc6cabd9c47 Mon Sep 17 00:00:00 2001 From: Alberto Bravo Date: Mon, 21 Oct 2024 12:22:21 +0200 Subject: [PATCH 10/20] Update sso-integration.md --- trento/migration/sso-integration.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/trento/migration/sso-integration.md b/trento/migration/sso-integration.md index 83fcb794..a0fd97de 100644 --- a/trento/migration/sso-integration.md +++ b/trento/migration/sso-integration.md @@ -41,7 +41,7 @@ To enable OIDC when using kubernetes deployment with helm, proceed as follows: ``` HELM_EXPERIMENTAL_OCI=1 helm ... \ --set trento-web.oidc.enabled=true \ - --set trento-web.oidc.cliendId= \ + --set trento-web.oidc.clientId= \ --set trento-web.oidc.clientSecret= \ --set trento-web.oidc.baseUrl= ``` @@ -534,4 +534,4 @@ SAML_SIGNED_ASSERTION SAML_SIGNED_ENVELOPES -: Require to receive SAML envelopes signed from the IDP. Set to false if the IDP doesn't sign the envelopes (default value: `true`) \ No newline at end of file +: Require to receive SAML envelopes signed from the IDP. Set to false if the IDP doesn't sign the envelopes (default value: `true`) From ed5c179a5e23c4982348e56a9b1b4c6fe4a1982b Mon Sep 17 00:00:00 2001 From: Alberto Bravo Date: Mon, 21 Oct 2024 12:23:07 +0200 Subject: [PATCH 11/20] Update sso-integration.xml --- trento/xml/sso-integration.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/trento/xml/sso-integration.xml b/trento/xml/sso-integration.xml index 3c5bbdea..2417322b 100644 --- a/trento/xml/sso-integration.xml +++ b/trento/xml/sso-integration.xml @@ -77,7 +77,7 @@ HELM_EXPERIMENTAL_OCI=1 helm ... \ --set trento-web.oidc.enabled=true \ - --set trento-web.oidc.cliendId=<OIDC_CLIENT_ID> \ + --set trento-web.oidc.clientId=<OIDC_CLIENT_ID> \ --set trento-web.oidc.clientSecret=<OIDC_CLIENT_SECRET> \ --set trento-web.oidc.baseUrl=<OIDC_BASE_URL> From 69441b6b7f106138237bca418ba7544d32e6d7a2 Mon Sep 17 00:00:00 2001 From: Alberto Bravo Date: Mon, 21 Oct 2024 15:00:13 +0200 Subject: [PATCH 12/20] Update sso-integration.md --- trento/migration/sso-integration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/trento/migration/sso-integration.md b/trento/migration/sso-integration.md index a0fd97de..d1513f80 100644 --- a/trento/migration/sso-integration.md +++ b/trento/migration/sso-integration.md @@ -136,7 +136,7 @@ To enable OAuth 2.0 when using kubernetes deployment with helm, proceed as follo ``` HELM_EXPERIMENTAL_OCI=1 helm ... \ --set trento-web.oauth2.enabled=true \ - --set trento-web.oauth2.cliendId= \ + --set trento-web.oauth2.clientId= \ --set trento-web.ouath2.clientSecret= \ --set trento-web.oauth2.baseUrl= \ --set trento-web.oauth2.authorizeUrl= \ From 92b5ad69fc66dab97bf338e07fbd8bee22d38591 Mon Sep 17 00:00:00 2001 From: Alberto Bravo Date: Mon, 21 Oct 2024 15:00:42 +0200 Subject: [PATCH 13/20] Update sso-integration.xml --- trento/xml/sso-integration.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/trento/xml/sso-integration.xml b/trento/xml/sso-integration.xml index 2417322b..92f4e6e3 100644 --- a/trento/xml/sso-integration.xml +++ b/trento/xml/sso-integration.xml @@ -238,7 +238,7 @@ docker run -d \ HELM_EXPERIMENTAL_OCI=1 helm ... \ --set trento-web.oauth2.enabled=true \ - --set trento-web.oauth2.cliendId=<OAUTH2_CLIENT_ID> \ + --set trento-web.oauth2.clientId=<OAUTH2_CLIENT_ID> \ --set trento-web.ouath2.clientSecret=<OAUTH2_CLIENT_SECRET> \ --set trento-web.oauth2.baseUrl=<OAUTH2_BASE_URL> \ --set trento-web.oauth2.authorizeUrl=<OAUTH2_AUTHORIZE_URL> \ From 72893d0cbce31d49fe3fcb490527e684ec56e043 Mon Sep 17 00:00:00 2001 From: arbulu89 Date: Mon, 21 Oct 2024 18:09:58 +0200 Subject: [PATCH 14/20] Fix and improve certs usage in SAML configuration chapter --- trento/migration/sso-integration.md | 47 ++++---------- trento/xml/sso-integration.xml | 99 ++++++++++------------------- 2 files changed, 46 insertions(+), 100 deletions(-) diff --git a/trento/migration/sso-integration.md b/trento/migration/sso-integration.md index d1513f80..7ef09bd7 100644 --- a/trento/migration/sso-integration.md +++ b/trento/migration/sso-integration.md @@ -25,7 +25,6 @@ During the installation process, a default admin user is defined using the `ADMI User permissions are entirely managed by Trento, they are not imported from the IDP. The abilities must be granted by some user with `all:all` or `all:users` abilities (admin user initially). This means that only basic user information is retrieved from the external IDP. - ## Using OpenID Connect Trento integrates with an IDP that uses the OIDC protocol to authenticate users accessing the Trento web console. @@ -249,21 +248,29 @@ If the IDP signs the messages, and expect signed messages back, certificates use To use an existing SAML IDP, follow the next instrunctions to met the specific requirements. You need: +1. Obtaining metadata content from the IDP 1. Start Trento to generate the certificates and get them 1. Provide the generated certificate to the IDP 1. Configure SAML IDP and user profiles -1. Restart Trento See the following subsections for details. +### Obtaining metadata content from the IDP + +The metadata.xml file defines the agreement between SP and IDP during SAML communications. It is used to identify the SAML client as well. The content of this file must be provided to Trento. Options and are available for that. + +If the option is being used, the content of this variable must be updated with the IDP metadata as single line string. On the other hand, if is used, the new metadata is automatically fetched when Trento starts. If neither of these steps are completed, communication will fail because the message signatures will not be recognized. + +If the used IDP has the endpoint to provide the metadata.xml file content, prefer the variable . Trento will automatically fetch metadata when started. + ### Getting certificates from Trento -Trento provides a certificates set created during the installation. Regardless of the installation mode, when Trento is installed the first time the certificates are created and the public certificate file content is available in the http://localhost:4000/api/public_keys route. +Trento provides a certificates set created during the installation. Regardless of the installation mode, when Trento is installed the first time the certificates are created and the public certificate file content is available in the https://#{TRENTO_WEB_ORIGIN}/api/public_keys route. Use the following command to get the certificate content: ```bash -curl http://localhost:4000/api/public_keys +curl https://#{TRENTO_WEB_ORIGIN}/api/public_keys ``` Copy the content of the certificate from there and provide it to the IDP. This way, the IDP will sign its messages and verify the messages received from Trento. @@ -274,7 +281,7 @@ Configure the existing IDP with the next minimum options to be able to connect w #### Providing certificates -As commented previously, a set of certificates is needed to enable signed communication. Provide the certificate generated by Trento to the IDP (each IDP has a different way to do this). Make sure that the provided certificate is available in the SAML metadata.xml file and has preference over other uploaded certificates. +As commented previously, a set of certificates is needed to enable signed communication. Provide the certificate generated by Trento to the IDP (each IDP has a different way to do this). Make sure that the configured certificate is used for signing and encrptying messages. #### Configuring SAML user profile @@ -292,36 +299,6 @@ Both IDP and Trento must know how these 4 fields are mapped. To do this, follow After a successful login, the IDP redirects the user's session back to Trento and redirected at https://trento.example.com/sso/sp/consume/saml. To ensure seamless SSO, this URI must be configured as valid within the IDP. -### Restarting Trento - -Once the certificate is provided to the IDP, the IDP recreates its own metadata.xml file. This file defines which certificate is used to sign the messages by both sides. At this point, Trento Web must be restarted to use the new metadata.xml content. - -If the option is being used, the content of this variable must be updated with the new metadata as single line string. On the other hand, if is used, the new metadata is automatically fetched. If neither of these steps are completed, communication will fail because the message signatures will not be recognized. - -If the used IDP has the endpoint to provide the metadata.xml file content, prefer the variable . Trento will automatically fetch metadata when restarted. - -```{=docbook} - - This restart must be done manually, by the admin. - -``` - -Follow the next instructions to restart with the configured options: - -1. Open the file /etc/trento/trento-web. -1. Add the following environment variables to this file. - Required variables are: - - ``` - # Other SAML options - SAML_METADATA_URL= - # Or - SAML_METDATA_CONTENT= - ``` - -1. Restart the application. - - ### Enabling SAML when using kubernetes deployment To enable SAML when using kubernetes deployment with helm, proceed as follows: diff --git a/trento/xml/sso-integration.xml b/trento/xml/sso-integration.xml index 92f4e6e3..f559f909 100644 --- a/trento/xml/sso-integration.xml +++ b/trento/xml/sso-integration.xml @@ -438,28 +438,54 @@ docker run -d \ - Start Trento to generate the certificates and get them + Obtaining metadata content from the IDP - Provide the generated certificate to the IDP + Start Trento to generate the certificates and get them - Configure SAML IDP and user profiles + Provide the generated certificate to the IDP - Restart Trento + Configure SAML IDP and user profiles See the following subsections for details. +
+ Obtaining metadata content from the IDP + + The metadata.xml file defines the agreement + between SP and IDP during SAML communications. It is used to + identify the SAML client as well. The content of this file must + be provided to Trento. Options + and + are available for that. + + + If the option is being + used, the content of this variable must be updated with the IDP + metadata as single line string. On the other hand, if + is used, the new metadata is + automatically fetched when Trento starts. If neither of these + steps are completed, communication will fail because the message + signatures will not be recognized. + + + If the used IDP has the endpoint to provide the + metadata.xml file content, prefer the + variable . Trento will + automatically fetch metadata when started. + +
Getting certificates from Trento @@ -467,13 +493,13 @@ docker run -d \ installation. Regardless of the installation mode, when Trento is installed the first time the certificates are created and the public certificate file content is available in the - http://localhost:4000/api/public_keys route. + https://#{TRENTO_WEB_ORIGIN}/api/public_keys route. Use the following command to get the certificate content: -curl http://localhost:4000/api/public_keys +curl https://#{TRENTO_WEB_ORIGIN}/api/public_keys Copy the content of the certificate from there and provide it to @@ -493,9 +519,8 @@ curl http://localhost:4000/api/public_keys As commented previously, a set of certificates is needed to enable signed communication. Provide the certificate generated by Trento to the IDP (each IDP has a different way to do - this). Make sure that the provided certificate is available in - the SAML metadata.xml file and has - preference over other uploaded certificates. + this). Make sure that the configured certificate is used for + signing and encrptying messages.
@@ -557,62 +582,6 @@ curl http://localhost:4000/api/public_keys
-
- Restarting Trento - - Once the certificate is provided to the IDP, the IDP recreates - its own metadata.xml file. This file - defines which certificate is used to sign the messages by both - sides. At this point, Trento Web must be restarted to use the - new metadata.xml content. - - - If the option is being - used, the content of this variable must be updated with the new - metadata as single line string. On the other hand, if - is used, the new metadata is - automatically fetched. If neither of these steps are completed, - communication will fail because the message signatures will not - be recognized. - - - If the used IDP has the endpoint to provide the - metadata.xml file content, prefer the - variable . Trento will - automatically fetch metadata when restarted. - - - This restart must be done manually, by the admin. - - - Follow the next instructions to restart with the configured - options: - - - - - Open the file /etc/trento/trento-web. - - - - - Add the following environment variables to this file. - Required variables are: - - -# Other SAML options -SAML_METADATA_URL=<SAML_METADATA_URL> -# Or -SAML_METDATA_CONTENT=<SAML_METADATA_CONTENT> - - - - - Restart the application. - - - -
Enabling SAML when using kubernetes deployment From a295fd45f1f6ee10deeab5d7ecaa703329341b58 Mon Sep 17 00:00:00 2001 From: arbulu89 Date: Wed, 23 Oct 2024 08:46:18 +0200 Subject: [PATCH 15/20] Fix typo in oauth2 helm deployment command --- trento/migration/sso-integration.md | 2 +- trento/xml/sso-integration.xml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/trento/migration/sso-integration.md b/trento/migration/sso-integration.md index 7ef09bd7..91014969 100644 --- a/trento/migration/sso-integration.md +++ b/trento/migration/sso-integration.md @@ -136,7 +136,7 @@ To enable OAuth 2.0 when using kubernetes deployment with helm, proceed as follo HELM_EXPERIMENTAL_OCI=1 helm ... \ --set trento-web.oauth2.enabled=true \ --set trento-web.oauth2.clientId= \ - --set trento-web.ouath2.clientSecret= \ + --set trento-web.oauth2.clientSecret= \ --set trento-web.oauth2.baseUrl= \ --set trento-web.oauth2.authorizeUrl= \ --set trento-web.oauth2.tokenUrl= \ diff --git a/trento/xml/sso-integration.xml b/trento/xml/sso-integration.xml index f559f909..c911526d 100644 --- a/trento/xml/sso-integration.xml +++ b/trento/xml/sso-integration.xml @@ -239,7 +239,7 @@ docker run -d \ HELM_EXPERIMENTAL_OCI=1 helm ... \ --set trento-web.oauth2.enabled=true \ --set trento-web.oauth2.clientId=<OAUTH2_CLIENT_ID> \ - --set trento-web.ouath2.clientSecret=<OAUTH2_CLIENT_SECRET> \ + --set trento-web.oauth2.clientSecret=<OAUTH2_CLIENT_SECRET> \ --set trento-web.oauth2.baseUrl=<OAUTH2_BASE_URL> \ --set trento-web.oauth2.authorizeUrl=<OAUTH2_AUTHORIZE_URL> \ --set trento-web.oauth2.tokenUrl=<OAUTH2_TOKEN_URL> \ From a39d28f7bd14996f7fd606dfb4952be2ab8d1f6b Mon Sep 17 00:00:00 2001 From: arbulu89 Date: Wed, 23 Oct 2024 09:23:31 +0200 Subject: [PATCH 16/20] Fix encrypting typo --- trento/migration/sso-integration.md | 2 +- trento/xml/sso-integration.xml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/trento/migration/sso-integration.md b/trento/migration/sso-integration.md index 91014969..5bcaa277 100644 --- a/trento/migration/sso-integration.md +++ b/trento/migration/sso-integration.md @@ -281,7 +281,7 @@ Configure the existing IDP with the next minimum options to be able to connect w #### Providing certificates -As commented previously, a set of certificates is needed to enable signed communication. Provide the certificate generated by Trento to the IDP (each IDP has a different way to do this). Make sure that the configured certificate is used for signing and encrptying messages. +As commented previously, a set of certificates is needed to enable signed communication. Provide the certificate generated by Trento to the IDP (each IDP has a different way to do this). Make sure that the configured certificate is used for signing and encrypting messages. #### Configuring SAML user profile diff --git a/trento/xml/sso-integration.xml b/trento/xml/sso-integration.xml index c911526d..46e9dd59 100644 --- a/trento/xml/sso-integration.xml +++ b/trento/xml/sso-integration.xml @@ -520,7 +520,7 @@ curl https://#{TRENTO_WEB_ORIGIN}/api/public_keys enable signed communication. Provide the certificate generated by Trento to the IDP (each IDP has a different way to do this). Make sure that the configured certificate is used for - signing and encrptying messages. + signing and encrypting messages.
From 6a4ae341f85e244925b082a7d28e3bb67edda39e Mon Sep 17 00:00:00 2001 From: arbulu89 Date: Thu, 24 Oct 2024 09:57:32 +0200 Subject: [PATCH 17/20] Add note to explain saml must be enabled to get certs --- trento/migration/sso-integration.md | 12 +++++++++--- trento/xml/sso-integration.xml | 15 ++++++++++----- 2 files changed, 19 insertions(+), 8 deletions(-) diff --git a/trento/migration/sso-integration.md b/trento/migration/sso-integration.md index 5bcaa277..92069ca4 100644 --- a/trento/migration/sso-integration.md +++ b/trento/migration/sso-integration.md @@ -248,8 +248,8 @@ If the IDP signs the messages, and expect signed messages back, certificates use To use an existing SAML IDP, follow the next instrunctions to met the specific requirements. You need: -1. Obtaining metadata content from the IDP -1. Start Trento to generate the certificates and get them +1. Obtain metadata content from the IDP +1. Start Trento to generate the certificates and get them (SAML must be enabled for this) 1. Provide the generated certificate to the IDP 1. Configure SAML IDP and user profiles @@ -265,7 +265,7 @@ If the used IDP has the endpoint to provide the metadata.xmlhttps://#{TRENTO_WEB_ORIGIN}/api/public_keys route. +Trento provides a certificates set created during the installation. Regardless of the installation mode, when Trento is installed the first time and SAML is enabled the certificates are created and the public certificate file content is available in the https://#{TRENTO_WEB_ORIGIN}/api/public_keys route. Use the following command to get the certificate content: @@ -275,6 +275,12 @@ curl https://#{TRENTO_WEB_ORIGIN}/api/public_keys Copy the content of the certificate from there and provide it to the IDP. This way, the IDP will sign its messages and verify the messages received from Trento. +```{=docbook} + + To get the certificate using this route Trento must be configured to start with SAML enabled. + +``` + ### Configuring SAML IDP setup Configure the existing IDP with the next minimum options to be able to connect with Trento as a Service Provider (SP). diff --git a/trento/xml/sso-integration.xml b/trento/xml/sso-integration.xml index 46e9dd59..b1f34f62 100644 --- a/trento/xml/sso-integration.xml +++ b/trento/xml/sso-integration.xml @@ -438,12 +438,13 @@ docker run -d \ - Obtaining metadata content from the IDP + Obtain metadata content from the IDP - Start Trento to generate the certificates and get them + Start Trento to generate the certificates and get them (SAML + must be enabled for this) @@ -491,9 +492,10 @@ docker run -d \ Trento provides a certificates set created during the installation. Regardless of the installation mode, when Trento - is installed the first time the certificates are created and the - public certificate file content is available in the - https://#{TRENTO_WEB_ORIGIN}/api/public_keys route. + is installed the first time and SAML is enabled the certificates + are created and the public certificate file content is available + in the https://#{TRENTO_WEB_ORIGIN}/api/public_keys + route. Use the following command to get the certificate content: @@ -506,6 +508,9 @@ curl https://#{TRENTO_WEB_ORIGIN}/api/public_keys the IDP. This way, the IDP will sign its messages and verify the messages received from Trento. + + To get the certificate using this route Trento must be configured to start with SAML enabled. +
Configuring SAML IDP setup From c801d1a47056c912b4fbf8333436ba66e5540608 Mon Sep 17 00:00:00 2001 From: arbulu89 Date: Thu, 24 Oct 2024 10:06:29 +0200 Subject: [PATCH 18/20] Explain how to restart docker deployments --- trento/migration/sso-integration.md | 23 +++++++++++++++-- trento/xml/sso-integration.xml | 38 +++++++++++++++++++++++++---- 2 files changed, 54 insertions(+), 7 deletions(-) diff --git a/trento/migration/sso-integration.md b/trento/migration/sso-integration.md index 92069ca4..49367e3b 100644 --- a/trento/migration/sso-integration.md +++ b/trento/migration/sso-integration.md @@ -74,6 +74,13 @@ To enable OIDC when using RPM packages, proceed as follows: To enable OIDC when using Docker images, proceed as follows: +1. If `trento-web` container is already running stop and delete the container before continuing. For that run: + + ```bash + docker stop trento-web + docker rm trento-web + ``` + 1. Provide the following environment variables to the Docker container via the `-e` option: @@ -98,8 +105,6 @@ To enable OIDC when using Docker images, proceed as follows: ...[other settings]... ``` -1. Restart the application. - ### Available variables for OpenID Connect @@ -177,6 +182,13 @@ To enable OAuth 2.0 when using RPM packages, proceed as follows: To enable OAuth 2.0 when using Docker images, proceed as follows: +1. If `trento-web` container is already running stop and delete the container before continuing. For that run: + + ```bash + docker stop trento-web + docker rm trento-web + ``` + 1. Use the following environment variables to the Docker container via the `-e` option: @@ -398,6 +410,13 @@ To enable SAML when using RPM packages, proceed as follows: To enable SAML when using Docker images, proceed as follows: +1. If `trento-web` container is already running stop and delete the container before continuing. For that run: + + ```bash + docker stop trento-web + docker rm trento-web + ``` + 1. Use the following environment variables to the Docker container via the `-e` option: ```bash diff --git a/trento/xml/sso-integration.xml b/trento/xml/sso-integration.xml index b1f34f62..3481f118 100644 --- a/trento/xml/sso-integration.xml +++ b/trento/xml/sso-integration.xml @@ -132,6 +132,17 @@ OIDC_CALLBACK_URL=<OIDC_CALLBACK_URL> To enable OIDC when using Docker images, proceed as follows: + + + If trento-web container is already + running stop and delete the container before continuing. For + that run: + + +docker stop trento-web +docker rm trento-web + + Provide the following environment variables to the Docker @@ -158,11 +169,6 @@ docker run -d \ ...[other settings]... - - - Restart the application. - -
@@ -294,6 +300,17 @@ OAUTH2_CALLBACK_URL=<OAUTH2_CALLBACK_URL> follows: + + + If trento-web container is already + running stop and delete the container before continuing. For + that run: + + +docker stop trento-web +docker rm trento-web + + Use the following environment variables to the Docker @@ -703,6 +720,17 @@ SAML_SIGNED_ENVELOPES=<SAML_SIGNED_ENVELOPES> To enable SAML when using Docker images, proceed as follows: + + + If trento-web container is already + running stop and delete the container before continuing. For + that run: + + +docker stop trento-web +docker rm trento-web + + Use the following environment variables to the Docker From eb4814046b484c7cac679debae036ee557f064f5 Mon Sep 17 00:00:00 2001 From: arbulu89 Date: Thu, 24 Oct 2024 10:31:12 +0200 Subject: [PATCH 19/20] Change SAML_SP_DIR default location --- trento/migration/sso-integration.md | 2 +- trento/xml/sso-integration.xml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/trento/migration/sso-integration.md b/trento/migration/sso-integration.md index 49367e3b..1cfde5a6 100644 --- a/trento/migration/sso-integration.md +++ b/trento/migration/sso-integration.md @@ -480,7 +480,7 @@ SAML_IDP_NAMEID_FORMAT SAML_SP_DIR -: SAML SP directory, where SP specific required files (such as certificates and metadata file) are placed (default value: /etc/trento/trento-web/saml) +: SAML SP directory, where SP specific required files (such as certificates and metadata file) are placed (default value: /etc/trento/saml) SAML_SP_ENTITY_ID diff --git a/trento/xml/sso-integration.xml b/trento/xml/sso-integration.xml index 3481f118..b52da620 100644 --- a/trento/xml/sso-integration.xml +++ b/trento/xml/sso-integration.xml @@ -842,7 +842,7 @@ docker run -d \ SAML SP directory, where SP specific required files (such as certificates and metadata file) are placed (default - value: /etc/trento/trento-web/saml) + value: /etc/trento/saml) From cae9576847dffe734194a782aed4ade19a049be1 Mon Sep 17 00:00:00 2001 From: arbulu89 Date: Mon, 4 Nov 2024 09:33:42 +0100 Subject: [PATCH 20/20] Add more corrections and format optional vars usage --- trento/migration/sso-integration.md | 21 ++++++++++----------- trento/xml/sso-integration.xml | 20 +++++++++++--------- 2 files changed, 21 insertions(+), 20 deletions(-) diff --git a/trento/migration/sso-integration.md b/trento/migration/sso-integration.md index 1cfde5a6..97251de8 100644 --- a/trento/migration/sso-integration.md +++ b/trento/migration/sso-integration.md @@ -145,12 +145,15 @@ To enable OAuth 2.0 when using kubernetes deployment with helm, proceed as follo --set trento-web.oauth2.baseUrl= \ --set trento-web.oauth2.authorizeUrl= \ --set trento-web.oauth2.tokenUrl= \ - --set trento-web.oauth2.userUrl= \ - --set trento-web.oauth2.scopes= + --set trento-web.oauth2.userUrl= ``` - variable is optional with `profile email` as default value. + Additionally, the following optional values are available: + ``` + HELM_EXPERIMENTAL_OCI=1 helm ... \ + --set trento-web.oauth2.scopes= + ``` ### Enabling OAuth 2.0 when using RPM packages @@ -244,7 +247,7 @@ OAUTH2_USER_URL OAUTH2_SCOPES -: OAUTH2 scopes, used to define the user values sent to the SP. It must be adjusted depending on IDP provider requirements (default value: `openid profile email`) +: OAUTH2 scopes, used to define the user values sent to the SP. It must be adjusted depending on IDP provider requirements (default value: `profile email`) OAUTH2_CALLBACK_URL @@ -269,9 +272,9 @@ See the following subsections for details. ### Obtaining metadata content from the IDP -The metadata.xml file defines the agreement between SP and IDP during SAML communications. It is used to identify the SAML client as well. The content of this file must be provided to Trento. Options and are available for that. +The metadata.xml file defines the agreement between SP and IDP during SAML communications. It is used to identify the SAML client as well. The content of this file must be provided to Trento. Options and are available for that. -If the option is being used, the content of this variable must be updated with the IDP metadata as single line string. On the other hand, if is used, the new metadata is automatically fetched when Trento starts. If neither of these steps are completed, communication will fail because the message signatures will not be recognized. +If the option is being used, the content of this variable must be updated with the IDP metadata as single line string. On the other hand, if is used, the new metadata is automatically fetched when Trento starts. If neither of these steps are completed, communication will fail because the message signatures will not be recognized. If the used IDP has the endpoint to provide the metadata.xml file content, prefer the variable . Trento will automatically fetch metadata when started. @@ -331,7 +334,7 @@ To enable SAML when using kubernetes deployment with helm, proceed as follows: --set trento-web.saml.metadataUrl= ``` - To use the option rather than use: + To use the option rather than use: ``` HELM_EXPERIMENTAL_OCI=1 helm ... \ @@ -345,10 +348,6 @@ To enable SAML when using kubernetes deployment with helm, proceed as follows: ``` HELM_EXPERIMENTAL_OCI=1 helm ... \ - --set trento-web.saml.enabled=true \ - --set trento-web.saml.idpId= \ - --set trento-web.saml.spId= \ - --set trento-web.saml.metadataUrl= \ --set trento-web.saml.idpNameIdFormat= \ --set trento-web.saml.spDir= \ --set trento-web.saml.spEntityId= \ diff --git a/trento/xml/sso-integration.xml b/trento/xml/sso-integration.xml index b52da620..4256ae41 100644 --- a/trento/xml/sso-integration.xml +++ b/trento/xml/sso-integration.xml @@ -249,7 +249,13 @@ HELM_EXPERIMENTAL_OCI=1 helm ... \ --set trento-web.oauth2.baseUrl=<OAUTH2_BASE_URL> \ --set trento-web.oauth2.authorizeUrl=<OAUTH2_AUTHORIZE_URL> \ --set trento-web.oauth2.tokenUrl=<OAUTH2_TOKEN_URL> \ - --set trento-web.oauth2.userUrl=<OAUTH2_USER_URL> \ + --set trento-web.oauth2.userUrl=<OAUTH2_USER_URL> + + + Additionally, the following optional values are available: + + +HELM_EXPERIMENTAL_OCI=1 helm ... \ --set trento-web.oauth2.scopes=<OAUTH2_SCOPES> @@ -414,7 +420,7 @@ docker run -d \ OAUTH2 scopes, used to define the user values sent to the SP. It must be adjusted depending on IDP provider requirements (default value: - openid profile email) + profile email) @@ -486,10 +492,10 @@ docker run -d \ identify the SAML client as well. The content of this file must be provided to Trento. Options and - are available for that. + are available for that. - If the option is being + If the option is being used, the content of this variable must be updated with the IDP metadata as single line string. On the other hand, if is used, the new metadata is @@ -624,7 +630,7 @@ HELM_EXPERIMENTAL_OCI=1 helm ... \ --set trento-web.saml.metadataUrl=<SAML_METADATA_URL> - To use the option + To use the option rather than use: @@ -639,10 +645,6 @@ HELM_EXPERIMENTAL_OCI=1 helm ... \ HELM_EXPERIMENTAL_OCI=1 helm ... \ - --set trento-web.saml.enabled=true \ - --set trento-web.saml.idpId=<SAML_IDP_ID> \ - --set trento-web.saml.spId=<SAML_SP_ID> \ - --set trento-web.saml.metadataUrl=<SAML_METADATA_URL> \ --set trento-web.saml.idpNameIdFormat=<SAML_IDP_NAMEID_FORMAT> \ --set trento-web.saml.spDir=<SAML_SP_DIR> \ --set trento-web.saml.spEntityId=<SAML_SP_ENTITY_ID> \