Custom identity

The Custom Identity page (route /custom-identity) is where you register your own OpenID Connect identity providers. Unlike Shared Identity, you create the application registration with the third party yourself, which gives you full control over scopes, secrets, and how identities are mapped into the platform.

Purpose

Custom identity manages upstream identity providers that speak OpenID Connect, for example Google Workspace, Microsoft Entra ID (Azure Active Directory), Okta, or any provider that supports the standard. Each provider appears as a row in a table on this page and becomes a sign-in option on your organisation’s issuer page at the URL shown above the table.

The page covers the whole lifecycle: adding a provider (with a guided wizard for Azure and a blank-row flow for any other OpenID Connect provider), editing a provider’s properties inline in the table, deleting providers, and configuring automatic group mappings from an upstream provider’s groups. See the web guide’s Authentication Issuer: Custom Identity for the concept behind it.

Why use it

Use your corporate identity provider (for example Google Workspace or Microsoft Entra ID) as the source of identity for your users.
Keep full control over the client registration, scopes, and settings rather than relying on a managed provider.
Map groups from your identity provider to portal groups automatically, so your existing group structure drives permissions (see Identity group mapping).
Auto-create users in the platform on their first successful sign-in.

When to use it

When you need a provider that is not in the managed shared set, or you want your own client registration.
When you want single sign-on from a corporate directory that the shared identity screen does not cover.
When you need group mappings or auto-provisioning from the upstream provider.

Prerequisite: permission to administer issuers (an owner or administrator role). The page shows a no permissions message otherwise. You also need the client ID (and secret, if used) from your third-party provider’s application registration.

How to use it

Open Authentication > Custom Identity from the left navigation.
The table lists your existing OpenID Connect providers. Select ADD PROVIDER to add one.

Choose the provider type:

Azure Active Directory runs a guided wizard that walks you through registering the application in Azure.
Other creates a blank row in the table that you complete inline.

The Azure Active Directory flow

Select Azure Active Directory, then select Next.

Register Azure Application. The wizard shows the Azure portal steps and the redirect URI to use when you register the application. Copy the redirect URI, then select Next.

Azure App Information. Enter the application Name, Client ID, and Tenant ID from the application’s Overview pane in Azure. The wizard validates the tenant ID against Microsoft; an invalid tenant shows an error under the field.

Choose Authentication Method. Select Federated Credentials (workload identity federation) or Client Secret. The following step provides the matching guidance and fields. Then select Apply and Add to save the provider.

The Other flow

Select Other, then select Add. The dialog closes and a new blank row appears in the table, ready for you to complete the provider’s properties inline.

Complete the row: a display Name, the Issuer URI, an Icon identifier, the Client Id, the Secret (if your provider uses one), and the toggle options (Federated Credential, Auto Create, Offline Consent, Request user info, Verifies Email). Leave the fields as they are and the row saves.

The Redirect URI column shows the callback URI your provider must accept (for example https://auth.ca-1.agilicus.ca/callback).

Configuring group mappings

Select the more (vertical ellipsis) action on a provider row and choose Configure Group Mappings to open the group mappings dialog.

In the dialog, add mappings from the upstream group names to portal group names, with a priority order, and optionally list excluded groups.

Deleting providers

Tick the checkbox on the rows you want to remove, then select DELETE PROVIDERS. The providers are marked for removal from the issuer immediately; the change propagates to the sign-in flow within a few seconds.

Fields and controls reference

Table columns

Column	Purpose	Editable	Notes
Name	The provider’s display name on the sign-in page	Yes	Required; up to 100 characters
Issuer	The upstream OpenID Connect issuer URI	Yes	Required
Icon	The icon identifier used on the sign-in page	Yes
Client Id	The client ID from your application registration	Yes	Required
Secret	The client secret, if your provider uses one	Yes	Leave blank for federated credentials
Federated Credential	Whether the client uses workload identity federation	Yes	Toggle
Auto Create	Whether users are created automatically on first sign-in	Yes	Default, active, pending, or disabled; avoid with public providers
Type	The OpenID Connect flavour	Yes	Generic or Microsoft
Offline Consent	Whether refresh (offline) flows are allowed	Yes	Toggle
Request user info	Whether user information is requested from the user-info endpoint	Yes	Toggle
Issuer External Host	An external host override for the issuer, when needed	Yes	Usually blank
Username Key	The claim that carries the username	Yes	Usually blank
User Id Key	The claim that carries the user’s stable identifier	Yes
Email Key	The claim that carries the email address	Yes	Often `email`
Verifies Email	Whether the provider verifies email addresses	Yes	Toggle
Redirect URI	The callback URI your provider must accept	Read-only	Built from your issuer
Actions	Row menu: Configure Group Mappings	n/a

Buttons

Control	Purpose
ADD PROVIDER	Opens the Certificates & Secrets dialog (the add-provider wizard)
DELETE PROVIDERS	Deletes the ticked providers

Dialogs and popups

Upstream provider setup (Add provider)

The Certificates & Secrets dialog is a wizard with up to seven steps: Choose Provider, Register Azure Application, Azure App Information, Choose Authentication Method, Federated Credential (or Client Secret), Apply, and Done. The Other flow collapses to a single step that creates a blank table row. The final Done step offers a CONFIGURE IDENTITY PROVIDER ALIASES button that takes you to the authentication clients screen.

Upstream group mappings

The Group Mappings dialog maps upstream groups to portal groups:

Control	Purpose
Input group	The group name as it arrives from the identity provider
Output group	The portal group to map it to
Priority	Order of evaluation when more than one mapping applies
ADD GROUP MAPPING	Adds a new mapping row
DELETE GROUP MAPPINGS	Removes the ticked mappings
MAP ALL GROUPS	Imports all upstream groups as-is
ADD EXCLUDED GROUP / DELETE EXCLUDED GROUPS	Maintains the list of upstream groups that are never imported

Configuration versus diagnostics versus confirmation

Configuration: adding, editing, and deleting providers; the auto-create status; the toggle options; and the group mappings.
Diagnostics: the table is an inventory. Live provider health is on the Authentication Overview, and sign-in attempts are in the authentication audit.
Confirmation: DELETE PROVIDERS removes the ticked providers with no second confirmation. Deleting a provider that users rely on stops those users from signing in once the change propagates.

Pagination and async behaviour

The table pages at 25 rows per page. The paginator shows the total, for example 1 – 2 of 2; use the paginator to move through larger lists.
Changes save asynchronously. After adding, editing, or deleting a provider, wait a few seconds and reload the page to confirm. The sign-in page updates after the issuer change propagates.

Troubleshooting

The Azure tenant validation fails: confirm the tenant ID is correct and that the tenant exists in Microsoft Entra ID. The wizard checks the tenant’s OpenID configuration directly.
Users cannot sign in with a new provider: confirm the Redirect URI shown in the table is registered as an authorised redirect in your third-party application registration.
A provider appears in the table but not on the sign-in page: check the provider’s operational status on the Authentication Overview and allow time for propagation.
Group mappings do not apply: check the upstream group names exactly match what the provider sends, and that the output groups exist in the portal (see Groups).
Auto-created users have no access: auto-creation only makes the user exist; assign permissions separately (see Application permissions).