Troubleshooting Guide for Setting up Access Server with SAML Authentication
Troubleshoot common SAML authentication issues on Access Server.
Access Server 2.11.0 and newer supports SAML authentication, allowing users to authenticate through an external Identity Provider (IdP). Here’s a guide to help troubleshoot common SAML authentication issues on Access Server. If needed, you can open a support ticket for additional assistance.
Troubleshooting common SAML errors
The following are common SAML error messages with causes and solutions provided.
Cause: SAML authentication isn't assigned correctly to the user or isn't enabled as the global authentication method.
Solution: Verify that SAML authentication is configured as the default method or enabled for the user. Additionally, ensure that the user is associated with the SAML app in your IdP.
Cause: The RelayState parameter isn't set correctly in the SAML configuration with the idP.
Solution: For users signing in via the Client Web UI, set RelayState to cws; for profile downloads, set it to profile. Also, check that the user is linked to the SAML app and associated groups on the IdP side.
Tip
Enable the SAML Debug Flag in Access Server for detailed logging to identify the exact cause in server logs.
Cause: The role_list is incorrectly set in the Assigned Default Client Scopes in Keycloak.
Solution: Remove role-list from Assigned Default Client Scopes for the SAML client app in Keycloak.
Cause: SAML assertion validation failed, which can occur due to incorrect URLs or invalid certificates.
Solution:
Verify that you accurately entered the IdP and SP URLs. To avoid errors, we recommend copying the URLs from Access Server as the Service Provider (SP) to the Identity Provider (IdP).
Import the correct Metadata XML file from the IDP to Access Server. Importing the XML file can minimize human errors.
Check that the IdP certificate used by the SP is correct and current.
Tip
Enable the SAML Debug Flag in Access Server for detailed logging to identify the exact cause in server logs.
Cause: A configuration error with the Keycloak settings or missing fields in the IdP Metadata file.
Solution: Verify that Keycloak is correctly configured and that the IdP Metadata file includes the x409cert field.
Cause: The certificate for the SAML app on the IdP is expired, causing authentication to fail. The certificate is included in the metadata XML file imported into the SP (Access Server).
Solution:
Generate a new certificate for the SAML app on the IdP.
Download a fresh Metadata XML file and re-import it to the SP in Access Server.
Cause: The metadata file from the IdP has invalid fields, incorrect values, or missing elements that the SP expects.
Solution: Review the metadata file for missing or incorrect fields. Ensure all necessary fields are formatted correctly.
Cause: The RequestedAuthnContext in the SAML request is mismatched. This happens when a user has already authenticated with a different AuthnContext (authentication method) than the one being requested.
Solution: Refer to the resolution in our support article.
Cause: Username mismatch between Access Server and the IdP.
Solution: Ensure that the username entered in Access Server matches exactly with the one on the IdP side, including case sensitivity. For more, refer to Mismatch between provided username 'UserA' and username provided by SMAL Identity provider 'UserB'.
Tip
Server-locked profiles can be used with SAML but are not optimal.
When using server-locked profiles with SAML:
Set the Username to the user's SAML username (e.g.,
user@domain.com).Any value can be entered in the Password field, as it will be ignored (use "saml" or similar). The field can't be left empty.
If the SAML username in Access Server and the IdP do not match in capitalization, authentication will fail.
Issue: You encountered one of these error messages:
DENY: user in deny list
user account suspended
User access denied
Reason: This error message occurs in one of two situations:
The deny access box is checked for the user in the User Permissions table.
The Deny access to unlisted accounts by default is set to Yes. The user authenticates with an external system (PAM, LDAP, RADIUS, or SAML) and doesn't exist in the User Permissions table or match the username in the external system.
Resolution for deny access box
Sign in to the Admin Web UI.
Click User Management > User Permissions.
Click Deny Access to uncheck the box for the username.
Resolution for Deny access to unlisted accounts by default
You can resolve the issue by adding the user to Access Server's user permissions table or by allowing Access Server to add users automatically by setting Deny access to unlisted accounts by default to No.
Follow the steps below for your preferred option.
Add the user:
Sign in to the Admin Web UI.
Click User Management > User Permissions.
Add the user to the User Permissions table if it doesn't exist.
Ensure the spelling and case match between Access Server and the external authentication server.
Allow Access Server to add users:
Sign in to the Admin Web UI.
Click Authentication > Settings.
Under External User Registration, set Deny access to unlisted accounts by default to No.
Connect to the console and get root privileges.
Run the blow command to change the value to "false" (Default) or "true":
./sacli --user "__DEFAULT__" --key "def_deny" --value "false" UserPropPut ./sacli start
If these steps do not resolve the issue, enable the SAML Debug Flag in Access Server to capture detailed logs for further analysis. You can then try authenticating with SAML and check the server logs to identify any specific errors. For advanced troubleshooting, consider opening a support ticket with OpenVPN Support.