Configure Single Sign-on for SAML

EnterWorks can be configured to manage users through an Identity Provider (IDP) using the SAML protocol.

Due to operational requirements, port and SAML protocol usages may differ between development, test, QA, staging, and production environments.

The services for both the New UI (enable2020) and the Classic UI (webcm) need to be configured to use SSO. The process of configuring them consists of editing the scripts that create the services to set parameters for the services, editing shared configuration properties, then using the scripts to recreate the affected services.

The below table indicates the names of the EnterWorks services that must be configured for SSO using SAML, plus the names of the scripts used to perform the configuration.

Service Script
enable-web-server-service create-enable-web-server-service.cmd
enable-api-go-service create-enable-api-go-service.cmd
enable-webcm-broker-service create-enable-webcm-broker-service.cmd

To configure EnterWorks for SSO using SAML:

  1. Metadata files define how communication occurs between an Identity Provider (IDP) and a Service Provider (SP) application. Both the IDP and the SP application need to either supply metadata files, provide the URLs of the metadata files, or provide some of the content that would be in their metadata files.

    EnterWorks (the Service Provider in this case) has two application endpoints that need to be configured to communicate with the IDP, enable2020 and webcm. Both need to be configured to support SSO, therefore they both need metadata from the IDP and they both need to supply metadata.

    1. IDP's metadata: The customer will provide you with either the IDP's metadata files or the URLs of the IDP's metadata files. If the customer supplies the files, on the server that hosts the enable-web-werver-service, copy the metadata files to the folder:

      <drive>:\Enterworks\certs\saml

    2. EnterWorks metadata: The customer may or may not request metadata files for enable2020 and webcm.

      1. If they do not want metadata files, supply them with the callback locations:

        <hostname>/authorization-code/callback
<hostname>/authorization-code/callback/webcm

      2. If they do want metadata files, generate them. Go to the indicated URL and a metadata file will be created and downloaded:

        • enable2020: <localhost>/saml/metadata

        • webcm: <localhost>/saml/metadata/webcm

      3. Some IDPs require that you use the information in the metadata files to configure the IDP manually. If the IDP you are using does, configure it now. For a list of IDP-specific configuration settings, see Settings for Manual Configuration of Specific IDPs.

        1. EnterWorks uses the following attribute statements:

          • login

          • firstName

          • lastName

          • email

        2. If login is not passed as an attribute, Named ID will be used instead.

          If firstname and lastname are both missing, EnterWorks will use login as the user name that will be displayed in the UI.

        3. If SSO is being configured to manage the user's group membership as well, the following group statement must also be specified:

          • groups

      4. Instructions are given below for mapping attribute statement tags that are named differently that what EnterWorks expects.

  2. On all servers that host any of the following services:

    enable-web-server-service
enable-api-go-service
enable-webcm-broker-service

    1. The create-scripts (create-<service-name>-service.cmd) should exist in the following folder. If they do not, create the create-scripts. 

      <drive>:\Enterworks\enable2020\services\install\

    2. Back up the create-service scripts for the affected services. Copy the following scripts:

      • create-enable-web-server-service.cmd

      • create-enable-api-go-service.cmd

      • create-enable-webcm-broker-service.cmd

      to:

      <drive>:\Backup

      In order to make possible future troubleshooting easier, rename the create-service scripts in the Backup folder by appending the date or datetime to the end of their filenames.

    3. Edit the shared configuration properties as follows:

      • fromApp.secureAuth.trustedSignOn=true

      • fromApp.secureAuth.idp.type=3

      1. Open create-enable-web-server-service.cmd for editing.

      2. If the setting -samlSsoSettings doesn't exist in the script, add it.

      3. Set the value of -samlSsoSettings to point to the IDP's metadata for enable2020 and webcm. The setting indicates if the locations of the metadata files are given as a file path or a URL. The metadata files do not have to both be in the same location. They also do not both have to be indicated the same way; one file's location can be stated as a file path and the other file's location can be stated as a URL.

        The format of the -samlSsoSettings string is:

        -samlSsoSettings=\"enable2020|<file or url>|<location of metadata>;webcm|<file or url>|<location of metadata>\"

        where:

        • <file or url> is the word "file" if <location of metadata> is a file path or the word "url" if <location of metadata> is a URL.

        • <location of metadata> is the file path or URL of the metadata file.

        For example:

        -samlSsoSettings=\"enable2020|url|http://dev-xxx.oktapreview.com/<...>/sso/saml/metadata;webcm|file|<drive>:\EnterWorks\certs\saml\"

      4. If the setting -spHost doesn't exist in the script, add it.

      5. The setting -spHost must be set to the domain name indicated in the -webapps.baseUrl setting in the shared configuration properties. For example, if:

        -webapps.baseURL=https://<domain>.com/webcm/

        then set:

        -sphost=https://<domain>.com

      6. Save the script and exit.

      1. Open create-enable-api-go-service.cmd for editing.

      2. The setting -ssoEnabled has been deprecated. If it is present in the file, remove it.

      3. If the setting -ssoIndicator doesn't exist in the script, add it.

      4. Set the value of -ssoIndicator:

        • -ssoIndicator=2 (Recommended setting.) EnterWorks will only request that the IDP authenticates users. When an existing EnterWorks user logs into EnterWorks, EnterWorks will confirm with the IDP that the user exists in the IDP's directory. If the user exists, EnterWorks will allow the user to log in.

        • -ssoIndicator=1: (Default) Just In Time (JIT) provisioning (also known as Automatic provisioning). See Just In Time Provisioning.

      5. Save the script and exit.

      1. Open create-enable-webcm-broker-service.cmd for editing.

      2. The setting -ssoEnabled has been disabled. If it exists in the file, delete it.

      3. Save the script and exit.

    7. Additional SSO Configuration Options:

      • The mapping feature allows EnterWorks to recognize attribute statement tags in the IDP's response that are different than what EnterWorks expects. To configure EnterWorks to recognize the new statement tags:

        1. Create a JSON file that maps the attribute statements EnterWorks is looking for to the tags the IDP is using.

          The JSON file must be named:

          sso-mappings.json

          and must be located in:

          <drive>:\Enterworks\enable2020\services\sso-mappings\

        2. The sso-mappings.json file has five key:value pairs:

          {
	"login": "login",
	"firstName": "firstName",
	"lastName": "lastName",
	"email": "email",
	"groups": "groups"										
}

        3. The key is what EnterWorks is looking for. Replace the value with the tag the IDP is using. For instance, if the IDP is using the "email" tag as the login value, the sso-mappings.json file would have a key:value pair of "login": "email" as shown below.

          {
	"login": "email",
	"firstName": "firstName",
	"lastName": "lastName",
	"email": "email",
	"groups": "groups"
}

        4. The sso-mappings.json file only needs to contain key:value pairs for the attribute statement tags that are different from what EnterWorks is searching for. For example, if the IDP is using the "email" tag as the login value but the rest of the attribute statements are tagged as expected, the sso-mappings.json file could only have the key:value pair for "login": "email" as shown below.

          {
	"login": "email"
}

        5. The create-<service-name>-service.cmd scripts should exist in the following folder. If they do not, create the create-service scripts. 

          <drive>:\Enterworks\enable2020\services\install

        6. In the create-enable-web-server-service.cmd file, set the ssoMappingConfig parameter to indicate the location of the sso-mapping.json file: 

          -ssoMappingConfig=<drive>:\Enterworks\enable2020\services\sso-mappings\

      • EnterWorks obtains the signing certificate in the following manner:

        1. EnterWorks will look for the file: 

          <drive>:\Enterworks\certs\token_cert.pem

          If it finds the file, it will pull the certificate out of it.

        2. EnterWorks will then look at the metadata. If a signing certificate is provided in the metadata, it will pull the certificate from the metadata and use it. If EnterWorks already has pulled a certificate from token_certs.pem file, EnterWorks will use the certificate it found in the metadata.

        To configure EnterWorks to use the signing certificate, in the create-enable-web-server-service.cmd file:

        1. Uncomment out the setting: samlSigningSPKeysPath.

        2. To tell EnterWorks to look for the token_cert.pem file, set the samlSigningSPKeysPath parameter to indicate the location of the token_cert.pem certificate file: 

          -samlSigningSPKeysPath=<drive>:\Enterworks\certs\saml

    8. Move to the directory:

      <install-drive>:\Enterworks\enable2020\services\install\

      and run the following scripts as an Administrator:

      create-enable-web-server-service.cmd
create-enable-api-go-service.cmd
create-enable-webcm-broker-service.cmd

    9. Restart all services.

EnterWorks is now configured for SSO using SAML.