Active Directory & SSO Login

Xylok’s SSO Login provides seamless single sign on (SSO) for Xylok on intranet environments that use OpenID Connect (OIDC) compatible identity providers, such as Windows Server (ADFS), Microsoft Entra ID (formerly Azure AD), or Keycloak.

Starting with the April 2026 release, Xylok has transitioned from the legacy Python-based Active Directory implementation to a modern Go-based OIDC implementation. Any existing configuration files for Xylok will change from a .conf extension to a .toml extension.

Configuration via UI

The preferred way to configure SSO is through the Xylok web interface.

Log in to Xylok as an administrator.
Navigate to Settings > SSO / Identity Provider.
Fill in the required OIDC settings:
- Enable OIDC Authentication: Toggle this to enable the SSO flow.
- Issuer URL: The base URL of your OIDC provider (e.g., login.microsoftonline.com/<tenant_id>/v2.0 or keycloak.example.com/realms/myrealm). Do not include https:// as it is toggled separately.
- Client ID: The application ID from your identity provider.
- Client Secret: The secret generated by your identity provider.
- Username Claim: The claim containing the user’s login name (defaults to preferred_username, but email or upn are common).
- Groups Claim: The claim containing user groups (e.g., groups or roles).
- Superuser Groups: Comma-separated list of groups that grant full administrative access.
- Staff Groups: Comma-separated list of groups that grant staff access.
- Enable TLS: Must be enabled for Microsoft implementations.
- CA Certificate: If using a self-signed certificate or internal CA, upload the PEM-encoded .crt or .pem file here.
Click Test OIDC Connection to verify your settings.
Click Save Configuration.
Click Restart Server to apply the changes.

Manual Configuration (xylok.toml)

Configuration is stored in /etc/xylok/xylok.toml. Below are the corresponding keys in the [oidc] section:

[oidc]
use = true
issuer = "login.microsoftonline.com/<tenant-id>/v2.0"
client_id = "your-client-id"
client_secret = "your-client-secret"
username_claim = "preferred_username"
groups_claim = "groups"
group_mapping_is_super = ["Admins", "XylokSuperusers"]
group_mapping_is_staff = ["Staff", "Analysts"]
enable_tls = true
skip_cert_verification = false

Migration from Legacy AD Settings

If you are upgrading from a version older than April 2026, Xylok will automatically attempt to migrate your legacy /etc/xylok.conf settings to the new xylok.toml format.

If you use a custom configuration file location via the --config flag, you must update your startup scripts after the migration occurs. Once you verify the .toml file exists in your config location, you will need to change your config flag. The flag now requires the .toml extension. For example, --config /etc/custom/xylok.conf must be updated to --config /etc/custom/xylok.toml.

Legacy Variable (xylok.conf)	New OIDC Setting
`AD_CLIENT_ID`	`client_id`
`AD_CLIENT_SECRET`	`client_secret`
`AD_GROUPS_CLAIM`	`groups_claim`
`AD_GROUP_TO_FLAG_MAPPING_IS_SUPERUSER`	`group_mapping_is_super`
`AD_GROUP_TO_FLAG_MAPPING_IS_STAFF`	`group_mapping_is_staff`
`AD_CHECK_CA`	`enable_tls`
`AD_TENANT_ID`	`issuer` (constructed as Microsoft Entra ID URL)

Automatic migration from the legacy .conf format to the new .toml format is supported until December 2026. It is recommended to verify your settings in the new SSO settings page after upgrading.

Troubleshooting

If you are having trouble connecting, you can check the server logs:

In a terminal, run sudo journalctl -u xylok -f.
Attempt a login and watch for OIDC-related error messages.
Common issues include incorrect Issuer URLs, mismatched Client Secrets, or missing CA certificates for internal providers.