OpenID Connect authentication

Octopus Deploy supports authentication using OpenID Connect (OIDC) from a third-party identity provider, such as:

• Azure Directory Federation Services (AD FS)
• Keycloak
• Authentik
• Ping Identity
• etc

To use OIDC authentication with Octopus you will need to:

1. Configure your Identity Provider (IdP) to trust your Octopus Deploy instance, by setting up a client ID & secret.
2. Configure your Octopus Deploy instance to trust and use OIDC as an authentication provider.
3. Optionally assign users to Teams based on the role information provided by your identity provider.

Configure your identity provider

1. Create a new client application in your identity provider, noting down the following details:

   • Issuer URL (usually the root URL of the identity provider)
   • Client ID
   • Client Secret

   Note that Keycloak supports multiple realms on the same server, so the Issuer URL needs to include the realm path, eg: https://keycloak-server/realms/octopus rather than just https://keycloak-server.

2. Configure at least one Redirect URL to be https://your-octopus-url/api/users/authenticatedToken/GenericOidc (replacing https://your-octopus-url with the URL of your Octopus Server)

3. If you want Octopus users to be automatically assigned to teams, configure your IdP to send a list of roles or groups in a custom claim. The default role claim is groups, but you can configure this if required.

Configure OIDC in Octopus Deploy

1. Navigate to Configuration ➜ Settings ➜ OpenID Connect and populate the following fields:
   • Enabled should be set to Yes.
   • Role Claim Type is optional, but should specify the claim that your identity provider returns containing role or group assignment information.
   • Username Claim Type should be set to the claim that your identity provider uses as a username.
   • Resource is optional, but allows you to specify a resource identifier for the identity provider. For example, AD FS requires a resource identifier to map custom claims.
   • Scopes has a default value, but can be configured if your identity provider requires a custom scope. The scope of groups is optional and can be omitted but the scopes of openid profile email are required for Octopus Deploy to retrieve user information from your identity provider.
   • Display Name can be used to customize the appearance of the button on the Octopus Deploy login screen. Use a name that your users will recognize for this identity provider.
   • Issuer should be set to the URL of your identity provider.
   • Client ID and Client Secret should be set based on the newly created client application in your identity provider.

     Note that the value of Client Secret cannot be retrieved once set - it can only be changed or deleted

   • Allow Auto User Creation determines if Octopus Deploy should automatically create user accounts, or only allow authentication for users that already exist in Octopus Deploy.
2. Click Save to apply the changes.
3. If you sign out of Octopus Deploy, you should now see a new button on the login screen to authenticate with the OIDC provider.

Assign external groups or roles to Octopus teams (optional)

If you followed the optional steps to include role information as a claim, you can assign them to Teams in the Octopus Portal.

1. Open the Octopus Portal and select Configuration ➜ Teams.

2. Either create a new Team or choose an existing one.

3. Under the Members section, select the option Add External Group/Role.

   

   Can’t see the “Add External Group/Role” button?

4. Create a mapping from the groups or roles in your identity provider to a team in Octopus Deploy. In this example, we need to supply octopusTesters as the Group/Role ID and OctopusTesters as the Display Name.

   

   The Group/Role ID value must match the value of the claim in the security token. The matching is performed without case sensitivity.

5. Save your changes by clicking the Save button.

Troubleshooting

We do our best to log warnings to your Octopus Server log whenever possible. If you are having difficulty configuring Octopus to authenticate with your identity provider, be sure to check your server logs for warnings.

Your identity provider likely also has logging functionality, so check to see what the logs report on that side too.

Double and triple check your configuration

Unfortunately security-related configuration is sensitive to everything. Make sure:

• You don’t have any typos or copy-paste errors.
• Remember things are case-sensitive.
• Remember to remove or add slash characters - they matter too!

Check OpenID Connect metadata is working

You can see the OpenID Connect metadata by going to the Issuer address in your browser adding /.well-known/openid-configuration to the end.

Inspect the contents of the security token

Perhaps the contents of the security token sent back by your identity provider aren’t exactly the way Octopus expected, especially certain claims which may be missing or named differently. This will usually result in the external user incorrectly mapping to a different Octopus User than expected. The best way to diagnose this is to inspect the JSON Web Token (JWT) which is sent from your IdP to Octopus via your browser. To inspect the contents of your security token:

1. Open the Developer Tools of your browser and enable Network logging making sure the network logging is preserved across requests.

2. In Chrome Dev Tools this is called “Preserve Log”. In Firefox this is called “Persist Logs”.

   

3. Attempt to sign into Octopus using OIDC and find the HTTP POST coming back to your Octopus instance from your identity provider on a route like /api/users/authenticatedToken/GenericOidc. You should see an id_token field in the HTTP POST body.

4. Grab the contents of the id_token field and paste that into https://jwt.io/ which will decode the token for you.

   

5. Octopus uses most of the data to validate the token, but primarily uses the sub, email and name claims. If these claims are not present you will likely see unexpected behavior.

6. If you are not able to figure out what is going wrong, please send a copy of the decoded payload to our support team and let them know what behavior you are experiencing.

Octopus user accounts are still required

Octopus still requires a user account so you can assign those people to Octopus teams and subsequently grant permissions to Octopus resources. If you have enabled Allow Auto User Creation, Octopus will automatically create a user account based on the profile information returned in the security token, which includes an Identifier, Name, and Email Address.

Add External Group/Role button is missing

At least one authentication provider must be enabled and have valid configuration for this button to show.

If the Add External Group/Role button is missing, check your OIDC configuration. Ensure that it is Enabled, there are no errors and that the required fields are populated.

Getting permissions

If you are installing a clean instance of Octopus Deploy you will need to seed it with at least one admin user. This user will have access to create and configure other users as required. To add a user, execute the following command

Octopus.Server.exe admin --username USERNAME --email EMAIL

The most important part of this command is the email, as usernames are not necessarily included in the claims from the external providers. When the user logs in the matching logic must be able to align their user record based on the email from the external provider or they will not be granted permissions.

Help us continuously improve

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

Send feedback

Page updated on Wednesday, November 5, 2025