Skip to main content

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.

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’.

​
Quick Start

1

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 instead.
2

Add OIDC Configuration in Nudj

Navigate to Organisation Settings → Authentication in the admin panel 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.
3

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. Paste the fully-resolved URL into your OAuth/OIDC provider’s allowed redirect list.
4

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.

​
Troubleshooting

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.
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.

​
When to Use This Method

Use OAuth Method

  • Users arrive directly at Nudj not authenticated
  • Users initiate login from Nudj interface
  • Standard authorization flow required
  • Redirects to your login system acceptable

Use API Link Instead

  • Users already authenticated elsewhere
  • Seamless session continuation needed
  • No login screen should be shown
  • Direct JWT-based authentication preferred

→ API Link User Token Auth

Alternative Method: For users already authenticated elsewhere who need seamless session continuation

→ Enterprise SSO Overview

Overview: Complete guide to all enterprise authentication options and patterns

→ Integration Overview

Next Steps: Understand access patterns and reward delivery after authentication setup