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 > System info 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:

Option	Description
Entity ID	Sometimes called the Issuer or Metadata URL.
SSO URL	The URL of the Single Sign On service endpoint. Sometimes called the SAML 2.0 Endpoint.
SLO URL	The URL of the Single Logout service endpoint.
X-509 certificate	Base-64 encoded (DER) certificate: - on a single line - without -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----
Default user group	When a new user logs in using SSO, a user will be created in this user group.

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.

Endpoint	Description
/v1/auth/saml/login	Login URL. Initiate SAML login request. Redirects to SAML Identity Provider SSO URL set in the SAML configuration. After a successful authentication (possibly interactive), it will redirect back to this APIs ACS endpoint.
/v1/auth/saml/logout	Logout URL. Initiate SAML login request. Redirects to SAML Identity Provider SLO URL set in the SAML configuration. After the user has been logged out, it will redirect back to this APIs SLS endpoint.
/v1/auth/saml/metadata	Entity ID / Metadata URL. Metadata about the SAML Service Provider instance will be published at this URL.
/v1/auth/saml/acs	Assertion Consumer Service. If the received response from the SAML Identity Provider is valid, redirects to the Exivity dashboard.
/v1/auth/saml/sls	Single Logout Service. If the received response from the SAML Identity Provider is valid, redirects back to the login screen of Exivity.

External resources

Azure-AD

Auth0

Integration examples

• Setup SSO with Azure AD

• Setup SSO with G Suite