> ## 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 OAuth 2.0 / OpenID Connect to enable login via your authentication provider

This guide explains how to configure your OAuth 2.0 / OpenID Connect (OIDC) provider so users can log into Nudj using your existing authentication system.

<Info>
  **Use this method if**: Users arrive at Nudj directly (not already authenticated) and initiate a login from the Nudj login page.

  **If users are already authenticated elsewhere**, use [API Link User Token Authentication](/developer/api-link-user-authentication) instead.
</Info>

## Quick Start

1. **Add OIDC configuration in Nudj**: Go to Organisation Settings → Authentication and enter your provider details
2. **Whitelist Nudj's redirect URI**: Add the callback URL to your OAuth provider's configuration
3. **Test the flow**: Log in via your provider and verify the integration works

## Determine the Authentication Method

Use OAuth 2.0 / OIDC if:

* Users will arrive at Nudj not authenticated
* You want to follow industry-standard authentication flows
* Users may access multiple services and need centralized authentication

If users are already authenticated in your system, use [API Link User Token Authentication](/developer/api-link-user-authentication) instead.

## Add Your OIDC Configuration in Nudj

Navigate to your Nudj admin panel at `https://your-domain/admin`:

1. Go to **Organisation Settings → Authentication**
2. Create a new OIDC configuration with these details:

<CardGroup cols={1}>
  <Card title="clientId" icon="key">
    Your OAuth provider's Client ID
  </Card>

  <Card title="clientSecret" icon="lock">
    Your OAuth provider's Client Secret
  </Card>

  <Card title="issuer" icon="globe">
    The OIDC base URL (discovery endpoint) from your provider. Used for token verification.
  </Card>
</CardGroup>

### Required Scopes

Configure these scopes in your provider:

* **openid** (required)
* **profile** (required)
* **email** (required)
* **offline\_access** (optional, for refresh tokens)

Once you save the configuration, **Nudj generates a unique `oidcConfig.id`** for your environment. You'll need this for the next step.

## Whitelist Nudj's Redirect URI

After creating the OIDC configuration in Nudj, you'll have a callback URL. Add this exact URL to your OAuth provider's redirect URI whitelist (no trailing slash):

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

Where:

* **`${rootDomain}`** = Your Nudj domain (found in Organisation Settings → Domains)
* **`${oidcConfig.id}`** = The ID generated when you created the OIDC config

### Example

If your domain is `loyalty.mycompany.com` and your `oidcConfig.id` is `abc123def456`, the redirect URI would be:

```
https://loyalty.mycompany.com/api/auth/callback/organisation-oidc-abc123def456
```

Add this exact URL to your OAuth provider's configuration and save.

## Testing the Integration

1. Confirm your OAuth provider lists the Nudj redirect URI correctly
2. Verify all required scopes are enabled in your provider
3. Log out of Nudj (if currently logged in)
4. On the Nudj login page, click **"Log in with \[Your Provider Name]"**
5. Complete authentication with your provider
6. Verify you're redirected back to Nudj and fully authenticated

## Troubleshooting

<Accordion title="Users can't see the OAuth option at login" icon="eye-slash">
  Make sure the OIDC configuration is saved in Nudj and enabled. It may take a few minutes to appear on the login page after enabling.
</Accordion>

<Accordion title="Redirect URI mismatch error" icon="alert-circle">
  The redirect URI in your OAuth provider must match **exactly** what Nudj generated. Check for:

  * Trailing slashes (Nudj doesn't use them)
  * Correct domain
  * Correct `oidcConfig.id`

  Any mismatch will cause the OAuth flow to fail.
</Accordion>

<Accordion title="'Invalid scope' or scope errors" icon="x">
  Ensure your OAuth provider has the required scopes (openid, profile, email) enabled. Check your provider's documentation if you're unsure how to enable additional scopes.
</Accordion>

<Accordion title="Token validation errors" icon="key">
  Verify that the `issuer` URL you provided in Nudj matches your OAuth provider's OIDC discovery endpoint. This is used to validate tokens. If the issuer is wrong, token verification will fail.
</Accordion>

## Common OAuth Providers

| Provider    | Issuer URL Format                                 | Setup Docs                                                                                                                           |
| ----------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| Auth0       | `https://your-domain.auth0.com`                   | [https://auth0.com/docs/get-started](https://auth0.com/docs/get-started)                                                             |
| Okta        | `https://your-domain.okta.com`                    | [https://developer.okta.com/docs/guides/implement-oauth-for-okta/](https://developer.okta.com/docs/guides/implement-oauth-for-okta/) |
| Azure AD    | `https://login.microsoftonline.com/{tenant}/v2.0` | [https://docs.microsoft.com/en-us/azure/active-directory/](https://docs.microsoft.com/en-us/azure/active-directory/)                 |
| Keycloak    | `https://your-keycloak-domain/realms/your-realm`  | [https://www.keycloak.org/docs](https://www.keycloak.org/docs)                                                                       |
| Custom OIDC | Check your provider's documentation               | See your provider's OIDC configuration                                                                                               |

## Need Help?

Contact Nudj support if you encounter any issues during setup or testing.