Single Sign-On (SSO) & Windows Authentication

Cockpit supports Single Sign-On (SSO) and passwordless authentication to integrate with corporate Identity Providers (IdPs) and domain environments.

---

Authentication Protocols

Cockpit integrates with standard SSO frameworks to validate user sessions:

1. SAML 2.0: Integrates with enterprise Identity Providers such as Okta, Keycloak, Ping Identity, and Microsoft Entra ID.
2. OpenID Connect (OIDC): A lightweight authentication layer built on top of OAuth 2.0 for cloud directory integrations.
3. Integrated Windows Authentication (Kerberos / GSSAPI): Allows domain-joined clients to authenticate automatically using their active Windows security ticket, removing the requirement to input credentials manually.

---

1. Configuring Windows Session Authentication (Kerberos)

Deploying Kerberos authentication requires generating a keytab file on the Active Directory Domain Controller and registering the GSSAPI module on Cockpit.

Step A: Active Directory Server Preparation

Run the following administrative commands on the Domain Controller to register the Service Principal Name (SPN) and generate the keytab:

# 1. Register the Cockpit service principal name under the service account
setspn -a HTTP/cockpit.corp.awan.io svc-cockpit

# 2. Export the cryptographic keytab file to "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 Service Configuration

1. Securely copy the generated cockpit.keytab file to /etc/cockpit/cockpit.keytab on the Cockpit server.
2. Add the following parameters to the [auth] section of /etc/cockpit/cockpit.conf:

[auth]
sso_enabled = true
sso_method = "kerberos"
sso_keytab_path = "/etc/cockpit/cockpit.keytab"
sso_realm = "CORP.AWAN.IO"
sso_service_principal = "HTTP/cockpit.corp.awan.io@CORP.AWAN.IO"

---

2. Configuring SAML 2.0 Integration

To connect Cockpit to external Identity Providers like Okta or Azure AD:

1. Log into Cockpit as an administrator.
2. Navigate to Settings > Identity Management > SAML.
3. Select Metadata Import and upload the Identity Provider Metadata XML file.
4. Extract the Cockpit configurations to register the application on the Identity Provider:
   • Entity ID: https://cockpit.corp.awan.io/api/v1/auth/saml/metadata
   • Assertion Consumer Service (ACS) URL: https://cockpit.corp.awan.io/api/v1/auth/saml/acs
5. Configure the attribute mapping in the Identity Provider:
   • Username Attribute: Map to the user's primary email address or unique ID (NameID or uid).
   • Groups Attribute: Map to the group assertion field (memberOf or groups) to enable automatic permission mapping.