SAML Debugging Guide

Patrick Russell
2019-08-20 15:07

SAML SSO Debugging Guide

SAML (Security Assertion Markup Language) is a standard that offers a Single Sign On (SSO) system. This form of authentication is usually centered around web browsers. 

Artifactory supports most forms of SAML SSO systems, with multiple guides for setting up a connection based on the "SAML Provider", also known as the server that runs the login system.

The SAML System Overview

Logging in via SAML SSO can be summarized in 3 steps:

1. The user first points their browser to Artifactory. Artifactory then redirects the user's browser to the SAML SSO login page. 
On the backend, Artifactory sends an XML login request containing the return URL.

2. In the SAML login page, the user logs in. This can involve 2-factor authentication or other security mechanisms, and is handled entirely on the SAML Provider site.

3. After a successful login, the SAML Provider will redirect the user back to Artifactory. The URL in use is either the URL Artifactory sent, or one configured in the SAML provider. The exact method depends on the provider.
On the backend, the SAML Provider will return an encrypted XML document containing the user's information. This always includes the NameID for the Artifactory User Name. It may also include an email address and Group Assertions.

In steps 1 and 3, a debug logger can decrypt and display the XML assertions to assist in troubleshooting. 

To turn on the logger, apply this XML snippet to the $ARTIFACTORY_HOME/etc/logback.xml file. It doesn't require a restart to take effect, and sends SAML XML data to the $ARTIFACTORY_HOME/logs/artifactory.log file:

[Warning: This logger prints SAML XML Assertions to a log file!]
<logger name="org.artifactory.addon.sso.saml">
        <level value="debug"/>
</logger>

Keep in mind this will display normally encrypted SAML information in plaintext. There are no passwords in this information, but emails and group associations will be stored in a log file. Once debugging is complete, you should remove the debug logger.

SAML SSO Best Practices for REST API tools

There are a few general best practices when relying on the SAML SSO system.

One common question is how to use REST API tools, as users cannot authenticate through SAML SSO. 

There are two solutions to this problem:

– Allow users to generate API keys via the "Allow Created Users Access To Profile Page" option
– Implement a system that can create Access Tokens for users

Users can use the Access Token or API Key as a password. As long as they pass in their SAML username, they can access the system via CLI tools.

Troubleshooting SAML Problems

Most SAML problems involve an incorrect URL, as there are many possible places where either the SAML SSO endpoint or where Artifactory's URL needs to be specified. 

Every SAML provider is different, but these are some solutions to common problems.

The SAML Auto-Redirect prevents logins
When the "Auto Redirect Login" option is checked in the Artifactory SAML settings, users are not normally able to log in via the internal Artifactory prompt. If the SAML setup isn't correct, users can be locked out of Artifactory.

You can bypass this by going directly to the Artifactory login menu, located under:

http://example.com/artifactory/webapp/#/login

Logging out via SAML fails
When Artifactory logs out a user, they are supposed to be sent back to the SAML provider to sign them out of the external system. This can happen if the SAML provider expects a Signed LogoutRequest, which currently Artifactory cannot perform. 

As of Artifactory 6.11.3, this is being worked on. Please see RTFACT-9324 for details on this problem.

A common workaround if the SAML Provider is facing an error is to use the Artifactory web page as the logout endpoint:

After the SAML Login, going back to Artifactory fails
This is usually due to some misconfiguration on the SAML provider side, but there is one place in Artifactory where the return URL might not be set up correctly. 

Artifactory uses a "Custom Base URL" setting as a fallback if network headers do not provide a URL. This setting might be involved in the problem. 

Try updating the setting under Admin -> Configuration -> General Configuration to match the current web browser's endpoint:

Otherwise, it's worth double-checking the SAML Provider's settings, especially if the URL that browsers are sent to matches one of its configuration fields. 

For example, in OneLogin, the redirect URL is specified on the SAML Provider side:

SAML Groups disappear or do not persist after a logout
SAML SSO is based entirely around using a web browser. While SAML group information can be sent and used in Artifactory, at this time the application will not persist a SAML group's members.

This is intended to be a security mechanism. For example, consider a situation where a user was removed from SAML-based Administrator group. Before this happened, they recorded their Artifactory API key or Access Token.

As long as the user does not log in via the SAML SSO mechanism, they will be able to use their CLI tools such as Maven with the same access level they had before.