SAML SSO Debugging Guide
Security Assertion Markup Language (SAML) is a standard that allows a Single Sign On (SSO) system. This form of authentication is usually centered around web browsers. Artifactory supports most SAML SSO systems, with guides available for setting up a multiplicity of SAML provider-based connections. Once the system is set up, the SAML provider will run the login system.
The SAML System Overview
Logging in to Artifactory via a SAML SSO can be summarized in three steps:
- Point your browser to Artifactory. Artifactory will redirect your browser to the SAML SSO login page. The Artifactory redirect will attach an XML login request to the browser session, this XML contains a return URL.
- At this step, the user logs into the SAML provider. If logging in involves 2-factor authentication and/or other security mechanisms, these will be handled entirely by the SAML provider.
- After successfully logging in, the SAML provider will redirect you back to Artifactory. The URL the redirect follows will depend on the SAML provider. It will either be the URL that was sent by Artifactory as part of the XML login request in Step #1 or one that your SAML provider has been configured to use. On the backend, your SAML provider will attach an encrypted XML document containing your user information. This XML contains the Artifactory User Name in the "NameID" field. It may also include the user's email address and group assertions.
SAML SSO Best Practices for REST API tools
Artifactory users frequently ask how REST API tools can be used, as all package managers, such as Maven, cannot log in through SAML SSO. There are two ways of getting around this problem:
- Allow users to generate API keys via the Allow Created Users Access to Profile Page
- Implement a system that creates access tokens for users
An API key or an access token can be used as a password. As long as the users know their SAML username, they can access Artifactory via CLI tools by passing the API key or access token.
Troubleshooting SAML Problems
To assist you in troubleshooting, use Artifactory's debug logger to decrypt and display the XML assertions from Steps #1 and #3. You can turn the debug logger on by adding the following XML snippet to your $ARTIFACTORY_HOME/etc/logback.xml file, which will cause SAML XML data to be sent to your $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>
This doesn't require a restart to take effect.
Keep in mind that this will display encrypted SAML information in plaintext. No passwords are contained in this information, but email addresses and group associations will be stored in a log file. Once debugging is complete, you should remove the debug logger.
As there are numerous locations where either your SAML SSO endpoint or Artifactory URL may need to be specified, most SAML problems arise from the use of an incorrect URL. And while every SAML provider is different, these are several solutions that are helpful to resolving common problems.
SAML’s Auto-Redirect Prevents Logins
Typically, when you tick the Auto-Redirect Login option in Artifactory’s SAML settings, you won’t be able to log in via the internal Artifactory prompt. If your SAML setup isn't correct, you might even find yourself locked out of Artifactory altogether. You can bypass this by going directly to the Artifactory login menu at:
[6.X] https://example.com/artifactory/webapp/#/login [7.X] https://example.com/ui/login/
Logging Out via SAML Fails
When Artifactory logs you out, you should be sent back to the SAML provider to sign out of the external system. A logout failure can happen if your SAML provider expects a signed LogoutRequest, which is an action that Artifactory cannot perform automatically (although this known, product improvement request issue, about which more information is available HERE , is currently being addressed). If your SAML provider is facing this kind of error, you can use your Artifactory web page as the logout endpoint:
After SAML Login, Returning to Artifactory Fails
This is usually due to some misconfiguration on the SAML provider side, but there is one place in Artifactory where your return URL might not have been set up correctly. Artifactory uses a custom base URL setting as a fallback if network headers don’t provide a URL. As this setting might be involved in the problem, try updating it at: Admin > Configuration > General Configuration in Artifactory 6.X and Admin > General > Settings in Artifactory 7.X. Please ensure the URL matches the current web browser's endpoint:
Otherwise, double-check the settings from your SAML provider, especially if the URL that browsers are sent to matches the SAML Provider's configuration. For example, in OneLogin, the redirect URL is specified on the SAML provider side, as follows:
If the SAML-side URL is wrong, a user's web browser will be sent to the wrong destination after logging in.
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 to and used by Artifactory, the application will not persist a SAML group's members as a security precaution.
Consider a situation where a particular user was removed from a SAML-based administrators group. Before this happened, they recorded their Artifactory API key or access token. As long as the user doesn’t log in via the SAML SSO mechanism, they’ll be able to use CLI tools, such as Maven, with the same access level they had before they were removed. There is no universal way for Artifactory to update the SAML user's groups without the SSO process.