1 of 6

Single sign-on

Exivity can act as a SAML Service Provider (SP) which can be connected to a SAML Identity Provider (IdP). Some configuration is required to setup a secure connection.

SAML configuration

The SAML configuration can be accessed by navigating to Administration > Settings and then clicking on the SAML tab. On this page, you'll find two sub-tabs:

Configuration: Your IdP endpoints can be entered here, along with details about the certificate used by the IdP.
Endpoints: When registering Exivity with your IdP, you need to provide these Exivity endpoints.

Configuration

The configuration settings are listed below:

Advanced settings

Using the advanced settings editor, even more options are exposed for configurating the integration. Please note that settings should be entered using a valid JSON format. Please consult with your implementation partner first before editing the advanced settings.

{
    // Service Provider Data that we are deploying
    "sp": {
        // Identifier of the SP entity  (must be a URI)
        "entityId": "",

        // Specifies info about where and how the <AuthnResponse> message MUST be
        // returned to the requester, in this case our SP.
        "assertionConsumerService": {

            // URL Location where the <Response> from the IdP will be returned
            "url": "",

            // SAML protocol binding to be used when returning the <Response>
            // message.  Onelogin Toolkit supports for this endpoint the
            // HTTP-Redirect binding only
            "binding": "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST",
        },

        // If you need to specify requested attributes, set a
        // attributeConsumingService. nameFormat, attributeValue and
        // friendlyName can be omitted. Otherwise remove this section.
        "attributeConsumingService": {
            "ServiceName": "SP test",
            "serviceDescription": "Test Service",
            "requestedAttributes": [
                {
                    "name": "",
                    "isRequired": false,
                    "nameFormat": "",
                    "friendlyName": "",
                    "attributeValue": ""
                }
            ]
        },

        // Specifies info about where and how the <Logout Response> message MUST be
        // returned to the requester, in this case our SP.
        "singleLogoutService": {

            // URL Location where the <Response> from the IdP will be returned
            "url": "",

            // SAML protocol binding to be used when returning the <Response>
            // message.  Onelogin Toolkit supports for this endpoint the
            // HTTP-Redirect binding only
            "binding": "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect",
        },

        // Specifies constraints on the name identifier to be used to
        // represent the requested subject.
        // Take a look on lib/Saml2/Constants.php to see the NameIdFormat supported
        "NameIDFormat": "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified",

        // Usually x509cert and privateKey of the SP are provided by files placed at
        // the certs folder. But we can also provide them with the following parameters
        "x509cert": "",
        "privateKey": "",

        // Key rollover
        // If you plan to update the SP x509cert and privateKey
        // you can define here the new x509cert and it will be 
        // published on the SP metadata so Identity Providers can
        // read them and get ready for rollover.
        "x509certNew": ""
    },

    // Compression settings 
    // Handle if the getRequest/getResponse methods will return the Request/Response deflated.
    // But if we provide a $deflate boolean parameter to the getRequest or getResponse
    // method it will have priority over the compression settings.
    "compress": {
        "requests": true,
        "responses": true
    },

    // Security settings
    "security": {
        /** signatures and encryptions offered */
        // Indicates that the nameID of the <samlp:logoutRequest> sent by this SP
        // will be encrypted.
        "nameIdEncrypted": false,

        // Indicates whether the <samlp:AuthnRequest> messages sent by this SP
        // will be signed.              [The Metadata of the SP will offer this info]
        "authnRequestsSigned": false,

        // Indicates whether the <samlp:logoutRequest> messages sent by this SP
        // will be signed.
        "logoutRequestSigned": false,

        // Indicates whether the <samlp:logoutResponse> messages sent by this SP
        // will be signed.
        "logoutResponseSigned": false,

        // Sign the Metadata: False || True (use sp certs)
        "signMetadata": false,

        /** signatures and encryptions required **/
        // Indicates a requirement for the <samlp:Response>, <samlp:LogoutRequest> and
        // <samlp:LogoutResponse> elements received by this SP to be signed.
        "wantMessagesSigned": false,

        // Indicates a requirement for the <saml:Assertion> elements received by
        // this SP to be encrypted.
        "wantAssertionsEncrypted": false,

        // Indicates a requirement for the <saml:Assertion> elements received by
        // this SP to be signed.        [The Metadata of the SP will offer this info]
        "wantAssertionsSigned": false,

        // Indicates a requirement for the NameID element on the SAMLResponse received
        // by this SP to be present.
        "wantNameId": true,

        // Indicates a requirement for the NameID received by
        // this SP to be encrypted.
        "wantNameIdEncrypted": false,

        // Authentication context.
        // Set to false and no AuthContext will be sent in the AuthNRequest,
        // Set true or don't present this parameter and you will get an AuthContext 'exact' 'urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport'
        // Set an array with the possible auth context values: {'urn:oasis:names:tc:SAML:2.0:ac:classes:Password', 'urn:oasis:names:tc:SAML:2.0:ac:classes:X509'),
        "requestedAuthnContext": false,

        // Allows the authn comparison parameter to be set, defaults to 'exact' if
        // the setting is not present.
        "requestedAuthnContextComparison": "exact",

        // Indicates if the SP will validate all received xmls.
        // (In order to validate the xml, 'strict' and 'wantXMLValidation' must be true).
        "wantXMLValidation": true,

        // If true, SAMLResponses with an empty value at its Destination
        // attribute will not be rejected for this fact.
        "relaxDestinationValidation": false,

        // Algorithm that the toolkit will use on signing process. Options:
        //    'http://www.w3.org/2000/09/xmldsig#rsa-sha1'
        //    'http://www.w3.org/2000/09/xmldsig#dsa-sha1'
        //    'http://www.w3.org/2001/04/xmldsig-more#rsa-sha256'
        //    'http://www.w3.org/2001/04/xmldsig-more#rsa-sha384'
        //    'http://www.w3.org/2001/04/xmldsig-more#rsa-sha512'
        // Notice that sha1 is a deprecated algorithm and should not be used
        "signatureAlgorithm": "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256",

        // Algorithm that the toolkit will use on digest process. Options:
        //    'http://www.w3.org/2000/09/xmldsig#sha1'
        //    'http://www.w3.org/2001/04/xmlenc#sha256'
        //    'http://www.w3.org/2001/04/xmldsig-more#sha384'
        //    'http://www.w3.org/2001/04/xmlenc#sha512'
        // Notice that sha1 is a deprecated algorithm and should not be used
        "digestAlgorithm": "http://www.w3.org/2001/04/xmlenc#sha256",

        // ADFS URL-Encodes SAML data as lowercase, and the toolkit by default uses
        // uppercase. Turn it True for ADFS compatibility on signature verification
        "lowercaseUrlencoding": false
    },

    // Contact information template, it is recommended to suply a technical and support contacts
    "contactPerson": {
        "technical": {
            "givenName": "",
            "emailAddress": ""
        },
        "support": {
            "givenName": "",
            "emailAddress": ""
        }
    },

    // Organization information template, the info in en_US lang is recomended, add more if required
    "organization": {
        "en-US": {
            "name": "",
            "displayname": "",
            "url": ""
        }
    }
}

Endpoints

To view the full SAML endpoints for your Exivity instance, navigate to Administration > System and then click on the SAML tab and then the Endpoints sub-tab.

Integration tutorials

External resources

Azure-AD

Setting up Azure Active Directory is pretty straight-forward, but it helps to know the exact steps to follow, as configuraing SAML can be a bit daunting.

To add Exivity to your Azure AD applications, follow these steps:

In your Azure portal, go to the Azure Active Directory service:

In the sidebar, click Enterprise applications:

Click the New application button:

Click the Non-gallery application button:

Enter a name for the new application (i.e. My Exivity instance) and click the Add button.
Click the Configure single sign-on (required) button:

From the Single Sign-On Mode dropdown list, select SAML-based Sign-on:

Now enter the following details on this page:

The resulting page could look something like this:

Click the Configure [your application name] button:

A new pane will open with instructions. Navigate to the Exivity SAML configuration (see configuration) and copy the following options from the pane in your Azure portal:

The Exivity configuration page could look something like this:

Now unfold the Advanced menu at the bottom of the screen, and paste the following JSON data:

{
  "security": {
    "wantXMLValidation": false
  }
}

Then in Exivity, click the Update button
And in your Azure Portal, click the Save button:

As the last step, enable Single Sign-On in Exivity by navigating to Administration > Configuration and then clicking on the System tab. Make sure the Single Sign-On option is set to Enabled, and click the Update button:

SSO is now configured and enabled, and you can now use Azure AD to login to your Exivity instance. The login screen will look something like this:

And by clicking on the Login button, you'll be taken to the Azure AD login screen. Exivity will receive the Azure AD e-mail address and create a new user with a minimal set of permissions if no existing user is found.

Auth0

First, we need to add Exivity to your Auth0 applications. Follow these steps:

On the Auth0 dashboard, click the Applications menu item, and then the Create application button:

Choose a descriptive name for your application, click the Single Page Web App button, and finally the Create button:

On the application overview page, click the Settings tab:

On this page, fill out the following details and click on the Save changes button:

Click on the SAML2 addon button. On the Settings tab, fill out the following details and click the Save button:

Click on the Usage tab.

As the last step, enable Single Sign-On in Exivity by navigating to Administration > Settings and then clicking on the System tab. Make sure the Single Sign-On option is set to Enabled, and click the Update button:

SSO is now configured and enabled, and you can now use Auth0 to login to your Exivity instance. The login screen will look something like this:

OneLogin

In order to use OneLogin as an Identity Provider, we need to set up a new application. To do so, navigate to the OneLogin administration, hover over Applications in the navigation bar, and click on Applications:

Click on the Add App button:

In the list of applications, search for "saml" and click on the item SAML Test Connector (IdP w/ attr w/ sign response):

Choose a descriptive name for your application and click the Save button:

Click the Configuration tab:

Refer to the endpoints section in the Single Sign On article how to obtain the endpoints values. Fill in these fields:

You need to add the OneLogin domain for your organisation to the CORS whitelist as well.

Now, we have to copy and paste some values from our OneLogin application into the Exivity instance Single Sign-on settings. In OneLogin, click on the SSO tab:

In a separate browser tab, open the Exivity SAML setting (See SAML configuration) and copy over the following settings:

Now, let's set up the OneLogin certificate in Exivity. Under the label X.509 Certificate, click the View Details link. Copy the X.509 Certificate and paste it in the X-509 certificate field in the Exivity settings.

As the last step, copy and paste this JSON object in the Advanced settings in the Exivity settings:

{
  "security": {
    "wantXMLValidation": false
  }
}

Now you're ready to use OneLogin as a SAML Identity Provider. Enable Single Sign-On in Exivity by navigating to Administration, Settings and then click on the System tab. Make sure the Single Sign-On option is set to an option including SAML2 Authentication:

OneLogin is now configured and enabled, and you can now use it to log in to your Exivity instance. The login screen will look something like this:

And by clicking on the Login button, you'll be taken to the OneLogin login screen. Exivity will receive the users e-mail address and create a new user in the configured user group (see configuration) if no existing user is found.

ADFS

Quick guide to setup ADFS access protocol in Exivity.

Setting up ADFS Configuration

On ADFS side, go to Trust Relationships -> Relying Party Trusts, click on Add Relying Party Trust

Select Data Source: Enter data about the relying party manually
Specify Display Name: Exivity
Choose Profile: AD FS Profile
Configure Certificate: Leave blank
Configure URL: Leave blank
Configure Identifier: https://EXIVITY-URL /v1/auth/saml/metadata
Configure Multi-factor authentication now?: Choose I do not want to configure multi-factor authentication settings for this relying party trust at this time.
Choose Issuance Authorization Rules: Permit all users to access this relying party
Ready to Add trust: --
Click on Finish.

Right click the newly added trust: Properties

Go to Endpoints – Add SAML:
- Endpoint type: SAML Assertion Consumer
- Binding: POST
- Trusted URL: https://EXIVITY-URL/v1/auth/saml/acs
Click on Save.

Right click the newly added trust: Edit Claim Rules

Go to Issuance Transform Rules – Add Rule
Choose Rule Type: Send Claims using a Custom Rule
Configure Claim Rule:
- Claim Rule Name – Exivity
- Custom Rule:
- c:[Type == "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn"]
  => issue(Type = "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier", Issuer = c.Issuer, OriginalIssuer = c.OriginalIssuer, Value = c.Value, ValueType = c.ValueType, Properties["http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/format"] = "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress");
Finally, click on Save.

Setting up ADFS in Exivity

Make sure to perform the following steps with an Exivity user with enough rights (admin user)

First, go to Administration - Settings - Single sign-on and choose the SAML tab:

In a separate browser tab, open the Exivity SAML configuration and fill the following settings:

As the last step, enable Single Sign-On in Exivity by navigating to Administration > Settings and then clicking on the System tab. Make sure the Single Sign-On option is set to Enabled, and click the Update button:

SSO is now configured and enabled, and you can now use ADFS to login to your Exivity instance. The login screen will look something like this:

And by clicking on the Login button, you'll be taken to the ADFS login screen.

LDAP

Quick guide to setup LDAP access protocol in Exivity

Setting up LDAP in Exivity

Make sure you are performing the following steps with a Exivity user with enough rights (admin user)

First, go to Administration - Settings - Single sign-on and choose the LDAP tab:

Fill the required Server and Attributes section parameters, and click on UPDATE.

Server section:

Attributes section:

Finally, go to the System tab, in the Core section, set the Single Sign-On parameter to Local and LDAP Authentication and click on UPDATE.

Now you can start login in Exivity using LDAP authentication.

Setting up your security certificate

This section only needs to be performed if you have chosen encryption SSL or TLS to authenticate with LDAP. These steps are done in the Exivity server side.

If you don't have a certificate in .pem format you can convert your current certificate with the OpenSSL tool.

Once you have your pem certificate stored in the server hard drive, take a note of its path, and create a system environmental variable LDAPTLS_CACERT . The value of this environmental variable will be the certificate full path.

Finally, restart the Exivity Web Service.