Configuring Keycloak

Authentication using Keycloak, a self-hosted identity management service.

To use Keycloak authentication with Octopus you will need to:

1. Configure Keycloak to trust your Octopus Deploy instance (by setting it up as an app in Keycloak).
2. Configure your Octopus Deploy instance to trust and use Keycloak as an Identity Provider.

Configure Keycloak

1. Install Keycloak using one of the many supported installation methods.

2. Open the Keycloak Administration Console in your web browser.

3. Navigate to Manage Realms and open or create the realm you wish to add Octopus Deploy to.

   Keycloak supports multiple realms, where each realm contains applications, users and groups. The master realm is typically used just for managing Keycloak and creating other realms, and we recommend that you create a new realm for managing other applications, including Octopus Deploy.

4. If you want Keycloak to provide group membership information, you’ll first need to create a new client scope. Under Client scopes, click Create client scope. Enter the following values:

   • Name: groups
   • Type: optional
   • Protocol: OpenID Connect

   

5. Click Save. Click the Mappers tab, then click Add predefined mapper and search for groups in the list. Check the box beside groups then click Add.

   

6. Navigate to Clients and click Create client to create a new client that represents Octopus Deploy:

   • Client Type: OpenID Connect
   • Client ID: can be anything, the domain name of the Octopus Deploy server is a good option
   • Name: Octopus Deploy or the domain name of the Octopus Deploy server is a good option

   

7. On the Capability config screen, ensure that Client Authentication is enabled and choose S256 for the PKCE Method.

   

8. On the Login settings screen, configure the URLs for Octopus Deploy. The Root, Home, Post Logout and Web Origins URLs should all be the URL of the Octopus Deploy server. The Valid redirect URIs should be https://your-octopus-url/api/users/authenticatedToken/GenericOidc (replacing https://your-octopus-url with the URL of your Octopus Server). Click Save.

   

9. Navigate to Client scopes, click Add client scope and check the box beside groups, to allow Octopus Deploy to request group membership information. Click Add.

10. Now collect the details you’ll need for configuring Octopus Server:

    • Issuer URL: the root URL for your Keycloak server, followed by /realms/ and the name of the realm, eg: https://keycloak-server/realms/company if the name of the realm is company.
    • Client ID: as configured above, and shown on the client page on the Settings tab
    • Client Secret: on the client page, go to the Credentials tab, then click the copy button beside Client Secret.

Configure Octopus Server

1. Navigate to Configuration ➜ Settings ➜ OpenID Connect and populate the following fields:
   • Enabled should be set to Yes.
   • Role Claim Type should be set to groups, to reference the custom claim created earlier.
   • Username Claim Type should be set to preferred_username.
   • Resource should be left unset.
   • Scopes should be left as the default of openid profile email.
   • 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, Client ID and Client Secret should be the values you noted when creating the application.
   • 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 to Octopus teams (optional)

If you want to use groups in Keycloak to manage permissions in Octopus Deploy, you can assign those groups 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.

4. Enter the name of the Keycloak group as the Group/Role ID and then choose the name that should be displayed in Octopus, then click Add. In this example, we’re adding an existing Keycloak group called octopusTesters.

   

5. Save your changes by clicking the Save button.

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. 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.

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.

Troubleshooting

If you are having difficulty configuring Octopus to authenticate with Keycloak, check your server logs for warnings and check the Keycloak logs. You may need to enable logging in Keycloak if it’s not already turned on, by going to Realm settings then the Events tab.

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. In our example this would have been something like https://keycloak-server/realms/company/.well-known/openid-configuration

Contact Octopus Support

If you aren’t able to resolve the authentication problems yourself using these troubleshooting tips, please reach out to our support team with:

1. The contents of your OpenID Connect Metadata or the link to download it (see above).
2. A screenshot of the Octopus User Accounts, including their username, email address, and name.

Help us continuously improve

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

Send feedback

Page updated on Tuesday, November 18, 2025