Configuration

Configure OpenID Connect providers in System > User & Roles > OpenId Connect > OpenId Connect Configuration in Pimcore Studio, or directly in a Symfony configuration file (see Configuration Storage). Opening this screen requires the OpenID Connect Configuration permission, see Installation.

Provider Configuration

Configure one or more OpenID Connect providers in parallel. Pimcore Studio shows a "Login with <Provider>" button per configured provider on its login page; clicking one starts that provider's OpenID Connect flow. Each provider needs a unique name.

On the provider side, register an application for Pimcore with:

• Redirect URL: https://<YOUR_PIMCORE_DOMAIN>/pimcore-studio/api/bundle/openid-connect/auth/endpoint
• Allowed scopes: openid profile email groups (see scopes below)

Once the application is set up, configure these required values per provider in Pimcore:

• client_id: Client ID provided by the provider.
• client_secret: Client secret provided by the provider.
• url_discovery: Endpoint for OpenID configuration discovery, based on the OpenID Connect Discovery spec. Typically something like <PROVIDER_DOMAIN>/.well-known/openid-configuration.

Optional values per provider:

• scopes: Scopes sent with the authorization request. Defaults to openid, profile, email and groups. Pimcore always adds openid, even if you remove it, because the OpenID Connect flow requires it.
• load_user_info: Merge the provider's userinfo response into the claims taken from the ID token, with the userinfo values winning. Enable this if the ID token alone does not carry all the claims Pimcore needs.
• dont_overwrite_roles: Skip role re-assignment after login, so you can manage roles in Pimcore instead of the provider. See Role Mapping.
• claim_mapping: Custom claim names, for providers that deviate from the OpenID Connect standard names. Maps the supported claims preferred_username (the username), given_name, family_name, email, groups (an array, or a comma- or semicolon-separated string, of group names), picture (URL of the user's avatar) and sub (the provider's remote user ID).

Default Provider

Optionally set a default provider by name. Pimcore Studio's login page then redirects to that provider's login immediately instead of showing the local credentials form.

warning

The redirect happens as soon as the login page loads, with no way to reach the local credentials form from that page. If the default provider becomes unreachable and locks out local accounts, remove PimcoreOpenIdConnectBundle::class from config/bundles.php and clear the cache to restore the plain login form. This works regardless of where the configuration is stored. If it is stored as symfony-config, removing default_provider from the configuration file (see Configuration Storage) works too and does not require disabling the bundle.

Studio Login Flow

Once at least one provider is configured, a user signs in like this:

1. Pimcore Studio's login page shows a "Login with <Provider>" button for each configured provider, next to the local credentials form (or redirects immediately if a default provider is set).
2. Clicking a button sends the browser to the bundle's public callback route, the same Redirect URL you registered with the provider above, with the provider name attached. The route redirects to that provider's authorization endpoint, starting the OAuth2 authorization code flow.
3. The user authenticates with the provider.
4. The provider redirects back to the same callback route with an authorization code. The bundle validates the OAuth2 state and redirects the browser to its login route, passing the code along.
5. Pimcore's security layer picks up that request with its OpenIdConnectAuthenticator. It exchanges the code for tokens, validates the ID token's signature and claims, and creates or updates the matching Pimcore user from the token claims (see Technical Details).
6. The login route redirects the browser into Pimcore Studio, restoring the perspective and page that were active before the login started.

The local credentials form keeps working alongside SSO, unless a default provider forces the redirect described above.

Configuration Storage

The configuration screen stores its data through a LocationAwareConfigRepository. Configure the storage location in the Symfony configuration tree:

• symfony-config: write configuration as YAML to /var/config/oidc/pimcore_open_id_connect.yaml.
• settings-store: write configuration to the Pimcore SettingsStore.
• disabled: do not allow writes. The configuration screen becomes read-only, and its Save button and input fields are disabled.

See the Pimcore Configuration Storage Locations and Fallbacks documentation for the underlying mechanism.

Example: Custom Storage Directory

pimcore_open_id_connect:
    config_location:
        open_id_connect:
            write_target:
                type: 'symfony-config'
                options:
                    directory: '/var/www/html/var/config/oidc'

Example: Providers Defined in Symfony Configuration

Define providers directly in a Symfony configuration file instead of using the configuration screen. In this case, the configuration screen becomes read-only, since the values it would edit no longer come from a writable source.

pimcore_open_id_connect:
    default_provider: onelogin

    providers:
        onelogin:
            client_id: <CLIENT_ID>
            client_secret: <CLIENT_SECRET>
            url_discovery: https://<USERNAME>.onelogin.com/oidc/2/.well-known/openid-configuration
        okta:
            client_id: <CLIENT_ID>
            client_secret: <CLIENT_SECRET>
            url_discovery: https://<USERNAME>.okta.com/.well-known/openid-configuration
            load_user_info: true
            dont_overwrite_roles: false
            scopes:
                - openid
                - profile
                - email
                - groups
            claim_mapping:
                preferred_username: preferred_username
                given_name: given_name
                family_name: family_name
                email: email
                groups: groups
                picture: picture
                sub: sub

Debugging

Open System > User & Roles > OpenId Connect > Debugging Tool in Pimcore Studio (same permission as the configuration screen) to troubleshoot a provider setup. It opens in a new browser tab and lists the configured providers.

Picking a provider runs a real sign-in against it, the same OAuth2 flow described above, but instead of logging you into Pimcore Studio, the tool shows the raw response: the ID token claims, the userinfo response, the configured claim_mapping, and the resulting merged user information Pimcore would use. Use it to verify a provider sends the claims your claim_mapping expects. If the flow fails, the tool renders the error message instead.