diff --git a/docs/system-admin-guide/authentication/README.md b/docs/system-admin-guide/authentication/README.md index 1a237ed39fd..f1097456fef 100644 --- a/docs/system-admin-guide/authentication/README.md +++ b/docs/system-admin-guide/authentication/README.md @@ -21,4 +21,6 @@ Configure **authentication** settings and authentication providers in OpenProjec | [Two-factor authentication](two-factor-authentication) | Set up and manage two-factor authentication (2FA) in OpenProject. | | [reCAPTCHA](recaptcha) | How to activate reCAPTCHA in OpenProject. | | [LDAP authentication](ldap-connections) | How to set up LDAP authentication in OpenProject. | -| [LDAP group synchronization](ldap-connections/ldap-group-synchronization) | How to configure LDAP group synchronization in OpenProject. (Enterprise add-on) | +| [LDAP group synchronization](ldap-connections/ldap-group-synchronization) | How to configure LDAP group synchronization in OpenProject (Enterprise add-on). | +| [SAML](saml) | How to set up SAML integration for SSO with OpenProject (Enterprise add-on). | +| [SCIM](scim) | How to set up SCIM clients in OpenProject (Enterprise add-on). | diff --git a/docs/system-admin-guide/authentication/ldap-connections/README.md b/docs/system-admin-guide/authentication/ldap-connections/README.md index 84fec7d8373..daeae95d6fb 100644 --- a/docs/system-admin-guide/authentication/ldap-connections/README.md +++ b/docs/system-admin-guide/authentication/ldap-connections/README.md @@ -1,7 +1,7 @@ --- sidebar_navigation: title: LDAP connections - priority: 500 + priority: 600 description: Manage LDAP Authentication in OpenProject. keywords: ldap authentication --- diff --git a/docs/system-admin-guide/authentication/recaptcha/README.md b/docs/system-admin-guide/authentication/recaptcha/README.md index c7516ac75f2..4cd68fa69f8 100644 --- a/docs/system-admin-guide/authentication/recaptcha/README.md +++ b/docs/system-admin-guide/authentication/recaptcha/README.md @@ -1,7 +1,7 @@ --- sidebar_navigation: title: reCAPTCHA - priority: 600 + priority: 300 description: configure reCAPTCHA for OpenProject. keywords: reCAPTCHA, turnstile --- diff --git a/docs/system-admin-guide/authentication/saml/README.md b/docs/system-admin-guide/authentication/saml/README.md index 5b103368bb4..ed54cd6e7dc 100644 --- a/docs/system-admin-guide/authentication/saml/README.md +++ b/docs/system-admin-guide/authentication/saml/README.md @@ -1,7 +1,7 @@ --- sidebar_navigation: title: SAML single sign-on - priority: 100 + priority: 700 description: How to set up SAML integration for SSO with OpenProject. keywords: SAML, SSO, single sign-on, authentication --- diff --git a/docs/system-admin-guide/authentication/scim/README.md b/docs/system-admin-guide/authentication/scim/README.md index beb9312660a..23e9f35e5a7 100644 --- a/docs/system-admin-guide/authentication/scim/README.md +++ b/docs/system-admin-guide/authentication/scim/README.md @@ -1,78 +1,96 @@ --- sidebar_navigation: title: SCIM - priority: 800 -description: SCIM -keywords: SCIM + priority: 500 +description: How to set up SCIM clients in OpenProject +keywords: SCIM, SCIM API, user management, app integration --- # SCIM provisioning (Enterprise add-on) -> [!IMPORTANT] -> SCIM provisioning is an Enterprise add-on. If you do not see the button you will have to activate the Enterprise edition first. +OpenProject supports automated user synchronization via SCIM API, enabling seamless integration with your identity provider. Simplify and secure user provisioning and de-provisioning while ensuring accurate user data across systems. -To activate and configure SCIM user and group provisioning in OpenProject, navigate to *Administration* -> *Authentication* and select -> *SCIM provisioning*. +> [!NOTE] +> SCIM provisioning is an Enterprise add-on. [Click here for more information](https://www.openproject.org/enterprise-edition/) on the OpenProject Enterprise edition. -## Configure new SCIM client. +To activate and configure SCIM user and group provisioning in OpenProject, navigate to *Administration* -> *Authentication* and select *SCIM clients* from the left-hand menu. -SCIM client is a system(e.g. Keycloak with [SCIM plugin](https://github.com/mitodl/keycloak-scim)) that uses SCIM protocol to provision user and group identities in an automated and standardized way. -A SCIM client sends requests to a SCIM server (OpenProject in this case), asking it to create, update, retrieve, or delete users and groups. -To add a new SCIM client, click the green **+ SCIM client** button. +## Configure a new SCIM client. -![Add SCIM client. Index page creation button.](add_scim_1.png) +SCIM client is a system (e.g. Keycloak with [SCIM plugin](https://github.com/mitodl/keycloak-scim)) that uses SCIM protocol to provision user and group identities in an automated and standardized way. -Configure your SCIM client in the following form: +A SCIM client sends requests to a SCIM server (in this case OpenProject), asking it to create, update, retrieve, or delete users and groups. -1. Enter the **Name** of your SCIM client. +To add a new SCIM client, click the **+ SCIM client** button in the upper right corner. - ![Add SCIM client. Creation form. Name field.](add_scim_2.png) -2. Choose an **Authentication provider**. +![A button to add a SCIM client on a SCIM clients index page under authentication settings in OpenProject administration](add_scim_1.png) + +A configuration form for your SCIM client will open, in which you can adjust the SCIM client details. + +### Step 1. Enter the **Name** of your SCIM client. + +![A SCIM client creation form in OpenProject administration, with the Name field highlighted and filled out](add_scim_2.png) + +### Step 2. Choose an **Authentication provider**. This is the service that users added by the SCIM provider will use to authenticate in OpenProject. It must have been configured before creating the SCIM client. It can be an [OIDC provider](../system-admin-guide/authentication/openid-providers/) or a [SAML provider](../system-admin-guide/authentication/saml/). - - ![Add SCIM client. Initial creation form. Authentication provider field.](add_scim_3.png) -3. Choose an **Authentication method**. - This is how the SCIM client authenticates at OpenProject. Please ensure that OAuth tokens include the **scim_v2** scope. - There are three option: - a. **Static access token** - - > [!IMPORTANT] - > Static access tokens are valid for period of 1 year. Then they expire and must be replaced. - This is the most commonly used authentication method for SCIM clients. In this case after clicking **Create** you get an access token that should be put to the SCIM client configuration on the other end. - - ![Add SCIM client. Creation form. Static access token. Generate token. ](add_scim_4.png) + ![A SCIM client creation form in OpenProject administration, with the "Authentication provider" field highlighted and filled out](add_scim_3.png) - There is generated access token. After closing the dialog with generated token you will not see it anymore. - - ![Add SCIM client. Creation form. Static access token. Copy token.](add_scim_5.png) +### Step 3. Choose an **Authentication method**. - Tokens can be revoked. And you can generate a new one. +This is how the SCIM client authenticates at OpenProject. Please ensure that OAuth tokens include the **scim_v2** scope. - ![Add SCIM client. Creation form. Static access token. Revoke token.](add_scim_6.png) +There are three *Authentication method* options you can choose from: - For example, if you use Keycloak with [SCIM plugin](https://github.com/mitodl/keycloak-scim) then configuration form looks like: - - ![Add SCIM client. Keycloak configuration form.](add_scim_10.png) - - 1. Fill in the **UI Display name** - 2. Fill in the **SCIM 2.0 endpoint** - It must be in the following form: `https:///scim_v2/` - 3. Set **Endoint content type** to **application/scim+json** - 4. Set **Auth mode** to **Bearer** - 5. Paste the generated static access token to **Auth password/token** - 6. Enable user and group propagation. Enable import during sync. - 7. **Save** the configuration. +#### a. **Static access token** - b. **OAuth 2.0 client credentials** - In this case after clicking **Create** you get client credentials of newly created [OpenProject OAuth Application](../oauth-applications/#oauth-applications) that should be put to the SCIM client configuration on the other end. Then SCIM client is supposed to use provided client credentials to send an access token request to OpenProject. - - ![Add SCIM client. Creation form. Client credentials. Generate client credentials.](add_scim_7.png) - - There are generated client id and client secret. After closing the dialog with not see client secret anymore. - - ![Add SCIM client. Creation form. Client credentials. Copy client credentials.](add_scim_8.png) - - c. **JWT from identity provider** - In this case you have to specify **Subject claim** that authentication JWT contains. - - ![Add SCIM client. Creation form. JWT from identity provider. Specify Subject claim.](add_scim_9.png) +> [!IMPORTANT] +> Static access tokens are valid for period of 1 year. After that, they expire and must be replaced. + +This is the most commonly used authentication method for SCIM clients. In this case after clicking **Create** you get an access token that should be put to the SCIM client configuration on the other end. + +![A SCIM client creation form in OpenProject administration, with the "Static access token" chosen as the authentication method](add_scim_4.png) + +Once you click the **Create** button, an access token will be generated. The generated token will be displayed in a pop-up dialogue form. Make sure you copy and save it. After closing the dialog, you will not see the client secret again. + +![Add SCIM client. Creation form. Static access token. Copy token.](add_scim_5.png) + + +Once created, a SCIM client will appear on the SCIM clients index page. + +![Scim clients index page listing all created clients under authentication settings in OpenProject administration](openproject_system_administration_authetication_scim_index_page.png) + +Click on the client name to open the detailed view, edit the information, add revoke or add tokens. You will be able to edit the client information and tokens. + +SCIM client tokens can be revoked. To revoke a token click the **Remove** icon at the far right end of the token listing. To add a new token click the **+ Token** button at the bottom of *Tokens* section. + +![Add or revoke static access token on a SCIM client detailed from under administration settings in OpenProject administration](add_scim_6.png) + +Here is an example of a configuration form in Keycloak, if you use it with [SCIM plugin](https://github.com/mitodl/keycloak-scim). + + +![An example of a Keycloak configuration form to add a SCIM client for OpenProject](add_scim_10.png) + +1. Fill in the **UI Display name**. +2. Fill in the **SCIM 2.0 endpoint**. It must be in the following format: `https:///scim_v2/` +3. Set **Endpoint content type** to `application/scim+json` +4. Set **Auth mode** to **Bearer** +5. Paste the generated static access token to **Auth password/token** +6. Enable user and group propagation. Enable import during sync. +7. **Save** the configuration. + +#### b. **OAuth 2.0 client credentials** + +If in [Step 3](#step-3-choose-an-authentication-method) you selected **OAuth 2.0 client credentials**, after clicking **Create** you will get client credentials of newly created [OpenProject OAuth Application](../oauth-applications/#oauth-applications). These credentials should be entered into the SCIM client configuration on the other end. Then SCIM client is supposed to use provided client credentials to send an access token request to OpenProject. + +![Add SCIM client. Creation form. Client credentials. Generate client credentials.](add_scim_7.png) + +Once you click **Create**, client credentials (client ID and secret) will be generated. Make sure you copy and save these values. After closing the dialog, you will not see the client credentials again. + +![A confirmation message that a SCIM client was created, showing client credentials to be copied in OpenProject administration](add_scim_8.png) + +#### c. **JWT from identity provider** + +If in [Step 3](#step-3-choose-an-authentication-method) you selected **JWT from identity provider**, you will have to specify **Subject claim** contained in the authentication JWT. + +![Add SCIM client. Creation form. JWT from identity provider. Specify Subject claim.](add_scim_9.png) diff --git a/docs/system-admin-guide/authentication/scim/openproject_system_administration_authetication_scim_index_page.png b/docs/system-admin-guide/authentication/scim/openproject_system_administration_authetication_scim_index_page.png new file mode 100644 index 00000000000..56fbf7b7231 Binary files /dev/null and b/docs/system-admin-guide/authentication/scim/openproject_system_administration_authetication_scim_index_page.png differ diff --git a/docs/system-admin-guide/authentication/two-factor-authentication/README.md b/docs/system-admin-guide/authentication/two-factor-authentication/README.md index f1bfcdbe855..c14d8a822e1 100644 --- a/docs/system-admin-guide/authentication/two-factor-authentication/README.md +++ b/docs/system-admin-guide/authentication/two-factor-authentication/README.md @@ -1,7 +1,7 @@ --- sidebar_navigation: title: Two-factor authentication - priority: 700 + priority: 400 description: configure two-factor authentication for OpenProject. keywords: two-factor authentication ---