Windows desktop sign-in (integrated Windows authentication)

Windows desktop sign-in, also called integrated Windows authentication, lets a person who is already signed in to a company Windows computer open SSOGEN, My Apps or a protected application without typing a password. Windows already holds a proof of who they are (a Kerberos ticket), and the browser hands it to SSOGEN. SSOGEN checks it, finds the person in your Active Directory, and signs them in.

This guide follows Acme Corp (domain acme.example, Active Directory realm ACME.EXAMPLE, SSOGEN at sso.acme.example) so that Maria Lopez (maria.lopez@acme.example) is signed in on her office laptop. It has these parts:

1. What people experience, and what it does not do.
2. Prepare Active Directory (steps outside SSOGEN).
3. Prepare the browsers (steps outside SSOGEN).
4. Create the connection in SSOGEN.
5. Test it with a real ticket, then activate it.
6. Use it in a sign-in policy.
7. When something goes wrong.

Before you start

You need an Active Directory connection already working in SSOGEN (see Connect Active Directory or LDAP), because Windows sign-in finds the person there. You also need a network zone for your office (see Network zones), and an administrator account that can manage sign-in connections.

A few words used throughout:

Term	Meaning
Kerberos	The sign-in system built into Active Directory. After Maria signs in to Windows, Windows can prove who she is to a website without her password.
Service principal name (SPN)	The name a Kerberos ticket is issued for. For SSOGEN it is HTTP/ followed by the SSOGEN host name, for example HTTP/sso.acme.example.
Keytab	A file that holds the secret key for a service account, so SSOGEN can open the tickets issued for its name.
Realm	The Kerberos name of your domain, in capitals: ACME.EXAMPLE.

1. What people experience

Maria is on her office laptop, on the office network. She opens My Apps. There is no password page: she lands on her applications. If the application’s policy needs a second step (for example an authenticator code), she is asked for it, exactly as after a password.

If anything is missing, she simply sees the normal sign-in page and signs in another way. That happens when:

• she is at home or on a network you have not listed;
• her browser has no Windows ticket (for example a computer that is not joined to the domain);
• her Windows account is not matched to anyone in SSOGEN, or is disabled;
• she signed out. After a failed attempt, and after signing out, SSOGEN does not try Windows sign-in again in that browser for twelve hours. She can still choose Windows sign-in from the sign-in page’s list.

What it does not do

• A Windows sign-in counts as a single-factor sign-in, the same strength as a password. SSOGEN cannot tell whether Windows itself used a password, a smart card or Windows Hello, so it does not give extra credit. A policy that requires a second factor still asks for it, and a policy that requires a passkey is never met by Windows sign-in.
• It never replaces your policies. A policy accepts Windows sign-in only if you add the connection to its list of providers (section 6).
• It is for managed computers. List only networks where every browser is managed by your domain.

2. Prepare Active Directory (steps in Active Directory)

Do these on a domain controller, or from a machine with the Active Directory tools.

2.1 Create a service account just for SSOGEN

Create a normal user account used only for this, for example svc-ssogen-platform, with a long random password. Do not reuse an account that another product uses: exporting the keytab (step 2.3) changes that account’s key and would break anything else that relies on it.

The account must:

• support AES encryption (SSOGEN does not accept the old RC4 or DES keys);
• not be trusted for delegation, and have no delegation settings of any kind;
• hold no other service principal names.

2.2 Register the SSOGEN name

SSOGEN’s name must be the exact host name people type in the browser, without a port. Run on a domain controller:

setspn -S HTTP/sso.acme.example svc-ssogen-platform

Check that exactly one account holds it:

setspn -Q HTTP/sso.acme.example

2.3 Export the keytab

ktpass -out ssogen-platform.keytab -princ HTTP/sso.acme.example@ACME.EXAMPLE -mapuser ACME\svc-ssogen-platform -crypto AES256-SHA1 -ptype KRB5_NT_PRINCIPAL -pass *

-pass * makes the tool ask for the account’s password. The command writes ssogen-platform.keytab. Treat it like a password: keep it off shared folders, and delete your copy once it is uploaded to SSOGEN. You need it again whenever the service account’s password changes.

2.4 Check that no one can delegate to SSOGEN’s name

An account that is trusted to delegate to HTTP/sso.acme.example could sign in to SSOGEN as anyone. Make sure none is. In particular, never add SSOGEN’s name to the delegation list of an SSOGEN Gateway service account (see Kerberos delegation and form fill sign-in). SSOGEN also looks for these cases when you test the connection (section 5).

2.5 Keep clocks in step

Kerberos allows a difference of five minutes between a computer and the SSOGEN server. SSOGEN does not allow more, so do not widen it on your computers. Make sure the SSOGEN server’s clock is synchronized to the same time source as your domain controllers.

3. Prepare the browsers (steps in your browser management)

Browsers only send a Windows ticket to sites they have been told to trust.

• Google Chrome and Microsoft Edge: set the policy AuthServerAllowlist to sso.acme.example on your managed computers (Group Policy or your device-management tool). Do not set AuthNegotiateDelegateAllowlist: SSOGEN does not need the person’s credentials to be forwarded, and discards them.
• Firefox: add https://sso.acme.example to the setting network.negotiate-auth.trusted-uris.

People must open SSOGEN by its normal host name (https://sso.acme.example), not by an address or an alias.

Behind a load balancer or reverse proxy, allow large request headers. A person who belongs to many groups sends a large ticket. On Apache httpd, set LimitRequestFieldSize 65536; configure the same headroom on any load balancer. Do not log the Authorization header on these servers (no %{Authorization}i in an httpd log format, and no header logging on the balancer): the ticket is a secret until it expires.

4. Create the connection in SSOGEN

Before you start, add the Active Directory under Identity > Directories and define the office networks under SSO policies > Network zones: the setup chooses from both.

1. In the Admin Console open SSO policies > Identity providers and select Add identity provider.
2. Under Generic SAML / OpenID Connect / Directory (LDAP) choose Windows sign-in (Kerberos). The page Add Windows sign-in opens with six steps: General, Service principal, Keytab, Realms, Network zones, Review and activate.

Step	What to enter
General	Display name: the name people see in the sign-in page’s list, for example Windows sign-in. Connection ID: a short name in lower case with hyphens, for example acme-windows; it fills in from the name and cannot be changed later.
Service principal	Host name: the host name people use to reach SSOGEN, for example sso.acme.example; SSOGEN refuses any other. Kerberos realm: your domain in capitals, for example ACME.EXAMPLE. Service account (for the commands below): “Not stored. Only used to write the commands.” The step shows the service principal (HTTP/sso.acme.example@ACME.EXAMPLE) and, under Commands for your domain administrator, copyable commands for section 2 and section 3: register the service principal (setspn), export the keytab (ktpass), and the Chrome and Edge and Firefox settings.
Keytab	Keytab file: the file ktpass wrote, at most 8 KiB. It is stored encrypted and never shown again; the connection shows only its name, key versions and encryption types.
Realms	One row per Active Directory realm whose people may sign in this way: the Realm in capitals and the Directory that holds those people. Add realm adds a row. A realm that is not listed is refused.
Network zones	Tick one or more of your network zones (see Network zones). Windows sign-in is offered only to people on these networks. Try Windows sign-in automatically when the page opens: on, the sign-in page tries it by itself before showing the form; off, it is offered only from the “Sign in with” list. Select Create connection: the connection is saved as a draft.

SSOGEN refuses the keytab, with a message, when it is not a keytab, has no entry for the service principal, or holds only RC4 or DES keys (for example “That file is not a keytab, or it is damaged or over 8 KiB. Export it again with ktpass.”). Only the newest key version and the one before it are kept, so changing the service account’s password does not lock everyone out at once; upload the new keytab afterwards.

Windows sign-in finds the person in the realm’s directory each time, by the user principal name (maria.lopez@acme.example) or, for a name without a domain, the Windows logon name. The person must match exactly one enabled account. The person is the same SSOGEN person as when signing in with a directory password.

5. Test it with a real ticket, then activate it

1. On Review and activate, check the summary and select Validate. SSOGEN checks the settings and the keytab. A normal Test does not apply to this connection, because only a real ticket proves it works.

2. On a domain-joined computer, in a browser set up as in section 3, signed in to the Admin Console, select Try connection (on the review step, or on the connection’s page). A browser that offers no Windows ticket is told so: “This browser did not offer a Windows sign-in. Open this test in a browser on a domain-joined computer, signed in to Windows, that lists this site for integrated authentication.”

3. The result page shows the Windows account SSOGEN received (for example maria.lopez@ACME.EXAMPLE), the directory it maps to, the SSOGEN person it would sign in, and its Strength, which for Windows sign-in is Password or single sign-on (single-factor). No session is created.

4. Read any warnings under Check before you activate. They are advice, not failures:

   • an account in your directory is trusted to delegate to SSOGEN’s name;
   • the service account allows another account to act for it;
   • the service account holds another service name;
   • the directory checks could not be run.

   Fix the first three in Active Directory, then test again.

5. A passed try is what allows activation: select Activate. SSOGEN refuses if another active Windows sign-in connection that tries automatically covers the same network zone: “Another active Windows sign-in connection already signs people in automatically in one of these zones. Change the zones or turn automatic sign-in off.”

6. Use it in a sign-in policy

Add the connection (Windows sign-in) to the providers of each authentication policy that should accept it. Policies that do not list it never accept a Windows sign-in. A good starting point for office computers is a policy that lists Windows sign-in and your Active Directory connection, so people who are out of the office sign in with their directory password. See Create a policy and assign it.

7. When something goes wrong

People see the normal sign-in page, and sometimes one of these messages:

What Maria sees	Why	What to do
The normal page, no message	No ticket, not on a listed network, the connection is not active, or the policy does not list it	Check section 3, the zones, activation, and the policy’s providers.
“Your browser didn’t offer a Windows sign-in. Sign in another way below, or contact your IT help desk.”	She chose Windows sign-in from the list, and her browser sent no ticket	Check section 3 for her browser.
“Your Windows account isn’t set up for SSOGEN. Sign in another way below, or contact your IT help desk.”	No matching person, or more than one, in the directory	Check her user principal name and logon name in Active Directory and the realm mapping.
“Your account is disabled. Contact your IT help desk.”	The Active Directory account is disabled	Enable it, or tell her to contact the help desk.
“We couldn’t check your account with the company directory. Sign in another way, or try again in a few minutes.”	The directory connection did not answer	Check the directory connection’s health.
“Windows sign-in isn’t working on this site right now. Sign in another way.”	The ticket was refused, for example the service name is wrong, the keytab is out of date, a clock is more than five minutes out, or the browser offered an older NTLM sign-in instead of Kerberos	See below.
“Too many sign-in attempts. Wait a minute and try again.”	Many tries from one network in a short time	Wait a minute.

The exact reason for a refusal is not shown on the page; it is recorded in the audit trail as a Windows sign-in refusal, with the Windows account named once the ticket has been accepted as genuine. Common causes:

• The browser sent NTLM, not Kerberos. The name is not registered (setspn -Q), is registered on two accounts, or the person opened SSOGEN by another name.
• The keytab is out of date. The service account’s password changed. Export a new keytab (step 2.3), then select Edit on the connection and, on the Keytab step, choose the new file (a file is only needed to replace the stored one). Save the revision, then validate, try and activate it.
• Only some people fail. Their tickets are large and a proxy cut the header (section 3), or their account is a machine or service account rather than a person.
• Nobody is signed in automatically after a sign-out. That is the twelve-hour pause after a sign-out, not a fault.