Setting up SAML Configuration

To integrate a SAML application into Zextras, you need to configure the SAML IDP (IDentity Provider) using the Zextras SAML SP data. In our sample scenario, we want to add SAML authentication to our domain example.com, accessible at SP_URL.

The SAML configuration is carried out at an IDP provider, then imported in Zextras Suite using a dedicated command.

The most important configuration options are the following. You should configure them on the SAML IDP side.

sp.entityid

https://SP_URL/zx/auth/samlMetadata?domain=example.com

sp.assertion_consumer_service.url

https://SP_URL/zx/auth/saml

sp.nameidformat

urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress

In order to validate against Zextras, make sure that the Name of the attribute that is used as NameID is set to mailPrimaryAddress.

You can now integrate a SAML application in Zextras in two ways, either automatic or manual. The following sections describe each method in detail.

Import SAML Configuration Automatically

The SAML IDP provides a URL from which to download the configuration; assuming that this URL is https://my-saml-provider.org/simplesaml/saml/idp/metadata.php, you can import the configuration using the command:

zxsuite auth saml import example.com URL  https://my-saml-provider.org/simplesaml/saml/idp/metadata.php
The URL supplied by the SAML IDP for an unsecured connection may be slight different from the previous one, like in our example. 
zxsuite auth saml import example.com url https://localidp.local.loc/app/xxxxxxxxxxxxxxx/sso/saml/metadata allow_unsecure true

You are now DONE! You can see the SAML button on the login page.

Login page with SAML enabled

By clicking it, you will be redirect to the SAML IDP login page.

Import SAML Configuration Manually

If you need to manually edit the SAML configuration, you can:

  1. Export the default SAML settings using:

    zxsuite auth saml get example.com export_to /tmp/saml.json

  1. Open the resulting file /tmp/saml.json in any editor and modify the requested attributes (see example in the previous section)

    • entityid

    • assertion_consumer_service.url

    • nameidformat

      The /tmp/saml.json fill should look similar to this one:

      {
  "sp.entityid":"https://SP_URL/zx/auth/samlMetadata?domain=example.com", (1)
  "sp.assertion_consumer_service.url":"https://SP_URL/zx/auth/saml", (1)
  "sp.nameidformat":"urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress", (1)
  "sp.assertion_consumer_service.binding":"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST",
  "sp.single_logout_service.url":"https://SP_URL/?loginOp=logout",
  "sp.single_logout_service.binding":"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect",
  "sp.x509cert":"aabbcc", (2)

  "idp.entityid":"https://IDP-URL/simplesamlphp/saml2/idp/metadata.php",
  "idp.x509cert":"xxyyzz", (2)
  "idp.single_sign_on_service.url":"https://IDP-URL/simplesamlphp/saml2/idp/SSOService.php",
  "idp.single_sign_on_service.binding":"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect",
  "idp.single_logout_service.binding":"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect",

  "organization.name":"ACME, INC.",
  "organization.displayname":"Example",
  "organization.url":"https://www.example.com/",

  "security.requested_authncontextcomparison":"exact",
  "security.requested_authncontext":"urn:oasis:names:tc:SAML:2.0:ac:classes:urn:oasis:names:tc:SAML:2.0:ac:classes:Password",
  "security.signature_algorithm":"http://www.w3.org/2000/09/xmldsig#rsa sha1",
  "security.logoutresponse_signed":"false",
  "security.want_nameid_encrypted":"false",
  "security.want_assertions_encrypted":"false",
  "security.want_assertions_signed":"false","debug":"true",
  "security.want_messages_signed":"false",
  "security.authnrequest_signed":"false",
  "security.want_xml_validation":"true",
  "security.logoutrequest_signed":"false"
}
      1 These values are taken from the example in the previous section.
      2 Certificates must be valid, they are omitted for clarity.

  2. Save the changes made to the file and import it into Zextras Suite using the command:

zxsuite auth saml import example.com /tmp/saml.json

Like in the SAML configuration automatic import, you are now done and you will be able to use SAML from the login page of your domain.

It is also possible to view or edit single attributes by using the zxsuite auth saml get and zxsuite auth saml set command options.