> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nudj.cx/llms.txt
> Use this file to discover all available pages before exploring further.

# OAuth Integration Setup

> Configure your OAuth 2.0 / OpenID Connect (OIDC) provider to work with Nudj Platform

<Info>
  This guide explains how to configure your OAuth 2.0 / OpenID Connect (OIDC) provider so it works with Nudj. This method is suitable for scenarios where users arrive directly at Nudj (not authenticated) and press 'log in'.
</Info>

## Quick Start

<Steps>
  <Step title="Verify Authentication Method">
    Ensure users will arrive directly at Nudj not authenticated and log in there. If users are already authenticated elsewhere, use [API Link User Token Authentication](/enterprise/api-link-user-authentication) instead.
  </Step>

  <Step title="Add OIDC Configuration in Nudj">
    Navigate to **Organisation Settings → Authentication** in the [admin panel](https://admin.nudj.cx/admin/settings/organisation?tab=authentication) and add your OAuth provider details.

    If your provider publishes an OIDC discovery document at `${issuer}/.well-known/openid-configuration`, paste the issuer URL and Nudj will auto-fetch the endpoints and advertised scopes (PR #1466). Otherwise fill the fields manually:

    * **issuer** (OIDC base URL)
    * **clientId**
    * **clientSecret**
    * **Required scopes**: `openid`, `profile`, `email` (optional: `offline_access`). Custom scopes beyond the OIDC defaults are supported (PR #1466).

    Save the configuration — Nudj generates your `oidcConfig.id` and displays it directly in the Authentication tab (PR #1433). No more emails to support.
  </Step>

  <Step title="Whitelist Nudj's Redirect URI">
    Copy the `oidcConfig.id` from the Authentication tab and build the Nudj redirect URI (exact match, no trailing slash):

    ```
    https://${rootDomain}/api/auth/callback/organisation-oidc-${oidcConfig.id}
    ```

    Find `${rootDomain}` in **Organisation Settings → Domains** in the [admin panel](https://admin.nudj.cx/admin/settings/organisation?tab=domains). Paste the fully-resolved URL into your OAuth/OIDC provider's allowed redirect list.
  </Step>

  <Step title="Test Integration">
    Save changes in your OAuth provider and test login in your Nudj environment. If you see a `PKCE cookie missing` error on callback, confirm that third-party cookies are permitted on the callback origin — this was tightened in PR #1538.
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="`PKCE cookie missing` on callback">
    PR #1538 enforces PKCE on the OIDC callback. The short-lived PKCE cookie is set on the auth initiation origin and must survive the round-trip back to `${rootDomain}/api/auth/callback/...`. Most failures come from:

    * A mismatched cookie domain between the initiation and callback hosts (e.g. initiating on a custom domain but the redirect lists the `.nudj.cx` host).
    * Aggressive third-party cookie blockers in embedded webviews.

    Ensure the domain you kick login off from is the same one listed in the provider's redirect URI.
  </Accordion>

  <Accordion title="`invalid_scope` from the provider">
    Nudj requests the scopes you configured plus `openid`, `profile`, `email`. If your provider rejects any of them, remove the unsupported scope from the Authentication tab and re-save. The auto-fetch flow (PR #1466) will surface the scopes your provider actually advertises.
  </Accordion>

  <Accordion title="Callback URI not matched">
    Providers match the redirect URI as an exact string. Confirm no trailing slash, correct scheme (`https`), and that `${oidcConfig.id}` is the value currently shown in the Authentication tab — regenerating the config produces a new ID.
  </Accordion>
</AccordionGroup>

## When to Use This Method

<CardGroup cols={2}>
  <Card title="Use OAuth Method" icon="check" color="#0ea5e9">
    * Users arrive directly at Nudj not authenticated
    * Users initiate login from Nudj interface
    * Standard authorization flow required
    * Redirects to your login system acceptable
  </Card>

  <Card title="Use API Link Instead" icon="arrow-right" color="#f59e0b" href="/enterprise/api-link-user-authentication">
    * Users already authenticated elsewhere
    * Seamless session continuation needed
    * No login screen should be shown
    * Direct JWT-based authentication preferred
  </Card>
</CardGroup>

## Related Authentication Methods

<CardGroup cols={3}>
  <Card title="→ API Link User Token Auth" icon="key" href="/enterprise/api-link-user-authentication">
    **Alternative Method**: For users already authenticated elsewhere who need seamless session continuation
  </Card>

  <Card title="→ Enterprise SSO Overview" icon="shield-check" href="/enterprise/sso-authentication">
    **Overview**: Complete guide to all enterprise authentication options and patterns
  </Card>

  <Card title="→ Integration Overview" icon="diagram-project" href="/enterprise/integration-overview">
    **Next Steps**: Understand access patterns and reward delivery after authentication setup
  </Card>
</CardGroup>