SSO setup

What SSO does in Linux Identity

Single Sign-On (SSO) replaces per-user passwords and ad-hoc SSH key handouts with org-wide authentication tied to your existing identity provider. When an admin signs in to the Linux Identity dashboard, we redirect them to your IdP (Okta, Google, Entra, etc.); when an engineer SSHes into a host, the agent on that host exchanges their IdP identity for a short-lived SSH certificate.

The practical effect:

• One off-boarding control point. Disable a user in your IdP and they lose dashboard + SSH access at the next certificate expiry (default 8 hours). No authorized_keysgrep across the fleet.
• Group-driven roles. Map an IdP group (e.g. eng-prod) to a Linux Identity role (e.g. prod-admin) and membership flows automatically.
• MFA is your IdP’s job. Whatever step-up, hardware key, or risk-based policy you already enforce in Okta / Google / Entra carries straight through.
• Audit lines are identity-tagged. Every sudo invocation in the audit log carries the IdP-verified email, not a shared ec2-user.

Supported IdPs

Pick the matching section below. If your IdP isn’t named, jump to Generic SAML 2.0 or Generic OIDC — they cover the long tail (OneLogin, JumpCloud, Auth0, Ping, Keycloak, Authentik, and anything else conformant).

Prerequisites

• A Linux Identity workspace. Sign up at dashboard.linuxidentity.com/signup.
• Admin access to your IdP. (You need to create an Application / Enterprise app / OIDC client.)
• A verified email domain on your workspace. We won’t let SSO bind to a domain you haven’t proven control of — see the Domains tab on the workspace settings page.
• The exact Workspace ID from the SSO setup page in the dashboard. It looks like ws_8f2a1d4e and appears in every SAML / OIDC URL below.

Okta

SAML 2.0 application with SCIM provisioning. ~10 minutes end-to-end.

1. In the Okta admin console, go to Applications → Applications and click Create App Integration.
2. Choose SAML 2.0 → Next. Name the app Linux Identity. Upload our logo if you like, click Next.
3. Single sign on URL: paste https://api.linuxidentity.com/v1/sso/saml/<workspace_id>/acs from the dashboard SSO page. Check Use this for Recipient URL and Destination URL.
4. Audience URI (SP Entity ID): paste https://api.linuxidentity.com/v1/sso/saml/<workspace_id> from the dashboard SSO page.
5. Name ID format: EmailAddress. Application username: Okta username.
6. Attribute Statements: add email → user.email, first_name → user.firstName, last_name → user.lastName, groups (Filter: Matches regex, .*).
7. Click Next → Finish. On the Sign On tab, click View Setup Instructions and download the IdP metadata XML (or copy the Identity Provider Single Sign-On URL + X.509 Certificate).
8. Back in the Linux Identity dashboard SSO page, paste the metadata XML into IdP metadata (or fill SSO URL + certificate manually). Click Save.
9. Click Test connection in the dashboard. Okta opens a login window; success returns you to the dashboard with a green Connected banner.
10. Enable Push groups (Okta → Linux Identity app → Push Groups) to map Okta groups to Linux Identity roles, then assign the app to the users + groups who should have access.

Google Workspace

SAML app in the Google Admin console. SCIM via the optional secure LDAP add-on (not required for v1).

1. In admin.google.com, go to Apps → Web and mobile apps and click Add app → Add custom SAML app.
2. App name: Linux Identity. Upload our square logo if you like. Click Continue.
3. Google Identity Provider details panel: click Download Metadata (an XML file). Click Continue.
4. Service provider details — ACS URL: paste https://api.linuxidentity.com/v1/sso/saml/<workspace_id>/acs from the dashboard.
5. Entity ID: paste https://api.linuxidentity.com/v1/sso/saml/<workspace_id> from the dashboard. Name ID format: EMAIL. Name ID: Basic Information → Primary email. Click Continue.
6. Attribute mapping: add Primary email → email, First name → first_name, Last name → last_name, Department → department (optional). Click Finish.
7. On the app page, click User access → ON for everyone (or scope to specific Org Units). Save.
8. Back in the dashboard SSO page, click Choose file under IdP metadata and upload the XML you downloaded in step 3.
9. Click Save → Test connection. Google bounces you through the consent screen on first run, then returns you to the dashboard with a green Connected banner.
10. Group sync is not native in Google Workspace SAML — assign Linux Identity roles directly in the dashboard, or upgrade to the secure LDAP add-on to drive group claims.

Microsoft Entra ID (formerly Azure AD)

Enterprise application with SAML SSO + automatic user/group provisioning over SCIM. ~15 minutes end-to-end.

1. In the Microsoft Entra admin center (entra.microsoft.com), open Identity → Applications → Enterprise applications. Click New application → Create your own application.
2. Name it Linux Identity, leave Integrate any other application you don't find in the gallery (Non-gallery) selected, click Create.
3. On the app overview, click Single sign-on → SAML.
4. Basic SAML Configuration → Edit. Identifier (Entity ID): paste https://api.linuxidentity.com/v1/sso/saml/<workspace_id>. Reply URL (ACS): paste https://api.linuxidentity.com/v1/sso/saml/<workspace_id>/acs. Sign-on URL: https://dashboard.linuxidentity.com/. Save.
5. Attributes & Claims → Edit. Set Unique User Identifier to user.mail. Add claims: email (user.mail), first_name (user.givenname), last_name (user.surname), groups (Group Claims → Security groups, source Group ID).
6. SAML Certificates section: click Download next to Federation Metadata XML.
7. Back in the Linux Identity dashboard SSO page, upload the Federation Metadata XML and click Save.
8. In Entra, go to Users and groups → Add user/group and assign the people who should have access.
9. Optional but recommended — Provisioning → Get started → Automatic. Tenant URL: https://api.linuxidentity.com/v1/sso/scim/<workspace_id>. Secret token: copy from the dashboard SSO page (SCIM token). Click Test Connection → Save → Start provisioning.
10. Click Test connection in the dashboard SSO page; first sign-in completes the round-trip and you should see the green Connected banner.

Active Directory (on-prem)

Linux Identity does not bind to LDAP directly — every external identity must come through a SAML or OIDC broker. For on-prem AD you have two supported paths; pick whichever you already operate.

Option A — Entra Connect (recommended)

Sync AD to Entra ID, then follow the Microsoft Entra ID section above. This is the path most teams already have running for Microsoft 365.

1. On a domain-joined Windows Server, download and run Microsoft Entra Connect (formerly Azure AD Connect) from microsoft.com/download.
2. Choose Express Settings if your AD is straightforward (single forest, user UPN matches email). Otherwise choose Customize and configure source anchor + UPN suffix matching.
3. Sign in with a Global Administrator account for your Entra tenant and an Enterprise Admin account for AD. Click Next.
4. On the Filtering page, scope which OUs sync into Entra. Limit to the security groups you intend to grant Linux Identity access to — full-tree sync is rarely what you want.
5. Click Install. Initial sync takes 5–30 min depending on directory size. Confirm in Entra → Users that AD users now appear with synced from on-premises.
6. Now follow the Microsoft Entra ID setup section above (steps 1–10). Group claims will resolve against the synced AD groups; map AD security groups to Linux Identity roles in the dashboard.

Option B — AWS AD Connector (for AWS-resident workloads)

Proxy AD over a VPC peering to your AWS account, then federate via IAM Identity Center (formerly AWS SSO) which exposes a SAML endpoint that Linux Identity treats as a generic SAML IdP.

1. In the AWS Directory Service console (us-east-1 or your preferred region), choose AD Connector → Set up directory.
2. Provide your AD DNS name (corp.example.com), DNS IPs of two domain controllers, and credentials of a service account with read-only directory access.
3. Pick the VPC + subnets that have routability to your DCs (typically a peered or Direct Connect VPC). Click Create directory; provisioning takes ~30 min.
4. Enable AWS IAM Identity Center, set the identity source to your AD Connector directory.
5. In IAM Identity Center → Applications → Add application → Customer managed → SAML 2.0, name it Linux Identity. Application ACS URL: https://api.linuxidentity.com/v1/sso/saml/<workspace_id>/acs. Application SAML audience: https://api.linuxidentity.com/v1/sso/saml/<workspace_id>.
6. Add attribute mappings: Subject → ${user:email} (format emailAddress), email → ${user:email}, first_name → ${user:givenName}, last_name → ${user:familyName}, groups → ${user:groups}.
7. Download the IAM Identity Center SAML metadata XML and upload it to the Linux Identity dashboard SSO page.
8. In IAM Identity Center, assign the AD groups that should have access to the Linux Identity application.
9. In the Linux Identity dashboard, map the AD group names (passed through verbatim in the groups claim) to roles. Click Test connection.
10. If AD Connector is overkill (you only have on-prem workloads, no AWS), use Option A — Entra Connect.

Generic SAML 2.0

Use this section for OneLogin, JumpCloud, Auth0, Ping Identity, Keycloak, Authentik, Shibboleth, ADFS, or any other SAML 2.0 IdP. The metadata exchange is the same; only the admin UI differs.

1. In your IdP admin console, create a new SAML 2.0 application. Name it Linux Identity.
2. Entity ID / Audience URI: paste https://api.linuxidentity.com/v1/sso/saml/<workspace_id> from the dashboard SSO page.
3. ACS URL / Reply URL / Single Sign-On URL: paste https://api.linuxidentity.com/v1/sso/saml/<workspace_id>/acs from the dashboard.
4. Name ID format: EmailAddress (urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress).
5. Signing: signed SAML response is required. Signed assertion is recommended (we accept both). RSA-SHA256 is the default; RSA-SHA1 is rejected.
6. Attribute mapping — at minimum: email (must match Name ID), first_name, last_name. Optional but recommended: groups (multi-valued, one entry per group).
7. Save the application. Download the IdP metadata XML, or copy the SSO URL + X.509 signing certificate.
8. Assign the application to the users + groups that should have access.
9. Back in the Linux Identity dashboard SSO page, upload the IdP metadata XML (or paste the SSO URL + certificate). Click Save.
10. Click Test connection. Resolve any errors against the Troubleshooting section below — most generic SAML failures are attribute-mapping issues, not protocol issues.

Generic OIDC

Use this section when your IdP only speaks OIDC, or when you prefer OIDC (shorter token lifetimes, simpler discovery). Works with Auth0, Keycloak, Ory Hydra, Authentik, Cognito, etc.

1. In your IdP admin console, create a new OIDC client. Application type: Web application (server-side).
2. Allowed grant types: authorization_code with PKCE. (We do NOT use implicit flow, client_credentials, or password grant.)
3. Redirect URI: paste https://api.linuxidentity.com/v1/sso/oidc/<workspace_id>/callback from the dashboard.
4. Post-logout redirect URI (optional): https://dashboard.linuxidentity.com/.
5. Scopes: openid, email, profile. Add groups if your IdP supports a groups scope (most do — check the discovery document at /.well-known/openid-configuration).
6. Token endpoint authentication: client_secret_basic or client_secret_post. (We do NOT support none/public clients.)
7. Capture the client_id and client_secret. Capture the issuer URL — it must be the value that appears in the iss claim, not a wrapper or proxy domain.
8. In the dashboard SSO page, choose Generic OIDC, paste the issuer URL, client_id, and client_secret. Click Save — we validate the discovery document immediately and surface errors if metadata can't be fetched or signing keys can't be discovered.
9. Set the email claim source (default: email), groups claim source (default: groups), and any custom claim mapping.
10. Click Test connection. The IdP&rsquo;s consent screen renders; on approval you're returned to the dashboard with a green Connected banner.

Troubleshooting

Sign-ins are logged at full fidelity in the dashboard under Audit → SSO events. Common failure modes:

Domain mismatch

The IdP returned an email outside the verified domains on your workspace. Add the domain in Workspace → Domains and prove control via a DNS TXT record before retrying. We do this on purpose so a misconfigured IdP can’t silently grant access to anyone in @gmail.com.

Expired SAML metadata

IdP signing certificates rotate (Okta and Entra rotate every 2–3 years by default). When the cert in the metadata XML we have on file no longer matches the cert the IdP is using to sign assertions, every login throws SAML signature verification failed. Fix: re-download the IdP metadata XML and re-upload it on the dashboard SSO page. Schedule a calendar reminder ~30 days before your IdP’s next rotation.

Attribute mapping issues

The IdP completed sign-in but no email, first_name, or last_name claim was returned. The dashboard surfaces the exact claim names we saw in the assertion under Audit → SSO events → last event → Raw claims. Go back to the IdP application and add the missing attribute mappings, or rename your existing ones to email / first_name / last_name.

SCIM not configured

Users sign in successfully but no group membership appears in the dashboard. SCIM is optional and provides automatic group provisioning — without it, you assign roles manually in the dashboard. To enable SCIM, follow the Provisioningsteps in the Okta or Entra ID sections above (Google Workspace and most generic SAML IdPs do not push groups; rely on the groups SAML attribute instead).

Group claim missing

The user signs in but Linux Identity says No roles granted. This means we got an authenticated identity but no group claim to map onto a role. Two fixes:

• Add a groups attribute mapping in the IdP application (multi-valued, one entry per group), OR
• In the dashboard, go to Roles → Assignments and grant the user a role directly. This is fine for small teams or for the initial admin account; for ongoing operations, group-driven roles scale better.

Clock skew

SAML assertions are time-bounded (NotBefore / NotOnOrAfter, usually a 5-minute window). If the IdP server clock and our control plane clock disagree by more than 5 minutes, every assertion is rejected. Both sides should be NTP-synced — this almost always points to an out-of-sync on-prem ADFS server or a JumpCloud agent on a laptop with wrong system time.

Test connection works, real sign-in fails

The Test connection button only validates that we can fetch and parse your IdP metadata. A real sign-in additionally requires that the user has been assigned to the application in the IdP. Confirm in the IdP’s Assignments tab (Okta), User access (Google), or Users and groups (Entra) that the failing user is actually granted the Linux Identity application.

Still stuck? Email support@linuxidentity.com with the SSO event ID from the audit log — that gives us the full SAML/OIDC trace and we can usually tell you the exact mismatched field within an hour.