Technical Details

These internals help you understand what happens during and after an OpenID Connect login.

User Mapping

Every SSO user gets a matching Pimcore user. Pimcore uses the preferred_username claim (mapped through claim_mapping, see Configuration) as that user's username, and looks up an existing user by that username on every login. The sub claim (the provider's remote user ID) is not part of this lookup; it only seeds the generated password of a newly created user and names the temporary file the avatar is downloaded into. Renaming a user in Pimcore therefore detaches it from the provider, and the next login creates a second user under the original username.

If no user with that username exists yet, Pimcore creates one in the oidc user folder with a random, unknown password, so it can only sign in through SSO unless an admin resets its password later. Either way, Pimcore then updates the user's name, email and avatar from the claims, and re-assigns roles (see Role Mapping below).

Pimcore never deletes these users automatically. You can edit their permissions and workspaces directly in Pimcore like any other user.

Role Mapping

Roles delivered by the provider (the groups claim, by default) are matched by name against roles that already exist in Pimcore. A group name with no matching Pimcore role is ignored.

Pimcore re-assigns a user's roles from this claim on every login, replacing whatever was assigned before, unless the provider's dont_overwrite_roles option is enabled. Enable it to manage roles for SSO users directly in Pimcore instead.

Token Validation

Pimcore verifies the ID token before trusting any of its claims:

• The token's signature is checked against the provider's JSON Web Key Set (fetched from the discovery document's jwks_uri). Supported signing algorithms are RS256, RS384, RS512, HS256, HS384 and HS512.
• The iss (issuer) and aud (audience) claims must match the provider's issuer and the configured client ID.
• The iat (issued at), nbf (not before) and exp (expiration) claims are checked with a 10-second leeway for clock drift.

A token that fails any of these checks is rejected and the login fails.

Configuration Caching

Pimcore caches each provider's discovery document (authorization, token and userinfo endpoints) and its JSON Web Key Set for 24 hours, so a login does not re-fetch them on every request.

To pick up provider-side changes immediately, clear the oidc cache tag:

bin/console pimcore:cache:clear --tags=oidc

Rate Limiting

The public login routes are rate-limited per client IP with a fixed window, independent of any permission check, since they run before a Pimcore session exists:

Route	Limit
OAuth2 callback (/auth/endpoint)	30 requests per 5 minutes (about 10 login attempts, since each login uses the route more than once)
Login button script (/auth/script)	50 requests per 5 minutes

A client that exceeds its limit gets 429 Too Many Requests until the window resets. Override the oidc_endpoint and oidc_script Symfony rate limiters in your own configuration to change these limits.