Skip to main content

SAML Integration

You can configure Lifecycle to work with a SAML Identity Provider for authentication via Single Sign-On (SSO) and to send user groups to Lifecycle 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.

IQ Server 157 and newer

SAML users and groups are now searchable in the UI. This allows them to be used for application contacts, for notifications by role, and for access control.

Note

SAML users and their associated groups must login at least once before they will be discoverable.

IQ Server 156 and older

Note

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

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'sSAML 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, 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 recognise.

  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.

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>

Create SAML User Tokens

To support SSO with other plug-ins and IDE integrations, users can generate SAML tokens via UI (recommended.) On submitting their token credentials, the users will be authenticated and authorized as if they had submitted their original credentials.

Note: User Token REST API can also be used to create a SAML token, provided an IQ server browser session is already active.

How to create SAML user token:

  1. Login to IQ server as System Administrator.

  2. Click on the Manage User Account on the left top navigation bar.

  3. Select Manage User Token.

  4. Click on Generate User Token button

  5. Copy the generated user code and passcode to use as SAML user token where needed.