Skip to main content

SAML REST API

SAML allows to integrate IQ Server with your single sign-on (SSO) infrastructure and this REST API enables system administrators to inspect and update the needed configuration for IQ Server. Consult the SAML Integration page for details on integrating IQ Server with an identity provider and/or configuring SAML using the UI instead of the REST API explained here.

Query Current SAML Configuration

The SAML configuration that is currently in effect can be determined using the request

GET /api/v2/config/saml

Using the cURL tool, the following example demonstrates a complete request to a local IQ Server using its built-in admin account

curl -u admin:admin123 http://localhost:8070/api/v2/config/saml

If SAML is not configured, the request yields HTTP status code 404. If SAML is configured, the response will be a JSON document similar to the one below.

{
  "identityProviderName": "My Identity Provider",
  "entityId": "http://localhost:8070/api/v2/config/saml/metadata",
  "firstNameAttributeName": "firstName",
  "lastNameAttributeName": "lastName",
  "emailAttributeName": "email",
  "usernameAttributeName": "username",
  "groupsAttributeName": "groups",
  "validateResponseSignature": null,
  "validateAssertionSignature": false,
  "identityProviderMetadataXml": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><EntityDescriptor ..."
}

The next section regarding changes to the configuration will detail the meaning of the individual parameters.

Configure SAML Integration

To enable single sign-on using SAML, the API accepts PUT requests to the same path as used for reading the SAML configuration

PUT /api/v2/config/saml

This request uses the content type multipart/form-data to transport the needed configuration to the IQ Server. The form data consists of two parameters:

  • identityProviderXml

    The SAML metadata of your identity provider (IdP), i.e. the server that will be handling the single sign-on for users accessing IQ Server. Consult the documentation of your identity provider on how exactly to obtain this metadata. 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>

  • samlConfiguration

    A JSON document with additional configuration properties needed for IQ Server to interact with the identity provider. This document supports the following properties, all of which are optional and defaulted if not specified:

    Property

    Description

    Default Value

    identityProviderName

    The name of your identity provider to be displayed on the login form when SAML is configured. Ideally this should be set to a name that users will recognise.

    identity provider

    entityId

    The URI that IQ Server will use to identify itself in requests to the single sign-on service.

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

    firstNameAttributeName

    The name of the SAML attribute that IQ Server will extract from the login response of the identity provider to determine the user's first name.

    firstName

    lastNameAttributeName

    The name of the SAML attribute that IQ Server will extract from the login response of the identity provider to determine the user's last name.

    lastName

    emailAttributeName

    The name of the SAML attribute that IQ Server will extract from the login response of the identity provider to determine the user's mail address.

    email

    usernameAttributeName

    The name of the SAML attribute that IQ Server will extract from the login response of the identity provider to determine the user's username/id.

    username

    groupsAttributeName

    The name of the SAML attribute that IQ Server will extract from the login response of the identity provider to determine the groups the user is a member of.

    groups

    validateResponseSignature

    A boolean flag (true/false) denoting whether SAML responses from the identity provider are cryptographically signed to avoid tampering.

    null in which case the setting is derived from the SAML metadata of the identity provider, performing signature validation if a signing key (<KeyDescriptor>) is included

    validateAssertionSignature

    A boolean flag (true/false) denoting whether SAML assertions from the identity provider are cryptographically signed to avoid tampering.

    null in which case the setting is derived from the SAML metadata of the identity provider, performing signature validation if a signing key (<KeyDescriptor>) is included

If SAML is not yet configured, the identityProviderXml parameter is mandatory for the request to succeed. If SAML is already configured, either identityProviderXml or samlConfiguration can be omitted from the request to keep its current setting and selectively update only the other parameter.

The following concrete example sets the identityProviderXml to the content of the file saml-idp-metadata.xml and uses default values for most of the remaning SAML configuration except for the groupsAttributeName:

curl -u admin:admin123 -X PUT -F identityProviderXml=@saml-idp-metadata.xml -F samlConfiguration='{"groupsAttributeName": "memberOf"}' http://localhost:8070/api/v2/config/saml

The response is either HTTP status code 204 if the operation was successful or status code 400 if any part of the new configuration is invalid in which case the previous SAML configuration remains in effect.

Query IQ Server's Metadata

IQ Server's metadata currently in effect can be downloaded using the request

GET /api/v2/config/saml/metadata

Using the cURL tool, the following example demonstrates a complete request to a local IQ Server using its built-in admin account

curl -u admin:admin123 http://localhost:8070/api/v2/config/saml/metadata

If SAML is not configured, the request yields HTTP status code 404. If SAML is configured, the response will be an XML document similar to the one below.

<EntityDescriptor xmlns="urn:oasis:names:tc:SAML:2.0:metadata" entityID="http://localhost:8070/api/v2/config/saml/metadata">
    <SPSSODescriptor AuthnRequestsSigned="false" WantAssertionsSigned="true"
        protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol urn:oasis:names:tc:SAML:1.1:protocol
                                    http://schemas.xmlsoap.org/ws/2003/07/secext">
        <KeyDescriptor use="encryption">
          <dsig:KeyInfo xmlns:dsig="http://www.w3.org/2000/09/xmldsig#">
            <dsig:X509Data>
              <dsig:X509Certificate>MIIC4heX5KLRbvE3Xnb1y3B9lSw0JpgINSXxKiwUVyJHtacCo+LQ==</dsig:X509Certificate>
            </dsig:X509Data>
          </dsig:KeyInfo>
        </KeyDescriptor>
        <SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="http://localhost:8070/saml"/>
        <NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</NameIDFormat>
        <AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="http://localhost:8070/saml"
                index="1" isDefault="true" />
    </SPSSODescriptor>
</EntityDescriptor>

Disable SAML Integration

If the SAML integration and thereby single sign-on needs to be disabled, an HTTP DELETE request is used

DELETE /api/v2/config/saml

For example

curl -u admin:admin123 -X DELETE http://localhost:8070/api/v2/config/saml

If SAML was configured, the request responds with HTTP status code 204. If SAML was not configured to begin with the HTTP status code 404 is returned instead.