Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/gnmyt/Nexterm/llms.txt

Use this file to discover all available pages before exploring further.

OIDC single sign-on lets users log in to Nexterm using their existing identity provider credentials. When a user clicks the sign-in button, Nexterm redirects them to your IdP, receives a token on callback, reads the user’s claims, and creates or updates a local account automatically. You can add multiple OIDC providers; each one appears as a separate button on the login page.

​
How it works

When a user initiates an OIDC login, Nexterm:
  1. Discovers the IdP configuration from the issuer URL’s /.well-known/openid-configuration endpoint.
  2. Builds an authorization URL with PKCE and redirects the user’s browser to the IdP.
  3. Receives the authorization code at the callback URL.
  4. Exchanges the code for tokens and fetches the userinfo endpoint.
  5. Maps claims to Nexterm fields (username, firstName, lastName) and creates or updates the account.
  6. Issues a Nexterm session token and logs the user in.
Nexterm stores a randomly generated placeholder password for OIDC-provisioned accounts. This password is never exposed and cannot be used to log in directly.

​
Adding a provider

1

Open authentication settings

Go to Settings → Authentication. You will see any existing providers listed here, along with the built-in internal provider.
2

Add a new provider

Click Add Provider and fill in the fields described in the table below.
3

Copy the redirect URI

Nexterm pre-fills the Redirect URI field. Copy this value — you will need to register it in your identity provider before the login flow will work.
4

Save and enable

Save the provider. Toggle it to enabled once you have registered the redirect URI in your IdP.

​
Provider fields

FieldDescription
Display NameLabel shown on the login button, for example Sign in with Okta.
Issuer URLYour IdP’s base URL. Nexterm appends /.well-known/openid-configuration to discover endpoints.
Client IDThe application/client ID assigned by your IdP when you registered the application.
Client SecretThe client secret from your IdP. Stored encrypted at rest using your ENCRYPTION_KEY.
Redirect URIPre-filled by Nexterm. Register this exact URL in your IdP.
ScopeOAuth scopes to request. Defaults to openid profile. Add email if your username mapping uses the email claim.

​
Provider-specific setup

1

Register an application

Open the Azure Portal, navigate to Microsoft Entra ID → App registrations, and click New registration. Give it a name such as Nexterm.
2

Add the redirect URI

Under Redirect URIs, add the URI from Nexterm’s provider form:
https://nexterm.yourdomain.com/api/auth/oidc/callback
Select Web as the platform type.
3

Copy the client ID

From the Overview page, copy the Application (client) ID and paste it into Nexterm’s Client ID field.
4

Create a client secret

Go to Certificates & secrets → Client secrets → New client secret. Set an expiry, create the secret, and copy the Value into Nexterm’s Client Secret field.
5

Set the issuer URL

Use the following URL, replacing {tenant-id} with your directory (tenant) ID from the Overview page:
https://login.microsoftonline.com/{tenant-id}/v2.0
1

Create OAuth credentials

Open the Google Cloud Console, navigate to APIs & Services → Credentials, click Create Credentials, and choose OAuth client ID. Select Web application as the application type.
2

Add the redirect URI

Under Authorized redirect URIs, add:
https://nexterm.yourdomain.com/api/auth/oidc/callback
3

Copy the client credentials

Copy the Client ID and Client Secret shown after creating the credential.
4

Set the issuer URL

https://accounts.google.com
Google requires OAuth consent screen verification for production use. During development, add your test users under OAuth consent screen → Test users so they can log in before verification is complete.
1

Create a client

In your Keycloak realm, go to Clients → Create client. Set the Client ID and enable Client authentication.
2

Add the redirect URI

Under Valid redirect URIs, add:
https://nexterm.yourdomain.com/api/auth/oidc/callback
3

Copy the client secret

Go to the Credentials tab and copy the Client secret.
4

Set the issuer URL

Replace {realm-name} with the name of your realm:
https://keycloak.yourdomain.com/realms/{realm-name}
1

Create a provider

In Authentik, go to Applications → Providers → Create and select OAuth2/OpenID Provider.
2

Configure the redirect URI

Set the Redirect URIs to:
https://nexterm.yourdomain.com/api/auth/oidc/callback
3

Copy the client credentials

After saving, note the Client ID and Client Secret from the provider detail page.
4

Set the issuer URL

Replace {application-slug} with the slug you set when creating the application:
https://authentik.yourdomain.com/application/o/{application-slug}/
The trailing slash in the issuer URL is significant. To confirm the exact value your instance expects, open https://authentik.yourdomain.com/application/o/{application-slug}/.well-known/openid-configuration and read the issuer field.
Add a client entry to your Authelia configuration:
identity_providers:
  oidc:
    clients:
      - client_id: nexterm
        client_secret: '$pbkdf2-sha512$your-hashed-secret'
        redirect_uris:
          - https://nexterm.yourdomain.com/api/auth/oidc/callback
        scopes: [openid, profile, email]
Set Nexterm’s issuer URL to your Authelia base URL:
https://auth.yourdomain.com
Use the plaintext version of your client_secret value in Nexterm’s Client Secret field. Authelia expects the hashed form in its configuration file.

​
Attribute mapping

Nexterm maps claims from the userinfo endpoint (or ID token fallback) to account fields. The defaults work for most standard OIDC providers. You can override them in the provider’s Advanced Settings.
Nexterm fieldDefault claimNotes
Usernamepreferred_usernameFalls back to email, then sub if the configured claim is absent.
First namegiven_nameSet to empty string if absent.
Last namefamily_nameSet to empty string if absent.
When a user logs in, Nexterm always updates the first and last name from the current claims. The username is matched to find an existing account and is not changed after initial creation.

​
Troubleshooting

The redirect URI registered in your IdP must match the value shown in Nexterm exactly — including protocol (https vs http), trailing slashes, and port numbers. Even a single character difference causes the IdP to reject the callback.Copy the URI directly from Nexterm’s provider form rather than typing it manually.
If the username or name fields are populated incorrectly, the claim names from your IdP may differ from Nexterm’s defaults. Check the actual claim names by inspecting the ID token or userinfo response from your IdP, then update the Attribute Mapping fields in the provider’s Advanced Settings to match.
Nexterm fetches the OIDC discovery document at startup of each login flow. If the issuer URL is wrong or unreachable, the login will fail immediately.Verify the issuer URL by opening {issuer-url}/.well-known/openid-configuration in a browser. You should see a JSON document listing the authorization endpoint and other metadata.

Build docs developers (and LLMs) love

Get started for freeTalk to us