Single Sign-On (SSO) & Windows Authentication

Single Sign-On (SSO) allows users to log into Cockpit using their existing corporate account (like Okta or Microsoft Azure), or even log in automatically without typing a password if they are using a company-managed Windows computer.

---

What is SSO? 🎟️

💡 Analogy: The Theme Park Wristband

Imagine going to a massive theme park with dozens of rides:

• Without SSO: You have to pull out your wallet and pay with a different cash ticket for every single ride (typing passwords for Cockpit, email, HR portal, etc.).
• With SSO: You buy a single universal wristband at the park entrance. When you want to go on a ride, the operator scans your wristband and waves you in immediately.

SAML and OIDC are simply the standard "wristband technologies" (like barcode vs RFID chip) that companies use to build these systems.

Supported SSO Protocols:

1. SAML 2.0: Connects Cockpit to business identity services like Okta, Keycloak, Ping Identity, or Azure AD.
2. OpenID Connect (OIDC): A modern, lightweight way to sign in using accounts like Google Workspace or Microsoft Entra ID.
3. Windows Session Authentication (Kerberos / Integrated Windows Authentication): A special "VIP pass". If your laptop is managed by your company's network domain, Cockpit will detect that you are already logged into Windows and log you into the web dashboard automatically—no username or password required.

---

1. Setting Up Windows Session Authentication (Kerberos)

To set up passwordless login for Windows domain users, you must prepare your Active Directory Domain Controller and configure Cockpit.

Step A: Active Directory Preparation

Your network administrator must run these commands on the Active Directory Domain Controller to generate a secure "Keytab" file for Cockpit:

# 1. Register the Cockpit website with your Active Directory
setspn -a HTTP/cockpit.corp.awan.io svc-cockpit

# 2. Export the security keytab file (save this as cockpit.keytab)
ktpass /out cockpit.keytab /princ HTTP/cockpit.corp.awan.io@CORP.AWAN.IO /mapuser svc-cockpit /pass Password123 /crypto AES256-SHA1 /ptype KRB5_NT_PRINCIPAL

Step B: Cockpit Server Configuration

1. Copy the generated cockpit.keytab file to your Cockpit server folder: /etc/cockpit/cockpit.keytab.
2. Add these configuration lines to your /etc/cockpit/cockpit.conf file:

[auth]
sso_enabled = true
sso_method = "kerberos"
sso_keytab_path = "/etc/cockpit/cockpit.keytab" # Location of the keytab file
sso_realm = "CORP.AWAN.IO" # Your Active Directory Domain
sso_service_principal = "HTTP/cockpit.corp.awan.io@CORP.AWAN.IO"

---

2. Setting Up SAML 2.0 Identity Providers

To allow your team to sign in using Okta, Azure AD, or Keycloak:

1. Log into Cockpit as an administrator.
2. Go to Settings > Identity Management > SAML.
3. Click Metadata Import and upload the Metadata XML file you downloaded from Okta/Azure.
4. Cockpit will generate the settings you need to paste back into your identity provider:
   • Entity ID: https://cockpit.corp.awan.io/api/v1/auth/saml/metadata (The unique name for this Cockpit app).
   • Assertion Consumer Service (ACS) URL: https://cockpit.corp.awan.io/api/v1/auth/saml/acs (Where the identity provider sends users after they log in).
5. Map user profiles:
   • Username Attribute: Set to NameID or uid so Cockpit knows the user's email/username.
   • Groups Attribute: Set to memberOf or groups so Cockpit can automatically assign permissions based on their company departments.