Single sign-on and directory accounts

Gardience supports three ways for people to sign in besides local accounts:

• OpenID Connect (OIDC), for example Microsoft Entra ID, Okta, Google, Keycloak or Ping.
• SAML 2.0, with any identity provider that publishes SAML metadata.
• LDAP or Active Directory, where each directory user is added to Gardience by name.

Local accounts keep working when you turn any of these on.

An identity provider (IdP) is the service that checks a person's password and tells Gardience who they are, for example Entra ID or Okta.

How single sign-on works#

1. The person clicks Sign in with ... on the console's sign-in page.
2. Their browser goes to the identity provider, then comes back with a signed answer.
3. Gardience checks the signature and reads the person's user name and groups.
4. Gardience picks one role from the groups (see Map groups to roles).
5. Gardience opens a Salt session for that person, held to that role's permissions.

Each person gets their own Salt session, so the audit log names them, not a shared account. Every successful sign-in is recorded in the audit log as sso.login, and every refused one as sso.denied.

Only one protocol (OIDC or SAML) can be active at a time.

Before you start#

• You need the admin role. The Single sign-on card appears only for admins.
• Decide the public URL of the console: the address people type, for example https://gardience.example.com. It must start with https:// and have no path. Add the port if it is not 443.
• In attach mode, your own Salt master needs Gardience's single sign-on module. Follow step 4 of the ATTACH.md file in the install directory.

Set up OpenID Connect#

1. In your identity provider, create an application (often called a "web app" or "confidential client").
2. In the console, open Settings and scroll to Single sign-on.
3. Set Protocol to OpenID Connect.
4. Set Public URL of this Gardience.
5. Give your identity provider the redirect URI the card shows. It is the public URL followed by /gardience/sso/callback.

6. Fill in:

   • Issuer URL: for Entra ID this looks like https://login.microsoftonline.com/TENANT-ID/v2.0. Gardience reads <issuer>/.well-known/openid-configuration from it.
   • Client ID and Client secret from the application you created.
   • Scopes: openid profile email by default.

7. Set the claim names if yours differ from the defaults:

   • User name claim: preferred_username by default. If the token has no such claim, Gardience uses email, then sub.
   • Groups claim: groups by default. Gardience also reads the roles claim, so app roles work too.
8. Add at least one group mapping (see below).
9. Click Save, then Test connection. A good result names the issuer and how many signing keys it found.
10. Tick Turn on single sign-on and click Save again.

What Gardience checks on every OIDC sign-in:

• The authorization code flow with PKCE (S256), plus state and nonce values.
• The ID token signature (RS256, RS384, RS512, PS256, ES256 or ES384) against the provider's published keys.
• The issuer, the audience (your client ID) and the nonce. Clocks may differ by up to 60 seconds.

The client secret is encrypted with the vault key before it is saved. The card never shows it again; leave the field empty to keep the saved one.

Set up SAML 2.0#

1. In the console, open Settings and scroll to Single sign-on.
2. Set Protocol to SAML 2.0 and set Public URL of this Gardience. Click Save.

3. Give your identity provider the values the card shows:

   • Entity ID: the public URL followed by /gardience/sso/saml/metadata.
   • ACS (reply) URL: the public URL followed by /gardience/sso/saml/acs.
   • Or give it Gardience's metadata, served at /gardience/sso/saml/metadata.
4. Give Gardience your identity provider's metadata. Either enter the IdP metadata URL, or paste the metadata XML into the box below it.

5. Set the attribute names:

   • User name claim / attribute: if the assertion carries this attribute, Gardience uses it. Otherwise it uses the assertion's NameID.
   • Groups claim / attribute: groups by default. Gardience also reads the Microsoft group and role claims (http://schemas.microsoft.com/ws/2008/06/identity/claims/groups and .../claims/role).
6. Add at least one group mapping, click Save, then Test connection. A good result names the identity provider found in the metadata.
7. Tick Turn on single sign-on and click Save.

What Gardience checks on every SAML sign-in:

• The response or the assertion must be signed.
• The response must answer a sign-in that Gardience started. Unsolicited responses are refused.
• Clocks may differ by up to 60 seconds.

Gardience does not sign its own requests to the identity provider.

Map groups to roles#

Under Groups to roles, add one row per group:

• IdP group: the group name or ID exactly as your provider sends it. For Entra ID this is often the group's object ID, not its display name. Matching ignores upper and lower case and spaces at either end.
• Gardience role: admin, approver, operator, helpdesk-windows or viewer.
• Limit to node groups (optional): node groups, separated by commas, that people in this IdP group see and change; empty for the whole fleet. See Team scopes. If someone matches several mappings for their role, they get every group those mappings list, and the whole fleet if any of them has none. Admin mappings are never limited.

If a person is in several mapped groups, the highest role wins, in this order:

1. admin
2. approver
3. operator
4. helpdesk-windows
5. viewer

A person in no mapped group can authenticate with the identity provider but cannot sign in to Gardience. They see "No Gardience access".

The role is worked out again at every sign-in. To change someone's role, change their groups in the identity provider; it takes effect the next time they sign in. People who signed in through single sign-on count as admins or approvers according to the role from their latest sign-in.

The card lists the 50 most recent single sign-on users, with their role and last sign-in time.

Rules for single sign-on user names#

• User names are changed to lower case.
• They may use letters, digits, _, ., @, + and -, up to 128 characters.
• Reserved names are refused.
• A name that matches a local account (including admins and approvers set with gardience roles) is refused. Rename one of the two.

A sign-in must be finished within 10 minutes, in the same browser that started it.

Step-by-step guides for Okta and Entra ID#

Okta and Microsoft Entra ID were each tested with both OIDC and SAML, including group-to-role mapping, in October

1. For every click on the provider's side:

• Set up sign-in with Okta
• Set up sign-in with Microsoft Entra ID

Turning off or removing access#

• To turn single sign-on off, clear Turn on single sign-on and click Save. Local and directory accounts keep working.
• To remove a person, remove them (or their group) in the identity provider. Gardience cannot see that removal. Their console session ends within the hour. Their API keys pause after 7 days without a sign-in. See API keys and the REST API.

Set up LDAP or Active Directory accounts#

This applies to all-in-one installs. In attach mode, set up LDAP on your own Salt master instead.

Directory accounts work differently from single sign-on. There is no group mapping: you add each person by name with a role, and they sign in with their directory password on the normal sign-in page.

1. Open config/users.yaml in the install directory (for example /opt/gardience/config/users.yaml). It is readable by root only.

2. Add an ldap: section next to the existing users: section. Leave users: as it is.

   Copy

   ldap:
     server: dc1.example.com
     basedn: dc=example,dc=com
     binddn: CN=svc-gardience,OU=Service Accounts,DC=example,DC=com
     bindpw: the-bind-password
     activedirectory: true
     ca_file: ad-ca.pem

   Directory servers usually have a certificate from your company's own certificate authority. Export that CA certificate (PEM, the -----BEGIN CERTIFICATE----- form), save it in the config directory as ad-ca.pem, and name it in ca_file. Gardience checks the directory's certificate against it on every sign-in.

3. Apply it:

   Copy

   /opt/gardience/gardience render

4. Add each person:

   Copy

   /opt/gardience/gardience user add alice operator --ldap

The settings Gardience reads from the ldap: section:

Searches cover the whole subtree under basedn. Once LDAP is on, the sign-in page offers it as a sign-in type.

Related#

• Users and roles
• API keys and the REST API
• Security model
• Troubleshooting