Managing tenants
The Tenants page is where you create, review, edit and remove the identity tenants of a workspace. Open it from Tenants in the sidebar.
Every workspace member can open the page. Only admins can create, edit or delete a tenant.
The Tenants page
Section titled “The Tenants page”The page title is Tenants, with the description “Create, monitor, and manage identity tenants for this workspace.” It is one page with stacked sections, from top to bottom:
- A trial banner, only when it applies. See Tenant health.
- Create a tenant: three cards.
- Tenant topology: a live picture of the tenants.
- Manage existing tenants: the Tenant overview table.
Create a tenant
Section titled “Create a tenant”| Card | Caption | Guide |
|---|---|---|
| Okta | Workforce identity | Connect Okta |
| Auth0 | Customer identity | Connect Auth0 |
| Entra ID | Microsoft ecosystem | Connect Microsoft Entra ID |
Admins choose Connect on a card. Members and viewers see “Only workspace admins can create tenants.” and a disabled Admin Access Required button on each card.
The plan tenant limit
Section titled “The plan tenant limit”Each plan allows a number of tenants per workspace.
| Plan | Tenants per workspace |
|---|---|
| Pro | 3 |
| Max | 10 |
| Super | 25 |
The Tenants page does not warn you when the workspace is at the limit, and the Connect buttons stay active. You learn about the limit when you submit the create form: “Failed to create tenant: The <Plan> plan allows up to N tenants per workspace, and this workspace already has M. Upgrade the plan to add more.” Delete a tenant or upgrade the plan. See Plans and billing.
Tenant overview
Section titled “Tenant overview”The card Manage existing tenants (“Review configured tenants, update integrations, and remove tenants when decommissioning access.”) holds the Tenant overview table.
| Control | What it does |
|---|---|
| Search tenants… | Filters by tenant name or type. The table returns to page 1. |
| Name, Type, Created column headers | Select a header to sort. Select it again to reverse the order. |
| Type badge | Shows okta, auth0 or microsoft. An Entra ID tenant shows as microsoft. |
| Actions column | Icon buttons, described below. |
| Page buttons, Previous page, Next page | The table shows 5 tenants per page. The footer reads Showing X to Y of N tenants. |
Row actions
Section titled “Row actions”The actions are icon buttons with tooltips. There is no text button and no menu.
| Icon | Tooltip | Shown on | Who can use it |
|---|---|---|---|
| Pencil | Edit | Every row | Admins. Others see the tooltip “Admin access required to edit tenant” and a disabled button. |
| Line chart | API Metrics | Auth0 rows only | Everyone. See Auth0 API metrics. |
| Bin | Delete tenant | Every row | Admins. Others see the tooltip “Admin access required to delete tenant” and a disabled button. |
Empty states
Section titled “Empty states”| What you see | Meaning |
|---|---|
| No tenants added yet with “Add a tenant using the options above to get started.” | The workspace has no tenants. |
| No tenants match your search with “Try a different name or tenant type.” | The search box filters out every tenant. |
Tenant topology
Section titled “Tenant topology”The Tenant topology card (“Animated view of tenant integrations connected to the Identiguard control plane.”) is a picture, not a control. Nothing in it can be selected, and it has no legend or tooltips.
| Element | Meaning |
|---|---|
| Header “Avg requests per minute per tenant (last 24h)” | What the labels on the tenants measure |
| Badge Live view (green) or Refreshing… | Whether the figures are loaded or loading |
| Centre node Identiguard, “N connected tenant(s)”, “control plane” | The workspace, with the number of tenants |
| One coloured node per tenant, with its name and “X req/min” | The tenant and its traffic |
| Node Alex AI at the top right | The state of the Ask Alex service: “AI service · Online” (green), “AI service · Offline” (red) or “AI service · Checking…” (amber). It shows “Last seen <time>” when known. |
| “+N more tenants not shown in this preview.” | The picture draws 12 tenants at most |
| “No connected tenants to display yet.” | The workspace has no tenants |
The topology is not a health view. A tenant with broken credentials looks the same as a healthy one, except that it may show “0 req/min”. See Tenant health.
The Edit page
Section titled “The Edit page”Choose the pencil icon (Edit) on a row to open Edit Tenant. Only admins can open it.
The page has one or two cards:
- Tenant Configuration (“Update tenant details, subscriptions, and monitoring preferences.”), with the buttons Save Changes and Cancel. Every provider has it.
- Credentials, with its own button Validate & save credentials. Okta and Entra ID only.
Save Changes saves everything in Tenant Configuration. The button reads Saving… while it works. On success you return to the Tenants page. On failure a banner titled Error appears at the top of the Edit page. Back to Tenants and Cancel leave without saving.
Sections by provider:
| Section | Okta | Auth0 | Entra ID |
|---|---|---|---|
| Basic Details | Yes | Yes | Yes |
| Event Subscriptions | Yes | Yes | Yes |
| Reporting permissions (optional) | No | No | Yes |
| Agent Monitoring | Yes | No | No |
| Credentials card | Yes | No | Yes |
Basic Details
Section titled “Basic Details”Every provider has Tenant Name and Customer Name (placeholder “Select or type a customer”, with suggestions from the workspace). The tenant name follows the same rules as at creation: required, 100 characters or fewer, no line breaks.
You cannot change the domain or directory of a tenant, for any provider. Delete the tenant and create it again.
Okta adds:
- Environment: Production or Development.
Entra ID adds:
- Poll Interval (Minutes): from
5to1440(24 hours). The create form stops at 60, so this is where you set a longer interval.
Auth0 shows read-only values:
| Item | What it shows |
|---|---|
| Auth0 Domain | The tenant’s domain |
| Provisioning | Manual or Deployed via Terraform |
| Log stream endpoint | The endpoint URL only. The token is never shown again. |
| Text | “Identiguard stores no Auth0 API credentials for this tenant.” The log stream is managed in the Auth0 dashboard or in your Terraform configuration. To change the domain, delete and recreate the tenant. |
| Manual tenants | “Connection details are read-only. To change the domain or credentials, delete and recreate the tenant.” |
| Terraform tenants | A box identiguard.tf with View Terraform configuration and Hide Terraform configuration, and a Copy button (toast “Terraform configuration copied to clipboard”). A note says the ingestion token is not in this file. It was shown once at creation. If it is lost, delete and recreate the tenant. |
| Synthetic journeys | A summary of the tenant’s journeys, or “Synthetic journey monitoring is available on Max and Super plans.” when journeys are not switched on for the workspace. See Journeys. |
The Auth0 Edit page has nothing for the metric stream or for Action logs. See Connect Auth0.
Event Subscriptions
Section titled “Event Subscriptions”This section is how you change which events a tenant sends after creation. It has the same picker as the create form, under the label Subscribed Event Types.
| Control | What it does |
|---|---|
| Search event types… | Filters the list. Shown when the list has more than 10 types. |
| Select Recommended | Auth0 only. Replaces the whole selection with the recommended set. |
| Select All | Ticks every type. While you search, it becomes Select All Visible. |
| Clear All | Unticks everything. |
| N of M selected | The current count. At least one type must be ticked. |
What saving does is different for each provider:
| Provider | On-screen text | Effect of Save Changes |
|---|---|---|
| Okta | “Updating this list changes the Okta event hook immediately.” | Identiguard rewrites the event hook in the Okta org at once. |
| Entra ID | “Updating this list changes the Microsoft subscription immediately.” | Identiguard polls the new set of streams from the next poll. |
| Auth0 | “Updating this list changes which Auth0 log events are ingested. Takes effect immediately; no changes are made in Auth0.” | Only what Identiguard keeps changes. The Auth0 stream still sends everything it is configured to send. |
For the task steps, see Change which events a tenant sends.
Reporting permissions (Entra ID)
Section titled “Reporting permissions (Entra ID)”Reporting permissions (optional) checks the app registration live each time the page loads. The on-screen instruction reads “Add these as application permissions on the app registration in the Entra admin centre, then select Grant admin consent.”
Each of six rows shows Granted or Not granted:
| Permission | Used for | Also counts as granted with |
|---|---|---|
Reports.Read.All |
MFA coverage (also needs Entra ID P1) | AuditLog.Read.All |
RoleManagement.Read.Directory |
Global Administrator count | RoleManagement.Read.All or Directory.Read.All |
Policy.Read.All |
Conditional Access inventory | |
Application.Read.All |
App credential expiry | Directory.Read.All |
SecurityEvents.Read.All |
Microsoft Secure Score | |
IdentityRiskyUser.Read.All |
Current risky users |
To fix a Not granted row:
- In the Entra admin centre, open the app registration and go to API permissions.
- Add the missing Microsoft Graph application permission.
- Choose Grant admin consent.
- Reload the Edit page. There is no refresh button.
Agent Monitoring (Okta)
Section titled “Agent Monitoring (Okta)”Agent Monitoring (“Track AD and LDAP agent health on a recurring schedule.”) has two panels: Monitor AD Agents and Monitor LDAP Agents. It needs the Okta scope okta.agentPools.read.
To switch a monitor on or off, or to change its interval:
- Open Tenants and choose the pencil icon (Edit) on the Okta tenant.
- Under Agent Monitoring, tick or untick Monitor AD Agents and Monitor LDAP Agents.
- For each ticked monitor, choose Check Interval (minutes):
5,10,15,30,60or120. While a monitor is unticked, the helper reads “Enable monitoring to configure the check interval.” - Choose Save Changes.
- Open the Edit page again, or look at the tenant’s card on the Dashboard, and read Status: and Last check:.
Opening the Edit page runs a fresh check of each monitor that is on. For the meaning of each status, see Tenant health.
Credentials (Okta and Entra ID)
Section titled “Credentials (Okta and Entra ID)”The Credentials card (“Rotate the client secret (and optionally the client ID) used to connect to Okta.” or “…to Microsoft.”) is a separate form. Save Changes does not submit it.
| Item | Detail |
|---|---|
| Heading Rotate credentials | “New credentials are verified against Okta before being saved.” (or Microsoft) |
| Client ID (optional) | Placeholder “Enter new client ID (leave blank to keep current)” |
| Client Secret | Placeholder “Enter new client secret” |
| Button Validate & save credentials | Reads Validating… while it checks |
| Alert Verified | “Credentials updated and verified against Okta.” or “…against Microsoft.” |
| Alert Credentials rejected | The reason. Nothing was saved. |
| Alert Monitoring paused | Shown when a monitor has paused itself. See Tenant health. |
For the steps, see Rotate credentials.
Rename a tenant or change its customer
Section titled “Rename a tenant or change its customer”- Open Tenants and choose the pencil icon (Edit).
- Under Basic Details, change Tenant Name or Customer Name. For Okta you can also change Environment.
- Choose Save Changes.
Change the Entra ID poll interval
Section titled “Change the Entra ID poll interval”- Open Tenants and choose the pencil icon (Edit) on the Entra ID tenant.
- Under Basic Details, set Poll Interval (Minutes) from 5 to 1440.
- Choose Save Changes.
A longer interval means events arrive later.
Delete a tenant
Section titled “Delete a tenant”Only admins can delete a tenant. Deleting cannot be undone. It removes the tenant’s stored data from Identiguard: its event history, its reports and its monitor state. It also revokes the tenant’s ingestion tokens.
- Open Tenants.
- In Tenant overview, choose the bin icon (Delete tenant) on the row.
- Read the dialog Delete tenant: <name>. It says what Identiguard does and does not remove on the provider side.
- Choose the red Delete tenant button, or Cancel.
- Accept the browser’s confirmation prompt.
The dialog closes and the table refreshes.
What happens on the provider side
Section titled “What happens on the provider side”| Provider | What Identiguard does | What you must do afterwards |
|---|---|---|
| Okta | Deactivates and removes the Okta event hook, then deletes the tenant. The dialog shows the Event Hook ID so you can check the clean-up in Okta. It can read “Loading…” or “Event Hook ID not available”. | Remove the Identiguard integration in Okta if the client is leaving. |
| Auth0, manual | Nothing in Auth0. Identiguard stores no Auth0 credentials and cannot remove the streams. | Delete the log stream, and the metric stream if there is one, in the Auth0 dashboard. |
| Auth0, Terraform | Nothing in Auth0. | Run terraform destroy, or delete the log stream in Auth0. |
| Entra ID | Stops polling Microsoft Graph. Nothing is changed inside the Entra ID tenant. | Revoke the app registration’s secret if you no longer need it. |
Force delete
Section titled “Force delete”Force delete tenant is not a standing option. It appears only inside the dialog, and only after a normal delete fails because Identiguard could not remove the Okta event hook. In practice it applies to Okta tenants only.
- A normal delete fails with “Failed to delete tenant: Failed to remove Okta event hook.”
- The dialog shows a red box Could not remove the Okta event hook: “Looks like the event hook has already been deleted on Okta, or Okta is not responding. You can force delete this tenant instead - its stored data (including event history) will be removed from Identiguard without making any further changes in Okta.”
- The button changes to Force delete tenant. Choose it.
- Accept the browser’s confirmation prompt.
- In Okta, go to Workflows → Event Hooks. If the
IG_Tenant_hook for this tenant still exists, deactivate and delete it yourself.
Troubleshooting
Section titled “Troubleshooting”Tenants page
Section titled “Tenants page”| What you see | Why | What to do |
|---|---|---|
| “Could not load tenants.” | The tenant list failed to load | Reload the page. Check that you still have access to the workspace. |
| “Only workspace admins can create tenants.” and Admin Access Required | Your role is member or viewer | Ask a workspace admin. |
| Disabled pencil or bin with “Admin access required to edit tenant” or “Admin access required to delete tenant” | Your role is member or viewer | Ask a workspace admin. |
| No line-chart icon on a row | API Metrics exists for Auth0 tenants only | Nothing. |
An Entra ID tenant shows microsoft |
The Type badge shows the stored type | Nothing. Search for microsoft to find Entra ID tenants. |
| No message after you create or edit a tenant | The Tenants page does not show a confirmation | Check the row in Tenant overview. |
| “Failed to create tenant: The <Plan> plan allows up to N tenants per workspace, and this workspace already has M. Upgrade the plan to add more.” | The plan tenant limit | Delete a tenant or upgrade the plan. |
| “0 req/min” for every tenant in the topology | No events in 24 hours, or the traffic figures failed to load | Reload the page, then check the Dashboard. |
| “AI service · Offline” in the topology | The Ask Alex service is not answering | See Ask Alex. |
Edit page
Section titled “Edit page”These appear in the Error banner at the top of the Edit page.
| What you see | Why | What to do |
|---|---|---|
| “At least one event type must be selected” | Nothing is ticked under Subscribed Event Types | Tick at least one. |
| “Invalid Microsoft event type submitted” or “Invalid Auth0 event type submitted” | The page sent a type that is not on the allowed list | Reload the page and select again. |
| “Customer name cannot be empty” | Customer Name was cleared | Enter the customer. |
| “At least one field (…) must be provided for update.” | The form was sent with nothing to change | Change a value, then save. |
| “Failed to update Okta event hook: <Okta message>” | Okta rejected the hook update. Common causes: the secret has expired, or a scope is missing. | Rotate the credentials first, then save again. |
| “Okta event hook ID missing from configuration; recreate the event hook before updating.” | The tenant has no stored hook ID | Delete the tenant and create it again. There is no screen to recreate the hook alone. |
| “Okta tenant configuration missing encrypted secrets; recreate the event hook before updating.”, “Failed to decrypt Okta credentials. Please recreate the event hook and try again.” or “Okta configuration is missing client details; please recreate the tenant.” | The stored credentials cannot be used | Delete the tenant and create it again. Escalate to the product team. |
| “Failed to update Auth0 tenant: <message>”, “Failed to update Microsoft tenant: <message>” or “An unexpected error occurred: …” | A server error | Try again, then escalate. |
| “Forbidden: Insufficient permissions. Admin role required to update tenant.” | You are not an admin | Ask a workspace admin. |
| “Editing is not supported for this tenant type.”, “Tenant not found” or “Internal Server Error” | An unexpected error | Escalate to the product team. |
| “Could not load reporting permissions.” | The permission check failed to load | Reload the page. |
| “Could not read the app registration permissions. Check the tenant credentials.” | Identiguard could not sign in to read the app registration | Rotate credentials, then reload. |
| Not granted on a reporting permission | The permission is missing, or admin consent is not granted | Add the permission, choose Grant admin consent, reload the page. |
| “Synthetic journey monitoring is available on Max and Super plans.” | Journeys are not switched on for the workspace | Needs the Max or Super plan, and a platform operator switches journeys on for the workspace. |
| A locked agent checkbox with “Monitoring paused after repeated failures - rotate the credentials below to resume.” | The monitor paused itself | Rotate credentials. |
| Alert Credentials rejected | The new credentials failed the check | See Rotate credentials. |
Delete
Section titled “Delete”| What you see | Why | What to do |
|---|---|---|
| “Failed to delete tenant: Failed to remove Okta event hook.” and the box Could not remove the Okta event hook | Okta refused or did not answer. The hook may already be deleted, the credentials may be revoked, or Okta may be down. | Choose Force delete tenant. Then remove the hook in Okta by hand if it still exists. |
| “Failed to delete tenant: Failed to cleanup tenant event history.”, “Failed to delete tenant: Failed to cleanup tenant monitor state.” or “Failed to delete tenant: Failed to delete tenant report artifacts.” | An internal clean-up step failed. Force delete is not offered for these. | Try again. If it repeats, escalate to the product team. |
| “Failed to delete tenant: API Error”, “An unexpected error occurred.” or “Failed to delete tenant.” | An unexpected server error | Try again, then escalate. |
| “Forbidden: Insufficient permissions. Admin role required.” | You are not an admin | Ask a workspace admin. |
| “Event Hook ID not available” in the dialog | The tenant has no stored hook ID | For information only. You can still delete. |
| Auth0 shows delivery failures on the stream after the delete | The stream still points at the revoked endpoint | Delete the stream in Auth0, or run terraform destroy. |