> ## Documentation Index > Fetch the complete documentation index at: https://docs.oleria.com/llms.txt > Use this file to discover all available pages before exploring further. # Octopus Deploy > Connect an Octopus Cloud instance to Oleria to discover users, service accounts, API keys, OIDC identities, teams, user roles, and audit activity, and take remediation actions directly from Oleria. 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](/integrations/overview.md#sync-model). > [!NOTE] > > 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: | Permission | Used for | | :- | :- | | `UserView` | Users, service accounts, API keys, and OIDC identities. Required. | | `TeamView` | Teams and their members, and role assignments. Required. | | `UserRoleView` | User roles. Required. | | `EventView` | Activity and last activity dates. Without it, Oleria can't sync activity, and last activity comes from API key use only. | | `UserEdit` | Required for **Disable user accounts**, **Enable user accounts**, **Revoke user sessions**, **Delete user**, and **Disable NHI accounts**. | | `TeamEdit` | Required for **Add user to group** and **Remove user from group**. | | `TeamCreate` | Required for **Create group**. | | `TeamDelete` | Required to revert **Create group**. | 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: **API key** 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. **OpenID Connect token exchange** Oleria gets a token from your identity provider and exchanges it at Octopus for a short-lived access token, so Oleria stores no Octopus credential. Octopus supports this only for service accounts. 1. In your identity provider, create a client-credentials application whose access tokens are JWTs. Note its client ID, client secret, and token endpoint, and the `iss`, `sub`, and `aud` claims of its access tokens. Some providers issue a JWT only for a scope, such as `api://octopus-sync/.default` in Microsoft Entra ID or a custom scope of an Okta custom authorization server. 2. In Octopus, open the service account from **Configuration** -> **Users**, open the **OpenID Connect** section, and select **New OIDC Identity**. Select **Other Issuer** as the issuer type. 3. Fill in the identity: * **Issuer URL** - your identity provider's issuer. It must use HTTPS and serve `/.well-known/openid-configuration` without authentication. * **Subject** - the `sub` claim of the application's access tokens. It's case-sensitive. * **Audience** - the `aud` claim of the application's access tokens. Without a custom audience, Octopus expects the service account's ID, which client-credentials tokens don't usually carry. 4. Select **Save**, and copy the **Service Account Id** that Octopus shows. It's a GUID. > [!NOTE] > > The Octopus interface changes over time. If these steps don't match what you see, refer to Octopus's [service accounts](https://octopus.com/docs/security/users-and-teams/service-accounts), [API key](https://octopus.com/docs/api/authentication/create-an-api-key), and [OpenID Connect with other issuers](https://octopus.com/docs/api/authentication/openid-connect/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: | Field | Notes | | :- | :- | | Instance URL | Required. Your Octopus Cloud address, such as `https://your-instance.octopus.app`. | | Authentication method | Required. **API key** (default) or **OpenID Connect token exchange**. | | API key | Required for **API key**. The API key you created. | | Service account ID | Required for **OpenID Connect token exchange**. The **Service Account Id** (a GUID) from the service account's OpenID Connect section. | | Token URL | Required for **OpenID Connect token exchange**. Your identity provider's OAuth 2.0 token endpoint, as an `https://` address. | | Client ID | Required for **OpenID Connect token exchange**. The client ID of the client-credentials application. | | Client secret | Required for **OpenID Connect token exchange**. The application's client secret. Oleria sends it with HTTP Basic authentication. | | Scope | Optional, **OpenID Connect token exchange** only. The scope your identity provider needs to issue a JWT access token, for example `api://octopus-sync/.default` in Microsoft Entra ID, or a custom scope in Okta. | **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**. | Action | What it does | Revert | | :- | :- | :- | | Disable user accounts | Deactivates the user, so they can no longer sign in or use their API keys. | Supported - reactivates the user if the action deactivated them. | | Enable user accounts | Reactivates the user. | Supported - deactivates the user again if the action reactivated them. | | Add user to group | Adds the user to a team as a direct member. | Supported - removes the user from the team. | | Remove user from group | Removes the user's direct membership of a team. If the user is also a member through an external group, Oleria removes the direct membership, but the action fails and can't be reverted. | Supported - adds the user back to the team. | | Revoke user sessions | Signs the user out of their Octopus sessions. Their API keys keep working. To revoke a key, use **Disable NHI accounts**. | Not supported. | | Delete user | Deletes the user and their API keys from the instance. | Not supported. | | Create group | Creates a system team with the name you enter, with no members or roles. If a system team with that name already exists, Oleria makes no change. | Supported - deletes the team, but only while it still has no members, external groups, or roles. | | Disable NHI accounts | Deactivates a service account or AI agent service account, revokes an API key, or deletes an OIDC identity. | Supported for service accounts - reactivates the account. Not supported for API keys and OIDC identities, which Octopus can't restore. Create a new key or identity in Octopus. | 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](#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](mailto:support@oleria.com). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.