diff --git a/docs/docs/admin/authentication/index.md b/docs/docs/admin/authentication/index.md new file mode 100644 index 000000000..c2c7c88aa --- /dev/null +++ b/docs/docs/admin/authentication/index.md @@ -0,0 +1,28 @@ + + +# Authentication Methods + +!!! info + + If you want to authenticate against the API using a personal access token, + please refer to the [API documentation](../../api/index.md#authentication). + +The Capella Collaboration Manager is developed to work together with OpenID +Connect (OIDC) compliant identity providers. Since we don't support any other +authentication methods, it is required to have an OIDC compliant identity +provider to use the Capella Collaboration Manager. + +The authentication has to be configured in the `backend.authentication` section +of the `values.yaml`. + +If no running OpenID Connect server is available in your environment, you can +set up Keycloak as an intermediate identity provider. +[Keycloak](https://www.keycloak.org/) is an open-source identity and access +management solution that supports many common protocols like OAuth 2.0, SAML +2.0, LDAP, and others. + +Learn more about how to integrate the Capella Collaboration Manager in Keycloak +[here](./keycloak/index.md). diff --git a/docs/docs/admin/authentication/keycloak/create-client-1.png b/docs/docs/admin/authentication/keycloak/create-client-1.png new file mode 100644 index 000000000..4e3dcf626 Binary files /dev/null and b/docs/docs/admin/authentication/keycloak/create-client-1.png differ diff --git a/docs/docs/admin/authentication/keycloak/create-client-1.png.license b/docs/docs/admin/authentication/keycloak/create-client-1.png.license new file mode 100644 index 000000000..7ea22469b --- /dev/null +++ b/docs/docs/admin/authentication/keycloak/create-client-1.png.license @@ -0,0 +1,2 @@ +SPDX-FileCopyrightText: Copyright DB InfraGO AG and contributors +SPDX-License-Identifier: Apache-2.0 diff --git a/docs/docs/admin/authentication/keycloak/create-client-2.png b/docs/docs/admin/authentication/keycloak/create-client-2.png new file mode 100644 index 000000000..b37a95279 Binary files /dev/null and b/docs/docs/admin/authentication/keycloak/create-client-2.png differ diff --git a/docs/docs/admin/authentication/keycloak/create-client-2.png.license b/docs/docs/admin/authentication/keycloak/create-client-2.png.license new file mode 100644 index 000000000..7ea22469b --- /dev/null +++ b/docs/docs/admin/authentication/keycloak/create-client-2.png.license @@ -0,0 +1,2 @@ +SPDX-FileCopyrightText: Copyright DB InfraGO AG and contributors +SPDX-License-Identifier: Apache-2.0 diff --git a/docs/docs/admin/authentication/keycloak/create-client-3.png b/docs/docs/admin/authentication/keycloak/create-client-3.png new file mode 100644 index 000000000..7d1eeefba Binary files /dev/null and b/docs/docs/admin/authentication/keycloak/create-client-3.png differ diff --git a/docs/docs/admin/authentication/keycloak/create-client-3.png.license b/docs/docs/admin/authentication/keycloak/create-client-3.png.license new file mode 100644 index 000000000..7ea22469b --- /dev/null +++ b/docs/docs/admin/authentication/keycloak/create-client-3.png.license @@ -0,0 +1,2 @@ +SPDX-FileCopyrightText: Copyright DB InfraGO AG and contributors +SPDX-License-Identifier: Apache-2.0 diff --git a/docs/docs/admin/authentication/keycloak/create-client-4.png b/docs/docs/admin/authentication/keycloak/create-client-4.png new file mode 100644 index 000000000..354e94154 Binary files /dev/null and b/docs/docs/admin/authentication/keycloak/create-client-4.png differ diff --git a/docs/docs/admin/authentication/keycloak/create-client-4.png.license b/docs/docs/admin/authentication/keycloak/create-client-4.png.license new file mode 100644 index 000000000..7ea22469b --- /dev/null +++ b/docs/docs/admin/authentication/keycloak/create-client-4.png.license @@ -0,0 +1,2 @@ +SPDX-FileCopyrightText: Copyright DB InfraGO AG and contributors +SPDX-License-Identifier: Apache-2.0 diff --git a/docs/docs/admin/authentication/keycloak/create-client.license b/docs/docs/admin/authentication/keycloak/create-client.license new file mode 100644 index 000000000..7ea22469b --- /dev/null +++ b/docs/docs/admin/authentication/keycloak/create-client.license @@ -0,0 +1,2 @@ +SPDX-FileCopyrightText: Copyright DB InfraGO AG and contributors +SPDX-License-Identifier: Apache-2.0 diff --git a/docs/docs/admin/authentication/keycloak/create-client.png b/docs/docs/admin/authentication/keycloak/create-client.png new file mode 100644 index 000000000..8af6fc3a1 Binary files /dev/null and b/docs/docs/admin/authentication/keycloak/create-client.png differ diff --git a/docs/docs/admin/authentication/keycloak/create-client.png.license b/docs/docs/admin/authentication/keycloak/create-client.png.license new file mode 100644 index 000000000..7ea22469b --- /dev/null +++ b/docs/docs/admin/authentication/keycloak/create-client.png.license @@ -0,0 +1,2 @@ +SPDX-FileCopyrightText: Copyright DB InfraGO AG and contributors +SPDX-License-Identifier: Apache-2.0 diff --git a/docs/docs/admin/authentication/keycloak/index.md b/docs/docs/admin/authentication/keycloak/index.md new file mode 100644 index 000000000..8e4067719 --- /dev/null +++ b/docs/docs/admin/authentication/keycloak/index.md @@ -0,0 +1,109 @@ + + +# Keycloak as Identity Provider + +This guide will help you set up [Keycloak](https://www.keycloak.org/) as an +identity provider for the _Capella Collaboration Manager (CCM)_. It focuses on +setting up the connection between Keycloak and CCM. The setup of the connection +between Keycloak and your identity provider is not covered. + +## Install Keycloak + +If you don't already have a running Keycloak server, please follow the +installation instructions in +[Keycloak - Getting Started](https://www.keycloak.org/guides#getting-started). + +After this step, you should have access to the Keycloak admin console, which is +required for the following steps. + +## Register the CCM Client in Keycloak + +1. Below **Manage** click on **Clients** and then **Create client**:
+ ![Create client](./create-client.png) +1. In **General settings** set the values as follows: + + | Key | Value | + | ----------------------- | ---------------------------------------------------------------------- | + | **Client type** | OpenID Connect | + | **Client ID** | capella-collaboration-manager | + | **Name** | Capella Collaboration Manager | + | **Description** | Client used to authenticate users in the Capella Collaboration Manager | + | **Allow display in UI** | Personal preference | + + ![Create client - Step 1](./create-client-1.png) + +1. In **Capability config** modify the the default values as follows: + + 1. Enable **Client Authentication** + 1. Disable **Direct access grants** + + ![Create client - Step 2](./create-client-2.png) + +1. In **Login settings** set the values as follows: + + | Key | Value | Example value
(development environment) | + | ------------------------------------------------------- | --------------------------------------------------------- | -------------------------------------------- | + | **Root URL** +
**Home URL** +
**Web origins** | `{scheme}://{host}:{port}`
(URL of the CCM frontend) | `http://localhost:4200` | + | **Valid redirect URIs** | `{scheme}://{host}:{port}/oauth2/callback` | `http://localhost:4200/oauth2/callback` | + | **Valid post logout redirect URIs** | None | - | + + ![Create client - Step 3](./create-client-3.png) + +1. Click **Save**, which should create the client in Keycloak. +1. Make the email claim optional. It is not required for the CCM. + + 1. In the Clients tab, open the client details of the newly created client + 1. Click on **Client scopes** + 1. For the _email_ scope, change the **Assigned Type** from _Default_ to + **Optional** + + ![Create client - Step 4)](./create-client-4.png) + +## Configure the CCM to use the Keycloak Client + +Update the `values.yaml` and set the following values for the +`backend.authentication` section: + +```yaml +backend: + authentication: + endpoints: + wellKnown: [...]/.well-known/openid-configuration # (1)! + + audience: default + + claimMapping: # (2)! + idpIdentifier: sub + username: preferred_username + email: email + + scopes: + - openid + - profile + - offline_access + + client: + id: capella-collaboration-manager # (3)! + secret: ... # (4)! + + redirectURI: [...]/oauth2/callback # (5)! +``` + +1. To find out the well-known endpoint, click _Realm Settings_ in Keycloak, + scroll down and click _OpenID Endpoint Configuration_, which should open the + configuration in a new tab. The well-known endpoint is the URL of the opened + page. +2. Make sure that the mentioned claims are available in the identity token. You + can evaluate the claims available in the token via Keycloak: Open the client + details, click on the _Client scopes_ tab and navigate to "Evaluate". +3. Set the _client.id_ to the value used when the client was created. If not + changed it should be _capella-collaboration-manager_. +4. To find out the client secret, open the client details in the Keycloak admin + console. Open the _Credentials_ tab and copy the _Client Secret_. Keep this + value confidential and generate a new client secret in case it gets leaked. +5. Set the _redirectURI_ to the CCM base url + _/oauth2/callback_ + +Then redeploy the application using Helm. diff --git a/docs/docs/admin/keycloak.md b/docs/docs/admin/keycloak.md deleted file mode 100644 index 865672c8d..000000000 --- a/docs/docs/admin/keycloak.md +++ /dev/null @@ -1,92 +0,0 @@ - - -# Setup Keycloak as Identity Provider - -This guide will help you set up [Keycloak](https://www.keycloak.org/) as an -identity provider for _Capella Collaboration Manager (CCM)_. However, it is -important to note that this guide only focuses on setting up the connection -between Keycloak and CCM and does not provide detailed information on how to -set up Keycloak for a production environment. - -## Step 1: Install Keycloak - -If you don't have a running Keycloak server, please select and follow the -installation instructions in -[Keycloak - Getting Started](https://www.keycloak.org/guides#getting-started). -We will go through the steps and configurations needed in both Keycloak and the -CCM to use Keycloak as an identity provider, but we still recommend that you -carefully read the Keycloak documentation to properly configure your instance. -After this step, you should have access to the Keycloak admin console, which is -required for the following steps. for the following steps. - -## Step 2: Create a Capella Collaboration Manager Client in Keycloak - -1. Below _Manage_ click on _Clients_ -1. Click on _Create client_ -1. In the first step, the _General settings_ set the values as follows: - 1. _Client type_: OpenID Connect - 1. _Client ID_: capella-collaboration-manager - 1. _Name_: Capella Collaboration Manager - 1. _Description_: Client used to authenticate users to Capella Collaboration - Manager - 1. _Allow display in UI_: Own preference -1. In the second step, the _Capability config_ set the values as follows: - 1. Disable _Direct access grants_ since the CCM should not have access to - the keycloak username or password - 1. Enable _Client Authentication_ because the CCM backend uses the client id - and client secret to exchange the authorization code retrieved by the - user after successful authentication to Keycloak for an identity token. -1. In the third step, the _Login settings_ set the values as follows: - 1. _Root URL_: http://localhost:4200 - 1. _Home URL_: http://localhost:4200 - 1. _Valid redirect URIs_: http://localhost:4200/oauth2/callback - 1. _Valid post logout redirect URIs_: None - 1. _Web origins_: http://localhost:4200 -1. Click _Save_, which should create the client in Keycloak -1. Now we just need to make the email claim optional for now, as it is not - required or used by the CCM, which can be done as follows: - 1. In the Clients tab, click the newly created CCM client - 1. Click on _Client scopes_ - 1. For the _email_ scope, change the _Assigned Type_ from _Default_ to - _Optional_ - -## Step 3: Configure the CCM to use the Keycloak Client - -In the following, we will only consider configurations below _authentication_ -or, in the case of the _values.yaml_ file, below _backend.authentication_, so -we will omit these prefixes. - -1. Configure the CCM configuration: - 1. Set the _jwt.usernameClaim_ to _preferred_username_, which will be the - username used in the CCM. You can set this to another field of the - identity token, but make sure that the field exists and is unique per - user. For example, we could use the user's email address here, which - would require you to set this to _email_ and also add the _email_ scope - below. - 1. Set _endpoints.wellKnown_ to the well-known Keycloak URL, which can be - found as follows - 1. In Keycloak, click _Realm Settings_ - 1. Scroll down and click _OpenID Endpoint Configuration_, which should - open the configuration in a new tab. - 1. The well-known URL is now simply the URL of the page. - 1. Set the _issuer_ to: http://localhost:8085/realms/master, which is - typically the well-known URL without the _/.well-known/..._ part. - 1. Set the _scopes_ to _openid_ and _profile_ - 1. Set the _client.id_ to the value used when the client was created, so if - not changed it should be _capella-collaboration-manager_. - 1. Set the _client.secret_ to the client secret which can be found as - follows: - 1. In Keycloak, click on _Clients_ and then select the CCM client - 1. Click on _Credentials_ (If Credentials is not visible, you have not - enabled _Client Authentication_, which can be done in the General - Settings just below _Capability Config_.) - 1. Here you can now copy the _Client Secret_, but be sure to keep this - value confidential and generate a new client secret in case it gets - leaked. - 1. Set the _redirectURI_ to the CCM base url + _/oauth2/callback_ - -The CCM should then be successfully configured and you can run it to verify -that you can authenticate to it using Keycloak. diff --git a/docs/docs/style.css b/docs/docs/style.css index 4ee080bcc..1f1b23e0a 100644 --- a/docs/docs/style.css +++ b/docs/docs/style.css @@ -6,3 +6,11 @@ html { overflow-y: scroll; } + +.md-typeset__table { + min-width: 100%; +} + +.md-typeset table:not([class]) { + display: table; +} diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index c3e96d15d..2c82a132c 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -74,6 +74,9 @@ nav: - Administrator Documentation: - Introduction: admin/index.md - Installation: admin/installation.md + - Authentication: + - Introduction: admin/authentication/index.md + - Keycloak: admin/authentication/keycloak/index.md - Uninstallation: admin/uninstallation.md - Getting started: admin/getting_started/index.md - Monitoring: