Skip to main content
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.
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 instead.

​
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 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:

clientId

Your OAuth provider’s Client ID

clientSecret

Your OAuth provider’s Client Secret

issuer

The OIDC base URL (discovery endpoint) from your provider. Used for token verification.

​
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

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

​
Common OAuth Providers

ProviderIssuer URL FormatSetup Docs
Auth0https://your-domain.auth0.comhttps://auth0.com/docs/get-started
Oktahttps://your-domain.okta.comhttps://developer.okta.com/docs/guides/implement-oauth-for-okta/
Azure ADhttps://login.microsoftonline.com/{tenant}/v2.0https://docs.microsoft.com/en-us/azure/active-directory/
Keycloakhttps://your-keycloak-domain/realms/your-realmhttps://www.keycloak.org/docs
Custom OIDCCheck your provider’s documentationSee your provider’s OIDC configuration

​
Need Help?

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