Differences

This shows you the differences between two versions of the page.

--- 711:user_groups_permissions_scim [2024/09/18 15:01] – created Nerlich, Axel
+++ 711:user_groups_permissions_scim [2025/01/29 16:02] (current) – [Setting the Token secret] Nerlich, Axel
@@ Line 1: / Line 1: @@
 ====== SCIM provisioning ======
+SCIM, or System for Cross-domain Identity Management, is an open standard for the provisioning and deprovisioning of users and user groups to enterprise applications. It is able to significantly simplify the rollout of users and their permission group assignments in Stages.
+Stages V7.11 implements the SCIM standard version 2.0 (see https://scim.cloud), which is supported by most modern identity providers like Okta Lifecycle Management or Microsoft Entra ID. They provide the capability to configure the connection to the Stages application.
+Before connecting with Stages, an API token has to be created. This will then be used by the identity provider to authenticate against the Stages application.
+===== Setting the Token secret =====
+Stages generates its API tokens on the basis of a unique secret that can only be set by the Stages administrator. This should be a random string value with at least 32 characters. This value should be stored in the file conf/secret.properties like this:
+<code ->
+apitoken.secret = <value>
+</code>
+In the conf/config.xml file the following configuration property needs to be declared:
+<code ->
+<property name="restapi.apitoken.secret" value="${apitoken.secret}"/>
+</code>
+After that, a service restart is necessary.
+===== Creating an API Token =====
+Users need to have READ and CREATE permissions on the API tokens permission domain to be allowed to create API tokens . In order to revoke API tokens, READ and DELETE permissions are required. Authorized Stages users can find and manage the API tokens under Administration > SCIM API.
+Each token is identified by a label that is defined upon generation. The resulting token values will not be stored at the server but the server is able to identify a valid token by its value. Tokens become invalid after explicitly being revoked by the Stages administrator or after their expiry date has been reached.
+{{issue_apitoken.png}}
+Directly after creating the API Token, the token value can be copied from the Stages popup dialog and saved in a secure location. Once the dialog has been closed, it can not be retrieved anymore.
+Requests to the Stages REST endpoint must contain the value of a valid API token in the Authorization header in the following format: Bearer <token_value> Typically, the identity providers do this under the hood. All actions will be logged at the server in the scim.log and audit-json.log files with the respective API token label as a logging context identifier.
+===== Defining attribute mappings =====
+SCIM specifies a core schema, declaring how to transfer the user and group data between the identity provider to the application and back. In addition, the server application is able to extend the core schema by its own extension schemas. Stages uses the core schema and specifies one User extension schema.
+In order to correctly process the data, the identity provider must have an attribute mapping from its own data model to the SCIM schema. Please refer to the manual of the specific identity provider on how this can be configured.
+On the other hand, within Stages the SCIM attributes are mapped to Stages attributes. Not all of the core schema attributes are applicable to Stages. Here is a table of the attribute mappings in Stages:
+^ Stages Attribute ^ SCIM Resource ^ SCIM Core Attribute ^ SCIM Custom Attribute ^ SCIM value ^
+| ''pkit_user.user_id'' | ''User'' | ''id'' |   |   |
+| ''pkit_user.external_id'' | ''User'' | ''externalId'' |   |   |
+| ''pkit_user.username'' | ''User'' | ''userName'' |   |   |
+| ''pkit_user.fullname'' | ''User'' | ''name.formatted'' |   |   |
+| ''pkit_user.password'' | ''User'' | ''password'' |   |   |
+| ''pkit_user.license_type'' | ''User'' | ''userType / active'' |   |   |
+| ''pkit_user.email_address'' | ''User'' | ''emails.value'' |   | ''type=”work” (preferred) or the first email address'' |
+| ''profile.language'' | ''User'' | ''preferredLanguage'' |   | ''two-letter language code or “WORKSPACE” for the workspace default''  |
+| ''profile.home_project_id'' | ''User'' |   | ''homeWorkspaceId'' |   |
+| ''user_session.session_start'' | ''User'' |   | ''lastLogin'' |   |
+| ''user_perm_group.user_perm_group_id'' | ''Group'' | ''id'' |   |   |
+| ''user_perm_group.external_id'' | ''Group'' | ''externalId'' |   |   |
+| ''user_perm_group.name'' | ''Group'' | ''displayName'' |   |   |
+| ''user_group.user_id'' | ''Group'' | ''members.value'' |   |   |
+===== Addressing the SCIM endpoint =====
+The identity provider must be able to access the Stages server under the specific base URL. The base address should be the same as for accessing the Stages web application, but with the path to the SCIM API endpoint. This URL has to be configured in the application’s settings of the identity provider, like this:
+''https:<host>:<port>/stages/api/1/scim/v2''
+===== Participant groups =====
+In classical Stages permission management, permissions are managed by user permission groups (under Administration > Groups), which also directly map to the respective SCIM core schema attributes.
+However, participants (defined under Administration > Process Release > Participants) are another powerful way to allocate permissions for specific workspace contexts to a specific set of users.
+Participants are defined globally but user assignments are workspace-specific (under Management > Participants). Therefore every combination of participant and workspace can be seen as another user permission group. Such combinations can be selectivly exposed as user groups via SCIM for managing user assignments. When SCIM exposure is enabled via the SCIM settings of a workspace-specific participant a custom name needs to be set, which will be visible by the SCIM client prefixed by ''VG-<workspace-id>''.
+{{scim_settings.png}}