{ "componentChunkName": "component---src-templates-plugin-tsx", "path": "/plugins/scm-oauth2-plugin", "result": {"data":{"plugin":{"name":"scm-oauth2-plugin","displayName":"OAuth2/OIDC","description":"Authentication for SCM-Manager using OAuth2/OIDC"},"readme":{"html":"

\n \n \"SCM-Manager\"\n \n

\n

\n OAuth2/OIDC Authentication Plugin\n

\n

Deutsche Fassung

\n

SSO authentication for SCM-Manager (3.x) via OAuth2 / OpenID Connect\nusing the authorization code flow. Tested with Keycloak, but works with\nany spec compliant identity provider (IdP).

\n

Features

\n\n

Installation

\n

The plugin is not part of the official plugin center and is therefore installed manually. It\nrequires SCM-Manager 3.9.0 or newer.

\n
    \n
  1. \n

    Download scm-oauth2-plugin.smp from the\nreleases page

    \n
    2. \n
  2. \n

    Copy the file into the plugins directory of your SCM-Manager home, e.g.

    \n
    cp scm-oauth2-plugin.smp /var/lib/scm/plugins/
    \n
    3. \n
  3. \n

    Restart SCM-Manager. The archive is unpacked during startup — afterwards the directory\nplugins/scm-oauth2-plugin/ exists and the .smp file is gone, which is expected.

    \n
    4. \n
  4. \n

    Verify the installation in Administration → Plugins → Installed, or via REST:

    \n
    curl -u \"scmadmin:secret\" http://localhost:8080/scm/api/v2/plugins/installed \\\n  | grep -o '\"name\":\"scm-oauth2-plugin\",\"version\":\"[^\"]*\"'
    \n
    5. \n
\n

Afterwards configure the plugin as described under Configuration.

\n

Finding the home directory

\n

The home directory is the one containing config/, repositories/ and plugins/. The reliable\nway to find it is the log entry written on every startup:

\n
grep \"scm home directory\" /var/log/scm/scm-manager.log\n# using directory /var/lib/scm as scm home directory
\n

Typical defaults, unless overridden by the environment variable SCM_HOME or the system property\nscm.home:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
InstallationHome directory
Linux package / Docker/var/lib/scm
macOS~/Library/Application Support/SCM-Manager
Windows%APPDATA%\\SCM-Manager
\n

Update

\n

Since the archive is unpacked, an old version has to be removed first, otherwise the previous\nplugin directory stays in place:

\n
# stop SCM-Manager first\nrm -rf /var/lib/scm/plugins/scm-oauth2-plugin\ncp scm-oauth2-plugin.smp /var/lib/scm/plugins/\n# start SCM-Manager
\n

The configuration is stored in config/oauth2.xml and survives an update. To uninstall, remove the\nplugin directory and restart.

\n

How it works

\n

Login

\n
    \n
  1. The user clicks \"Login with <provider>\" (or is redirected by the force login filter) —\nGET /api/v2/oauth2/auth?from=<original url>
    2. \n
  2. The plugin creates a random state (CSRF protection, valid once, 10 minutes), a PKCE verifier\nand a nonce, stores the state in an HttpOnly cookie of this browser and redirects to the\nauthorization endpoint of the IdP (with code_challenge, if the IdP supports S256)
    3. \n
  3. After authentication the IdP redirects back to the callback\nGET /api/v2/oauth2/auth/callback?code=...&state=...
    4. \n
  4. The plugin checks that the state belongs to the state cookie of this browser, exchanges the\nauthorization code for tokens at the token endpoint (server-to-server, client_secret_post,\nwith code_verifier), verifies the id token (signature, issuer, audience, expiry, nonce) and\nfetches the user claims from the userinfo endpoint
    5. \n
  5. The user is created/updated/migrated, groups and permissions are synchronized, the id token is\nkept in memory for a later SSO logout and an SCM access token cookie is issued
    6. \n
  6. The browser is redirected to the originally requested url
    7. \n
\n
\n

Important: the plugin reads the claims (username, display name, email, groups) from the\nuserinfo endpoint — not from the access or id token. Make sure your IdP adds the claims to\nthe userinfo response (in Keycloak: protocol mapper setting Add to userinfo). The only\nexception is the optional role import from the access token.

\n
\n

Logout (optional, ssoLogout)

\n

On logout SCM-Manager redirects the browser to the end session endpoint of the IdP with:

\n\n

If the id token is not available (e.g. after a server restart), the logout still works — the IdP\nmay then show a confirmation page.

\n

Configuration

\n

Administration → Settings → OAuth2 / OIDC, or via REST (see below).

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
SettingKeyDefaultDescription
EnabledenabledfalseMaster switch for the plugin
Force loginforceLoginfalseRedirect unauthenticated browsers to the IdP automatically; conventional login is no longer possible
Full SSO logoutssoLogoutfalseRP-initiated logout at the IdP (see above)
Take over local accountsmigrateLocalUsersfalseAllows the IdP to take over accounts which still have a local password, see Migration of existing users
Provider nameproviderName—Display name of the IdP, shown as \"Login with <provider name>\". Required if the plugin is enabled
OIDC Discovery URLdiscoveryUrl—Issuer url or complete url of the .well-known/openid-configuration document. If set, all endpoints below are resolved automatically (cached for one hour) and the manual entries are ignored
Authorization endpointauthorizationUrl—Manual endpoint configuration (only used without discovery url)
Token endpointtokenUrl—\"
Userinfo endpointuserinfoUrl—\"
End session endpointendSessionUrl—\", optional; only needed for ssoLogout
JWKS endpointjwksUrl—\", public keys used to verify the signatures of id token and access token. Without it (and without a discovery url) no token is verified and none is used
Client IDclientId—Client registered at the IdP
Client secretclientSecret—Secret of the (confidential) client. Stored encrypted, never returned by GET; send an empty value on update to keep the stored secret (the read-only flag clientSecretSet tells whether one is stored)
Scopesscopesopenid profile emailSpace separated list of requested scopes
Username claimusernameAttributepreferred_usernameUserinfo claim used as SCM username (falls back to sub)
Display name claimdisplayNameAttributenameUserinfo claim for the display name
Mail claimmailAttributeemailUserinfo claim for the email address (invalid addresses are ignored)
Group claimgroupAttributegroupsUserinfo claim for group memberships (string or array of strings)
Import realm roles from access tokenimportRealmRolesfalseAdditionally read roles from the access token, see below
JSON path of the rolesrealmRolesPathrealm_access.rolesPath to the roles inside the access token, field names separated by dots
Administrator groupadminGroupscmadminMembers of this group get the global administrator permission on login, non-members get it revoked. Empty = permissions are never touched
\n

Redirect URI

\n

Register the following redirect uri at the IdP client:

\n
<scm-base-url>/api/v2/oauth2/auth/callback
\n

e.g. http://scm-server.localhost:8080/scm/api/v2/oauth2/auth/callback. For the SSO logout the\nSCM base url (e.g. http://scm-server.localhost:8080/scm) has to be registered as valid post\nlogout redirect uri additionally.

\n

Configuration via REST

\n
curl -u \"scmadmin:secret\" -H \"Content-Type: application/vnd.scmm-oauth2Config+json;v=2\" -XPUT -d '{\n  \"providerName\": \"Sonia\",\n  \"discoveryUrl\": \"https://id.dev.sonia.de/realms/sonia\",\n  \"clientId\": \"scm-server\",\n  \"clientSecret\": \"<secret>\",\n  \"scopes\": \"openid profile email\",\n  \"usernameAttribute\": \"preferred_username\",\n  \"displayNameAttribute\": \"name\",\n  \"mailAttribute\": \"email\",\n  \"groupAttribute\": \"groups\",\n  \"adminGroup\": \"scmadmin\",\n  \"importRealmRoles\": false,\n  \"realmRolesPath\": \"realm_access.roles\",\n  \"migrateLocalUsers\": false,\n  \"forceLogin\": false,\n  \"ssoLogout\": true,\n  \"enabled\": true\n}' http://scm-server.localhost:8080/scm/api/v2/oauth2/configuration
\n

GET on the same url returns the current configuration. Setting enabled: true without a\nproviderName is rejected with 400 Bad Request.

\n

Migration of existing users

\n

Users are identified by the username claim, so an instance which already\nauthenticates against another source (e.g. LDAP) can be switched to OAuth2\nwithout losing anything, as long as the identity provider delivers the same\nuser names. On the first OAuth2 login the existing account is reused, which\nkeeps everything that is bound to the user name:

\n\n

Attributes which the identity provider does not deliver keep their stored\nvalue — a missing mail claim does not wipe the mail address of a migrated user.\nThe stored active flag is preserved as well, so a deactivated account is not\nreactivated by a login.

\n

Accounts which can still be used for a local password login are not taken\nover by default: the login is rejected with a warning in the log, because\notherwise a user of the identity provider could seize a local account (e.g. the\ninitial scmadmin) just by using its name. Users of other external\nauthentications (LDAP, CAS) have no local password and are migrated silently.\nTo migrate local accounts as well, enable Take over local accounts\n(migrateLocalUsers) — their local password is removed in that case, because\nthe account is authenticated by the identity provider from then on.

\n

To check upfront how an existing user is stored:

\n
curl -u \"scmadmin:secret\" https://scm.example.com/scm/api/v2/users/<username> | grep -o '\"external\":[a-z]*'
\n

Group and permission synchronization

\n

On every login the group claim is compared with the state of the previous login:

\n\n

Characters which SCM-Manager does not allow in a name (/ : ? # ; & = % \\, a leading @ and\nleading/trailing whitespace) are replaced by an underscore, so no group is lost. A Keycloak\ngroup mapper with Full group path enabled therefore results in:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
ClaimSCM group
/developers_developers
/team/backend_team_backend
SCM RZ-internSCM RZ-intern (unchanged, internal blanks are allowed)
\n

The sanitized name is used consistently — for the created group, for the membership and for the\nauthorization — so permissions granted to the group really apply. Keep that in mind for the\nadministrator group: if the identity provider sends /scmadmin, the setting has to be\n_scmadmin. Two claim values which only differ in invalid characters (a/b and a:b) end up in\nthe same SCM group.

\n

Additionally the effective groups of the user are resolved directly from the claim at\nauthorization time (group resolver), so permissions assigned to a group name work even before the\ngroup entity exists.

\n

Roles from the access token

\n

Some identity providers deliver roles only in the access token and not in the\nuserinfo response — Keycloak realm roles are the typical example. With\nImport realm roles from access token (importRealmRoles) these roles are read\nfrom the token and added to the groups of the userinfo response. The\nlocation is configured as a dot separated path (realmRolesPath):

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
PathReads
realm_access.rolesKeycloak realm roles (default)
resource_access.<client-id>.rolesKeycloak client roles of that client
groupsa top level claim of the token
\n

The path may also contain array indexes (realm_access.roles.0). Both arrays\nand single string values are accepted. If the access token is not a JWT (some\nproviders issue opaque tokens) or the path does not exist, no roles are\nimported and the login continues normally.

\n

The signature of the access token is not verified for this, which is safe\nbecause the token was received directly from the token endpoint of the\nconfigured identity provider over TLS — the same trust level as the userinfo\nresponse.

\n
\n

Note: every imported role becomes an SCM group (see below). Keycloak realm\nroles often include many technical roles (offline_access,\numa_authorization, default-roles-<realm>, …), so the group list can grow\nconsiderably. If only a few roles are relevant, a client role mapper with\nresource_access.<client-id>.roles is the more targeted choice.

\n
\n

If the group claim contains the configured administrator group (default scmadmin), the user\ngets the global administrator permission (*) assigned; if the group is missing, a previously\nassigned permission is revoked on the next login. With a configured admin group the claim is the\nsingle source of truth for this one permission — manually granting it to an OAuth2 user without\nthe group does not survive the next login. Leave the field empty to disable this mechanism.

\n

Security notes

\n

The plugin implements the current recommendations for the authorization code flow\n(RFC 6749/9700):

\n\n

Two points to keep in mind when operating the plugin:

\n\n

Run the instance behind TLS — the client secret is transmitted in the body when the configuration\nis saved, and the session cookie is only marked Secure on an HTTPS connection.

\n

Keycloak example

\n

scm-server.json contains an export of a working sample client for the setup\ndescribed above (SCM-Manager reachable at http://scm-server.localhost:8080/scm). Import it in\nthe Keycloak admin console via Clients → Import client and generate a client secret afterwards —\nthe file contains the placeholder GENERATE_YOUR_OWN_SECRET_IN_KEYCLOAK instead of a real secret.

\n

The important settings of the sample client:

\n\n

With this mapper setup, SCM groups are managed as Keycloak client roles of the scm-server\nclient:

\n
    \n
  1. Keycloak → Clients → scm-server → Roles → create role, e.g. scmadmin or developers
    2. \n
  2. Assign the role to users (Users → Role mapping → Assign role → filter by client)
    3. \n
  3. On the next SCM login the role shows up in the groups claim, the corresponding SCM group is\ncreated/updated and — in case of scmadmin — the global administrator permission is assigned
    4. \n
\n

Alternatively a Keycloak Group Membership mapper (claim groups, Add to userinfo enabled,\nFull group path disabled) can be used to map real Keycloak groups instead of client roles.

\n

Build and testing

\n

The plugin can be compiled and packaged with the following tasks:

\n\n

Gradle has no profiles like maven; the build evaluates the project property stage instead.\nWith -Pstage=release the api documentation is written to docs/javadoc next to\nthe sources instead of into the build directory, so it is committed together with the release:

\n
# regenerate only the documentation\n./gradlew javadoc -Pstage=release\n\n# complete release build including the committed documentation\n./gradlew build -Pstage=release
\n

The directory is emptied before it is regenerated, so pages of removed classes do not stay behind.\nWithout the property everything stays in the build directory and docs/javadoc is untouched.

\n

For the development and testing the run task of the plugin can be used:

\n\n

If the plugin was started with gradle run, the default browser of the os should be automatically opened.\nIf the browser does not start automatically, start it manually and go to http://localhost:8081/scm.

\n

In this mode each change to web files (src/main/js or src/main/webapp), should trigger reload of the browser with the made changes.

\n

Running with an OIDC provider using Docker

\n

If you don't have an OIDC provider at hand, you can just run one using Docker. To do so, you can use the\nprovided docker-compose.yml file and the dex.yaml configuration. Assuming a working Docker installation,\nsimply run

\n
docker compose up
\n

This will start a small Dex provider with two users: trillian@hog.org and dent@example.com, both with the password secret.\nYou can simply add mor user accounts by editing the dex.yaml file. You can generate hashes for other passwords with this command:

\n
docker run --rm httpd:alpine htpasswd -C 10 -bnB \"\" \"other-password\" | tr -d ':\\n'
\n

To configure SCM-Manager, use this cURL call:

\n
curl -vu scmadmin:scmadmin \\\n  http://localhost:8081/scm/api/v2/oauth2/configuration \\\n  -H 'Content-Type: application/vnd.scmm-oauth2config+json;v=2' \\\n  -XPUT \\\n --data '{\n   \"providerName\":\"Local Test\",\n   \"discoveryUrl\":\"http://localhost:5556/dex/.well-known/openid-configuration\",\n   \"clientId\":\"scm-manager\",\n   \"clientSecret\":\"scm-secret-12345\",\n   \"clientSecretSet\":false,\n   \"scopes\":\"openid profile email\",\n   \"usernameAttribute\":\"name\",\n   \"displayNameAttribute\":\"name\",\n   \"mailAttribute\":\"email\",\n   \"groupAttribute\":\"groups\",\n   \"adminGroup\":\"\",\n   \"importRealmRoles\":false,\n   \"realmRolesPath\":\"realm_access.roles\",\n   \"forceLogin\":false,\n   \"ssoLogout\":false,\n   \"migrateLocalUsers\":false,\n   \"enabled\":true\n }'
\n

Directory & File structure

\n

A quick look at the files and directories you'll see in an SCM-Manager project.

\n
.\n├── node_modules/\n├── src/\n|   ├── main/\n|   |   ├── java/\n|   |   ├── js/\n|   |   └── resources/\n|   └── test/\n|       ├── java/\n|       └── resources/\n├── .editorconfig\n├── .gitignore\n├── build.gradle\n├── CHANGELOG.md\n├── gradle.properties\n├── gradlew\n├── LICENSE.txt\n├── package.json\n├── README.md\n├── scm-server.json\n├── settings.gradle\n├── tsconfig.json\n└── yarn.lock
\n
    \n
  1. \n

    node_modules/: This directory contains all modules of code that your project depends on (npm packages) are automatically installed.

    \n
    2. \n
  2. \n

    src/: This directory will contain all code related to what you see or not. src is a convention for “source code”.

    \n
      \n
    1. main/\n
        \n
      1. java/: This directory contains the Java code.
        2. \n
      2. js/: This directory contains the JavaScript code for the web ui, inclusive unit tests: suffixed with .test.ts
        3. \n
      3. resources/: This directory contains the classpath resources.
        4. \n
      \n
      2. \n
    2. test/\n
        \n
      1. java/: This directory contains the Java unit tests.
        2. \n
      2. resources/: This directory contains classpath resources for unit tests.
        3. \n
      \n
      3. \n
    \n
    3. \n
  3. \n

    .editorconfig: This is a configuration file for your editor using EditorConfig. The file specifies a style that IDEs use for code.

    \n
    4. \n
  4. \n

    .gitignore: This file tells git which files it should not track / not maintain a version history for.

    \n
    5. \n
  5. \n

    build.gradle: Gradle build configuration, which also includes things like metadata.

    \n
    6. \n
  6. \n

    CHANGELOG.md: All notable changes to this project will be documented in this file.

    \n
    7. \n
  7. \n

    gradle.properties: Defines the module version.

    \n
    8. \n
  8. \n

    gradlew: Bundled gradle wrapper if you don't have gradle installed.

    \n
    9. \n
  9. \n

    LICENSE.txt: This project is licensed under AGPLv3.

    \n
    10. \n
  10. \n

    package.json: Here you can find the dependency/build configuration and dependencies for the frontend.

    \n
    11. \n
  11. \n

    README.md: This file, containing useful reference information about the project. A German version is available in README_de.md.

    \n
    12. \n
  12. \n

    scm-server.json: Export of the Keycloak sample client (see Keycloak example).

    \n
    13. \n
  13. \n

    settings.gradle: Gradle settings configuration.

    \n
    14. \n
  14. \n

    tsconfig.json This is the typescript configuration file.

    \n
    15. \n
  15. \n

    yarn.lock: This is the ui dependency configuration.

    \n
    16. \n
\n

Further documentation

\n

Below docs/ you will find the generated api documentation as well as four documents (in German)\nwhich describe the plugin from a data protection and information security point of view:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
DocumentContent
PROZESS_BESCHREIBUNG.mdProcessing operations, data categories, storage locations, retention and recipients — basis for a record of processing activities (art. 30 GDPR)
COMPLIANCE_BERICHT.mdAssessment against GDPR and the NIS2 risk management measures (art. 21(2)), including implemented measures, findings and residual risks
DATENSCHUTZ_FOLGEABSCHAETZUNG.mdThreshold analysis and data protection impact assessment (art. 35 GDPR)
SOURCECODE_STATISTIK.mdSize, test coverage, documentation ratio and dependencies
docs/javadocApi documentation, regenerated with ./gradlew javadoc -Pstage=release
\n

The documents describe the software; the organisational parts (legal basis, retention periods,\nresponsibilities) have to be completed by the operator of the instance.

\n

Need help?

\n

Looking for more guidance? Full documentation lives on the SCM-Manager homepage or the dedicated pages for the plugins.

"}},"pageContext":{"name":"scm-oauth2-plugin"}}, "staticQueryHashes": ["1973669194","2742214048","2956773653"]}