Authentication¶

IsardVDI supports different authentication providers. There can be multiple providers in the same installation

OAuth2¶

You should set up your application auth tokens to enable this kind of logins.

BACKEND_HOST: Set it to your domain
BACKEND_AUTH_AUTOREGISTRATION: Activate auto registering

Google¶

BACKEND_AUTH_GOOGLE_ID: Set your google ID.
BACKEND_AUTH_GOOGLE_SECRET: Set your google secret.

Github¶

BACKEND_AUTH_GITHUB_ID: Set your github ID.
BACKEND_AUTH_GITHUB_SECRET: Set your github secret.

LDAP¶

The LDAP authentication uses the same form that the local login.

In order to configure the LDAP authentication, we have to set the following parameters: isardvdi.cfg.example

We'll go through each configuration parameter:

Parameter	Default value	Description
`AUTHENTICATION_AUTHENTICATION_LDAP_ENABLED`	`false`	If set to `true`, this will enable the LDAP authentication
`AUTHENTICATION_AUTHENTICATION_LDAP_PROTOCOL`	`ldap`	The LDAP protocol. Other possible values are `ldaps`
`AUTHENTICATION_AUTHENTICATION_LDAP_HOST`		The LDAP server
`AUTHENTICATION_AUTHENTICATION_LDAP_PORT`	389	The LDAP port where the server is listening
`AUTHENTICATION_AUTHENTICATION_LDAP_BIND_DN`		The DN that Isard is going to use to query the LDAP
`AUTHENTICATION_AUTHENTICATION_LDAP_PASSWORD`		The password that Isard is going to use to query the LDAP
`AUTHENTICATION_AUTHENTICATION_LDAP_BASE_SEARCH`		The DN that all the users share (e.g. `ou=people,dc=example,dc=com`)
`AUTHENTICATION_AUTHENTICATION_LDAP_FILTER`	`(&(objectClass=person)(uid=%s))`	The filter that Isard is going to use to find each user. The `%s` represents the username that gets sent through the form. More information here
`AUTHENTICATION_AUTHENTICATION_LDAP_FIELD_UID`		The field from the LDAP entry that contains the user UID
`AUTHENTICATION_AUTHENTICATION_LDAP_REGEX_UID`	`.*`	The regex filter that is going to be applied in the field. By default it gets the whole field
`AUTHENTICATION_AUTHENTICATION_LDAP_FIELD_USERNAME`		The field from the LDAP entry that contains the user username
`AUTHENTICATION_AUTHENTICATION_LDAP_REGEX_USERNAME`	`.*`	The regex filter that is going to be applied in the field. By default it gets the whole field
`AUTHENTICATION_AUTHENTICATION_LDAP_FIELD_NAME`		The field from the LDAP entry that contains the user name
`AUTHENTICATION_AUTHENTICATION_LDAP_REGEX_NAME`	`.*`	The regex filter that is going to be applied in the field. By default it gets the whole field
`AUTHENTICATION_AUTHENTICATION_LDAP_FIELD_EMAIL`		The field from the LDAP entry that contains the user email
`AUTHENTICATION_AUTHENTICATION_LDAP_REGEX_EMAIL`	`.*`	The regex filter that is going to be applied in the field. By default it gets the whole field
`AUTHENTICATION_AUTHENTICATION_LDAP_FIELD_PHOTO`		The field from the LDAP entry that contains the user photo
`AUTHENTICATION_AUTHENTICATION_LDAP_REGEX_PHOTO`	`.*`	The regex filter that is going to be applied in the field. By default it gets the whole field

In regards of the field / regex configuration parameters: these are the fields that the LDAP search responds. For example, in some installations, the field for the email is called 'mail'. Then, a regex is applied to this field, in case we needed to filter inside a LDAP field. By default it collects the whole field. The regex match tries to extract the first group, but if there's no group it will extract the whole match

With this, the LDAP authentication is going to work. However, there's a ✨ extra feature ✨! With the LDAP authentication we can autoregister the users in groups, so there's no need to use the registration codes.

Autoregistration¶

If a group has a registration code, and the LDAP auto registration is enabled, the LDAP autoregistration is always going to take preference. To configure it, we have to set the following configuration parameters: isardvdi.cfg.example

We'll go through each parameter:

Parameter	Default value	Description
`AUTHENTICATION_AUTHENTICATION_LDAP_AUTO_REGISTER`	`false`	If set to `true`, this will enable the LDAP auto registration
`AUTHENTICATION_AUTHENTICATION_LDAP_GUESS_CATEGORY`	`false`	If set to `true`, Isard is going to attempt to guess the category based in the search results, instead on relying in the category ID provided by the form. This enables multiple categories to use the same form and login URL
`AUTHENTICATION_AUTHENTICATION_LDAP_FIELD_CATEGORY`		The field from the LDAP entry that contains the user category
`AUTHENTICATION_AUTHENTICATION_LDAP_REGEX_CATEGORY`	`.*`	The regex filter that is going to be applied in the field. By default it gets the whole field
`AUTHENTICATION_AUTHENTICATION_LDAP_FIELD_GROUP`		The field from the LDAP entry that contains the user group
`AUTHENTICATION_AUTHENTICATION_LDAP_REGEX_GROUP`	`.*`	The regex filter that is going to be applied in the field. By default it gets the whole field
`AUTHENTICATION_AUTHENTICATION_LDAP_GROUPS_SEARCH`		The DN that all the groups share (e.g. `dc=example,dc=com`)
`AUTHENTICATION_AUTHENTICATION_LDAP_GROUPS_FILTER`	`(&(objectClass=posixGroup)(memberUid=%s))`	The filter that Isard is going to use to find each user. The `%s` represents the username that gets sent through the form. More information here
`AUTHENTICATION_AUTHENTICATION_LDAP_ROLE_ADMIN_GROUPS`		A comma separated list of the groups that are going to be part of the `admin` role
`AUTHENTICATION_AUTHENTICATION_LDAP_ROLE_MANAGER_GROUPS`		A comma separated list of the groups that are going to be part of the `manager` role
`AUTHENTICATION_AUTHENTICATION_LDAP_ROLE_ADVANCED_GROUPS`		A comma separated list of the groups that are going to be part of the `advanced` role
`AUTHENTICATION_AUTHENTICATION_LDAP_ROLE_USER_GROUPS`		A comma separated list of the groups that are going to be part of the `user` role
`AUTHENTICATION_AUTHENTICATION_LDAP_ROLE_DEFAULT`	`user`	The default role that the user is going to be assigned if it doesn't match with a group - role mapping. Possible values are `admin`, `manager`, `advanced` and `user`

Example LDAP configurations¶

LDAP with autoregistration

## LDAP
AUTHENTICATION_AUTHENTICATION_LDAP_ENABLED=true
AUTHENTICATION_AUTHENTICATION_LDAP_PROTOCOL=ldap
AUTHENTICATION_AUTHENTICATION_LDAP_HOST=ldap.example.com
#AUTHENTICATION_AUTHENTICATION_LDAP_PORT=389

### Credentials used for querying the LDAP
AUTHENTICATION_AUTHENTICATION_LDAP_BIND_DN="uid=isard,ou=users,dc=example,dc=com"
AUTHENTICATION_AUTHENTICATION_LDAP_PASSWORD=password

### Base Search is the DN that all the users share, e.g. ou=people,dc=example,dc=com
AUTHENTICATION_AUTHENTICATION_LDAP_BASE_SEARCH=dc=example,dc=com
### Filter is the actual filter used to search users. The '%s' represents the user that is sent through the form
### More information: https://confluence.atlassian.com/kb/how-to-write-ldap-search-filters-792496933.html
AUTHENTICATION_AUTHENTICATION_LDAP_FILTER="(&(objectClass=person)(uid=%s))"

### These are the fields that the LDAP search responds. For example, in some installations, the field for the email is called 'mail'
### Then, a regex is applied to this field, in case we needed to filter inside a LDAP field. By default it collects the whole field
AUTHENTICATION_AUTHENTICATION_LDAP_FIELD_UID=uid
#AUTHENTICATION_AUTHENTICATION_LDAP_REGEX_UID=.*
AUTHENTICATION_AUTHENTICATION_LDAP_FIELD_USERNAME=uid
#AUTHENTICATION_AUTHENTICATION_LDAP_REGEX_USERNAME=.*
AUTHENTICATION_AUTHENTICATION_LDAP_FIELD_NAME=sn
#AUTHENTICATION_AUTHENTICATION_LDAP_REGEX_NAME=.*
AUTHENTICATION_AUTHENTICATION_LDAP_FIELD_EMAIL=mail
#AUTHENTICATION_AUTHENTICATION_LDAP_REGEX_EMAIL=.*
#AUTHENTICATION_AUTHENTICATION_LDAP_FIELD_PHOTO=
#AUTHENTICATION_AUTHENTICATION_LDAP_REGEX_PHOTO=.*

### Auto Register the existing ldap users into IsardVDI
AUTHENTICATION_AUTHENTICATION_LDAP_AUTO_REGISTER=true
AUTHENTICATION_AUTHENTICATION_LDAP_GUESS_CATEGORY=true
### These are the fields that the LDAP search responds. For example, in some installations, the field for the group is called 'group'
### Then, a regex is applied to this field, in case we needed to filter inside a LDAP field. By default it collects the whole field
AUTHENTICATION_AUTHENTICATION_LDAP_FIELD_CATEGORY=homeDirectory
AUTHENTICATION_AUTHENTICATION_LDAP_REGEX_CATEGORY="/home/users.images/([^/]+)/[^/]+/[^/]+"
AUTHENTICATION_AUTHENTICATION_LDAP_FIELD_GROUP=homeDirectory
AUTHENTICATION_AUTHENTICATION_LDAP_REGEX_GROUP="/home/users.images/[^/]+/([^/]+)/[^/]+"
### The base search for listing all the groups of a user
AUTHENTICATION_AUTHENTICATION_LDAP_GROUPS_SEARCH=dc=example,dc=com
### Filter is the actual filter used to search all the groups of a user. The '%s' represents the user that is sent through the form
### More information: https://confluence.atlassian.com/kb/how-to-write-ldap-search-filters-792496933.html
AUTHENTICATION_AUTHENTICATION_LDAP_GROUPS_FILTER="(&(objectClass=posixGroup)(memberUid=%s))"
### The field that contains the group in the AUTHENTICATION_AUTHENTICATION_LDAP_GROUPS_FILTER search
AUTHENTICATION_AUTHENTICATION_LDAP_GROUPS_SEARCH_FIELD=cn
#AUTHENTICATION_AUTHENTICATION_LDAP_GROUPS_SEARCH_REGEX=.*
### All the users that are in at least one of the groups specified here, will be created in the admin role (comma separated)
AUTHENTICATION_AUTHENTICATION_LDAP_ROLE_ADMIN_GROUPS=isard-admins
AUTHENTICATION_AUTHENTICATION_LDAP_ROLE_MANAGER_GROUPS=isard-managers
AUTHENTICATION_AUTHENTICATION_LDAP_ROLE_ADVANCED_GROUPS=profes,ofi
#AUTHENTICATION_AUTHENTICATION_LDAP_ROLE_USER_GROUPS=ldapusers
# This is the default role that users will have if they don't match in any of the previous groups.
# Values can be 'admin', 'manager', 'advanced', 'user'
AUTHENTICATION_AUTHENTICATION_LDAP_ROLE_DEFAULT=user

SAML¶

IsardVDI supports SAML 2.0 authentication through integration with any SAML Identity Provider (IdP). SAML authentication allows users to log in using their organization's existing identity provider instead of managing separate credentials in IsardVDI.

Basic Configuration¶

In order to configure SAML authentication, we have to set the following parameters: isardvdi.cfg.example

We'll go through each configuration parameter:

Parameter	Default value	Description
`AUTHENTICATION_AUTHENTICATION_SAML_ENABLED`	`false`	If set to `true`, this will enable the SAML authentication
`AUTHENTICATION_AUTHENTICATION_SAML_METADATA_URL`		The URL to fetch the IdP metadata from (e.g. `https://idp.example.com/metadata`)
`AUTHENTICATION_AUTHENTICATION_SAML_METADATA_FILE`	`/keys/idp-metadata.xml`	Optional: Local IdP metadata file. If this file exists, it will be used instead of fetching from the URL. This allows the service to start without network access to the IdP
`AUTHENTICATION_AUTHENTICATION_SAML_ENTITY_ID`		Optional: Custom Entity ID for the Service Provider. If not set, defaults to the metadata URL (`https://your-domain.com/authentication/saml/metadata`). Set this if your IdP requires a specific Entity ID (e.g., `my-app`)
`AUTHENTICATION_AUTHENTICATION_SAML_SIGNATURE_METHOD`		Optional: Signature method for signing SAML AuthnRequests. If not set, requests will NOT be signed. Set this if your IdP requires signed requests (`AuthnRequestsSigned="true"`). Valid values: `http://www.w3.org/2001/04/xmldsig-more#rsa-sha256` (recommended), `http://www.w3.org/2000/09/xmldsig#rsa-sha1`, or `http://www.w3.org/2001/04/xmldsig-more#rsa-sha512`
`AUTHENTICATION_AUTHENTICATION_SAML_KEY_FILE`	`/keys/isardvdi.key`	The path to the Service Provider private key file
`AUTHENTICATION_AUTHENTICATION_SAML_CERT_FILE`	`/keys/isardvdi.cert`	The path to the Service Provider certificate file
`AUTHENTICATION_AUTHENTICATION_SAML_MAX_ISSUE_DELAY`	`90s`	The maximum time between the initial login request and the response
`AUTHENTICATION_AUTHENTICATION_SAML_FIELD_UID`		The SAML attribute name that contains the user UID
`AUTHENTICATION_AUTHENTICATION_SAML_REGEX_UID`	`.*`	The regex filter that is going to be applied to the UID field. By default it gets the whole field
`AUTHENTICATION_AUTHENTICATION_SAML_FIELD_USERNAME`		The SAML attribute name that contains the username
`AUTHENTICATION_AUTHENTICATION_SAML_REGEX_USERNAME`	`.*`	The regex filter that is going to be applied to the username field. By default it gets the whole field
`AUTHENTICATION_AUTHENTICATION_SAML_FIELD_NAME`		The SAML attribute name that contains the user's display name
`AUTHENTICATION_AUTHENTICATION_SAML_REGEX_NAME`	`.*`	The regex filter that is going to be applied to the name field. By default it gets the whole field
`AUTHENTICATION_AUTHENTICATION_SAML_FIELD_EMAIL`		The SAML attribute name that contains the user's email
`AUTHENTICATION_AUTHENTICATION_SAML_REGEX_EMAIL`	`.*`	The regex filter that is going to be applied to the email field. By default it gets the whole field
`AUTHENTICATION_AUTHENTICATION_SAML_FIELD_PHOTO`		The SAML attribute name that contains the user's photo URL
`AUTHENTICATION_AUTHENTICATION_SAML_REGEX_PHOTO`	`.*`	The regex filter that is going to be applied to the photo field. By default it gets the whole field
`AUTHENTICATION_AUTHENTICATION_SAML_SAVE_EMAIL`	`true`	If set to `true`, the email will be saved to the database

In regards to the field / regex configuration parameters: these are the fields that the SAML assertion contains. For example, in some installations, the field for the email is called 'mail'. Then, a regex is applied to this field, in case we need to extract specific parts from a SAML attribute value. By default it collects the whole field. The regex match tries to extract the first capture group, but if there's no group it will extract the whole match.

Certificate Setup¶

The Service Provider (IsardVDI) requires a certificate and private key for signing SAML requests. You can:

Generate a self-signed certificate:

openssl req -new -x509 -days 3652 -nodes -out /opt/isard/authentication/keys/isardvdi.cert -keyout /opt/isard/authentication/keys/isardvdi.key

Use a certificate from your organization's CA
Let IsardVDI generate a self-signed certificate automatically (if files don't exist)

Local Metadata File¶

IsardVDI supports using a local IdP metadata file as a fallback. This is useful for: - Air-gapped deployments - Development/testing without network access - Faster startup (no network latency) - Resilience when IdP is temporarily unavailable

To use a local metadata file:

# Download IdP metadata to local file
curl -o /opt/isard/authentication/keys/idp-metadata.xml https://idp.example.com/metadata

Behavior: IsardVDI will first attempt to load metadata from the local file. If the file doesn't exist or fails to parse, it will automatically fall back to fetching from the METADATA_URL.

Auto-registration¶

If a group has a registration code, and the SAML auto-registration is enabled, the SAML auto-registration is always going to take preference. To configure it, we have to set the following configuration parameters:

Parameter	Default value	Description
`AUTHENTICATION_AUTHENTICATION_SAML_AUTO_REGISTER`	`false`	If set to `true`, this will enable the SAML auto-registration
`AUTHENTICATION_AUTHENTICATION_SAML_AUTO_REGISTER_ROLES`	`[]`	Only users with these role values will be auto-registered (comma separated). Empty means all users can register
`AUTHENTICATION_AUTHENTICATION_SAML_GUESS_CATEGORY`	`false`	If set to `true`, IsardVDI is going to attempt to guess the category based on SAML attributes, instead of relying on the category ID provided by the form. This enables multiple categories to use the same form and login URL
`AUTHENTICATION_AUTHENTICATION_SAML_FIELD_CATEGORY`		The SAML attribute name that contains the user's category
`AUTHENTICATION_AUTHENTICATION_SAML_REGEX_CATEGORY`	`.*`	The regex filter that is going to be applied to the category field. By default it gets the whole field
`AUTHENTICATION_AUTHENTICATION_SAML_FIELD_GROUP`		The SAML attribute name that contains the user's group
`AUTHENTICATION_AUTHENTICATION_SAML_REGEX_GROUP`	`.*`	The regex filter that is going to be applied to the group field. By default it gets the whole field
`AUTHENTICATION_AUTHENTICATION_SAML_GROUP_DEFAULT`	`default`	The default group that the user will be assigned if no group is detected
`AUTHENTICATION_AUTHENTICATION_SAML_GUESS_ROLE`	`false`	If set to `true`, IsardVDI will attempt to determine the user's role from SAML attributes
`AUTHENTICATION_AUTHENTICATION_SAML_FIELD_ROLE`		The SAML attribute name that contains role information
`AUTHENTICATION_AUTHENTICATION_SAML_REGEX_ROLE`	`.*`	The regex filter to extract the role value from the attribute. Important: Must be wrapped in single quotes if using special characters
`AUTHENTICATION_AUTHENTICATION_SAML_ROLE_ADMIN_IDS`	`[]`	A comma-separated list of role values that will be mapped to the `admin` role
`AUTHENTICATION_AUTHENTICATION_SAML_ROLE_MANAGER_IDS`	`[]`	A comma-separated list of role values that will be mapped to the `manager` role
`AUTHENTICATION_AUTHENTICATION_SAML_ROLE_ADVANCED_IDS`	`[]`	A comma-separated list of role values that will be mapped to the `advanced` role
`AUTHENTICATION_AUTHENTICATION_SAML_ROLE_USER_IDS`	`[]`	A comma-separated list of role values that will be mapped to the `user` role
`AUTHENTICATION_AUTHENTICATION_SAML_ROLE_DEFAULT`	`user`	The default role that the user is going to be assigned if it doesn't match any role mapping. Possible values are `admin`, `manager`, `advanced` and `user`

Important: Category auto-registration matches the extracted category value against the category's uid field in the database (not the id or name fields). When creating a category in the webapp for SAML users, you must set the UID field to the value that will be extracted by your REGEX_CATEGORY. For example, if your regex extracts "department-a", create a category with UID set to "department-a".

Group Auto-Creation: Unlike categories, groups are automatically created when AUTO_REGISTER=true is enabled. When a SAML user logs in, IsardVDI extracts group values using REGEX_GROUP and automatically creates any missing groups with auto-generated names (e.g., "saml_provider-saml_student-group"). If no groups are extracted from SAML attributes, the user is assigned to the default group specified in GROUP_DEFAULT (default: "default"). The admin does not need to manually create groups in the webapp - they are created automatically on first login.

Single Logout (SLO)¶

SAML Single Logout is supported. The SLO endpoint is automatically configured at:

https://your-domain.com/authentication/saml/slo

You can configure where users are redirected after logout:

Parameter	Default value	Description
`AUTHENTICATION_AUTHENTICATION_SAML_LOGOUT_REDIRECT_URL`		URL to redirect users after logout. If empty, redirects to `/`

SAML Endpoints¶

When SAML is enabled, IsardVDI exposes the following endpoints:

Endpoint	Path	Purpose
ACS	`https://your-domain.com/authentication/saml/acs`	Assertion Consumer Service - receives SAML assertions from the IdP
Metadata	`https://your-domain.com/authentication/saml/metadata`	Service Provider metadata for IdP configuration
SLO	`https://your-domain.com/authentication/saml/slo`	Single Logout endpoint

Provide the ACS and Metadata URLs to your IdP administrator to complete the SAML setup.

Example SAML Configuration¶

Basic SAML authentication with user attribute mapping:

## SAML
AUTHENTICATION_AUTHENTICATION_SAML_ENABLED=true
AUTHENTICATION_AUTHENTICATION_SAML_METADATA_URL=https://idp.example.com/auth/realms/example/protocol/saml/descriptor

# Optional: Use local metadata file for offline startup
# curl -o /opt/isard/authentication/keys/idp-metadata.xml https://idp.example.com/auth/realms/example/protocol/saml/descriptor
#AUTHENTICATION_AUTHENTICATION_SAML_METADATA_FILE=/keys/idp-metadata.xml

# Optional: Custom Entity ID (if IdP requires a specific value)
#AUTHENTICATION_AUTHENTICATION_SAML_ENTITY_ID=my-app

# Optional: Enable request signing (if IdP requires AuthnRequestsSigned="true")
#AUTHENTICATION_AUTHENTICATION_SAML_SIGNATURE_METHOD=http://www.w3.org/2001/04/xmldsig-more#rsa-sha256

# Certificate files (will be auto-generated if they don't exist)
AUTHENTICATION_AUTHENTICATION_SAML_KEY_FILE=/keys/isardvdi.key
AUTHENTICATION_AUTHENTICATION_SAML_CERT_FILE=/keys/isardvdi.cert

# User Attribute Mapping
AUTHENTICATION_AUTHENTICATION_SAML_FIELD_UID=uid
AUTHENTICATION_AUTHENTICATION_SAML_FIELD_USERNAME=uid
AUTHENTICATION_AUTHENTICATION_SAML_FIELD_NAME=displayName
AUTHENTICATION_AUTHENTICATION_SAML_FIELD_EMAIL=mail
AUTHENTICATION_AUTHENTICATION_SAML_SAVE_EMAIL=true

SAML with auto-registration and role mapping:

## SAML
AUTHENTICATION_AUTHENTICATION_SAML_ENABLED=true
AUTHENTICATION_AUTHENTICATION_SAML_METADATA_URL=https://idp.example.com/metadata

# Optional: Custom Entity ID and request signing
#AUTHENTICATION_AUTHENTICATION_SAML_ENTITY_ID=my-app
#AUTHENTICATION_AUTHENTICATION_SAML_SIGNATURE_METHOD=http://www.w3.org/2001/04/xmldsig-more#rsa-sha256

# User Attributes
AUTHENTICATION_AUTHENTICATION_SAML_FIELD_UID=uid
AUTHENTICATION_AUTHENTICATION_SAML_FIELD_USERNAME=uid
AUTHENTICATION_AUTHENTICATION_SAML_FIELD_NAME=displayName
AUTHENTICATION_AUTHENTICATION_SAML_FIELD_EMAIL=mail

# Auto-registration
AUTHENTICATION_AUTHENTICATION_SAML_AUTO_REGISTER=true
AUTHENTICATION_AUTHENTICATION_SAML_AUTO_REGISTER_ROLES=teacher,student
AUTHENTICATION_AUTHENTICATION_SAML_GROUP_DEFAULT=default-group

# Role mapping from SAML attributes
# Example: Extract role from attribute like "urn:example:role:teacher:department:it"
AUTHENTICATION_AUTHENTICATION_SAML_GUESS_ROLE=true
AUTHENTICATION_AUTHENTICATION_SAML_FIELD_ROLE=eduPersonAffiliation
AUTHENTICATION_AUTHENTICATION_SAML_REGEX_ROLE='.*:role:([^:]+):.*'
AUTHENTICATION_AUTHENTICATION_SAML_ROLE_ADVANCED_IDS=teacher,staff
AUTHENTICATION_AUTHENTICATION_SAML_ROLE_USER_IDS=student
AUTHENTICATION_AUTHENTICATION_SAML_ROLE_DEFAULT=user

Troubleshooting¶

Service won't start - "fetch metadata" error: - Check that METADATA_URL is accessible from the server - Verify network connectivity to the IdP - Use METADATA_FILE option to load metadata from a local file - Check logs: docker logs isard-authentication

"No attributes received": - Confirm the IdP is configured to send attributes - Verify FIELD_* parameter names match the actual SAML attribute names - Enable debug logging to see the raw SAML assertion

Certificate errors: - Ensure certificate and private key files exist - Verify file permissions (key should be 600, cert should be 644) - Check certificate hasn't expired - Verify key and certificate match:

openssl rsa -modulus -noout -in /opt/isard/authentication/keys/isardvdi.key | openssl md5
openssl x509 -modulus -noout -in /opt/isard/authentication/keys/isardvdi.cert | openssl md5

Users not auto-registered: - Verify AUTO_REGISTER=true is set - Check that user's role matches AUTO_REGISTER_ROLES (if configured) - Review authentication service logs for registration errors

Regex not extracting correctly: - Test regex patterns at https://regex101.com/ - Remember to wrap regex in single quotes if it contains special characters - The regex tries to extract the first capture group (), or the whole match if no group exists

"Invalid Request" or "Invalid Entity ID" errors from IdP: - Verify the IdP is configured with the correct Entity ID - Check your SP metadata matches what the IdP expects:

curl -sk https://your-domain.com/authentication/saml/metadata | grep entityID

- If IdP requires a specific Entity ID, set AUTHENTICATION_AUTHENTICATION_SAML_ENTITY_ID - Ensure IdP has the correct ACS and SLO URLs configured

"Invalid Redirect URI" errors: - Verify the IdP has the correct Valid Redirect URIs configured: - https://your-domain.com/authentication/saml/acs - https://your-domain.com/authentication/saml/slo - https://your-domain.com/authentication/callback - Check that the IdP's client configuration has these URLs in the allowed list

Signed requests required but not working: - Set AUTHENTICATION_AUTHENTICATION_SAML_SIGNATURE_METHOD=http://www.w3.org/2001/04/xmldsig-more#rsa-sha256 - Ensure certificate and key files are properly configured and match - Verify the IdP has the correct certificate in its configuration - Check logs for "SAML request signing enabled" message