# Custom identity

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

![](https://www.agilicus.com/www/ca24985b-featured-anyx-admin-authenticationcustom-identity.png)## Custom identity

[CONTACT](/contact-us/)

The **Custom Identity** page (route `/custom-identity`) is where you register your own OpenID Connect identity providers. Unlike [Shared Identity](/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](/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](/anyx-guide/agilicus-anyx-administrative-web-interface/authentication/overview/), and sign-in attempts are in the [authentication audit](/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](/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](/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](/anyx-guide/agilicus-anyx-administrative-web-interface/access/application-permissions/)).

## See also

- [Identity and authentication](/anyx-guide/agilicus-anyx-administrative-web-interface/concepts/identity-and-authentication/)
- [Authentication overview](/anyx-guide/agilicus-anyx-administrative-web-interface/authentication/overview/)
- [Shared identity](/anyx-guide/agilicus-anyx-administrative-web-interface/authentication/shared-identity/)
- [Onsite identity](/anyx-guide/agilicus-anyx-administrative-web-interface/authentication/onsite-identity/)
- [Application identity](/anyx-guide/agilicus-anyx-administrative-web-interface/authentication/application-identity/)
- [Getting started: identify users](/anyx-guide/agilicus-anyx-administrative-web-interface/getting-started/identify-users/)
- [Groups](/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)