From 093054be25ba85609ef32a96ff8d3eb41113e4e3 Mon Sep 17 00:00:00 2001 From: domenicsim1 Date: Thu, 5 Mar 2026 09:21:22 +1100 Subject: [PATCH 1/4] do updates --- .../authentication/active-directory/index.md | 26 ++++++++----------- 1 file changed, 11 insertions(+), 15 deletions(-) diff --git a/src/pages/docs/security/authentication/active-directory/index.md b/src/pages/docs/security/authentication/active-directory/index.md index 628bfa1a62..e8d4f06e55 100644 --- a/src/pages/docs/security/authentication/active-directory/index.md +++ b/src/pages/docs/security/authentication/active-directory/index.md @@ -1,7 +1,7 @@ --- layout: src/layouts/Default.astro pubDate: 2023-01-01 -modDate: 2023-11-30 +modDate: 2026-03-05 title: Active Directory authentication description: Octopus Deploy can use Windows credentials to identify users. navOrder: 5 @@ -28,11 +28,11 @@ If you are using Active Directory Authentication with Octopus, there are two way By default, Active Directory Authentication will use NTLM as the Authentication Scheme. In many circumstances, you can also configure Octopus to use Kerberos for authentication. -If you would like to use Kerberos for authentication, you should consider if you require User Mode authentication. User Mode is required for Kerberos authentication when Octopus is in a [High Availability](/docs/administration/high-availability) configuration. By default, Kerberos authentication for Octopus Deploy runs in Kernel Mode. The mode is dictated by the web server running Octopus Deploy, which can be configured using the `configure` command. Select HTTP.sys for Kernel Mode, or Kestrel for User Mode: +If you would like to use Kerberos for authentication, you will need to use User Mode authentication (Kestrel). By default, Active Directory authentication for Octopus Deploy runs in Kernel Mode via HTTP.sys. The mode is dictated by the web server running Octopus Deploy, which can be configured using the `configure` command. Select HTTP.sys for Kernel Mode, or Kestrel for User Mode: ### Kernel Mode authentication via HTTP.sys (default) - Command Line -Select this mode if you require features of HTTP.sys, such as port sharing. +Select this mode if you require features of HTTP.sys, such as port sharing. This mode supports NTLM in both single server and High Availability configurations. ```bash Octopus.Server.exe configure --webServer=HttpSys @@ -40,7 +40,7 @@ Octopus.Server.exe configure --webServer=HttpSys ### User Mode authentication via Kestrel - Command Line -Select this mode for High Availability configurations. +Select this mode if you require Kerberos authentication. ```bash Octopus.Server.exe configure --webServer=Kestrel @@ -89,17 +89,13 @@ Without some additional configuration, AD authentication, whether forms-based or ### Supported setups for Active Directory authentication {#supported-active-directory-setups} -Octopus Deploy supports various options for Active Directory authentication. +Octopus Deploy supports various options for Active Directory authentication. Both HTTP.sys and Kestrel web server modes are compatible with High Availability configurations. The choice of web server determines which authentication protocols are available. -:::div{.hint} -Not all high availability and Active Directory configurations are supported. There are limitations on the use of Kerberos in high availability scenarios. This is due to a requirement to [use a machine level SPN in order to allow Kerberos to work](#configuring-kerberos) with our web server. -::: - -| Octopus Option | Single Octopus Server | High-Availability | -|---------------------------------|-----------------------|-------------------| -| NTLM | Yes | Yes | -| Negotiate | Yes | No | -| IntegratedWindowsAuthentication | Yes | No | +| Octopus Option | HTTP.sys (Kernel Mode) | Kestrel (User Mode) | +|---------------------------------|------------------------|----------------------| +| NTLM | Yes | Yes | +| Negotiate | NTLM only | Kerberos, NTLM | +| IntegratedWindowsAuthentication | NTLM only | Kerberos, NTLM | :::div{.hint} **Service Accounts and Kerberos** @@ -139,7 +135,7 @@ setspn.exe -S HTTP/od.domain.local server1 :::div{.hint} **HA Clusters** -If you are running a HA Octopus Deploy environment, Kerberos authentication is not currently supported. Please refer to our section on [Supported Setups for Active Directory Authentication](#supported-active-directory-setups) +Kerberos authentication in a High Availability environment requires configuring Octopus to use Kestrel (User Mode). Please refer to our section on [Supported Setups for Active Directory Authentication](#supported-active-directory-setups). ::: For more information about configuration of SPNs [please see this microsoft support article](https://support.microsoft.com/en-us/help/929650/how-to-use-spns-when-you-configure-web-applications-that-are-hosted-on). From 20910a62465b0a6ebc499fbe4e8538b830f5cf7d Mon Sep 17 00:00:00 2001 From: domenicsim1 Date: Thu, 5 Mar 2026 09:43:57 +1100 Subject: [PATCH 2/4] trouble shooting --- ...leshooting-active-directory-integration.md | 28 ++++++++++++++++++- 1 file changed, 27 insertions(+), 1 deletion(-) diff --git a/src/pages/docs/security/authentication/active-directory/troubleshooting-active-directory-integration.md b/src/pages/docs/security/authentication/active-directory/troubleshooting-active-directory-integration.md index 5db2a7e72d..271a3bc63d 100644 --- a/src/pages/docs/security/authentication/active-directory/troubleshooting-active-directory-integration.md +++ b/src/pages/docs/security/authentication/active-directory/troubleshooting-active-directory-integration.md @@ -1,7 +1,7 @@ --- layout: src/layouts/Default.astro pubDate: 2023-01-01 -modDate: 2023-10-04 +modDate: 2026-03-05 title: Troubleshooting Active Directory integration description: Information on troubleshooting common Active Directory integration issues. navOrder: 30 @@ -201,3 +201,29 @@ To resolve this issue, open Active Directory Administrative Center for the domai Octopus Server `2020.1.x` has a known issue with users signing in across domains. The underlying cause relates to server moving from .NET Framework (HttpListener) to .NET Core (HttpSys). For more information about the issue, see this [GitHub issue](https://github.com/OctopusDeploy/Issues/issues/6265). For configuration guidelines and troubleshooting integrated authentication, see our [Active Directory authentication](/docs/security/authentication/active-directory) guide. For users on a different domain to the domain the Octopus Server is a member of, the workaround is to use forms authentication instead of the `Sign in with a domain account` button. As of `2020.1.7` the server will detect this issue when users attempt to sign in across domains, and it will provide guidance to those users who are impacted. + +## Sign in with a domain account fails with no clear error + +When using HTTP.sys (Kernel Mode), certain server-side errors may not be surfaced in the response. Instead, you may see a generic 500 error or the message: + +> An error occurred with Windows authentication, possibly due to a known issue, please try using forms authentication. + +This can make the root cause difficult to diagnose. A useful diagnostic step is to temporarily switch to Kestrel (User Mode), which surfaces the full error response: + +```bash +Octopus.Server.exe service --stop +Octopus.Server.exe configure --webServer=Kestrel +Octopus.Server.exe service --start +``` + +Reproduce the sign-in failure and note the error message returned. Once you have identified and resolved the underlying issue, you can switch back to HTTP.sys if desired. See [GitHub issue #9835](https://github.com/OctopusDeploy/Issues/issues/9835) for more detail. + +## Maximum Session Duration breaks Active Directory SSO + +Setting the **Maximum Session Duration** to a low value (for example, `3600` seconds) can prevent users from signing in via the **Sign in with a domain account** button. The underlying error is: + +> Expiration cannot exceed maximum session duration + +When using HTTP.sys, this error is not surfaced directly (see the section above), making it particularly difficult to diagnose. + +To resolve this, increase the Maximum Session Duration in **Configuration ➜ Settings ➜ Server** to a value greater than or equal to the session expiry configured in your environment. See [GitHub issue #9836](https://github.com/OctopusDeploy/Issues/issues/9836) for more detail. From 1299858239a6b2332f4b62bad94fdc7eecd9bea8 Mon Sep 17 00:00:00 2001 From: domenicsim1 Date: Thu, 5 Mar 2026 10:15:39 +1100 Subject: [PATCH 3/4] fixed pre-existing errors --- .../authentication/active-directory/index.md | 53 ++++++++++--------- ...leshooting-active-directory-integration.md | 15 +++--- 2 files changed, 36 insertions(+), 32 deletions(-) diff --git a/src/pages/docs/security/authentication/active-directory/index.md b/src/pages/docs/security/authentication/active-directory/index.md index e8d4f06e55..e99c953668 100644 --- a/src/pages/docs/security/authentication/active-directory/index.md +++ b/src/pages/docs/security/authentication/active-directory/index.md @@ -14,11 +14,12 @@ Active Directory authentication can only be configured for Octopus Server and no Octopus Deploy can authenticate users using Windows credentials. Windows AD authentication can be chosen during installation of the Octopus Server, or later through the configuration. -**Domain user required during setup** +## Domain user required during setup When setting AD Authentication, either via the Octopus setup wizard or running the commands outlined below to switch to AD authentication mode, make sure you are signed in to Windows as a domain user. If you are signed in as a local user account on the machine (a non-domain user) you won't be able to query Active Directory, so setup will fail. ## Active Directory sign-in options + If you are using Active Directory Authentication with Octopus, there are two ways to sign in. 1. Integrated authentication @@ -48,7 +49,7 @@ Octopus.Server.exe configure --webServer=Kestrel ## Integrated authentication -The easiest way to sign in when using Active Directory is to use Integrated Authentication. +The easiest way to sign in when using Active Directory is to use Integrated Authentication. This allows a one-click option to *Sign in with a domain account* as pictured below. :::figure @@ -63,7 +64,7 @@ This will instruct the Octopus Server to issue a browser challenge. NTLM Authent Octopus.Server.exe configure --webAuthenticationScheme=IntegratedWindowsAuthentication ``` -Setting `IntegratedWindowsAuthentication` will mean that Octopus will attempt to [use Kerberos Authentication](#ActiveDirectoryAuthentication-UsingNegotiate) instead. [Read about other supported values](https://msdn.microsoft.com/en-us/library/system.net.authenticationschemes(v=vs.110).aspx). +Setting `IntegratedWindowsAuthentication` will mean that Octopus will attempt to use Kerberos Authentication instead. [Read about other supported values](https://msdn.microsoft.com/en-us/library/system.net.authenticationschemes(v=vs.110).aspx). :::div{.hint} **How it works** @@ -98,9 +99,9 @@ Octopus Deploy supports various options for Active Directory authentication. Bot | IntegratedWindowsAuthentication | NTLM only | Kerberos, NTLM | :::div{.hint} - **Service Accounts and Kerberos** +**Service Accounts and Kerberos** -From Octopus version 2020.1.0 and above, an upgrade to .Net Core 3.1 and usage of the HTTP.sys library, the Octopus Deploy Service running with Domain Service Account credentials, does not have the ability to read the HttpContext.User.Identity.Name property which is used for Kerberos authentication. There is a requirement to run the Octopus Deploy Service as Local System in order to allow for Kerberos to successfully Authenticate. You can read more about this here: https://github.com/OctopusDeploy/Issues/issues/6602 +From Octopus version 2020.1.0 and above, an upgrade to .Net Core 3.1 and usage of the HTTP.sys library, the Octopus Deploy Service running with Domain Service Account credentials, does not have the ability to read the HttpContext.User.Identity.Name property which is used for Kerberos authentication. There is a requirement to run the Octopus Deploy Service as Local System in order to allow for Kerberos to successfully Authenticate. You can read more about this in [GitHub issue #6602](https://github.com/OctopusDeploy/Issues/issues/6602). ::: ### Configuring Kerberos authentication for Active Directory {#configuring-kerberos} @@ -113,23 +114,25 @@ Here's a simple checklist to help you on your way to allowing Kerberos Authentic 4. Allow Automatic logon via a browser. 5. Set the appropriate SPNs. 6. Enable AES256 encryption for Kerberos tickets. - + - A valid Service Principal Name (SPN) for the `HTTP` service class for each Octopus host NETBIOS name. If you are accessing your Host via its FQDN then you will need to also add an FQDN also for the `HTTP` service class. (Please Note: Whether you've configured your Octopus host to use `HTTP` or `HTTPS`, you will only need to set an `HTTP` SPN.) - Included FQDNs of all Octopus Deploy Hosts and Octopus clusters within your trusted sites or Intranet zones. - Client Machines configured to allow auto logon with current username and password. -**SPN Configuration** +#### SPN Configuration Set an `HTTP` service class SPN for the NETBIOS name and FQDN of your OD hosts. For example, if you are hosting `od.domain.local` from server `server1` you will require the following registered service principal names for your server: -``` + +```text HTTP/od HTTP/od.domain.local ``` + These can be registered by running the following commands in an elevated command prompt or PowerShell session: -``` +```shell setspn.exe -S HTTP/od server1 -setspn.exe -S HTTP/od.domain.local server1 +setspn.exe -S HTTP/od.domain.local server1 ``` :::div{.hint} @@ -138,13 +141,13 @@ setspn.exe -S HTTP/od.domain.local server1 Kerberos authentication in a High Availability environment requires configuring Octopus to use Kestrel (User Mode). Please refer to our section on [Supported Setups for Active Directory Authentication](#supported-active-directory-setups). ::: -For more information about configuration of SPNs [please see this microsoft support article](https://support.microsoft.com/en-us/help/929650/how-to-use-spns-when-you-configure-web-applications-that-are-hosted-on). +For more information about configuration of SPNs [please see this Microsoft support article](https://support.microsoft.com/en-us/help/929650/how-to-use-spns-when-you-configure-web-applications-that-are-hosted-on). -**Internet Security Configuration - Adding Octopus to the Trusted Zone** +#### Internet Security Configuration - Adding Octopus to the Trusted Zone -The aim here is to allow the current user's logon credentials to be sent through to Octopus and authenticated against the SPNs. It is important to remember that a URI is considered to be in the "Internet Zone" whenever it contains a `.`. +The aim here is to allow the current user's logon credentials to be sent through to Octopus and authenticated against the SPNs. It is important to remember that a URI is considered to be in the "Internet Zone" whenever it contains a `.`. -``` +```text Internet Zone http://host.local http://192.168.x.x @@ -157,14 +160,14 @@ http://host http://local ``` -Accessing a host via the NETBIOS name will mean that the "Intranet zone" rules will be applied. **This can be overruled by adding the NETBIOS name to "Trusted Sites" list**. (More detail [here](https://support.microsoft.com/en-au/help/303650/intranet-site-is-identified-as-an-internet-site-when-you-use-an-fqdn-o)). +Accessing a host via the NETBIOS name will mean that the "Intranet zone" rules will be applied. **This can be overruled by adding the NETBIOS name to "Trusted Sites" list**. (More detail in this [Microsoft support article](https://support.microsoft.com/en-au/help/303650/intranet-site-is-identified-as-an-internet-site-when-you-use-an-fqdn-o)). The recommend way to configure this, is to add all potential URIs that will be used to access Octopus, to the "Trusted Sites" list. -This can be done in several ways including via Group Policy, scripting or via [internet security settings menu](https://www.computerhope.com/issues/ch001952.htm). +This can be done in several ways including via Group Policy, scripting or via [internet security settings menu](https://www.computerhope.com/issues/ch001952.htm). -**Internet Security Configuration - Allow Automatic logon via browser** +#### Internet Security Configuration - Allow Automatic logon via browser -All **client machines** will need to be configured to allow automatic logon. We can set this option on all sites added to the trusted sites zone. This can be done via Group Policy, scripting or via the internet security settings menu. +All **client machines** will need to be configured to allow automatic logon. We can set this option on all sites added to the trusted sites zone. This can be done via Group Policy, scripting or via the internet security settings menu. To enable the option via the Internet Security Settings **Internet Explorer** go to **Tools ➜ Internet Options ➜ Security** tab, Select "Trusted Zones" then **Custom level...**. @@ -193,7 +196,7 @@ To set trusted sites via GPO: 1. Select the **Logon Options**. 1. Select **Enabled** and click the drop-down menu that has appeared. 1. Select **Automatic logon with current username and password**. -1. Click **OK** +1. Click **OK** That is all the is needed for kerberos to be used as the logon method when using integrated sign-in or Forms-based authentication. @@ -213,7 +216,7 @@ Using this option, the credentials are posted back to the Octopus Server, and Oc Keep in mind that if your Octopus Server isn't [configured to use HTTPS](/docs/security/exposing-octopus/expose-the-octopus-web-portal-over-https), these are posted in plain text (just like signing in to any other website). ::: -If the Octopus Server and its users are on the **same domain**, it is sufficient to provide a simple username in this field, for example *paul**.*User Principal Names, of the form *user@domain.com* are also accepted in this scenario. +If the Octopus Server and its users are on the **same domain**, it is sufficient to provide a simple username in this field, for example *paul*. User Principal Names, of the form `user@domain.com` are also accepted in this scenario. If the server and its users are on different domains, or **many domains** are in use, the *DOMAIN\user* username format must be provided for users who are not a member of the domain the server is in. @@ -225,7 +228,7 @@ Users will receive the error "**Username not found. UPN format may not be suppo Forms-based authentication can also be disabled: -**Disabling HTML form sign-in** +#### Disabling HTML form sign-in ```bash Octopus.Server.exe configure --allowFormsAuthenticationForDomainUsers=false @@ -245,7 +248,7 @@ It is possible to reconfigure an existing Octopus Server to use a different auth To switch from username/password authentication to Active Directory authentication, use the following script from an administrative command prompt on the Octopus Server: -**Selecting Active Directory authentication** +#### Selecting Active Directory authentication ```bash Octopus.Server.exe configure --activeDirectoryIsEnabled=true @@ -259,7 +262,7 @@ The text `YOUR_USERNAME` should be your Active Directory account name, in either To switch from Active Directory authentication to username/password authentication, use the following script from an administrative command prompt on the Octopus Server: -**Switching to username/password authentication** +#### Switching to username/password authentication ```bash Octopus.Server.exe configure --activeDirectoryIsEnabled=false @@ -271,7 +274,7 @@ Octopus.Server.exe admin --username=YOUR_USERNAME In **Octopus 2.5.11** and newer you can specify a custom container to use for AD Authentication. This feature addresses the issue of authenticating with Active Directory where the Users container is not in default location and permissions prevent queries as a result. Specifying the container will result in the container being used as the root of the context. The container is the distinguished name of a container object. All queries are performed under this root which can be useful in a more restricted environment. This may be the solution if you see a "The specified directory service attribute or value does not exist" error when using Active Directory authentication. -**Setting a custom container** +#### Setting a custom container ```bash Octopus.Server.exe configure --activeDirectoryContainer "CN=Users,DC=GPN,DC=COM" @@ -307,4 +310,4 @@ The following topics are explained further in this section: - [Moving your Octopus Server to another Active Directory domain](/docs/security/authentication/active-directory/moving-active-directory-domains) - [Specify a custom container for AD authentication](/docs/security/authentication/active-directory/custom-containers-for-ad-authentication) -- [Troubleshooting Active Directory integration](/docs/security/authentication/active-directory/troubleshooting-active-directory-integration) \ No newline at end of file +- [Troubleshooting Active Directory integration](/docs/security/authentication/active-directory/troubleshooting-active-directory-integration) diff --git a/src/pages/docs/security/authentication/active-directory/troubleshooting-active-directory-integration.md b/src/pages/docs/security/authentication/active-directory/troubleshooting-active-directory-integration.md index 271a3bc63d..71f3f18b0c 100644 --- a/src/pages/docs/security/authentication/active-directory/troubleshooting-active-directory-integration.md +++ b/src/pages/docs/security/authentication/active-directory/troubleshooting-active-directory-integration.md @@ -39,11 +39,11 @@ Octopus Deploy uses .dlls provided by Microsoft to interact with Active Director - System.DirectoryServices - System.DirectoryServices.ActiveDirectory -The code will use the method `LoginUser()` to authenticate the user's credentials. +The code will use the method `LoginUser()` to authenticate the user's credentials. Assuming the login is successful, Octopus Deploy will create [System.DirectoryServices.AccountManagement.UserPrincipal](https://docs.microsoft.com/en-us/dotnet/api/system.directoryservices.accountmanagement.userprincipal) object to query group membership. Group membership query in this order of operations: -1. First call [GetAuthorizationGroups](https://docs.microsoft.com/en-us/dotnet/api/system.directoryservices.accountmanagement.userprincipal.getauthorizationgroups) as that does a recursive search and returns security groups only. +1. First call [GetAuthorizationGroups](https://docs.microsoft.com/en-us/dotnet/api/system.directoryservices.accountmanagement.userprincipal.getauthorizationgroups) as that does a recursive search and returns security groups only. 2. If `GetAuthorizationGroups()` fails (for a variety of reasons), then run [GetGroups](https://docs.microsoft.com/en-us/dotnet/api/system.directoryservices.accountmanagement.principal.getgroups). The downside of `GetGroups()` is it only returns groups a user is a direct member of and includes distribution groups. Octopus Deploy ignores distribution groups. When a cross-domain trust is configured, both `GetAuthorizationGroups()` and `GetGroups()` methods will include groups in the trusted domains of the user. Octopus Deploy relies on what those methods return to determine group membership. We've found the vast majority of the time; Active Directory issues are a misconfiguration within Active Directory itself. We've provided scripts below where you can take Octopus Deploy out of the equation and test your configuration directly. @@ -57,10 +57,10 @@ Octopus relies on Active Directory users being configured with enough informatio 3. Email Address :::figure -![](/docs/img/security/authentication/active-directory/images/5866202.png) +![Active Directory user properties showing the Account tab](/docs/img/security/authentication/active-directory/images/5866202.png) ::: -![](/docs/img/security/authentication/active-directory/images/5866203.png) +![Active Directory user properties showing additional fields](/docs/img/security/authentication/active-directory/images/5866203.png) These values can be used by Octopus to uniquely identify which Octopus User Account should be associated with each Active Directory User. @@ -101,7 +101,8 @@ Notes: - Ensure you replace the domain username ``ExampleUser`` with a sample Octopus username who would normally log into the system. - It's recommended that you run this script as the same user you're running the Octopus service under and on the same server so it reproduces the problem accurately. -If specifying a container. +If specifying a container: + - Ensure you replace the active directory container string ``CN=Users, DC=acme, DC=local`` with the appropriate value for your network. If you're not sure of this value, we suggest talking to your network team (active directory expert) or trying different values and testing it with the script. For additional help on building/finding your container string, this StackOverflow answer is excellent. [http://serverfault.com/a/130556](http://serverfault.com/a/130556) See the following documentation page for further information on configuring Octopus to use a [specific Active Directory container](/docs/security/authentication/active-directory/custom-containers-for-ad-authentication). @@ -146,7 +147,7 @@ If problems persist, we suggest turning on active directory diagnostic logging a It's recommended that you backup any registry entries before making changes. ::: -``` +```text Path: HKLM\SYSTEM\CurrentControlSet\Services\NTDS\Diagnostics\15 Field Engineering Type: DWORD Value: 5 @@ -163,7 +164,7 @@ For more information on diagnostic logging, see the following Microsoft TechNet The diagnostic logs can be viewed in the Event Viewer. :::figure -![](/docs/img/security/authentication/active-directory/images/5865632.png) +![Event Viewer showing Active Directory diagnostic logs](/docs/img/security/authentication/active-directory/images/5865632.png) ::: :::div{.hint} From 1ff080b83f3ac4bfe98f138745c45c423e298c60 Mon Sep 17 00:00:00 2001 From: domenicsim1 Date: Thu, 5 Mar 2026 10:19:20 +1100 Subject: [PATCH 4/4] fix issue --- .../docs/security/authentication/active-directory/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/docs/security/authentication/active-directory/index.md b/src/pages/docs/security/authentication/active-directory/index.md index e99c953668..f8119297d1 100644 --- a/src/pages/docs/security/authentication/active-directory/index.md +++ b/src/pages/docs/security/authentication/active-directory/index.md @@ -228,7 +228,7 @@ Users will receive the error "**Username not found. UPN format may not be suppo Forms-based authentication can also be disabled: -#### Disabling HTML form sign-in +### Disabling HTML form sign-in ```bash Octopus.Server.exe configure --allowFormsAuthenticationForDomainUsers=false