Skip to main content
Connect FusionAuth to Oleria to see who can sign in through your FusionAuth instance: its users in every tenant, the groups they belong to, the applications they’re registered for, the roles they hold, and the Entities and client secrets that act as non-human identities. Oleria reads this data with a FusionAuth API key. You can add a second API key for Oleria’s remediation actions.

​
What Oleria discovers

Once connected, Oleria continuously discovers and maps the following from every tenant of your FusionAuth instance:
  • Accounts - every user, with name, email address, username, and whether the user is enabled. A user is enabled when FusionAuth marks it active and its expiry date, if it has one, hasn’t passed. Oleria also shows when each user was created, last modified, and last changed their password, the user’s expiry date and tenant, whether the user is verified, whether a password change is required, and the breached-password status FusionAuth reports. Last activity is the latest sign-in FusionAuth records for the user, their application registrations, their identity provider links, and their passkeys.
  • Sign-in methods, MFA, and SSO - each user’s FusionAuth password, when they’ve set one, the authenticator app, SMS, and email codes they’ve enrolled, the identity providers they’re linked to, and their passkeys. MFA comes from the tenant’s multi-factor login policy and the codes the user has enrolled: If the tenant has no login policy, MFA shows as unavailable. SSO shows as required for a user who is linked to an identity provider and has no FusionAuth password, as configured for a linked user who also has a password, and as not configured otherwise.
  • Administrators - users with any role in the built-in FusionAuth application, which controls the FusionAuth admin console, and users with the admin role in the Tenant manager application, are marked as administrators. Each administrator’s account role is the highest of these roles they hold, in this order: FusionAuth admin; user_manager, user_deleter, tenant_manager, api_key_manager, system_manager, or key_manager; any other FusionAuth role; Tenant manager admin. Their other admin roles appear as secondary roles. Other users show the account role user.
  • Tenants - each tenant appears as a built-in group named Tenant: <tenant name>, with every user of the tenant as a member. The group shows the tenant’s multi-factor login policy, the sign-in methods the tenant enables, and its password rules: minimum length, required character types, whether previous passwords can be reused, and maximum password age.
  • Groups - every FusionAuth group and its members. The roles a group grants appear on the group, as <application ID>:<role name>. FusionAuth gives a group’s roles only to members who are registered for that application, so Oleria shows them as roles held through each member’s registration. See Roles.
  • Roles - every application role, named <application name>: <role name>, with its description and when it was created and last modified. Roles of the FusionAuth and Tenant manager applications are standard roles. Roles of your own applications are custom roles. A user holds a role when their registration for the application includes it. Each role a user holds shows whether it’s granted directly or by a group, with the IDs of the granting groups. FusionAuth reports a single combined list of a user’s roles, so a role that one of the user’s groups grants shows as granted by group, even if it’s also granted directly.
  • Applications - every application except the built-in FusionAuth and Tenant manager applications, which are FusionAuth itself. Each application shows its OAuth client ID, its SAML issuer when SAML is enabled, whether it’s active, whether it requires registration, whether self-service registration is on, its enabled OAuth grants, its client authentication policy, and whether it’s universal. It also shows the multi-factor policy that applies: the application’s own policy when it has one, otherwise its tenant’s.
  • Application access - each user registered for an application has access to it, with the roles in their registration. When an active application doesn’t require registration, any user of its tenant can sign in to it, so Oleria also shows access to it from the tenant’s group, marked as inferred. For a universal application, or one with no tenant, that access comes from every tenant group.
  • Non-human identities: Each client secret also appears as a credential. Oleria records that a secret exists, never its value. FusionAuth doesn’t report when a client secret was created or regenerated, so client secrets show no creation or modification date.
  • Activity:
    • Successful sign-ins, from FusionAuth’s login records, with the user, application, login ID, IP address, and location when FusionAuth records one. FusionAuth writes a login record when a login completes, including through an identity provider or passwordless login, when a two-factor login completes, when a refresh token is exchanged for a new token, and when a user is created with a password. Sign-ins to the FusionAuth admin console, to the Tenant manager, or to no application are linked to the FusionAuth instance. Other sign-ins are linked to their application.
    • Failed sign-ins, when FusionAuth records them in its Webhook Event Log. See Record failed sign-ins. Each shows the user, application, IP address, location when FusionAuth records one, sign-in method (password, passwordless, or passkey) when FusionAuth reports it, and FusionAuth’s reason. Browser and operating system appear only for failures on FusionAuth’s hosted login pages.
    • Entries from the FusionAuth audit log, under FusionAuth’s own message. Oleria keeps each entry’s reason, tenant, and the names of the fields that changed, but not the old or new values. When FusionAuth masks the changed values, no field names are shown. Entries added through the audit log API carry whatever user name the caller sets. Oleria credits an entry to the user registered for the FusionAuth or Tenant manager application, in any tenant, whose email address or username matches the entry’s user, ignoring letter case, only when exactly one such user matches.
    See Known limitations for what FusionAuth doesn’t record.
Oleria refreshes users, groups, roles, and applications on its regular sync schedule. Activity syncs separately.
This integration covers identities, access to applications, roles, and activity. It doesn’t inventory resources, so Oleria doesn’t populate resource-level Access Graph or Access Inventory data for FusionAuth.

​
Prerequisites

  • A FusionAuth instance that Oleria can reach over HTTPS at a public address: a FusionAuth Cloud deployment such as https://acme.fusionauth.io, a custom domain, or a self-hosted instance. Oleria doesn’t connect to private addresses.
  • A FusionAuth admin user with the admin or api_key_manager role, to create API keys under Settings -> API Keys.
  • Admin access on the Oleria platform to add a new integration.
Each integration connects one FusionAuth instance and covers all of its tenants. To connect another instance, add another integration. See Multi-instance support.
A FusionAuth API key with no endpoints selected can call every endpoint. Always select the endpoints listed below. Don’t turn on Key Manager for Oleria’s keys: a key manager key can create other API keys.

​
Create API keys in FusionAuth

1

Open API Keys

Sign in to the FusionAuth admin console and go to Settings -> API Keys. Add a new API key.
2

Create the read key

Enter a name and description that identify the key as Oleria’s. Leave Tenant empty: Oleria needs a global key, because a tenant-scoped key can’t read login records, and you can’t change a key’s tenant after you create it. Under Endpoints, allow these endpoints and methods:If you set an Expiration, note the date and replace the key in Oleria before it expires. FusionAuth refuses expired keys.If you set an Access Control List on the key, allow Oleria’s IP addresses in it. If a firewall sits in front of your self-hosted instance, allow inbound connections from Oleria’s IP addresses there too. Contact support@oleria.com for the current list.
3

Copy the read key

Save the key and copy its Key value. If you set Retrievable to Not Retrievable, FusionAuth doesn’t show the key again.
4

Create the remediation key (optional)

To let Oleria take remediation actions with a separate key, add a second global API key the same way, with the endpoints of the actions you’ll use. See Remediation actions for each action’s endpoints. Copy its Key value.
The exact location of these settings can change over time. If the steps above don’t match what you see, refer to the FusionAuth API key documentation.

​
Record failed sign-ins (optional)

FusionAuth’s login records and audit log don’t include failed sign-ins. Oleria reads them from FusionAuth’s Webhook Event Log, available in FusionAuth 1.53 and later, which records events that FusionAuth sends to a webhook or to Kafka. To have Oleria import failed sign-ins:
  1. Turn on the Webhook Event Log under Settings -> System, on the Advanced tab. FusionAuth 1.57 and later turn it off by default, and keep entries for 30 days by default.
  2. Enable the user.login.failed event for each tenant under Tenants -> Webhooks, and send it to a webhook under Settings -> Webhooks, or to Kafka.
  3. Allow POST /api/system/webhook-event-log/search on Oleria’s read key.
If the Webhook Event Log isn’t available to the key, the activity sync skips failed sign-ins and continues. See FusionAuth’s Webhook Event Log documentation.

​
Connect FusionAuth to Oleria

1

Open the integration

Go to your Oleria workspace, select Integrations -> select FusionAuth.
2

Complete the connection form

Provide the following:
3

Confirm the connection

Select Authenticate. Before it saves anything, Oleria checks that:
  • the URL uses HTTPS and points to a public address;
  • the API key can search users;
  • the API key can search login records, which only a global key can do;
  • if you entered a remediation key, FusionAuth accepts it on at least one remediation endpoint.
Find the newly connected instance, named after its host, on the Connected tab of your Oleria Integrations page.
If Authenticate, or Update when you edit the integration, fails, the message says what’s wrong:
  • FusionAuth URL must be an https:// address with no credentials, FusionAuth URL must use HTTPS, FusionAuth URL must not contain credentials, or FusionAuth URL is not a valid URL - enter the instance’s https:// address with no user name or password. A message about the URL’s address means its host name doesn’t resolve to a public address that Oleria connects to.
  • could not reach FusionAuth - Oleria couldn’t complete a user search with the API key. The message includes the error. Check the host name, and that the instance is reachable at a public address. If a firewall sits in front of a self-hosted instance, allow Oleria’s IP addresses in it.
  • FusionAuth refused the API key - the key is wrong, expired, or doesn’t allow POST /api/user/search, or its Access Control List blocks Oleria’s IP addresses. FusionAuth refuses a blocked address the same way as a wrong key. Contact support@oleria.com for Oleria’s IP addresses.
  • the API key cannot read login records - create a global key, with Tenant empty, that allows POST /api/system/login-record/search.
  • the stored FusionAuth connection could not be read - Oleria couldn’t load the saved connection while you edited it, so it saved nothing. Try the edit again.
  • the remediation API key was refused by every remediation endpoint - the remediation key is wrong, expired, or allows none of the remediation endpoints, or its Access Control List blocks Oleria’s IP addresses.
  • login record search failed or could not validate the remediation API key - FusionAuth returned an error other than a refusal. The message includes the error. Try again.
  • must be the API key value - paste the key value itself into the field.
When you edit the integration, leave API key or Remediation API key blank to keep the stored key. To remove the stored remediation key, select Remove stored remediation API key. Remediation actions then run with the API key. You can’t change the FusionAuth URL of an existing integration: the field is read-only when you edit it. To connect a different instance, add a new integration.

​
Verify the integration

Confirm the FusionAuth instance appears on the Connected tab of your Oleria Integrations page with a status of Healthy. After the first sync completes, review the discovered users, groups, roles, applications, non-human identities, and activity in your Oleria workspace. In the integration’s Capabilities and operation readiness section, Read users, Read groups, and Read roles show Available. If one shows Needs permission, add the missing endpoints to the API key: Oleria checks GET /api/identity-provider/link only when an identity provider is configured, and GET /api/webauthn only when a tenant has WebAuthn enabled. If the API key is missing a read endpoint, the sync of that data fails rather than showing it as empty. Activity has no row in this section. Authenticate checks that the API key can search users and login records, but not the audit log. If the key doesn’t allow POST /api/system/audit-log/search, the integration still connects and the read rows show Available, but the activity sync fails at the audit log step. Allow both POST /api/system/login-record/search and POST /api/system/audit-log/search on the key.

​
Remediation actions

Oleria can take these actions in FusionAuth. They use the Remediation API key when you’ve added one, and the API key otherwise. The Remediations page offers Revert only for Disable user, Remove user from group, Remove application entitlement, and Disable NHI. The integration supports the other reverts in this table, but the Remediations page doesn’t offer them yet. Each action needs these FusionAuth API key endpoints. Before it offers an action, Oleria checks that the key allows each of them, without changing anything in FusionAuth:
FusionAuth uses DELETE /api/user both to deactivate a user and to delete a user permanently, so a key that allows it can do both. Oleria deletes a user permanently only for Delete user and to revert Create user.
Keep these limits in mind when you use these actions:
  • Oleria reads the user before it changes anything. If the user is already in the requested state, Oleria makes no change, and reverting the action makes no change either. If the user, role, or Entity doesn’t exist, the action fails. Reverting an action whose target no longer exists reports that nothing was reverted.
  • Disable user, Enable user, and Activate user read the user again after the change. If FusionAuth didn’t apply it, the action fails.
  • Add user to group fails if the group doesn’t exist or belongs to a different tenant than the user.
  • Assign application entitlement and Remove application entitlement refuse the FusionAuth application. Use Add user to role and Remove user from role to change a user’s admin console roles.
  • Add user to role needs the user to be registered for the role’s application. Run Assign application entitlement first. If one of the user’s groups already grants the role, the action reports that the user holds the role through the group, names the group, and writes nothing.
  • Remove user from role refuses a role that one of the user’s groups grants, and names the groups. Remove the user from the group instead.
  • FusionAuth reports a user’s direct and group roles as one list, so Oleria works out the direct roles by leaving out the roles the user’s groups grant. If a role is granted both directly and by a group, Oleria treats it as granted by the group. A role change on that registration, or reverting Remove application entitlement, keeps the user’s access through the group but drops the direct grant. If the user later leaves the group, they lose the role. The results of the role actions and Remove application entitlement name each role held through a group that Oleria didn’t write back as a direct grant.
  • Create user can’t add the user to groups: a request that lists groups fails. Create the user first, then run Add user to group. If the tenant can’t send email, a request without a password fails: configure email for the tenant, or ask Oleria to generate a password. A user whose email address or username is already in use can’t be created. If Oleria can’t deactivate the new user, it tries to delete it, and the action fails. If the delete also fails, the action reports a partial failure that names the user, and the user stays active: deactivate or delete it in FusionAuth.
  • Revoke user sessions makes no change when the user has no refresh tokens.
  • Disable NHI makes no change when the Entity holds no permissions on other Entities. After removing the permissions, Oleria reads the Entity’s permissions again and removes any that remain, up to three times. If a permission is still there after the third time, the action fails and names the Entities it’s on. If removing a permission fails partway, the action fails and reports only how many permissions it removed. It can’t be reverted: check the Entity’s permissions in FusionAuth and grant again any that should stay. Reverting a successful Disable NHI skips permissions on Entities that no longer exist and permissions the Entity already holds again.
  • Oleria doesn’t stop you from changing FusionAuth administrators, including the last user with the admin role. The integration keeps working, because FusionAuth API keys don’t belong to a user.

​
Known limitations

  • API keys aren’t inventoried. FusionAuth has no API that lists API keys, so Oleria can’t discover them as non-human identities, including the keys this integration uses. A key with no endpoints selected can call every endpoint, so review your keys under Settings -> API Keys.
  • Changes made through the FusionAuth API aren’t audited. FusionAuth’s audit log records changes made in the admin console and entries added to the audit log, not changes made through its API. Changes made by Oleria’s remediation actions, or by your own provisioning scripts, don’t appear as audit log activity.
  • Failed sign-ins need the Webhook Event Log. FusionAuth doesn’t record failed logins in its login records or audit log. Oleria imports them only when you record failed sign-ins.
  • Successful sign-ins show no sign-in method, browser, or operating system. FusionAuth’s login records don’t include them.
  • Audit log entries aren’t classified. Each entry appears under FusionAuth’s own message. An entry whose user matches no administrator, or more than one, isn’t credited to anyone.
  • Create user and Create group work only on single-tenant instances. On an instance with more than one tenant, FusionAuth needs the target tenant to create a user or group, and Oleria can’t send one, so the action fails. Create those users and groups in FusionAuth.
  • Users deleted during a sync. A user deleted in FusionAuth while Oleria reads it appears without its identity provider links and passkeys until the next sync removes it.
  • Activity history depends on retention. FusionAuth can delete login records and audit log entries automatically after a set number of days. Login record retention is under Settings -> System -> Advanced -> Login record settings. Audit log deletion is off by default. When it’s on, FusionAuth keeps 365 days of entries unless you set a different number. Oleria can’t import login records or audit log entries that FusionAuth has deleted.
  • Entities need a Starter plan or higher. If your FusionAuth plan doesn’t include Entity Management, Oleria finds no Entities or Entity client secrets, and the rest of the sync continues. FusionAuth doesn’t report who created an Entity or when it or a client secret was last used, so Entity client secrets show their status as unavailable. Permissions Entities grant to users aren’t shown, because this integration doesn’t inventory Entities as resources.
  • Application MFA policies need an Enterprise plan. Without them, each application shows its tenant’s multi-factor policy.
  • No user type or country. FusionAuth doesn’t tell employees from customers, so every user appears as a standard user. FusionAuth users have no country.
  • Role flags aren’t shown. Whether a role is a super role or a default role doesn’t appear in Oleria.
  • Group roles can’t be changed. Oleria can’t change the roles a group grants. Change them in FusionAuth.
  • No AI agents. FusionAuth has no API that lists AI agents. Agents that authenticate as Entities appear as service accounts.
  • Large instances take longer. When an identity provider is configured, or a tenant has WebAuthn enabled, Oleria reads each user’s identity provider links or passkeys with a separate request per user.

​
Contact us

For questions about this integration, contact us at support@oleria.com.