Skip to main content
Octopus Deploy is a deployment and release automation platform. Connect an Octopus Cloud instance to Oleria to see who can sign in, which service accounts and API keys can act on the instance, which teams people belong to, and which roles those teams hold in each space. Oleria reads this data from the Octopus REST API as an Octopus service account, with an API key or through OpenID Connect token exchange. You can then review over-provisioned access and take action directly from Oleria. One Oleria integration covers one Octopus Cloud instance, such as https://your-instance.octopus.app. To connect another instance, add another integration.

​
What Oleria discovers

Once connected, Oleria continuously discovers and maps the following from your Octopus instance:
  • Accounts - every user, with display name, username, email, whether the user is active, and when the user was created. Members of a team that holds the System administrator or System manager role system-wide, or any role that grants the AdministerSystem permission, such as a custom role, are marked as administrators. This includes members who get that team through an external group, such as an Octopus ID group.
    • Last activity - the user’s most recent action in the audit log in the last 90 days, such as a successful sign-in or a change they made, or the most recent use of one of their API keys, whichever is later. Failed sign-ins don’t count. A user with neither shows no last activity.
    • SSO - users who sign in with an external identity provider, such as Octopus ID, are shown with SSO required when the instance has no username and password sign-in, and with SSO configured when it does.
  • Teams - every team appears as a group, both system teams and the teams of each space, with its members. Members who belong to a team through an external group are included.
  • Roles - built-in and custom user roles, and the teams that hold each role. Each assignment shows its scope: system-wide, or a space, with any project, project group, environment, or tenant restrictions.
  • Non-human identities (NHIs):
    • Service accounts - shown as machine accounts. Service accounts that Octopus marks as AI agent accounts are shown as agent users. Each service account shows whether it signs in with API keys, OpenID Connect, or both.
    • API keys - every user’s and service account’s API keys, shown as credentials linked to the account that owns them. A person’s key is shown as a personal access token. Each key shows its purpose, access level (Full access or Read-only), creation date, expiry, and when it was last used. Expired keys are shown as expired.
    • OIDC identities - the OpenID Connect identities of service accounts, shown as federated credentials with their issuer, subject, and audience.
  • Activity - events from the Octopus audit log, such as:
    • successful and failed sign-ins
    • users, teams, roles, API keys, and other documents being created, changed, or deleted
    • password changes and certificate private key exports
    • deployment and runbook events, kept as custom events
    Each event shows who made it, the IP address, and the API key that was used, if any.
Oleria refreshes users, teams, roles, and NHIs on its regular sync schedule.
Oleria doesn’t import projects, environments, tenants, deployment targets, or their settings. Project, environment, and tenant IDs appear only as restrictions on role assignments.

​
Prerequisites

  • An Octopus Cloud instance, at an address like https://your-instance.octopus.app. Self-hosted Octopus Server isn’t supported.
  • An Octopus user who can create a service account and add it to a team, such as an Octopus account admin.
  • For OpenID Connect token exchange only: an identity provider, such as Okta or Microsoft Entra ID, where you can create a client-credentials application whose access tokens are JWTs.
  • Admin access to the Oleria workspace.

​
Permissions

Oleria connects as an Octopus service account. Octopus checks each request against the permissions of the service account’s teams: The built-in Octopus Managers team holds the System manager role and the Space manager role in every space, which covers all of these permissions. If you use your own team instead, give it these permissions at the system level and in every space. Octopus shows the service account only the teams, role assignments, and events it’s allowed to see, so a team with fewer permissions syncs an incomplete inventory without an error. With an API key, a Read-only key is enough for discovery. Remediation actions need a Full access key. With OpenID Connect token exchange, the service account’s team permissions alone decide what Oleria can do.

​
Set up access in Octopus Deploy

1

Create a service account

Sign in to your Octopus instance. Navigate to Configuration -> Users -> Create user. Select The user is a service account, enter a username such as oleria and a display name, and save.
2

Add the service account to a team

Navigate to Configuration -> Teams -> Octopus Managers, add the service account as a member, and save.
3

Create the credential

Create the credential for the authentication method you want to use:
  1. Open the service account from Configuration -> Users, expand API Keys, and select New API key.
  2. Fill in the form:
    • Purpose - enter Oleria.
    • Expiration date - choose an expiry that fits your rotation policy. Octopus defaults to 180 days, and discovery stops when the key expires.
    • What is this key for? - select A person.
    • Permissions level - select Full access if Oleria should run remediation actions, or Read-only for discovery only.
  3. Select Generate New and copy the key, which starts with API-. Octopus shows it only once.
The Octopus interface changes over time. If these steps don’t match what you see, refer to Octopus’s service accounts, API key, and OpenID Connect with other issuers documentation.

​
Connect Octopus Deploy to Oleria

1

Open the integration

Sign in to your Oleria workspace, navigate to Integrations, and select Octopus Deploy.
2

Complete the connection form

Select your authentication method, then fill in the fields for that method:
3

Authenticate

Select Authenticate. Before it saves the integration, Oleria signs in and checks that the service account holds UserView, TeamView, and UserRoleView. For OpenID Connect token exchange, Oleria first gets a token from your identity provider and exchanges it at Octopus. If either step fails, the error from your identity provider or Octopus is shown. The integration is named after your instance address.

​
Edit the connection

You can change the authentication method and its fields, for example when you rotate the API key or client secret. You can’t change the Instance URL. To connect a different instance, add a new integration. Leave API key or Client secret blank to keep the stored value. If you switch the authentication method, or change the Token URL or Client ID, enter the secret again.

​
Verify the integration

Confirm the Octopus Deploy integration appears on the Connected tab of your Oleria Integrations page with a status of Healthy. After the first sync completes, check that users, service accounts, teams, roles, and API keys appear in your Oleria workspace, and that members of Octopus Administrators and Octopus Managers are marked as administrators.

​
Remediation actions

Oleria runs actions as the integration’s service account. Before an action runs, Oleria checks that the service account has the permissions the action needs and, for an API key connection, that the key isn’t Read-only. Oleria refuses these actions and sends no change to Octopus:
  • Deactivating, reactivating, signing out, or deleting the service account the integration connects with, removing it from a team, or revoking its API keys or OIDC identities.
  • Deactivating, reactivating, signing out, or deleting a member of Octopus Administrators, or revoking their API keys or OIDC identities. On Octopus Cloud, this team holds only accounts that Octopus manages.
  • Changing the members of Octopus Administrators or Everyone, which Octopus manages.
  • Removing a user from a team they belong to through an external group. Change the group in your identity provider instead.
  • Running Disable NHI accounts on a person’s account. Use Disable user accounts instead.
Keep these points in mind:
  • If the target is already in the requested state, such as a user who’s already deleted, the action succeeds without making a change, and there’s nothing to revert.

​
Known limitations

  • No MFA or password-change data. Octopus’s API doesn’t report whether a user has MFA or when they last changed their password. MFA is shown as unavailable.
  • Pending invitations aren’t shown. Octopus Cloud invitations are managed in Control Center, and invited users appear only after they first sign in.
  • External groups aren’t expanded. Oleria shows which teams a user belongs to through an external group, but not the group’s own members who haven’t signed in to Octopus.
  • Incomplete data with fewer permissions. Octopus filters lists to what the service account can see instead of returning an error. See Permissions.
  • Activity covers the audit log’s retention period. Octopus keeps 90 days of events in the audit log and archives older events to files, which Oleria doesn’t read.
  • Self-hosted Octopus Server isn’t supported. Only Octopus Cloud instances can be connected.
  • OpenID Connect token exchange needs a standard client-credentials token. Oleria sends only the grant type and the optional scope, and authenticates with the client ID and secret over HTTP Basic. If your identity provider needs another parameter to issue a JWT, such as Auth0’s audience, configure it to issue one without it, for example with the Auth0 tenant’s Default Audience. If your token URL is on a custom domain or a self-hosted identity provider, first contact Oleria support to allowlist that domain.
  • Projects and environments aren’t inventoried. Oleria shows role assignments and their project and environment restrictions, but not the projects or environments themselves.

​
Contact us

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