Octopus Deploy Security: Secure Teams, API Keys, Tentacles and Variables

An Octopus Deploy server holds the credentials, certificates and trust relationships needed to change every environment it deploys to, so its teams, API keys and Tentacle trust are as sensitive as production admin access. This guide covers the customer side of running Octopus securely, with most attention on self-hosted Octopus Server: user roles and team scoping, service accounts, API keys and OIDC identities, OIDC accounts for cloud deployments, sensitive variables and the Master Key, Tentacle communication, workers, auditing and hardening. It is written for release engineers, platform teams and security reviewers, including those running Windows-heavy estates where Tentacles are common. For identity controls across all delivery tools, see the CI/CD Pipeline Identity Security Guide.

This is an independent guide from NHI Mgmt Group, based on Octopus Deploy's public documentation as of November 2026. It is not sponsored or reviewed by Octopus Deploy. Product features change, so confirm settings against Octopus Deploy's current documentation.

Key takeaways

• Scope roles to environments and projects. Built-in roles such as Project Deployer and Deployment Creator can be scoped per team to specific environments, so production deployment rights stay with the people who need them.
• Give every automated caller a service account. Service accounts cannot use the Web Portal; pair each one with an OIDC identity so it exchanges an ID token for a short-lived access token instead of holding an API key.
• Keep API keys short-lived and narrow. Keys default to 180 days and, from 2025.4, cannot be non-expiring; use read-only access where your version offers it and turn off user API key creation if only service accounts should automate.
• Back up the Master Key separately. It encrypts sensitive variables, account credentials and private keys in the database; without it, database backups cannot be used for those values.
• Move scripts off the server. Octopus highly recommends external workers on a different host from the Octopus Server, so deployment scripts never run beside the server's own secrets.

How identity and access work in Octopus Deploy

Octopus separates who you are (authentication providers) from what you can do (teams and roles, scoped by space, project, environment and tenant). Octopus describes its security as a shared responsibility model: on self-hosted Octopus Server the host, database and network are yours to secure.

For OIDC login, configure Issuer, Client ID, Client Secret, Username Claim Type and, optionally, Role Claim Type (default groups) under Configuration, Settings, OpenID Connect. Turn off Allow Auto User Creation unless you want any IdP user to get an account on first login, and map teams to IdP groups so access follows joiner, mover and leaver changes. A fresh install still needs a seeded admin account; keep it as a break-glass credential in a vault.

Admin roles and privileged access

System and space roles

• Environment scoping: apply a role to a team with optional scope so the same team can deploy to development and test but only view production.
• Custom roles: the docs advise treating editable built-in roles as references and creating custom roles for different permission sets. New permissions in later versions are not added automatically to editable built-in or custom roles, so review roles after each upgrade.
• Who can change a process: anyone who can edit a deployment process or step templates can change what runs with the project's variables and accounts. Separate edit rights (Project Contributor) from production deploy rights, and require review for process changes where you can.
• Checking access: Configuration, Test Permissions lists a user's permissions at system level or within a space, with CSV export. Use it in quarterly access reviews.

Integrations, API tokens and service accounts

Service accounts and OIDC identities

Create a service account under Configuration, Users with The user is a service account checked, add it to a least-privilege team, then give it an OIDC identity or an API key. With an OIDC identity the calling service, for example a CI pipeline that can issue ID tokens, exchanges its token for a short-lived Octopus access token, so no long-lived key is stored. If you use Active Directory, an AD account can be added as an external login so AD group membership drives the service account's teams. See the Workload Identity Federation Guide for the pattern.

API keys

• Expiry: keys default to 180 days. From 2025.4 the default maximum is 366 days, configurable up to 1,096 days under Configuration, Settings, Authentication; non-expiring keys were removed in that release. Our recommendation at NHI Mgmt Group: 90 days or less for service account keys.
• Access level: full access gives the key the user's permissions, and a key never exceeds them. Read-only scopes are available on Octopus Cloud and, per the docs, on self-hosted Octopus Server from 2026.3. Use Preview Permissions before generating.
• Admin controls: administrators can disable API key creation for regular users (existing keys keep working; service accounts can still get keys) and view all keys, their last use and permissions on the API Keys page.
• Storage: Octopus stores only a one-way hash, so copy the key straight into your secrets manager. See the Secrets Management Guide.
• Expiry alerts: subscriptions to the API key expiry events group send warnings at 20 days and 10 days and an expired event, which helps rotate before pipelines break.

OIDC accounts for cloud deployments

For deployments to cloud providers, Octopus can act as the OIDC token issuer so it holds no static cloud keys. The provider must reach two anonymous HTTPS endpoints on the server, /.well-known/openid-configuration and /.well-known/jwks, and the server URI must be set under Configuration, Nodes, Server Uri. Deployment tokens carry a subject built from slugs, by default space, project, tenant and environment, for example space:[space-slug]:project:[project-slug]:environment:[environment-slug]. Write cloud trust policies against the full subject your deployments actually produce, including environment, so a development deployment cannot assume a production role. Exposing only those two discovery paths publicly, rather than the whole portal, is the approach we recommend for self-hosted servers; Octopus also documents how to expose a server safely.

Sensitive variables and the Master Key

• Sensitive variables: set the variable type to Sensitive. Values are encrypted with AES-256 in the database from 2024.4 (AES-128 earlier) and cannot be read back through the Web Portal or REST API. During deployment they are available to scripts in clear text.
• Log masking: Octopus masks sensitive values in task logs where possible, for values longer than 3 characters. Transformations such as unquoted echo in Bash can change output so it no longer matches, and sensitivity does not carry over to composite values. Mark the specific secret as sensitive, never print it, and substitute it into non-sensitive files.
• External secrets managers: community step templates can fetch secrets from cloud and enterprise secrets managers at deployment time into sensitive output variables. Anyone who can edit the process or manage step templates could reach those values, so control those rights.
• Master Key: generated at install, protected with Windows Data Protection and stored in the server configuration file, it encrypts sensitive variables, Tentacle and endpoint private keys, and SSH and external feed credentials. Export it with View Master Key in Octopus Manager or Octopus.Server.exe show-master-key and store it in an enterprise password manager, apart from database backups.
• Database: most other data is plain text in SQL Server. Use Integrated Security where possible and limit the Octopus login to its own database, as the hardening guide advises.

Tentacle trust

All Octopus Server and Tentacle traffic uses TLS (1.2 minimum, 1.3 on modern operating systems) with mutual certificate authentication. Each side has a 2,048-bit X.509 key pair, self-signed by default, and trust is established by exchanging thumbprints: the server only sends commands to Tentacles it trusts, and Tentacles only accept commands from servers they trust.

Confirm the server thumbprint out of band when you register a Tentacle, run the Tentacle service under a dedicated account with the rights deployments need, disable TLS 1.0 and 1.1 on targets as the hardening guide shows, and regenerate or replace certificates using the documented procedures when a host is rebuilt or a key may be exposed. Remove deployment targets promptly when hosts are retired so stale trust does not remain.

Logging and detection

The audit log records creates, edits and deletes with the initiator, process and variable changes, deployments queued and cancelled, logins and sensitive reads such as downloading a certificate private key. Actions with an API key record a masked key you can match on the API Keys page, and an AI events only filter isolates agent activity. Sensitive values appear only as changed, never as values. Retention defaults to 90 days and can be raised to 3,650 days on self-hosted; older entries are archived as daily JSONL files. Restrict SQL permissions on the Events table and filesystem permissions on the archive folder, since the docs note those are where tampering would be possible.

Availability: Audit Stream to a SIEM is documented for Enterprise-tier customers from Octopus 2022.4.

Metrics that show it is working:

• Percentage of automated callers using service accounts with OIDC identities rather than API keys.
• Number of active API keys on human accounts, and the median days to expiry.
• Number of members holding System Administrator, System Manager or production-scoped deploy roles, reviewed quarterly.
• Percentage of deployment work running on external workers rather than the built-in worker.
• Audit retention and SIEM coverage: days retained and percentage of events forwarded.

Hardening baseline

1. Inventory: list spaces, teams and their scopes, service accounts, API keys, cloud accounts, certificates and Tentacles. Upgrade to the latest version on a regular schedule, as Octopus recommends, and review custom roles after each upgrade.
2. Expose safely: HTTPS only, with the built-in HTTP security headers configured; publish only what external parties need.
3. Authenticate through your IdP with OIDC and MFA; map teams to IdP groups and turn off auto user creation unless intended.
4. Scope roles by environment and project; separate process editors from production deployers.
5. Replace API keys with service accounts and OIDC identities; cap key lifetime and disable user API key creation where only service accounts should automate.
6. Use OIDC accounts for cloud deployments with environment-specific trust policies.
7. Protect secrets: sensitive variables for every secret, Master Key exported and escrowed, SQL login limited to the Octopus database.
8. Move execution to external workers on separate hosts, and run any remaining built-in worker as a different user.
9. Harden Tentacles: polling where targets should accept no inbound connections, verified thumbprints, TLS 1.2 or later, dedicated service accounts.
10. Extend audit retention and stream events to your SIEM where your tier allows. Test changes in a non-production space first and keep role exports so you can revert.

Common misconfigurations

• Unscoped deploy roles. A team with Project Deployer across all environments can push to production. Scope by environment.
• Personal API keys in CI. Keys tied to a person carry that person's full permissions and break when they leave. Use a service account with an OIDC identity.
• Master Key kept only on the server. A rebuild without the key leaves sensitive data in backups unusable. Escrow it.
• Secrets printed in scripts. Masking covers matching values longer than 3 characters only; transformed output can slip through. Never echo secrets.
• Scripts on the built-in worker. Deployment code then runs on the server host. Move it to external workers.
• Broad cloud trust policies. Matching only the space or project lets any environment assume a production role. Include the environment in the subject condition.

Framework mapping

See the OWASP CI/CD Top 10 CICD-SEC-6 Insufficient Credential Hygiene Guide for credential controls across delivery platforms.

Practitioner checklist

• Use OIDC login with MFA and map teams to IdP groups.
• Scope deploy roles by environment and keep System Administrator to a break-glass group.
• Create one service account per automated caller and give it an OIDC identity.
• Cap API key lifetime, use read-only keys where available and disable user key creation if not needed.
• Use OIDC accounts for cloud deployments with environment-specific trust policies.
• Mark every secret as a sensitive variable and never print secrets in scripts.
• Export the Master Key and store it apart from database backups.
• Run deployment work on external workers on separate hosts.
• Verify Tentacle thumbprints at registration, prefer polling for isolated targets and enforce TLS 1.2 or later.
• Extend audit retention, stream events where available and alert on role, key and target changes.

Standards and references

• Octopus Deploy: Security
• Octopus Deploy: User Roles
• Octopus Deploy: How to Create an API Key
• Octopus Deploy: OpenID Connect
• Octopus Deploy: Sensitive Variables
• Octopus Deploy: Octopus Tentacle Communication
• Octopus Deploy: Hardening Octopus
• Octopus Deploy: Auditing

Related NHI Mgmt Group resources: CI/CD Security Guide · Software Supply Chain Security Guide · NHI Discovery Across Cloud, SaaS, CI/CD and On-Premises Environments · Secrets Management Guide