references/openproject
1
0
Fork 0
mirror of https://github.com/opf/openproject.git synced 2026-06-14 03:30:14 +00:00
Code Issues Packages Projects Releases Wiki Activity

update the new SCIM docs page

Browse Source
This commit is contained in:
Maya Berdygylyjova
2025-07-14 16:27:38 +02:00
parent 236d521e75
commit 82a86b542b
7 changed files with 82 additions and 62 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/system-admin-guide/authentication/README.md
+3 -1
View File
@@ -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). |
docs/system-admin-guide/authentication/ldap-connections/README.md
+1 -1
View File
@@ -1,7 +1,7 @@
---
sidebar_navigation:
title: LDAP connections
priority: 500
priority: 600
description: Manage LDAP Authentication in OpenProject.
keywords: ldap authentication
---
docs/system-admin-guide/authentication/recaptcha/README.md
+1 -1
View File
@@ -1,7 +1,7 @@
---
sidebar_navigation:
title: reCAPTCHA
priority: 600
priority: 300
description: configure reCAPTCHA for OpenProject.
keywords: reCAPTCHA, turnstile
---
docs/system-admin-guide/authentication/saml/README.md
+1 -1
View File
@@ -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
---
docs/system-admin-guide/authentication/scim/README.md
+75 -57
View File
@@ -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://<your_openproject_hostanme>/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://<your_openproject_hostname>/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)
docs/system-admin-guide/authentication/scim/openproject_system_administration_authetication_scim_index_page.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 52 KiB

docs/system-admin-guide/authentication/two-factor-authentication/README.md
+1 -1
View File
@@ -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
---