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.
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.