Studio Integration

Studio API Endpoints

The OpenID Connect Bundle provides a RESTful API for the Pimcore Studio interface, enabling management of OpenID Connect configuration and handling OAuth2 authentication flows. All endpoints are prefixed with /pimcore-studio/api/bundle/openid-connect.

Configuration Management

Get Configuration

Endpoint: GET /config Operation ID: bundle_openid_connect_config_get Permission: OIDC_CONFIG Authentication: Required

Returns the full OpenID Connect configuration including providers, default provider, and writeability status.

Response: Configuration object with the following fields:

• data (object): Configuration data
• isWriteable (boolean): Whether the configuration is writeable
• providerNames (string[]): List of configured provider names

Example:

GET /pimcore-studio/api/bundle/openid-connect/config

Example Response:

{
    "data": {
        "providers": {
            "my-provider": {
                "clientId": "...",
                "clientSecret": "...",
                "discoveryUrl": "https://example.com/.well-known/openid-configuration"
            }
        },
        "defaultProvider": "my-provider"
    },
    "isWriteable": true,
    "providerNames": ["my-provider"]
}

---

Update Configuration

Endpoint: PUT /config Operation ID: bundle_openid_connect_config_update Permission: OIDC_CONFIG Authentication: Required

Updates the OpenID Connect configuration with the provided providers and default provider.

Request Body: JSON object (UpdateConfigurationParameters)

• providers (object, required): Provider configurations
• defaultProvider (string, nullable): Default provider name

Response: SuccessResponse object with success (boolean)

Example:

PUT /pimcore-studio/api/bundle/openid-connect/config
Content-Type: application/json

{
    "providers": {
        "my-provider": {
            "clientId": "my-client-id",
            "clientSecret": "my-client-secret",
            "discoveryUrl": "https://example.com/.well-known/openid-configuration"
        }
    },
    "defaultProvider": "my-provider"
}

Possible Errors:

• 400 Bad Request: Empty or malformed JSON body
• 415 Unsupported Media Type: Wrong content type (must be application/json)
• 422 Unprocessable Entity: Missing required providers field or invalid types

---

Authentication Flow

These endpoints handle the OAuth2 authorization code flow for OpenID Connect login. The login, endpoint, and script endpoints are publicly accessible (no authentication required) and are protected by rate limiters instead.

Important: For these public endpoints to work, you must add an access_control rule to your config/packages/security.yaml that grants public access before the catch-all Studio API rule. See Installation — Pimcore Studio UI for details.

OAuth2 Callback Endpoint

Endpoint: GET /auth/endpoint Operation ID: bundle_openid_connect_auth_endpoint Permission: Public (no authentication required) Rate Limiter: oidc_endpoint — 30 requests per 5 minutes

Handles the OAuth2 authorization code flow callback from the identity provider. This endpoint is called by the OIDC provider after the user authenticates, exchanging the authorization code for tokens and establishing the Pimcore admin session.

Query Parameters:

• code (string): Authorization code returned by the identity provider
• error (string): Error code if the provider returned an error
• redirect (integer): Whether to redirect (1) or return HTML (0)
• provider (string): Name of the OIDC provider
• state (string): CSRF state token for security
• perspective (string): Pimcore perspective context
• debug (boolean): Enable debug mode

Response: Either a redirect (302) to the admin interface, or HTML content depending on the flow state.

Example (initial redirect to provider):

GET /pimcore-studio/api/bundle/openid-connect/auth/endpoint?provider=my-provider&redirect=1

Example (callback from provider):

GET /pimcore-studio/api/bundle/openid-connect/auth/endpoint?code=AUTH_CODE&state=STATE_TOKEN

---

Login Redirect

Endpoint: GET /auth/login Operation ID: bundle_openid_connect_auth_login Permission: Public (no authentication required)

Handles the post-authentication redirect after a successful OpenID Connect login. Reads the stored perspective from the session and redirects the user to the admin interface.

Response: Redirect (302) to the admin interface with the perspective parameter

Example:

GET /pimcore-studio/api/bundle/openid-connect/auth/login

---

Login Button Script

Endpoint: GET /auth/script Operation ID: bundle_openid_connect_auth_script Permission: Public (no authentication required) Rate Limiter: oidc_script — 50 requests per 5 minutes

Returns a JavaScript file that injects OpenID Connect login buttons into the Pimcore login page. This script is loaded by the login page to render "Login with [Provider]" buttons for each configured OIDC provider.

Query Parameters:

• perspective (string, optional): The Pimcore perspective context

Response: JavaScript content (Content-Type: text/javascript)

Example:

GET /pimcore-studio/api/bundle/openid-connect/auth/script
GET /pimcore-studio/api/bundle/openid-connect/auth/script?perspective=default

---

Debug Page

Endpoint: GET /auth/debug Operation ID: bundle_openid_connect_auth_debug Permission: OIDC_CONFIG Authentication: Required

Returns an HTML debug page listing all configured OpenID Connect providers with clickable test links. This endpoint is useful for testing and debugging the OIDC integration.

Response: HTML content (Content-Type: text/html)

Example:

GET /pimcore-studio/api/bundle/openid-connect/auth/debug

---

Permissions

The Studio API uses the following permission constants:

• OIDC_CONFIG (permission_oidc_config): Required for managing the OpenID Connect configuration (get/update) and accessing the debug page

The authentication flow endpoints (/auth/endpoint, /auth/login, /auth/script) are publicly accessible and do not require permissions. They are protected by rate limiters instead.

Rate Limiting

Two separate rate limiters protect the public authentication endpoints from abuse:

Rate Limiter	Endpoint	Limit	Window
oidc_endpoint	GET /auth/endpoint	30 requests	5 minutes
oidc_script	GET /auth/script	50 requests	5 minutes

When the rate limit is exceeded, the endpoint returns 429 Too Many Requests.

Common Response Codes

Code	Description
200 OK	Successful request
302 Found	Redirect (login and endpoint flows)
400 Bad Request	Invalid request data
401 Unauthorized	Missing or invalid authentication (config/debug endpoints)
403 Forbidden	User lacks required permissions
415 Unsupported Media Type	Wrong content type on PUT requests
422 Unprocessable Entity	Validation error (missing required fields)
429 Too Many Requests	Rate limit exceeded (public endpoints)

API Tags

All endpoints are tagged with Bundle OpenID Connect for OpenAPI documentation grouping.

Usage Examples

Managing Configuration

1. Retrieve the current configuration:

   GET /pimcore-studio/api/bundle/openid-connect/config

2. Update providers:

   PUT /pimcore-studio/api/bundle/openid-connect/config
   Content-Type: application/json
   
   {
       "providers": {
           "azure-ad": {
               "clientId": "your-client-id",
               "clientSecret": "your-client-secret",
               "discoveryUrl": "https://login.microsoftonline.com/{tenant}/v2.0/.well-known/openid-configuration"
           }
       },
       "defaultProvider": "azure-ad"
   }

3. Test with the debug page:

   GET /pimcore-studio/api/bundle/openid-connect/auth/debug

Authentication Flow

The typical OAuth2 login flow works as follows:

1. The login page loads the login button script:

   GET /pimcore-studio/api/bundle/openid-connect/auth/script

   This injects "Login with [Provider]" buttons on the login page.

2. User clicks the login button, triggering a redirect to the OIDC provider:

   GET /pimcore-studio/api/bundle/openid-connect/auth/endpoint?provider=azure-ad&redirect=1
   → 302 Redirect to https://login.microsoftonline.com/...

3. After authentication, the provider redirects back to the callback:

   GET /pimcore-studio/api/bundle/openid-connect/auth/endpoint?code=AUTH_CODE&state=STATE
   → 302 Redirect to /pimcore-studio/api/bundle/openid-connect/auth/login

4. The login handler establishes the session and redirects to admin:

   GET /pimcore-studio/api/bundle/openid-connect/auth/login
   → 302 Redirect to /admin?perspective=default