Advanced SAML Custom Connector


The Advanced SAML Custom Connector (previously known as the SAML Test Connector) allows you to build a custom application connector for apps that are unavailable in the OneLogin catalog, like internal applications original to your organization. It combines and expands different configuration options from former SAML Custom Connectors, providing granular control over your connection settings to create a customized single-sign on (SSO) connector that meets your unique authentication requirements.

Related Documentation

 

 

  1. In your OneLogin admin portal, add the application SAML Custom Connector (Advanced). Provide it with a display name, icon, and description to reflect the app you'll be connecting and Save your changes.

  2. Go to Configuration and configure the following settings:

    RelayState

    Enter the URL that the user will be directed to after they sign in, or leave blank to direct users to the app's default home page. This is used to address deep linking and to preserve and convey the state information of the original entity.

    Note: In some workflows initiated by the app as the service provider (SP), rather than by OneLogin as the identity provider (IdP), the SP may include a RelayState parameter in the SAML request, overriding the value entered here.

    Audience (EntityID)

    If the SP provides an EntityID indicating the target destination for the SAML response, enter it here.

    Recipient (Required for some configurations)

    Some SPs may expect and validate a recipient URL for an endpoint that receives the SAML assertion and matches it to the ACS URL. This improves security by ensuring the SAML response reaches its intended target, such as the EntityID.

    ACS (Consumer) URL Validator (Required)

    Enter a regular expression used to ensure that OneLogin posts the SAML response to the correct URL by validating the ACS (Consumer) URL entered in the next field. For example, the ACS (Consumer) URL https://example.com/saml/consume/ would have the validator ^https:\/\/example\.com\/saml\/consume\/$. If the source URL matches the regular expression, then we reply back to the URL. Otherwise, OneLogin generates a warning event log and responds to the existing ACS (Consumer) URL value.

    Important: It is essential that your regex includes the ^ and $ anchors denoting the beginning and end of the URL. If you were to enter https:\/\/example\.com\/saml\/consume\/ as your validator, this could be bypassed by a malicious actor using http://www.hacker.com/saml/consumer?getparam=https://example.com/saml/consume/.

    For testing purposes, you may also use a * wildcard to allow any URL to pass, such as with ^https:\/\/.*.

    Important: The wildcard should only be used when testing your configuration. For your organization's security, do not implement a validator using wildcards in production.

    Tip! You can use Rubular to validate your regex before entering it into OneLogin.

    ACS (Consumer) URL (Required)

    Enter the URL where OneLogin should POST the SAML response for the SP to process.

    Single Logout URL

    If you've configured a single log-out (SLO) flow, enter the URL where OneLogin should send the logout request.

    • For an IdP-initiated SLO flow, this is the endpoint address used when a user logs out of the app, through either GET or POST. Its response simply logs the user out of the application.
    • For an SP-initiated SLO flow, this is the endpoint address used when a user logs out of OneLogin. Its response closes all previously initiated SP sessions.

    Login URL (Required for some configurations)

    If using an SP-initiated flow, enter the SP's login URL for initiating SSO.

    SAML not valid before (Required)

    Enter the number of minutes that must elapse before the assertion can be accepted by the SP; this allows for time differential between OneLogin and the SP.

    SAML not valid on or after (Required)

    Enter the number of minutes that the assertion remains valid once it can be accepted by the SP.

    SAML initiator (Required)

    Select OneLogin for an IdP-initiated flow, or Service Provider for an SP-initiated flow.

    SAML nameID format (Required)

    Select how users' nameID values should be determined:

    • Unspecified — OneLogin defines the data format and the SP understands how to parse and extract the data.
    • Persistent — The nameID is generated by OneLogin and registered with the SP (or group of SPs), using the same value for multiple sessions.
    • Transient — The SP internally identifies the user with the nameID provided by OneLogin. This value is treated as opaque and temporary, making it valid for one session only.
    • Email (Default) — The nameID matches the user's email address.

    SAML issuer type (Required)

    Choose whether to set the application to a Specific or Generic EntityID.

    If you configure multiple SAML connectors, all those with the Generic option share the same EntityID value. This can make configuration and maintenance easier for complex services running on multiple servers.

    SAML signature element (Required)

    Choose whether the authentication should be signed with a Response or an Assertion element.

    Encrypt assertion

    Select this option if you would like to encrypt the assertion for extra security. After saving your changes, a Public Key field appears at the bottom of this configuration where you may enter your public key for encryption.

    SAML encryption method (Required for some configurations)

    If you enabled Encrypt assertion in the previous setting, select the encryption method to use.

    Send NameID Format in SLO Request

    If you have SLO configured, select whether the nameID format should be included in SLO requests.

    Generate AttributeValue tag for empty values

    Select whether the SAML assertion should include an attribute tag for all multi-valued parameters, even those with no values present.

    SAML sessionNotOnOrAfter (Required)

    Enter the maximum length of a valid user session in minutes; the session will automatically be ended after this time if the user has not already ended it.

    Sign SLO Request (Required for some configurations)

    Select this option to sign SLO requests. In some rare cases, this may be required by the application.

    Sign SLO Response (Required for some configurations)

    Select this option to sign SLO responses. In some rare cases, this may be required by the application.

  3. Configure any additional application or SAML settings necessary for your app, and assign it to your users.