|
SAML (Security Assertion Markup Language) is one of the most popular ways of handling single-sign on (SSO) for web-based applications. It's standards-based, fast, very secure, and does not rely on user passwords. OneLogin is pre-integrated with hundreds of SAML-enabled apps with easy setup and configuration. This article provides a general overview of how to configure any SAML-enabled app, and can be used as the framework for the details provided in our app-specific SAML documentation.
Before you begin, you should add your application, configure your desired setup details, and Save it in order to enable the options below. If the Connector Version option appears during initial configuration, select SAML2.0.
Note: If you intend to configure both SAML and provisioning for an application, you must enable provisioning first and only then complete your SAML configuration.
Configuration
Some SAML apps may not display the Configuration page. If Configuration does not appear, move to the next section.
The prompt on this page varies by your application requirements. Many apps request the full URL used to access the app, while others just need your organization's unique subdomain. Others may ask for your company, group, or organization name. Follow the instructions displayed on this page or consult the app's documentation for details.
If your app is enabled for provisioning, you may also see a prompt for API Connection settings on this page. Disregard this section unless configuring user provisioning for this app.
Parameters
In most cases, you can accept the default Configured by admin and attribute mappings on this page. At minimum, SAML assertions must pass a user identifier, which is usually shown as NameID or Username and is almost always mapped to OneLogin's Email attribute.
In other words, OneLogin sends the user's OneLogin email address as the app's username, so for SAML SSO to work, their username in the app must be identical to their email address in OneLogin. If this is not how your accounts are configured, you can change this parameter to another OneLogin field, like Username to match their OneLogin username, Email domain part to use only the first part of their email address (before the @ symbol), or any custom field you've previously configured.
SSO
This page displays the SAML metadata that you can copy over to your app provider in order to complete the integration. Typically, this involves logging into the app as an administrator, going to their SSO or SAML setup interface, and pasting the values into their respective fields. However, some app providers may require that you contact their support team to provide them with the metadata.
|
X.509 Certificate
|
This is the public certificate that establishes trust between OneLogin and the app provider. You can click Change to select another certificate you may have created, or View Details to see which apps are currently using this certificate and download or copy its full content.
|
|
SAML Signature Algorithm
|
A strong SAML signature encryption algorithm provides a more secure SAML assertion and response. Select the algorithm you'd like to use to encrypt this integration.
Note: SHA-1 is the least secure signature algorithm of these options and may not be supported by all applications for security reasons. Consider switching to a more complex algorithm and verify with your app provider which algorithms they support.
|
|
Issuer URL
|
This URL conveys data about OneLogin as a SAML-providing IdP; it usually takes the form of https://app.onelogin.com/saml/metadata/12a34567-8bcd-901e-2345-f6gh7ij8kl90. Terminology may vary by application, but typically when an app requests something like a Metadata URL, Identity Provider ID, or IdP Entity ID, it's referring to this URL.
|
|
SAML 2.0 Endpoint (HTTP)
|
This URL is the address that the app redirects to for SSO if a session isn't already established; it usually takes the form of https://YourDomain.onelogin.com/trust/saml2/http-post/sso/12a34567-8bcd-901e-2345-f6gh7ij8kl90. Terminology may vary by application, but typically when an app requests something like a Login URL, SSO URL, or Endpoint URL, it's referring to this address.
|
|
SLO Endpoint (HTTP)
|
This URL is the address used for single logout (SLO) if it's supported by the app; it usually takes the form of https://YourDomain.onelogin.com/trust/saml2/http-redirect/slo/1234567. Terminology may vary by application, but typically when an app requests a Logout Service URL or Sign-Out Page URL, it's referring to this address. Providing an SLO endpoint is optional; if you enter it, then the user is also signed out of OneLogin whenever they sign out of the application.
|
Sometimes an app provider will accept a single XML file containing all of the SAML metadata required for setup. You can download it it by choosing ꜜ SAML Metadata from the More Actions menu.
X.509 Certificate
If an app's setup interface requires a certificate, you can retrieve yours by clicking View Details under X.509 Certificate or by going to Security > Certificates in your admin menu and selecting the correct certificate. Click the clipboard icon to copy the entirety of the certificate and paste it into the app's interface, being sure to include the entire content of the certificate, including -----BEGIN CERTIFICATE----- and -----END CERTIFICATE------.
If necessary, you can also choose to Download a copy of your certificate in one of several formats. The default X.509 PEM format is the most broadly accepted; only select an alternate format if directed to by the app's documentation.
Some app providers request the SHA fingerprint instead of the certificate. Select the correct encryption algorithm and click the clipboard icon to copy the fingerprint; depending on the algorithm used, it typically takes the form of 12:3A:45:67:8B:9C:D0:12:E3:45:F6:7G:89:0H:IJ:K1:LM:2N:O3:45.
Testing Your SAML Connection
After completing your SAML configuration and any other app configuration requirements you have, test your connection with the steps below. If SAML has been configured correctly, you will be automatically logged into the app.
- Assign the app to a test user and ensure the account's app username is identical to its corresponding OneLogin attribute.
- Open a fresh browser session in an alternate browser or incognito tab to ensure that your test user is not logged into the app.
- Log in to OneLogin as the test user and select the app from their OneLogin user portal.
|