OpenID Connect

Sign users in through an OpenID Connect provider: basic setup and PKCE, filters by domain, email or group, group sync, claims, and per-provider notes.

Slopscale supports authentication via external identity providers using OpenID Connect (OIDC). It features:

Auto configuration via OpenID Connect Discovery Protocol
Proof Key for Code Exchange (PKCE) code verification
Authorization based on a user’s domain, email address or group membership
Synchronization of standard OIDC claims
Sign-in to the admin console with the same provider and redirect URI

See limitations for known issues.

Configuration

OpenID requires configuration in Slopscale and your identity provider:

Slopscale: The oidc section of the Slopscale configuration contains all available configuration options along with a description and their default values.
Identity provider: the provider’s own documentation has the exact steps. Additionally, there might be some useful hints in the Identity provider specific configuration section below.

Basic configuration

A basic configuration connects Slopscale to an identity provider and typically requires:

OpenID Connect Issuer URL from the identity provider. Slopscale uses the OpenID Connect Discovery Protocol 1.0 to automatically obtain OpenID configuration parameters (example: https://sso.example.com).
Client ID from the identity provider (example: slopscale).
Client secret generated by the identity provider (example: generated-secret).
Redirect URI for your identity provider (example: https://slopscale.example.com/oidc/callback).

oidc:
  issuer: "https://sso.example.com"
  client_id: "slopscale"
  client_secret: "generated-secret"

Create a new confidential client (Client ID, Client secret)
Add Slopscale’s OIDC callback URL as valid redirect URL: https://slopscale.example.com/oidc/callback
Configure additional parameters to improve user experience such as: name, description, logo, …

Proof Key for Code Exchange (PKCE) adds an additional layer of security to the OAuth 2.0 authorization code flow by preventing authorization code interception attacks, see: https://datatracker.ietf.org/doc/html/rfc7636. PKCE is recommended and needs to be configured for Slopscale and the identity provider alike:

oidc:
  issuer: "https://sso.example.com"
  client_id: "slopscale"
  client_secret: "generated-secret"
  pkce:
    enabled: true

Enable PKCE for the slopscale client
Set the PKCE challenge method to “S256”

Authorize users with filters

Slopscale allows to filter for allowed users based on their domain, email address or group membership. These filters can be helpful to apply additional restrictions and control which users are allowed to join. Filters are disabled by default, users are allowed to join once the authentication with the identity provider succeeds. In case multiple filters are configured, a user needs to pass all of them.

Check the email domain of each authenticating user against the list of allowed domains and only authorize users whose email domain matches example.com.
A verified email address is required unless email verification is disabled.
Access allowed: alice@example.com
Access denied: bob@example.net

oidc:
  issuer: "https://sso.example.com"
  client_id: "slopscale"
  client_secret: "generated-secret"
  allowed_domains:
    - "example.com"

Check the email address of each authenticating user against the list of allowed email addresses and only authorize users whose email is part of the allowed_users list.
A verified email address is required unless email verification is disabled.
Access allowed: alice@example.com, bob@example.net
Access denied: mallory@example.net

oidc:
  issuer: "https://sso.example.com"
  client_id: "slopscale"
  client_secret: "generated-secret"
  allowed_users:
    - "alice@example.com"
    - "bob@example.net"

Users whose email address is in admin_users hold the admin role from their first sign-in, so the admin console can be administered without granting roles over the CLI first.
The list is checked on every sign-in and only promotes members; the owner and users who already hold a role are left alone, and removing an address does not demote anyone.
A verified email address is required unless email verification is disabled.

oidc:
  issuer: "https://sso.example.com"
  client_id: "slopscale"
  client_secret: "generated-secret"
  admin_users:
    - "alice@example.com"

Use the OIDC groups claim of each authenticating user to get their group membership and only authorize users which are members in at least one of the referenced groups.
Access allowed: users in the slopscale_users group
Access denied: users without groups, users with other groups

oidc:
  issuer: "https://sso.example.com"
  client_id: "slopscale"
  client_secret: "generated-secret"
  scope: ["openid", "profile", "email", "groups"]
  allowed_groups:
    - "slopscale_users"

With groups.sync on, every group in the user’s groups claim becomes a slopscale group of the same name with the user as a member, and the user leaves the synced groups the claim no longer lists. The claim is read at every sign-in, so a change at the identity provider takes effect the next time the person signs in, the way Tailscale’s user and group provisioning does.
groups.prefix limits the sync to the claims that start with it and strips it from the name, so hs-eng becomes eng and a provider’s other groups stay out.
A synced group carries source: oidc; its users cannot be edited by hand, while machines can still be added directly and the group can be renamed, described, used in rules and deleted. A group an operator made is never taken over by name; a claim that collides with one is logged and skipped.

oidc:
  issuer: "https://sso.example.com"
  client_id: "slopscale"
  client_secret: "generated-secret"
  scope: ["openid", "profile", "email", "groups"]
  groups:
    sync: true
    prefix: "hs-"

Control email verification

Slopscale uses the email claim from the identity provider to synchronize the email address to its user profile. By default, a user’s email address is only synchronized when the identity provider reports the email address as verified via the email_verified: true claim.

Unverified emails may be allowed in case an identity provider does not send the email_verified claim or email verification is not required. In that case, a user’s email address is always synchronized to the user profile.

oidc:
  issuer: "https://sso.example.com"
  client_id: "slopscale"
  client_secret: "generated-secret"
  email_verified_required: false

Customize node expiration

The node expiration is the amount of time a node is authenticated with OpenID Connect until it expires and needs to reauthenticate. The default node expiration can be configured via the top-level node.expiry setting.

node:
  expiry: 30d   # Use 0 to disable node expiration

The Access Token is typically a short-lived token that expires within a few minutes. You will have to configure token expiration in your identity provider to avoid frequent re-authentication.

oidc:
  issuer: "https://sso.example.com"
  client_id: "slopscale"
  client_secret: "generated-secret"
  use_expiry_from_token: true

Reference a user in the policy

You may refer to users in the Slopscale policy via:

Email address
Username
Provider identifier (this value is currently only available from the API, database or directly from your identity provider)

Howto use the provider identifier in the policy

The provider identifier uniquely identifies an OIDC user and a well-behaving identity provider guarantees that this value never changes for a particular user. It is usually an opaque and long string and its value is currently only available from the API, database or directly from your identity provider).

Use the API with the /api/v1/user endpoint to fetch the provider identifier (providerId). The value (be sure to append an @ in case the provider identifier doesn’t already contain an @ somewhere) can be used directly to reference a user in the policy. To improve readability of the policy, one may use the groups section as an alias:

{
  "groups": {
    "group:alice": [
      "https://sso.example.com/oauth2/openid/59ac9125-c31b-46c5-814e-06242908cf57@"
    ]
  },
  "grants": [
    {
      "src": ["group:alice"],
      "dst": ["*"],
      "ip": ["*"]
    }
  ]
}

Supported OIDC claims

Slopscale uses the standard OIDC claims to populate and update its local user profile on each login. OIDC claims are read from the ID Token and from the UserInfo endpoint.

Slopscale profile	OIDC claim	Notes / examples
email address	`email`	Only verified emails are synchronized, unless `email_verified_required: false` is configured
display name	`name`	eg: `Sam Smith`
username	`preferred_username`	Depends on identity provider, eg: `ssmith`, `ssmith@idp.example.com`, `\\example.com\ssmith`
profile picture	`picture`	URL to a profile picture or avatar
provider identifier	`iss`, `sub`	A stable and unique identifier for a user, typically a combination of `iss` and `sub` OIDC claims
	`groups`	Only used to filter for allowed groups

Limitations

Support for OpenID Connect aims to be generic and vendor independent. It offers only limited support for quirks of specific identity providers.
OIDC groups are not visible to the policy file: groups in the file are defined in the file. With groups.sync on, a provider’s groups become slopscale groups that access rules can name.
The username provided by the identity provider needs to adhere to this pattern:
- The username must be at least two characters long.
- It must only contain letters, digits, hyphens, dots, underscores, and up to a single @.
- The username must start with a letter.

See the GitHub label “OIDC” for OIDC related issues.

Identity provider specific configuration

Any identity provider with OpenID Connect support should “just work” with Slopscale. The following identity providers are known to work:

Authelia
Authentik
Kanidm
Keycloak

Authelia

Authelia is fully supported by Slopscale.

Authentik

Authentik is fully supported by Slopscale.
Slopscale does not support JSON Web Encryption. Leave the field Encryption Key in the providers section unset.
See Authentik’s Integrate with Slopscale

Google OAuth

In order to integrate Slopscale with Google, you’ll need to have a Google Cloud Console account.

Google OAuth has a verification process if you need to have users authenticate who are outside of your domain. If you only need to authenticate users from your domain name (ie @example.com), you don’t need to go through the verification process.

However if you don’t have a domain, or need to add users outside of your domain, you can manually add emails via Google Console.

Steps

Go to Google Console and login or create an account if you don’t have one.
Create a project (if you don’t already have one).
On the left hand menu, go to APIs and services -> Credentials
Click Create Credentials -> OAuth client ID
Under Application Type, choose Web Application
For Name, enter whatever you like
Under Authorised redirect URIs, add Slopscale’s OIDC callback URL: https://slopscale.example.com/oidc/callback
Click Save at the bottom of the form
Take note of the Client ID and Client secret, you can also download it for reference if you need it.
Configure Slopscale following the “Basic configuration” steps. The issuer URL for Google OAuth is: https://accounts.google.com. The client ID and secret may also come from the environment as SLOPSCALE_OIDC_CLIENT_ID and SLOPSCALE_OIDC_CLIENT_SECRET.
The same client signs operators in to the admin console; no further redirect URI is needed. List the addresses that should administer it in admin_users (or SLOPSCALE_OIDC_ADMIN_USERS) so they sign in as admins right away.

Kanidm

Kanidm is fully supported by Slopscale.
Groups for the allowed groups filter need to be specified with their full SPN, for example: slopscale_users@sso.example.com.
Kanidm sends the full SPN (alice@sso.example.com) as preferred_username by default. Slopscale stores this value as username which might be confusing as the username and email fields now contain values that look like an email address. Kanidm can be configured to send the short username as preferred_username attribute instead:
```
kanidm system oauth2 prefer-short-username <client name>
```
Once configured, the short username in Slopscale will be alice and can be referred to as alice@ in the policy.

Keycloak

Keycloak is fully supported by Slopscale.

Additional configuration to use the allowed groups filter

Keycloak has no built-in client scope for the OIDC groups claim. This extra configuration step is only needed if you need to authorize access based on group membership.

Create a new client scope groups for OpenID Connect:
- Configure a Group Membership mapper with name groups and the token claim name groups.
- Add the mapper to at least the UserInfo endpoint.
Configure the new client scope for your Slopscale client:
- Edit the Slopscale client.
- Search for the client scope group.
- Add it with assigned type Default.
Configure the allowed groups in Slopscale. How groups need to be specified depends on Keycloak’s Full group path option:
- Full group path is enabled: groups contain their full path, e.g. /top/group1
- Full group path is disabled: only the name of the group is used, e.g. group1

Microsoft Entra ID

In order to integrate Slopscale with Microsoft Entra ID, you’ll need to provision an App Registration with the correct scopes and redirect URI.

Configure Slopscale following the “Basic configuration” steps. The issuer URL for Microsoft Entra ID is: https://login.microsoftonline.com/<tenant-UUID>/v2.0. The following extra_params might be useful:

domain_hint: example.com to use your own domain
prompt: select_account to force an account picker during login

When using Microsoft Entra ID together with the allowed groups filter, configure the Slopscale OIDC scope without the groups claim, for example:

oidc:
  scope: ["openid", "profile", "email"]

Groups for the allowed groups filter need to be specified with their group ID(UUID) instead of the group name.

Switching OIDC providers

Slopscale only supports a single OIDC provider in its configuration, but it does store the provider identifier of each user. When switching providers, all user details (name, email, groups) might be identical with the new provider, but the identifier will differ. Slopscale will be unable to create a new user as the name and email will already be in use for the existing users.

Set oidc.match_by_email: true while migrating. A login whose identifier is unknown is then matched to the existing OIDC user with the same email, that user takes over the new identifier, and the machines stay with it. The switch is recorded in the audit log as user.provider.switch with the old and the new identifier. Only a verified email (or any email when email_verified_required is off) is matched, and a login is refused when several users share the email. Turn the setting off again once every user has logged in through the new provider.

Without the setting you need to manually update the provider_identifier column in the users table for each user with the appropriate value for the new provider. The identifier is built from the iss and sub claims of the OIDC ID token, for example https://id.example.com/12340987.