Skip to main content
Connect Gravitee API Management (APIM) to Oleria to see who can manage your APIs and applications: console users and service accounts, environment groups, organization, environment, API, application, and group roles (held directly or through a group), and the personal access tokens, consumer applications, API keys, and client certificates that act as non-human identities (NHIs), with their owners. Oleria connects as a Gravitee user with the Organization ADMIN role, and can also change role and group membership, create users and groups, delete users, and disable NHIs.
This integration supports Gravitee APIM 4.x, self-hosted or on Gravitee Cloud. Gravitee Access Management (AM) isn’t covered. Each integration connects one APIM organization. If you have more than one, add an integration for each. See Multi-instance support.

​
What Oleria discovers

Once connected, Oleria continuously discovers and maps the following from your APIM organization:
  • Accounts - every console user and service account in the organization, with name, email, creation date, and last sign-in. Oleria also shows:
    • Status - a user is enabled when Gravitee reports them as ACTIVE. Pending, rejected, and archived (deleted) users can’t sign in.
    • Account role - the user’s organization roles. Users with the Organization ADMIN role are marked as administrators.
    • Single sign-on (SSO) - users who sign in through an identity provider configured in Gravitee show SSO as required, with the provider type. Local users show SSO as not configured.
    • MFA - APIM has no MFA of its own. Local users show MFA as not required, and users from an identity provider as unavailable.
    • Last activity - the user’s last console sign-in, or the newest use of one of their personal access tokens, whichever is later.
  • Groups - every group in each connected environment, with its members and each member’s roles. Members who hold the group’s ADMIN role are shown as the group’s owners.
  • Roles - every organization and environment role, and a role for each API, application, and group role that someone holds, such as OWNER — Payments API (API). Each role lists its Gravitee permissions. Roles that a user gets through a group show the group as their source.
  • Memberships - which users belong to which groups, and who holds each role, directly or through a group.
  • Non-human identities (NHIs): Oleria never reads token, API key, client secret, or private key values.
  • Activity - the organization and environment audit trail: sign-ins, and user, membership, group, role, personal access token, application, API key, subscription, API, and identity provider events, attributed to the user who made them. Events by Oleria’s own user are kept and tagged, because the audit trail can’t tell Oleria’s changes apart from other use of that user. The audit trail needs a Gravitee Enterprise Edition licence that includes it. See Known limitations.
Oleria refreshes this data on its regular sync schedule.

​
Prerequisites

  • Gravitee APIM 4.x, with its Management API reachable from the internet over HTTPS, by a host name that resolves to a public IP address.
  • For self-hosted APIM, the Management API host on Oleria’s egress allowlist. Before you connect, contact support@oleria.com with the host name, such as apim.example.com, and ask for it to be allowlisted. Gravitee Cloud hosts (*.api.gravitee.io) are already allowlisted.
  • A Gravitee user with the Organization ADMIN role, to create Oleria’s service account and its token.
  • Admin access on the Oleria platform to add a new integration.
Organization ADMIN can change anything in the organization. Gravitee has no narrower role that can read the members of every API and application, so Oleria needs it to read your organization. Oleria uses the same credential for remediation actions. Give Oleria its own service account, and store its token securely.

​
Create the Oleria service account in Gravitee

1

Create a service account

In the Gravitee APIM Console, go to Organization > Users > Add user, and create a service account dedicated to Oleria, such as oleria-governance.
2

Grant Organization ADMIN

Open the service account (Organization > Users > service account) and set its organization role to ADMIN.
3

Generate a personal access token

Under Organization > Users > service account > Tokens, generate a personal access token and copy it. Gravitee shows it only once.You can use a local console user’s username and password instead. Users who sign in through an identity provider have no Gravitee password, so they can’t be used.
4

Collect the connection details

Copy your Management API URL, for example https://apim.example.com/management, or https://<org>.<region>.api.gravitee.io/management on Gravitee Cloud. Note the organization ID if it isn’t DEFAULT. To sync only some environments, note their IDs.

​
Gravitee permissions

Organization ADMIN holds every permission Oleria needs. The integration’s Capabilities and operation readiness section lists them by row: Oleria also reads applications, their subscriptions, API keys, and client certificates (APPLICATION_SUBSCRIPTION[READ], APPLICATION_DEFINITION[READ]), the audit trail (ORGANIZATION_AUDIT[READ], ENVIRONMENT_AUDIT[READ]), and the console’s sign-in settings and identity providers (ORGANIZATION_SETTINGS[READ], ORGANIZATION_IDENTITY_PROVIDER[READ]). Remediation actions are optional. Each action lists these permissions, also held by Organization ADMIN: Gravitee doesn’t report these permissions for a user, so before every action Oleria checks only that its user still holds Organization ADMIN. If it doesn’t, the action fails and names the permissions it needs.

​
Connect Gravitee to Oleria

1

Open the integration

Go to your Oleria workspace, select Integrations -> select Gravitee API Management.
2

Complete the connection form

Provide the following:
3

Confirm the connection

Select Authenticate. Before it saves anything, Oleria checks that the credential’s user holds the Organization ADMIN role, and that the user can see every environment you listed.Find the newly connected organization on the Connected tab of your Oleria Integrations page. It’s named Gravitee APIM followed by the Management API host.
If Authenticate fails, the message says what’s wrong:
  • Gravitee getCurrentUser: HTTP 401 - check the personal access token, or the username and password.
  • the Gravitee user must hold the Organization ADMIN role in organization ID - give the user the Organization ADMIN role, or check Organization ID (optional).
  • Gravitee getCurrentUser: HTTP 404 - check that Management API URL ends with /management and that the organization ID exists.
  • configured environments are not visible to the connection - check Environment IDs (optional). Each ID must exist and be visible to the user.

​
Edit the integration

When you edit the integration, you can change Environment IDs (optional), Authentication method, and the credential. Management API URL and Organization ID (optional) can’t be changed. To connect a different installation or organization, add a new integration.
  • Leave Personal access token or Password blank to keep the stored value. If you switch the authentication method, enter the new method’s credential.
  • Clear Environment IDs (optional) to sync every environment again.
Select Update to save. Oleria runs the same checks as Authenticate.

​
Verify the integration

Confirm the organization appears on the Connected tab of your Oleria Integrations page with a status of Healthy. After the first sync completes, review the discovered accounts, groups, roles, NHIs, and activity in your Oleria workspace. In the integration’s Capabilities and operation readiness section, Read users, Read groups, and Read roles show Available. Oleria checks each row by reading a sample: users; the groups of the first connected environment; and the organization roles, users, and the members of one API and one application. If Gravitee refuses a read, the row shows Needs permission. Check that Oleria’s user still holds Organization ADMIN. If Gravitee refuses or can’t find a few items, such as one application’s members, Oleria skips them, logs each one, and syncs the rest. If every item of a kind is refused, or more than 10% of them and at least 3, the sync of accounts, groups, roles, and NHIs fails, so incomplete data is never reported as complete. A refused list of groups, APIs, or applications always fails the sync. Client certificates are the exception: if Gravitee refuses them, applications still sync without them.

​
Remediation actions

Oleria can take these actions in Gravitee. Each needs Oleria’s user to hold Organization ADMIN. See Gravitee permissions. Disable NHI accounts works as follows:
The Remediations page offers Revert only for Remove user from group and Disable NHI accounts. The integration supports the other reverts in these tables, but the Remediations page doesn’t offer them yet. Oleria can revert only an action that completed or partially completed, never one that failed.
Delete user and disabling a personal access token can’t be undone. Gravitee has no disabled state for users, so Oleria doesn’t offer Disable user accounts or Enable user accounts: deleting is the only way to remove a user’s access.
Keep these limits in mind when you use these actions:
  • Oleria refuses to delete its own user, to remove its own Organization ADMIN role, and to delete its own user’s personal access tokens. Gravitee doesn’t say which token Oleria uses, so Oleria refuses all of them.
  • Remove user from role refuses to remove the last Organization ADMIN.
  • Add user to role and Remove user from role refuse the PRIMARY_OWNER role, which needs an ownership transfer in Gravitee. Gravitee also refuses Delete user while the user is the primary owner of an API or application: transfer ownership first.
  • Remove user from role refuses a role the user holds only through a group, and names the group. Remove the user from that group instead. It also refuses a group role that is the user’s only role in the group: use Remove user from group instead.
  • Add user to role refuses an API or application role when the user is already a direct member with another role, and a group role when the user already holds another one. Remove that role first.
  • Environment roles can be changed only in a connected environment.
  • Create user refuses an email address that a user who isn’t deleted already has. Gravitee doesn’t take a password when it creates a user, and has no inactive state, so password and activation settings in the request are ignored and the result says so.
  • Create group refuses a name that a group in that environment already has, ignoring upper and lower case.
  • If the user, role, group, or NHI is already in the state the action asks for, Oleria makes no change, and reverting the action makes no change either.
  • After it changes an organization or group role, or deletes a user, Oleria reads the result again. If Gravitee accepted the change but it doesn’t show, for example because an identity provider’s role mapping applied the role again, the action fails and says so.
  • Reverting an action changes only what the action changed. If the target no longer exists, the revert makes no change and says why.

​
Known limitations

  • Audit trail needs Enterprise Edition. Activity comes from the audit trail, which needs a Gravitee Enterprise Edition licence with the apim-audit-trail feature. On Community Edition, Oleria collects no activity and the sync still completes. Activity has no failed sign-ins, sign-outs, or IP addresses.
  • No password change date or MFA. APIM doesn’t report when a user changed their password, and has no MFA of its own.
  • No disable or session revocation. APIM has no disabled state for users and no session API, so users can’t be disabled, re-enabled, or signed out. Deleting is the only way to remove a user.
  • APIs and plans aren’t resources. APIs appear only as the scope of API roles. Plans, subscriptions, and keyless plans aren’t shown as access to resources. Subscriptions appear on their application and its API keys.
  • Other role scopes. Integration, cluster, API product, and AI catalog roles aren’t read.
  • Client certificates can’t be disabled. Disable NHI accounts doesn’t apply to client certificates. To stop an application’s certificates from being used, disable the application, which pauses its subscriptions. To remove a certificate, revoke it in Gravitee.
  • Network access. Oleria connects only over public HTTPS. A self-hosted Management API must be allowlisted for each customer. See Prerequisites.

​
Contact us

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