# Custom identity - Link: https://www.agilicus.com/anyx-guide/agilicus-anyx-administrative-web-interface/authentication/custom-identity/ - Published: 2026-08-24T01:47:17+00:00 - Author: Don Bowman 1. [Home](https://www.agilicus.com/) 2. [Agilicus AnyX Administrative Web Interface](https://www.agilicus.com/anyx-guide/agilicus-anyx-administrative-web-interface/) 3. [Authentication](https://www.agilicus.com/anyx-guide/agilicus-anyx-administrative-web-interface/authentication/) 4. Custom identity ![ca24985b-featured-anyx-admin-authenticationcustom-identity](https://www.agilicus. com/www/ca24985b-featured-anyx-admin-authenticationcustom-identity.png) ## Custom identity [CONTACT](https://www.agilicus.com/contact-us/) The **Custom Identity** page (route `/custom-identity`) is where you register your own OpenID Connect identity providers. Unlike [Shared Identity](https://www.agilicus.com/anyx-guide/agilicus-anyx-administrative-web-interface/authentication/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. ![Custom identity overview](https://www.agilicus.com/www/612286e6-custom-identity- overview.png) ## 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](https://www.agilicus.com/product-guide/authentication-issuer) 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](https://www.agilicus.com/product-guide/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 1. Open **Authentication > Custom Identity** from the left navigation. 2. The table lists your existing OpenID Connect providers. Select **ADD PROVIDER** to add one. ![Add provider, step 1: choose provider](https://www.agilicus.com/www/ce4525eb-custom- identity-add-provider-step1.png) 1. 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**. ![Azure selected](https://www.agilicus.com/www/c580a585-custom-identity-add-azure- step1-selected.png) **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**. ![Register the Azure application](https://www.agilicus.com/www/3895b193-custom-identity- azure-register-app.png) **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. ![Azure app information with tenant error](https://www.agilicus.com/www/682d382b- custom-identity-azure-tenant-error.png) **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. ![Other selected](https://www.agilicus.com/www/9faea6cd-custom-identity-add-other- selected.png) ![New provider row](https://www.agilicus.com/www/c677fa1f-custom-identity-new-row. png) 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. ![Completed provider row](https://www.agilicus.com/www/19632e7d-custom-identity- guide-demo-row.png) 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. ![Provider row actions](https://www.agilicus.com/www/b8745722-custom-identity-row- actions-menu.png) In the dialog, add mappings from the upstream group names to portal group names, with a priority order, and optionally list excluded groups. ![Group mappings dialog](https://www.agilicus.com/www/19632e7d-custom-identity-group- mappings-dialog.png) ![Group mapping added](https://www.agilicus.com/www/682d382b-custom-identity-group- mapping-added.png) ### 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](https://www.agilicus.com/anyx-guide/agilicus-anyx-administrative-web-interface/resources/applications/) 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](https://www.agilicus.com/anyx-guide/agilicus-anyx-administrative-web-interface/authentication/overview/), and sign-in attempts are in the [authentication audit](https://www.agilicus.com/anyx-guide/agilicus-anyx-administrative-web-interface/organisation/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](https://www.agilicus.com/anyx-guide/agilicus-anyx-administrative-web-interface/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](https://www.agilicus.com/anyx-guide/agilicus-anyx-administrative-web-interface/access/groups/)). * **Auto-created users have no access**: auto-creation only makes the user exist; assign permissions separately (see [Application permissions](https://www.agilicus.com/anyx-guide/agilicus-anyx-administrative-web-interface/access/application-permissions/)). ## See also * [Identity and authentication](https://www.agilicus.com/anyx-guide/agilicus-anyx-administrative-web-interface/concepts/identity-and-authentication/) * [Authentication overview](https://www.agilicus.com/anyx-guide/agilicus-anyx-administrative-web-interface/authentication/overview/) * [Shared identity](https://www.agilicus.com/anyx-guide/agilicus-anyx-administrative-web-interface/authentication/shared-identity/) * [Onsite identity](https://www.agilicus.com/anyx-guide/agilicus-anyx-administrative-web-interface/authentication/onsite-identity/) * [Application identity](https://www.agilicus.com/anyx-guide/agilicus-anyx-administrative-web-interface/authentication/application-identity/) * [Getting started: identify users](https://www.agilicus.com/anyx-guide/agilicus-anyx-administrative-web-interface/getting-started/identify-users/) * [Groups](https://www.agilicus.com/anyx-guide/agilicus-anyx-administrative-web-interface/access/groups/) ## Web guide * [Authentication Issuer: Custom Identity](https://www.agilicus.com/product-guide/authentication-issuer) * [When should I use a custom identity provider?](https://www.agilicus.com/when-should-i-use-a-custom-identity-provider) * [Identity group mapping](https://www.agilicus.com/product-guide/identity-group-mapping)