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 and the Classic UI 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:

Obtain Metadata
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-server-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.
    
    EnterWorks uses the following attribute statements:
    
    login
    
    firstName
    
    lastName
    
    email
    
    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 username that will be displayed in the UI.
    
    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.
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
4. Set the configuration parameters for enable-web-server-service
  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.
  7. Use the script.
5. Set the configuration parameters for enable-api-go-service
  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.
  6. Use the script.
6. Set the configuration parameters for enable-webcm-broker-service
  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.
  4. Use the script.
7. Additional SSO Configuration Options:
  - To map attribute statements tags that are different than what EnterWorks expects, see Configure SSO: Map Attribute Statement Tags.
  - To configure SSO to use a token signing certificate, see Configure SSO: Use a Token Signing Certificate.
8. Restart all services.

EnterWorks is now configured for SSO using SAML.