Enable SAML-based single sign-on

Security Assertion Markup Language (SAML) single sign-on allows users to sign in to Adaxes Web interface with the same authentication mechanisms that you use within the rest of your organization. Adaxes supports the SAML 2.0 protocol, which can be used with a variety of identity providers, including Okta, OneLogin, Microsoft Entra ID, Auth0, etc.

In this tutorial, you will learn how to enable SAML authentication in Adaxes Web interface and how to configure your identity provider to communicate with Adaxes.

  1. Login to Adaxes Web interface configurator using the credentials of an Adaxes service administrator.

     How to open the configurator {id=how_open_configurator}
    • On the computer where Web interface configurator is installed, open Windows Start menu.

    • Click Adaxes Web Interface Configurator.

    Only Adaxes service administrators are allowed to enable SAML-based authentication for Adaxes Web interface. The permission cannot be granted to other users via security roles.

  2. In the top left corner, select the Web interface you want to customize.

    By default, all Web interfaces use the Sign In settings of the Common Sign In page. If you want to enable SAML authentication for a particular Web interface, select it in the list. Otherwise, select Common Sign In.

  3. In the left navigation menu, click Sign in.

  4. Select the Single sign-on (SSO) using SAML option in the Sign In section.

  5. Identity provider configuration

    Prior to continuing with the Web interface configuration, you need to setup your identity provider to communicate with Adaxes. Below are the steps to register the Web interface with the most popular providers.

     Okta {id=okta}

    To set up an application for Adaxes Web interface in Okta:

    • Log in to your Okta organization as a user with administrative privileges.

    • Expand Applications and then click Applications.

    • Click the Create App Integration button.

    • In the dialog that opens, select the SAML 2.0 option and then click Next.

    • On the General Settings step, enter the application name (e.g. Adaxes Web interface) and, optionally, upload Adaxes logo.

    • Click Next.

    • In the Single sign on URL field, enter the base URL of the Web interface, plus /Saml2.

      http://<base-url>/Saml2
      

      Examples:

      • https://acme.com/Adaxes/Saml2

      • https://acme.com/MyDirectory/Saml2

      • https://adaxes.acme.com/Saml2

      The URL must not contain the Web interface configuration name, like Admin, HelpDesk or SelfService.

      Incorrect URL: https://acme.com/Adaxes/Admin/Saml2

    • Copy Entity ID from Adaxes Web interface configurator and paste it into the Audience URI (SP Entity ID) field in Okta. The default Web interface entity ID is https://adaxes.com/saml2.

    • By default, when signing in into Adaxes Web interface from the Okta portal, users will be redirected to the Common Sign In page. To redirect users to a particular Web interface, specify its name (e.g. Admin) in the Default RelayState field.

    • Click Next, complete the form and click Finish.

    • Activate the Sign On tab of the newly created application.

    • Scroll down to the SAML Signing Certificates section.

    • Click View SAML setup instructions.

    • Copy Identity Provider Single Sign-On URL from Okta and paste it into the Provider URL field in Adaxes Web interface configurator.

    • Copy X.509 Certificate from Okta and paste it into the Certificate field in Web interface configurator.

    • To complete the application setup in Okta, assign it to the users you would like to provide access to.

     OneLogin {id=onelogin}

    To set up an application for Adaxes Web interface in OneLogin:

    • Log in to OneLogin administrator dashboard.

    • Navigate to Applications > Applications.

    • Click Add App.

    • Find and select the SAML Test Connector (Advanced) application.

    • Enter a display name for the application (e.g. Adaxes Web interface).

    • Optionally, upload rectangular and square Adaxes logos.

    • Click Save.

    • Activate the Configuration tab.

    • By default, when signing in into Adaxes Web interface from the OneLogin portal, users will be redirected to the Common Sign In page. To redirect users to a particular Web interface, specify its name (e.g. Admin) in the RelayState field.

    • Copy Entity ID from Adaxes Web interface configurator and paste it into the Audience (EntityID) field in OneLogin. The default Web interface entity ID is https://adaxes.com/saml2.

    • In the Recipient and ACS (Consumer) URL fields, enter the base URL of the Web interface, plus /Saml2.

      http://<base-url>/Saml2
      

      Examples:

      • https://acme.com/Adaxes/Saml2

      • https://acme.com/MyDirectory/Saml2

      • https://adaxes.acme.com/Saml2

      The URL must not contain the Web interface configuration name, like Admin, HelpDesk or SelfService.

      Incorrect URL: https://acme.com/Adaxes/Admin/Saml2

    • In the ACS (Consumer) URL Validator field, enter the same URL, but with the following modifications:

      • Add a forward slash before each period and backslash.

      • Optionally, to make URL validation more secure, add the ^ character at the beginning of the URL and the $ character at the end of it.

      Example:

      URL: https://acme.com/Adaxes/Saml2
      
      Validator: ^https:\/\/acme\.com\/Adaxes\/Saml2$
      

      Using the ^ and $ anchors makes the validation more restrictive, as their presence indicates that the URL must exactly match the pattern. For example, if the expression doesn't contain the two characters, the validation can be bypassed with the following URL:

      http://www.hack.com/saml?param=https://acme.com/Adaxes/Saml2/
      

      Multiple URLs

      If your Web interface is accessible from multiple URLs, all the URLs must pass the regular expression validation. For example, if the Web interface can be reached via the following two URLs:

      • https://A.adaxes.acme.com
      • https://B.adaxes.acme.com

      The regular expression could be as follows:

      ^https:\/\/(A|B)\.adaxes\.acme\.com\/Saml2$
      
    • In the Single Logout URL field, enter the same URL as in the Recipient field, plus /Logout.

      Example:

      https://acme.com/Adaxes/Saml2/Logout
      

      If your Web interface is accessible from multiple URLs, you can use any of them.

    • Activate the Parameters tab.

    • Set the NameID value field to userPrincipalName.

    • Click Save.

    • Activate the SSO tab.

    • Copy SAML 2.0 Endpoint (HTTP) from OneLogin and paste it into the Provider URL field in Adaxes Web interface configurator.

    • Copy Issuer URL from OneLogin and paste it into the Provider Entity ID field in Adaxes Web interface configurator.

    • Copy SLO Endpoint (HTTP) from OneLogin and paste it into the Provider Logout URL field in Adaxes Web interface configurator.

    • Copy X.509 Certificate from OneLogin and paste it into the Certificate field in Web interface configurator.

    • To complete the application setup in OneLogin, assign it to the users you would like to provide access to.

     Microsoft Entra ID {id=ME-ID}

    To set up an application for Adaxes Web interface in Microsoft Entra ID:

    • Log in to the Microsoft Entra admin center using the credentials of an administrator account.

    • Navigate to and open the Enterprise applications service.

      To quickly locate the service, type Enterprise applications in the Search field.

    • Click New application.

    • Click Create your own application.

    • Specify a display name for the application (e.g. Adaxes Web interface).

    • Click Create.

    • In the Manage section, select Single sign-on.

    • Click SAML.

    • Within the Basic SAML Configuration section, click Edit.

    • Copy Entity ID from Adaxes Web interface configurator. The default Web interface entity ID is https://adaxes.com/saml2.

    • In the Microsoft Entra admin center, click Add identifier below the Identifier (Entity ID) field and paste the identifier copied on the previous step.

    • Click Add reply URL below the Reply URL (Assertion Consumer Service URL) field.

    • Enter the base URL of the Web interface, plus /Saml2.

      https://<base-url>/Saml2
      

      Examples:

      • https://acme.com/Adaxes/Saml2

      • https://acme.com/MyDirectory/Saml2

      • https://adaxes.acme.com/Saml2

      The URL must not contain the Web interface configuration name, like Admin, HelpDesk or SelfService.

      Incorrect URL: https://acme.com/Adaxes/Admin/Saml2

    • If your Web interface is accessible from multiple URLs, enter all of them in the Reply URL (Assertion Consumer Service URL) section.

    • By default, when signing in into Adaxes Web interface from Microsoft Entra ID, users will be redirected to the Common Sign In page. To redirect users to a particular Web interface, specify its name (e.g. Admin) in the Relay State field.

    • In the Logout URL field, enter the same URL as in the Reply URL (Assertion Consumer Service URL) field, plus /Logout.

      Example:

      https://acme.com/Adaxes/Saml2/Logout
      

      If your Web interface is accessible from multiple URLs, you can use any of them.

    • Click Save and close the form.

    • Optionally, upload Adaxes logo.

       Step by step {id=StepByStep}
      • In the Manage section, click Properties.

      • In the Logo field, upload the Adaxes logo.

      • Click Save.

    • Copy Login URL from the Set up <Application Name> section in the Microsoft Entra admin center and paste it into the Provider URL field in Adaxes Web interface configurator.

    • Copy Microsoft Entra ID Identifier from the Set up <Application Name> section in the Microsoft Entra admin center and paste it into the Provider Entity ID field in Adaxes Web interface configurator.

    • Copy Logout URL from the Set up <Application Name> section in the Microsoft Entra admin center and paste it into the Provider Logout URL field in Adaxes Web interface configurator.

    • Download the certificate from the Certificate (Base64) field in the Microsoft Entra admin center and then load it into the Certificate field in Web interface configurator.

    • To complete the application setup in Microsoft Entra ID, assign it to the users you would like to provide access to.

     Duo {id=duo}

    To set up an application for Adaxes Web interface in Duo:

    • Log in to your Duo admin panel.

    • In the left pane, click Applications and then click Protect an Application.

    • Locate the entry for Generic SAML Service Provider in the applications list and click Protect next to it.

    • On the Configure SAML Service Provider step, enter the application name (e.g. Adaxes Web interface).

    • Copy Entity ID from Adaxes Web interface configurator and paste it into the Entity ID field in Duo. The default Web interface entity ID is https://adaxes.com/saml2.

    • In the Assertion Consumer Service field, enter the base URL of the Web interface, plus /Saml2.

      http://<base-url>/Saml2
      

      Examples:

      • https://acme.com/Adaxes/Saml2

      • http://acme.com/MyDirectory/Saml2

      • http://adaxes.acme.com/Saml2

      The URL must not contain the Web interface configuration name, like Admin, HelpDesk or SelfService.

      Incorrect URL: https://acme.com/Adaxes/Admin/Saml2

    • In the Single Logout URL field, enter the same URL, plus /Logout.

      Example:

      https://acme.com/Adaxes/Saml2/Logout
      
    • By default, when signing in into Adaxes Web interface via the URL provided by Duo, users will be redirected to the Common Sign In page. To redirect users to a particular Web interface, specify its name (e.g. Admin) in the Default Relay State field.

    • Set the NameID attribute field to userPrincipalName.

    • Click Save Configuration.

    • Download your configuration file.

    • Log in to the Duo Access Gateway server console as a user with administrative privileges.

    • In the left pane, click Applications.

    • In the Add Application section, upload your configuration file.

    • Optionally, upload Adaxes logo for the application.

    • Copy SSO URL from the Metadata section and paste it into the Provider URL field in Adaxes Web interface configurator.

    • Copy Logout URL from the Metadata section and paste it into the Provider Logout URL field in Adaxes Web interface configurator.

    • Copy Entity ID from the Metadata section and paste it into the Provider Entity ID field in Adaxes Web interface configurator.

    • Click Download Certificate in Duo and then load the certificate into the Certificate field in Web interface configurator.

     Auth0 {id=auth0}

    To set up an application for Adaxes Web interface in Auth0:

    • Log in to Auth0.

    • Expand Applications and then click Applications.

    • Click Create Application.

    • Enter the application name (e.g. Adaxes Web interface).

    • Select the Regular Web Applications application type and click Create.

    • Activate the Settings tab.

    • Optionally, upload Adaxes logo for the application.

    • In the Allowed Callback URLs field, enter the base URL of the Web interface, plus /Saml2.

      http://<base-url>/Saml2
      

      Examples:

      • https://acme.com/Adaxes/Saml2

      • http://acme.com/MyDirectory/Saml2

      • http://adaxes.acme.com/Saml2

      The URL must not contain the Web interface configuration name, like Admin, HelpDesk or SelfService.

      Incorrect URL: http://acme.com/Adaxes/Admin/Saml2

    • If your Web interface is accessible from multiple URLs, enter all the URLs separated by commas.

    • In the Allowed Logout URLs field, enter the same URL as in the Allowed Callback URLs field, plus /Logout.

      Example:

      https://acme.com/Adaxes/Saml2/Logout
      

      If your Web interface is accessible from multiple URLs, you can use any of them.

    • Click Save Changes.

    • Activate the Connections tab.

    • Disable all the connections except for Active Directory / LDAP.

    • Activate the Addons tab.

    • Click SAML2 Web App.

    • Activate the Settings tab.

    • Replace <callback-url> in the code below with a URL specified in the Allowed Logout URLs field and paste the code into the Settings field.

      {
          "nameIdentifierProbes": [
              "http://schemas.auth0.com/userPrincipalName"
          ],
          "logout": {
              "callback": "<callback-url>"
          }
      }
      
    • At the bottom of the dialog, click Enable.

    • Activate the Usage tab.

    • Download provider metadata from the Identity Provider Metadata field.

    • In Adaxes Web interface configurator, click provide metadata.

    • Paste the data from the file and click OK.

     ADFS {id=adfs}

    To set up a relying party trust for Adaxes Web interface in ADFS:

    • Log in to your federation server as a user with administrative privileges.

    • In Server Manager, click Tools and then click AD FS Management.

    • In the Actions pane on the right, click Add Relying Party Trust.

    • Click Start.

    • Select Enter data about the relying party manually and click Next.

    • Specify a relying party display name (e.g. Adaxes Web interface) and click Next.

    • Optionally, upload a token encryption certificate and click Next.

    • Select Enable support for the SAML 2.0 WebSSO protocol.

    • In the Relying party SAML 2.0 SSO service URL field, enter the base URL of the Web interface, plus /Saml2.

      https://<base-url>/Saml2
      

      Examples:

      • https://acme.com/Adaxes/Saml2

      • https://acme.com/MyDirectory/Saml2

      • https://adaxes.acme.com/Saml2

      The URL must not contain the Web interface configuration name, like Admin, HelpDesk or SelfService.

      Incorrect URL: https://acme.com/Adaxes/Admin/Saml2

      All URLs are case-sensitive in ADFS.

    • Click Next.

    • Copy Entity ID from Adaxes Web interface configurator and paste it into the Relying party trust identifier field in ADFS. The default Web interface entity ID is https://adaxes.com/saml2.

    • Click Add and then click Next.

    • Select an access control policy and click Next two times.

    • Click Close.

    • In the Relying Party Trusts section, right-click the relying party you created and then click Edit Claim Issuance Policy in the context menu.

    • Click Add Rule.

    • Select Send LDAP Attributes as Claims and click Next.

    • Enter a claim rule name.

    • In the Attribute store drop-down, select Active Directory.

    • In the Mapping of LDAP attributes to outgoing claim types section, select User-Principal-Name in the LDAP Attribute column.

    • In the Outgoing Claim Type column, select Name ID.

    • Click Finish and then click OK.

    • Right-click the relying party you created again and click Properties in the context menu.

    • Activate the Endpoints tab.

    • Click Add SAML.

    • In the Endpoint type drop-down, select SAML Logout.

    • In the Trusted URL field, enter the base URL of the Web interface, plus /Saml2/Logout.

      Example:

      https://acme.com/Adaxes/Saml2/Logout
      

      If your Web interface is accessible from multiple URLs, you can use any of them.

    • Click OK twice.

    • In Adaxes Web interface configurator, click provide metadata.

    • Replace <adfs-server> in the below URL with the fully qualified domain name of your federation server and paste the URL into the Metadata dialog in Web interface configurator.

      https://<adfs-server>/FederationMetadata/2007-06/FederationMetadata.xml
      

      Example:

      https://adfs.acme.com/FederationMetadata/2007-06/FederationMetadata.xml

    • Click OK.

     Other {id=other}

    If you cannot find your identity provider in the list above, it doesn't mean that Adaxes doesn't support it. Refer to the provider's documentation to find out how to set up a Service Provider application to integrate with, and follow the on-screen instructions in Web interface configurator to configure SAML settings for the Web interface.

  6. Switch to Adaxes Web interface configurator and save the changes.

    The Sign In settings configured for the selected Web interface can be applied to other Web interfaces. To do it, in the top right corner of the Sign In section, click the down arrow button and select Apply to other Web interfaces.

     View screenshot