docs(idp): use placeholder request params and warn on reserved keys

[ssveta7ak]

Summary

The Identity Provider Request Params reference used the reserved OAuth parameters client_id, response_type, and redirect_uri as their own example values. Because these looked like real settings, users copied them literally into their config — overriding the values Pomerium sets itself during the OAuth 2.0 code flow and breaking sign-in.

This change:

• Replaces the example values with neutral placeholders (foo: bar, baz: qux) in both the config-file and environment-variable snippets, so nothing in the example is copy-pasteable into a broken state.
• Adds a warning listing the parameters Pomerium manages (client_id, response_type, redirect_uri, scope, state, nonce) that must not be set here, and clarifies this setting is for additional provider-specific parameters (e.g. prompt, access_type).

Related

• Related to ENG-4222 (identity provider request params saved with placeholder values)

AI disclosure

Claude Code made the documentation edits and drafted this PR; I reviewed and directed the changes.

Checklist

• reference any related issues
• disclosed AI usage (or wrote "none") per AI_POLICY.md

[netlify]

✅ Deploy Preview for pomerium-docs ready!

Name	Link
🔨 Latest commit	de0846e
🔍 Latest deploy log	https://app.netlify.com/projects/pomerium-docs/deploys/6a5927a3b4a937000801f70c
😎 Deploy Preview	https://deploy-preview-2318--pomerium-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[greptile-apps]

Greptile Summary

This PR fixes a documentation bug where the Identity Provider Request Params examples used real OAuth 2.0 reserved keys (client_id, response_type, redirect_uri) as their own example values, causing users to copy them literally and break Pomerium sign-in. The fix replaces those examples with neutral placeholders and adds a warning listing all parameters Pomerium manages internally.

• Replaces client_id: client_id, response_type: response_type, redirect_uri: redirect_uri with foo: bar, baz: qux in both the YAML and env-var snippets.
• Adds a :::warning admonition enumerating the six reserved parameters (client_id, response_type, redirect_uri, scope, state, nonce) and links the purpose of this setting to provider-specific extras like prompt or access_type.
• Updates the Enterprise Console screenshot (idp-request-params.png) to reflect the new example values.

Confidence Score: 5/5

Documentation-only change; corrects a misleading example and adds a safety warning with no code-path impact.

Both changed files are documentation assets. The MDX edit adds a well-formed admonition and swaps misleading example values for neutral placeholders; the PNG is a matching screenshot update. No links are broken, the MDX syntax is valid, and the reserved-parameter list in the warning is accurate against the OAuth 2.0 code-flow Pomerium implements.

No files require special attention.

Important Files Changed

Filename	Overview
content/docs/reference/identity-provider-settings.mdx	Adds a :::warning admonition listing six reserved OAuth parameters and replaces the misleading example values with neutral placeholders; no broken links or MDX syntax issues found.
content/docs/reference/img/idp_options/idp-request-params.png	Updated Enterprise Console screenshot to match the new placeholder example values; binary asset replacement with no other concerns.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant Browser
    participant Pomerium
    participant IdP as Identity Provider

    Browser->>Pomerium: GET /oauth2/sign_in
    Note over Pomerium: Builds authorization URL<br/>Sets: client_id, response_type,<br/>redirect_uri, scope, state, nonce<br/>(RESERVED — do not override)
    Note over Pomerium: Merges idp_request_params<br/>(e.g. prompt=select_account)<br/>onto the URL
    Pomerium-->>Browser: 302 redirect → IdP /authorize?...
    Browser->>IdP: "GET /authorize?client_id=...&prompt=select_account&..."
    IdP-->>Browser: "302 redirect → Pomerium redirect_uri?code=..."
    Browser->>Pomerium: "GET /oauth2/callback?code=..."
    Pomerium->>IdP: POST /token (exchange code)
    IdP-->>Pomerium: access_token, id_token
    Pomerium-->>Browser: Session cookie + access granted

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
    participant Browser
    participant Pomerium
    participant IdP as Identity Provider

    Browser->>Pomerium: GET /oauth2/sign_in
    Note over Pomerium: Builds authorization URL<br/>Sets: client_id, response_type,<br/>redirect_uri, scope, state, nonce<br/>(RESERVED — do not override)
    Note over Pomerium: Merges idp_request_params<br/>(e.g. prompt=select_account)<br/>onto the URL
    Pomerium-->>Browser: 302 redirect → IdP /authorize?...
    Browser->>IdP: "GET /authorize?client_id=...&prompt=select_account&..."
    IdP-->>Browser: "302 redirect → Pomerium redirect_uri?code=..."
    Browser->>Pomerium: "GET /oauth2/callback?code=..."
    Pomerium->>IdP: POST /token (exchange code)
    IdP-->>Pomerium: access_token, id_token
    Pomerium-->>Browser: Session cookie + access granted

Loading

_{Reviews (2): Last reviewed commit: "docs(idp): update request params screens..." | Re-trigger Greptile}

[desimone]

fix img pls :)