Documentation: Add Descope as User Identity Provider

[antonsmolyanyy]

Summary

Adds a new identity provider guide for Descope at
content/docs/integrations/user-identity/descope.mdx.

The page covers:

• Create a Descope OIDC Application — walking through the Descope
  console (Federated Apps → Generic OIDC Application), noting where to
  find the Issuer URL (IdP Configuration) and the Client ID /
  Client Secret (SP Configuration, Confidential client). Includes
  three supporting screenshots under img/descope/.
• Configure Pomerium — Core config using idp_provider: oidc with
  the Descope issuer as idp_provider_url, shown in both config.yaml
  and environment-variable tabs.
• Role-Based Access Control and Custom Claims — how to authorize on
  Descope roles/permissions by requesting the descope.claims scope,
  with example claim/roles and claim/permissions policies, plus
  descope.custom_claims for custom claims (e.g. claim/department).
  No existing pages or shared components are changed; this is additive
  (one new .mdx file and three images).

AI disclosure

none, only the PR summary was written by AI ^

Checklist

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

[netlify]

👷 Deploy request for pomerium-docs pending review.

Visit the deploys page to approve it

Name	Link
🔨 Latest commit	b3a4d8e

[CLAassistant]

All committers have signed the CLA.

[greptile-apps]

Greptile Summary

This PR adds a new identity-provider guide for Descope at content/docs/integrations/user-identity/descope.mdx, along with three supporting screenshots. No existing pages or shared components are modified; the change is purely additive.

• OIDC app setup: Walks through creating a Generic OIDC Application in the Descope console, noting the Issuer URL, Client ID/Secret, and configuring the Pomerium callback/logout domain via Descope's project-level Approved Domains settings.
• Pomerium configuration: Shows idp_provider: oidc with the Descope issuer URL in both config.yaml and environment-variable tabs, consistent with the pattern used by other OIDC guides (e.g., Ping).
• RBAC and custom claims: Documents the descope.claims and descope.custom_claims scopes and provides claim/roles, claim/permissions, and claim/department PPL policy examples.

Confidence Score: 5/5

• This PR is safe to merge — it is purely additive documentation with no changes to shared components, config, or existing pages.
• The change adds a single new .mdx guide and three screenshots. The OIDC configuration values, claim-path examples (claim/roles, claim/permissions), and the Approved Domains callback setup all follow established patterns. The previous review threads identified the outstanding nits (link definition, trailing newline); no new blocking issues were found during this review.
• content/docs/integrations/user-identity/descope.mdx warrants a final pass to resolve the open comments from prior review threads before merging.

Important Files Changed

Filename	Overview
content/docs/integrations/user-identity/descope.mdx	New IdP guide covering OIDC app creation, Approved Domains callback config, Core config keys/env-var tabs, and RBAC/custom-claims policy examples. Several issues were flagged in prior review threads (missing link definition for [environmental variables], trailing newline, scope ordering) that remain unresolved in this revision.
cspell.json	Adds "descope" to the custom dictionary. Correct and minimal change.

Sequence Diagram

sequenceDiagram
    participant User
    participant Pomerium
    participant Descope

    User->>Pomerium: Access protected route
    Pomerium->>Descope: "OIDC Authorization Request<br/>(scopes: openid, profile, email,<br/>offline_access, descope.claims)"
    Descope-->>User: Redirect to Descope login flow
    User->>Descope: Authenticate
    Descope-->>Pomerium: "Authorization code<br/>(redirect to /oauth2/callback on approved domain)"
    Pomerium->>Descope: Token exchange (client_id + client_secret)
    Descope-->>Pomerium: ID token with roles/permissions claims
    Pomerium->>Pomerium: "Evaluate PPL policy<br/>(e.g. claim/roles: admin)"
    Pomerium-->>User: Allow or deny access

Loading

_{Reviews (4): Last reviewed commit: "Merge branch 'main' into docs/add-descop..." | Re-trigger Greptile}

[antonsmolyanyy]

Hello @kenjenkins, kindly following up on this PR, would really appreciate a review from you. Thank you!

[wasaga]

@antonsmolyanyy if your identity provider supports directory (users+group) sync, please feel free to contribute the driver in github.com/pomerium/datasource