Authentication providers – signing in with an external identity provider¶
This chapter describes how users sign in to nexxcite with an account of an external identity provider (single sign-on) instead of a nexxcite password: which kinds of providers are supported, how a provider is set up and how nexxcite finds the user who belongs to an external account.
It is intended for administrators who connect nexxcite to the identity provider of their organisation.
1. External sign-in at a glance¶
nexxcite offers two ways to sign in. Both can be used side by side, also by the same user.
| Way | How the user signs in | Who checks the password |
|---|---|---|
| Internal sign-in | User name and password on the nexxcite sign-in page | nexxcite |
| External sign-in | The button "Sign in using …" on the sign-in page, then the page of the identity provider | The identity provider |
External sign-in uses OpenID Connect, the standard that identity providers such as Microsoft Entra ID, Okta, Keycloak or Active Directory Federation Services offer. Every provider is a definition in the Admin Studio under Access → Authentication Providers.
| Kind | Supported |
|---|---|
| OpenID Connect | Yes |
| SAML 2.0 | No. The entry "SAML2 Provider" in the menu for adding a provider has no function yet. |
| Signing in against LDAP / Active Directory directly | No. The "LDAP Credentials" are used by actions that read and change a directory, not for signing in (see API access and credentials). |
nexxcite does not create users from the provider automatically. Every user who signs in externally needs a user account in nexxcite that is linked to their external account (section 3).
The permissions "Open Authentication Provider Manager", "Add Authentication Provider", "Edit Authentication Provider" and "Delete Authentication Provider" are granted to system administrators by default.
2. Setting up an OpenID Connect provider¶
At the identity provider¶
Register nexxcite as an application with your identity provider. You need:
| Item | Value |
|---|---|
| Redirect address (reply URL) | https://<address of your nexxcite installation>/signin-oidc |
| Type of sign-in | nexxcite receives an ID token directly from the provider and uses no client secret. The provider has to allow this for the application. |
nexxcite always gives the provider an https redirect address, also when it runs behind a proxy that
forwards plain HTTP. Ports 80 and 443 are left out of the address.
How these settings are made depends on the provider – in Microsoft Entra ID, for example, the reply URL is entered under the authentication settings of the app registration, together with the option to issue ID tokens. Please refer to the documentation of your provider.
In nexxcite¶
- Open Admin Studio → Access → Authentication Providers and add an "Open ID Connect Provider".
- Fill in the fields:
| Field | Meaning |
|---|---|
| Name (header) | Shown on the sign-in page: "Sign in using |
| "Enabled" | Only enabled providers are offered on the sign-in page |
| "Authority" | The address of the provider, for example https://login.microsoftonline.com/<tenant id>/v2.0 for Microsoft Entra ID |
| "Client ID" | The ID of the application registered at the provider |
| "Identity Claim Type" | The claim in the provider's answer that identifies the user (section 3). Empty uses http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name. |
- Save. The sign-in page offers the provider right away.
A provider without "Authority" or "Client ID" is not offered, even when it is enabled.
3. Linking users to their external account¶
When the provider has confirmed a user, nexxcite reads one value from the provider's answer – the claim named in "Identity Claim Type" – and looks for the nexxcite user who is linked to this value.
The link is made in the user editor, tab "Ext Assignments" (see Users):
| Field | Meaning |
|---|---|
| "Authentication Provider" | The provider |
| "Claim Value" | The value the provider sends for this user in the identity claim |
A user can have assignments for several providers. Upper and lower case do not matter when the values are compared.
Example: The provider "Contoso Entra ID" has the identity claim type preferred_username. For the
nexxcite user jdoe, the tab "Ext Assignments" contains "Contoso Entra ID" with the claim value
jane.doe@contoso.com. When Jane signs in at Entra ID as Jane.Doe@contoso.com, nexxcite signs her
in as jdoe.
Choosing the identity claim¶
Choose a claim that is unique and does not change, and whose value you can enter for every user – for example the sign-in name or an object ID of the provider. Which claims are available and how they are named depends on the provider.
If a sign-in fails because the claim is missing, the user sees "Login failed" on the sign-in page, and the application log names the claim types the provider actually delivered. Use one of them.
4. What the user sees¶
| Situation | What happens |
|---|---|
| A linked user signs in | Back in nexxcite, signed in as the linked user |
| The provider reports an error | Sign-in page with "Error from external provider: …" |
| The identity claim is missing in the answer | Sign-in page with "Login failed" |
| No nexxcite user is linked, registration switched off | Page "Registration is disabled. You were authenticated successfully with …, but external registration is currently not available." |
| No nexxcite user is linked, registration switched on | Page "Associate your … account." (section 5) |
| The linked user is locked | Page "This account is locked" |
| All licenses are in use | Waiting screen, see Licensing |
What applies to external sign-ins¶
| Topic | Behaviour |
|---|---|
| Two-factor authentication | nexxcite does not ask for a second factor. Use the second factor of your provider. |
| Password policy and password expiry | Do not apply – the password is managed by the provider. |
| "Remember me" | Not offered. The session ends when the browser is closed. |
| Session lifetime, revalidation | The same as for the internal sign-in, see Sign-in and sessions |
| Permanent lock of the nexxcite user | Applies |
| Licenses | Taken as for the internal sign-in |
A user without a nexxcite password who uses "Forgot password?" receives a mail that names the provider they sign in with instead of a reset link.
5. External login registration¶
The setting "Enable external login registration" (Admin Studio → System → Settings, category "Login", default: on) decides what happens when the provider confirms a person for whom no nexxcite user is linked.
| Setting | Behaviour |
|---|---|
| Off | The person sees "Registration is disabled …" and is not signed in. |
| On | The person sees a page with their mail address (taken from the provider, if it sends one) and the button "Register". nexxcite creates a new user with the mail address as user name, no password and no roles, and signs them in. If a user with this name already exists and has a password, the person is asked for that password instead ("Associate Account"). |
Important: In the current version, registering or associating does not store the link to the external account. The next external sign-in of this person does not find their account again and fails. An administrator then has to add the assignment in the tab "Ext Assignments" of the user.
For administrators
- Switch "Enable external login registration" off and create the users with their assignments yourself. This is the reliable way in the current version.
- If you keep it on, check new users regularly: they have no roles until you assign them.
6. Several servers¶
A new, changed or deleted provider takes effect on the server on which it was saved immediately. The
other servers of the installation pick it up as soon as the change is published, if the servers are
connected through a message bus (Messaging:Provider = Redis, see
Running several servers). Without a message bus, they pick
it up only when they are restarted.
A change saved while a sketch is open applies on the server on which it was saved right away, but on the other servers only when the sketch is published. Until then, the servers offer different providers.
For administrators
- Save changes to authentication providers while no sketch is open.
- Without a message bus, restart the other servers after changing a provider.
7. Limitations¶
- Only OpenID Connect is supported. SAML 2.0 and a direct sign-in against LDAP are not available.
- nexxcite does not use a client secret with the provider and does not read groups or roles from it. Roles are always assigned in nexxcite.
- Users are not created or updated from the provider. The external login registration does not link the created account (section 5).
- With several servers and no message bus, a changed provider reaches the other servers only after a restart (section 6).
8. Frequently asked questions¶
Can a user sign in both with a password and with the provider? Yes, if their account has a password and an assignment to the provider.
Are roles taken over from groups in the identity provider? No. Roles are assigned to the user in nexxcite.
Does nexxcite ask users who sign in externally for a second factor? No. The second factor of the identity provider applies.
We locked a user in the identity provider. Can they still work in nexxcite? They can no longer sign in through the provider. A session that is already open keeps running until it ends; end it in Admin Studio → Access → Authenticated Users → "User Sessions".
Can several providers be offered at the same time? Yes. Every enabled provider gets its own button on the sign-in page.