Skip to main content

SAML Integration

Use a SAML Identity Provider (IdP) for authentication via Single Sign-On (SSO). 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.

IQ Server SAML Changelog

  • Release 180 and newer

    • Starting from release 180, Java 17 is required to run IQ Server.

      Starting Java version 17 the use of SHA-1 based digests and signature algorithms for XML signatures has been forbidden. Users may need to reconfigure the signature algorithm on their identity provider platform.

  • IQ Server 157 and newer

    • SAML users and groups are searchable in the UI to be used for: application contacts, notifications by role, and access control.

    • SAML users and their associated groups must log into the UI at least once before they are discoverable.

  • IQ Server 156 and older

    • Notifications by role will not work for SAML-only authenticated users. Back up SAML authentication with internal or LDAP users to configure notifications.

Create User Tokens for SAML

SAML users must generate user tokens to access the plug-ins and the IDE integrations. The User Token REST API or UI may be used to create user tokens after the user has logged into the UI at least once.

See IQ Server User Tokens for details.

Integrating IQ Server with an Identity Provider

This process requires the System Administrator role in IQ Server.

  1. Download the Identity Provider's SAML Metadata file.

  2. In IQ Server, upload the SAML Metadata file. This is done through the SAML REST API or the UI.

    • The attribute names configured in IQ Server must match those from the Identity Provider.

    • Make sure that if you want response and/or assertion signature validation, those signatures are provided by your Identity Provider and that your Identity Provider metadata provides a signing key.

    • 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 recognize.

  3. DownloadIQ 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 the unique identifier used when registering IQ Server to the Identity Provider as a Service Provider. It must be a valid URI. The default value is

<iqServerBaseUrl>/api/v2/config/saml/metadata

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.

The metadata is in the following format:

<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>

A SAML Request from IQ Server will 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 will 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>