SAML Integration

NEW IN RELEASE 74

You can configure IQ Server to work with a SAML Identity Provider for authentication via Single Sign-On (SSO) and to send user groups to IQ Server for authorization.

IQ Server SAML Support

IQ Server implements the Web Browser SSO Profile from the  SAML 2.0 specification Supported bindings for sign-on are HTTP-POST (the default) and HTTP-Redirect for requests to the Identity Provider and HTTP-POST binding for responses from the Identity Provider. The Basic Attribute Profile is used for retrieving further information regarding the subjects and supported attributes are explained in SAML Configuration Details

Integrating IQ Server with an Identity Provider

Note that steps 3 and 4 require the System Administrator role in IQ Server.

  1. Download the Identity Provider's SAML Metadata file. As an orientation, the metadata should have the following form:

    <EntityDescriptor xmlns="urn:oasis:names:tc:SAML:2.0:metadata" xmlns:dsig="http://www.w3.org/2000/09/xmldsig#" entityID="...">
      <IDPSSODescriptor WantAuthnRequestsSigned="true" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
        <KeyDescriptor use="signing">
          ...
        </KeyDescriptor>
        <SingleLogoutService Binding="..." Location="..."/>
        <NameIDFormat>...</NameIDFormat>
        <SingleSignOnService Binding="..." Location="..."/>
      </IDPSSODescriptor>
    </EntityDescriptor>
  2. For IQ Server, upload via either the  SAML REST API or the  UI.
    • Make sure the attribute names configured in IQ Server match the ones used by the Identity Provider.
    • Make sure that if you want response and/or assertion signature validation, that those signatures are provided by your Identity Provider and that your Identity Provider metadata provides a signing key.
    • You may also want to assign groups that IQ Server is expected to receive to IQ Server roles via the role membership REST API.
    • You may also want to change your identity provider name, which will be displayed on the login form when SAML is configured, to something users will easily recognise.
  3. Download IQ Server 's SAML Metadata (also known as the Service Provider Metadata) using the  Download IQ Server Metadata  button or via the SAML REST API .

  4. Upload IQ Server's SAML Metadata (downloaded in the previous step) to the Identity Provider.
    • This is also referred to as registering a Service Provider to an Identity Provider.
    • If the Identity Provider does not allow uploading IQ Server's SAML Metadata, then you can inspect it to extract the needed values.  Also note that the "Audience" of your Identity Provider should be IQ Server's Entity ID, and its "Recipient" should be IQ Server's assertion consumer service URL. Please note that IQ Server's assertion consumer service URL is /saml.
  5. Configure the Identity Provider to send expected subject information as basic attributes. Note that these attribute names can be customized later.

At this point, integration is done and Single Sign-On using SAML should be functional via the  SAML Workflow  according to the following:

  • As long as a SAML configuration exists in IQ Server, the user login modal will also show the Single Sign-On button, which can be clicked to initiate SAML Single Sign-On. Note that regular sign in is also still available.
  • If no SAML configuration exists, the Single Sign-On button will not appear.
  • When you delete an existing SAML configuration and create a new one, even if you use the same Identity Provider Metadata XML, IQ Server will generate new keys, requiring SAML Metadata XML to be downloaded and re-registered to the Identity Provider.

Uploading the Identity Provider Metadata and Configuring the Attribute Names Using the UI 

  • Access the SAML Configuration UI using the SAML link in the System Preferences menu.
  • When SAML is not configured in IQ Server, the Identity Provider Metadata XML will be empty, and the attributes will have their default values populated.
  • Upload the Identity Provider's Metadata XML either by using the Load XML File button or pasting the XML directly in the text area.
  • Modify the response/assertion signature validation if needed.
  • Modify the Attribute Names if needed.
  • Hit Save.

SAML Configuration Details

Entity ID

Entity ID is a unique identifier that will be used when registering IQ Server to the Identity Provider as a Service Provider. It must be a valid URI. If an explicit value is not provided, the default value <iqServerBaseUrl> /api/v2/config/saml/metadata  is used. Normally there is no need to modify the Entity ID, but it is required if the deployed IQ Server instance does not have a fixed URL and or port. 

Attribute Names

IQ Server expects the following basic SAML attributes to carry/extract the user information:

  • username attribute
  • first name attribute
  • last name attribute
  • e-mail attribute
  • groups attribute

These attribute names must be configured on the Identity Provider, and must match the SAML Configuration in IQ Server. Note that the values are case-sensitive.

For example, if the Identity Provider sends the email information of a user with the attribute user-email-address, please make sure you configure the email attribute name to user-email-address in IQ Server as well.

All of these properties are optional to configure. If they are not explicitly configured, default values for them will be used.

Securing SAML Integration

Signed requests/responses to/from the Identity Provider are supported and recommended for security purposes. Signing responses can only be configured from the Identity Provider and not within IQ Server. In case signed messages are used and the Identity Provider's signature keys are renewed (or changed for any other reason), Identity Provider metadata in IQ Server 's SAML configuration must be updated.

IQ Server's SAML configuration can be set to validate the Identity Provider's signature(s) on its response and/or its assertions within that response by setting the

  • validate response signature
  • validate assertion signature

options. By default, if a signing key is found in the Identity Provider metadata, then IQ Server will attempt to validate signatures on the response and its assertions.

SAML Workflow

Once IQ Server is configured to use SAML

  • Login can be done using the Identity Provider's login experience by clicking the Single Sign-On button at the user login.
  • Once the user logs in to the Identity Provider, they will be redirected back to IQ Server with an active session.
  • Logging out of IQ Server will not invalidate the session on the Identity Provider.

Note that

  • Any existing sessions will not be invalidated once SAML is configured meaning any users already logged in when SAML is configured will need to logout and login again via the Single Sign-On button to use SAML SSO.
  • Notifications by role will not work for SAML-only authenticated users but they will continue to work for internal or LDAP users.
    • Backing up SAML authenticated users with one or more internal users or LDAP users can be considered in case notifications by role is needed for SAML users.

SAML Request - Response Example

A SAML Request from IQ Server should have the following form:

<samlp:AuthnRequest xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" xmlns="urn:oasis:names:tc:SAML:2.0:assertion" 
    Destination="http://localhost:8080/auth/realms/master/protocol/saml" ForceAuthn="false" ID="ID_a6998aaa-5136-43e8-9f4f-dfff023509c8" 
    IsPassive="false" IssueInstant="2019-09-09T15:26:05.647Z" Version="2.0">
    <saml:Issuer xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">http://localhost:8070/api/v2/config/saml/metadata</saml:Issuer>
    <dsig:Signature xmlns:dsig="http://www.w3.org/2000/09/xmldsig#">
        <dsig:SignedInfo>
            <dsig:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
            <dsig:SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"/>
            <dsig:Reference URI="#ID_a6998aaa-5136-43e8-9f4f-dfff023509c8">
                <dsig:Transforms>
                    <dsig:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
                    <dsig:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
                </dsig:Transforms>
                <dsig:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
                <dsig:DigestValue>...</dsig:DigestValue>
            </dsig:Reference>
        </dsig:SignedInfo>
        <dsig:SignatureValue>...</dsig:SignatureValue>
        <dsig:KeyInfo>...</dsig:KeyInfo>
    </dsig:Signature>
    <samlp:NameIDPolicy AllowCreate="true" Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified"/>
</samlp:AuthnRequest>


A SAML Response from the Identity Provider should have the following form:

<samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" Destination="http://localhost:8070/saml" ID="ID_8c7224bc-a04d-43d8-8fb7-02747425b6d2" InResponseTo="ID_a6998aaa-5136-43e8-9f4f-dfff023509c8" IssueInstant="2019-09-09T15:27:33.971Z" Version="2.0">
    <saml:Issuer>http://localhost:8080/auth/realms/master</saml:Issuer>
    <dsig:Signature xmlns:dsig="http://www.w3.org/2000/09/xmldsig#">
        <dsig:SignedInfo>
            <dsig:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
            <dsig:SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"/>
            <dsig:Reference URI="#ID_8c7224bc-a04d-43d8-8fb7-02747425b6d2">
                <dsig:Transforms>
                    <dsig:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
                    <dsig:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
                </dsig:Transforms>
                <dsig:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
                <dsig:DigestValue>...</dsig:DigestValue>
            </dsig:Reference>
        </dsig:SignedInfo>
        <dsig:SignatureValue>...</dsig:SignatureValue>
        <dsig:KeyInfo>...</dsig:KeyInfo>
    </dsig:Signature>
    <samlp:Status>
        <samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/>
    </samlp:Status>
    <saml:Assertion xmlns="urn:oasis:names:tc:SAML:2.0:assertion" ID="ID_526c9596-fedb-4909-ab27-7b15d5692c53" IssueInstant="2019-09-09T15:27:33.971Z" Version="2.0">
        <saml:Issuer>http://localhost:8080/auth/realms/master</saml:Issuer>
        <dsig:Signature xmlns:dsig="http://www.w3.org/2000/09/xmldsig#">
            <dsig:SignedInfo>
                <dsig:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
                <dsig:SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"/>
                <dsig:Reference URI="#ID_526c9596-fedb-4909-ab27-7b15d5692c53">
                    <dsig:Transforms>
                        <dsig:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
                        <dsig:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
                    </dsig:Transforms>
                    <dsig:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
                    <dsig:DigestValue>...</dsig:DigestValue>
                </dsig:Reference>
            </dsig:SignedInfo>
            <dsig:SignatureValue>...</dsig:SignatureValue>
            <dsig:KeyInfo>...</dsig:KeyInfo>
        </dsig:Signature>
        <saml:Subject>
            <saml:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">nameId</saml:NameID>
            <saml:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
                <saml:SubjectConfirmationData InResponseTo="ID_a6998aaa-5136-43e8-9f4f-dfff023509c8" NotOnOrAfter="2019-09-09T15:28:31.971Z" Recipient="http://localhost:8070/saml"/>
            </saml:SubjectConfirmation>
        </saml:Subject>
        <saml:Conditions NotBefore="2019-09-09T15:27:31.971Z" NotOnOrAfter="2019-09-09T15:28:31.971Z">
            <saml:AudienceRestriction>
                <saml:Audience>http://localhost:8070/api/v2/config/saml/metadata</saml:Audience>
            </saml:AudienceRestriction>
        </saml:Conditions>
        <saml:AuthnStatement AuthnInstant="2019-09-09T15:27:33.971Z" SessionIndex="4517351d-1303-4208-935d-852944760239::e1f45bba-dfac-4294-bbc2-7020da66a3a4">
            <saml:AuthnContext>
                <saml:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified</saml:AuthnContextClassRef>
            </saml:AuthnContext>
        </saml:AuthnStatement>
        <saml:AttributeStatement>
            <saml:Attribute FriendlyName="username" Name="username" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
                <saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">jonny</saml:AttributeValue>
            </saml:Attribute>
            <saml:Attribute FriendlyName="firstName" Name="firstName" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
                <saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">John</saml:AttributeValue>
            </saml:Attribute>
            <saml:Attribute FriendlyName="lastName" Name="lastName" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
                <saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">Smith</saml:AttributeValue>
            </saml:Attribute>
            <saml:Attribute FriendlyName="email" Name="email" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
                <saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">john@smith.com</saml:AttributeValue>
            </saml:Attribute>
            <saml:Attribute FriendlyName="groups" Name="groups" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
                <saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">group1</saml:AttributeValue>
                <saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">group2</saml:AttributeValue>
                ...
                <saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">groupN</saml:AttributeValue>
            </saml:Attribute>
        </saml:AttributeStatement>
    </saml:Assertion>
</samlp:Response>