Snipe-IT Asset Management Installation Documentation

Welcome to the Snipe-IT documentation hub. You'll find comprehensive guides and documentation to help you install Snipe-IT as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

- SAML

Configuration guidelines for SAML Single-Sign On (SSO) support

❗️

SAML + LDAP

SAML can only authenticate a user in Snipe-IT if the user exists in Snipe-IT. We do not attempt to create a user on SAML login. This means that if a user exists in your SAML directory but NOT in Snipe-IT, that user will not be able to login to Snipe-IT with SAML. We typically recommend using the LDAP sync to pull your users in, then SAML to authenticate them.

Snipe-IT includes the ability to integrate SAML for login, which will allow you to login using third-party services such as OneLogin and Jumpcloud.

General Steps

  • Configure SAML values at IDP (Entity-ID, Assertion Consumer Service (ACS) URL, Single Logout Service (SLS) URL)
  • Download IdP Metadata / Get IdP Metadata URL
  • Upload IdP Metadatafile / Paste IdP Metadata URL to Snipe-IT SAML settings
  • If necessary, add additional custom config to Snipe-IT SAML settings

Snipe-IT SAML settings

Attribute Mapping - Username

It is possible to override the default setting, to use the value from the NameID response element to match against the username of existing users. If your IdP uses another element in the SAML response, set the value here.

Relevant example from SAML response:

<Subject>
    <NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">[email protected]</NameID>
    <SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
        <SubjectConfirmationData InResponseTo="ONELOGIN_..." NotOnOrAfter="2020-10-01T00:00:00.000Z" Recipient="https://assets.example.com/saml/acs"/>
    </SubjectConfirmation>
</Subject>

If you have existing users configured in Snipe-IT, make sure that their usernames match the value of the NameID element!

SAML Force Login

When this checkbox is enabled, you will not see a login form of Snipe-IT anymore when you go to the Snipe-IT website. Instead it will redirect you directly to the IdP SAML Login.

When you need to see the login form of Snipe-IT to login with an existing user without SAML login, you could add the following query parameter to your Snipe-IT URL: /login?nosaml:

https://assets.example.com/login?nosaml

This might be useful when there are some technical problems with your IdP to be able to sill login to Snipe-IT. For this scenario, make sure that there is an "admin" user in the Snipe-IT user database, who does not login via SAML.

SAML Single Log Out

When this checkbox is enabled, then Snipe-IT will send a logout request to your IdP when you click on the Logout button in Snipe-IT.

This will cause the user to be first redirected to the IdP on logout. Leave unchecked if the IdP doesn't correctly support SP-initiated SAML SLO.

SAML Custom Settings

Here you can add custom settings to adjust the configuration of the underlaying library which provides the SAML functionality.

Values are defined as key-value pairs like the following: key=value

Config values are (some may be missing) (Source)

Config Values

strict=true|false

baseurl=...

debug=true|false

sp.anySpConfig=...

idp.anyIdpConfig=...

security.anySecurityConfig=...

When you run Snipe-IT behind a reverse proxy the following property might be necessary: baseurl=https://assets.example.com/saml

Advanced SAML Settings (Security and Encryption)

A few options in the "SAML Custom Settings" can be useful if you're implementing a high-security setup. When implemented, Snipe-IT will use the same certificates for all signing and encryption. Changing any of these settings will change the contents of the Snipe-IT Metadata XML, so if your IdP is not directly referencing the Metadata URL, you will need to re-download the Metadata and re-present it to your IdP after changing these settings.

Most of these settings are overkill for most environments. The biggest exception would be if your Snipe-IT instance is not secured by TLS (formerly SSL). Then some of these settings could be useful to secure your installation. But in general, an administrator's time would be better spent securing their Snipe-IT installation with TLS.

security.authnRequestsSigned=true - This will activate signed authorization requests.

security.wantAssertionsEncrypted=true - This means that Snipe-IT will require that any assertions coming from your Identity Provider (IdP) must be encrypted.

security.wantAssertionsSigned=true - This will make Snipe-IT require that any assertions sent by your Identity Provider must be digitally signed.

security.wantNameIdEncrypted=true - This will make Snipe-IT require that the NameId that is sent from the IdP must be encrypted.

security.logoutResponseSigned=false - This will remove the requirement that Single Logout Service (SLO/SLS) requests be signed. Try setting this if a logout from your Snipe-IT instance results in an error in your laravel.log file like:

There was an error with SAML SLS: invalid_logout_response  
Reason: Signature validation failed. Logout Response rejected  

Debug SAML Settings

When you need to check the SAML response which is received by Snipe-IT, a simple workaround might be to use the developer tools of your browser.

After configuring your SAML config in Snipe-IT, just go to an incognito tab, open the devloper tools (mostly with F12) and go to the "network" tab.

Now open your Snipe-IT website and wait that the login of your IdP is shown. Login in with your IdP credentials and wait until you are redirected back to your Snipe-IT instance.

Now check the entries of your developer tools "network" tab. There should be an entry for "acs" or "saml/acs", which represents the redirect from your IdP to your callback URL which includes the SAML Response as body parameter. Click on the entry and scroll down in the entry's details to the request body and copy the value of the parameter SAMLResponse.

The value is base64 encoded, so find a tool which could decode it (I would not suggest to do this online, because the value contains a valid access token for your user at your IdP!). When you have decoded it you have the SAML response in XML format :)

Hint: Works in Google Chrome, and other browsers may work the same way

Azure AD as SAML Provider

Key

Value

Entity-ID

https://assets.example.com

Assertion Consumer Service (ACS) URL

https://assets.example.com/saml/acs

Single Logout Service (SLS) URL

https://assets.example.com/saml/sls

Also be sure to configure a certificate at IdP, which is used to sign the SAML Responses.

Azure will automatically configure a certificate for you to sign the SAML responses when you click on the "add certificate" link.

🚧

Azure AD x509 Error with Microsoft Edge

If you see an error like:

Sorry, but we're having trouble signing you in."

AADSTS75011: Authentication method 'X509, MultiFactor' by which the user authenticated the with the service doesn't match requested authentication method 'Password, Protected Transport'. Contact the Snipe-IT application owner.

Add security.requestedAuthnContext=false to the "SAML Custom Settings" text box near the bottom of the SAML settings page. This should resolve the error.

❗️

Azure SAML Single Logout Service (SLO / SLS)

To enable SAML SLO Service on Azure in versions of Snipe-IT at version 5.1.2-pre or later, make sure to add:

retrieveParametersFromServer=true

to the SAML Custom Settings text box near the bottom of the SAML Settings page.

📘

Using username as NameId in Azure (as opposed to email-address-like userprincipalname)

In "User Attributes & Claims", for Unique User Identifier (Name ID), you need to add a "Transformation." Pick Trim(), then pick 'Trailing'. For 'Value', type '@yourdomain.com' (for whatever domain you need to 'trim' off of the userprincipalname).

This will ensure that Azure sends just the username-portion of the email address over to Snipe-IT, rather than the full address. If that username-portion matches the username field of a Snipe-IT user, the user will be logged in to Snipe-IT.

Okta as SAML Provider:

  • In Snipe-IT, check the SAML Enabled checkbox and save.

  • Create a new Application in Okta (select web and SAML 2.0).

  • Add the Assertion Consumer Service (ACS) URL from snipe settings to the Single sign on URL field in Okta.

  • Add the Entity ID from snipe to the Audience URI (SP Entity ID) field in Okta.

  • Click next.

  • Select the Sign On tab and click on "View Setup Instructions"

  • Copy the IDP Metada from the setup instructions and paste it to SAML IdP Metadata in Snipe-IT.

After testing the SAML login (do not forget to assign your application in Okta to accounts that should be able to login to Snipe) you can select the Make SAML the primary login to bypass classic login.

Updated about a month ago


- SAML


Configuration guidelines for SAML Single-Sign On (SSO) support

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.