OpenID Connect

Configuration

To use federated credentials, your Octopus instance will need to have two anonymous URLs exposed to the public internet.

• https://server-host/.well-known/openid-configuration
• https://server-host/.well-known/jwks

These must be exposed with anonymous access on HTTPS. Without this, the OpenID Connect protocol will not be able to complete the authentication flow.

The hostname of the URL that these two endpoints are available on must either be configured under Configuration->Nodes->Server Uri or set as the first ListenPrefix in the server configuration.

Authenticating using OpenID Connect with third party services and tools

If you have a third-party service or tool that supports OpenID Connect, you can add any OIDC account variable into your projects variable set and use the [account name].OpenIdConnect.Jwt variable to get access to the request token that can be used for authenticating. The JWT for the account on a step or the target is available in the Octopus.OpenIdConnect.Jwt variable.

Subject Keys

When using OpenID Connect to authenticate to with external services, the Subject claim can have its contents customized.

This allows you to grant resource access at a fine or coarse grained level in your Cloud host, depending on your requirements.

The subject can be modified for the three different uses within Octopus:

• Deployments and Runbooks
• Health Checks
• Account Test

Subject key parts

• Only the requested keys for a Subject claim will be include in the generated Subject claim
• Any Octopus resource types included in the Subject claim will use the slug value for the Octopus resource. The slug value is generated from the name of the Octopus resource when it was created, it can be edited on the edit page of resource type.
• The Subject claim parts will always be in the following order
  • Space
  • Project
  • Runbook
  • Tenant
  • Environment
  • Target
  • Account
  • Type

Deployments and Runbooks

The Subject claim for a deployment or a runbook supports the following parts:

• Space slug
• Project slug
• Runbook slug
• Tenant slug
• Environment slug
• Account slug
• Type

The default format for a deployment and runbook is space:[space-slug]:project:[project-slug]:tenant:[tenant-slug]:environment:[environment-slug].

The value for the type is either deployment or runbook.

When changing the Subject claim format for a deployment and runbook, the runbook value will not be included (if specified) when running a deployment.

For example, in the Default space, you have a project called Deploy Web App, and a runbook called Restart. If you set the Subject claim format to space, project, runbook and type, when running a deployment the Subject claim will be space:default:project:deploy-web-app:type:deployment and for the run of the runbook the Subject claim would be space:default:project:deploy-web-app:runbook:restart:type:runbook. This is using the default generated slug values for the space, project and runbook.

Health Checks

The Health Check Subject claim supports the Space slug, the Account slug, the Target slug and the Type

The default format for a health check is space:[space-slug]:target:[target-slug]:account:[account-slug].

The value for the type is health.

Account Test

The Account Test Subject claim supports the Space slug, the Account slug and the Type

The default format for an account test is space:[space-slug]:account:[account-slug].

Help us continuously improve

Please let us know if you have any feedback about this page.

Send feedback

Page updated on Thursday, January 25, 2024