The application supports web browser Single Sign On (SSO) using Security Assertion Markup Language (SAML). SAML is an XML-based open standard data format for exchanging authentication and authorization between parties, in particular, between an Identity Provider (IdP) and a Service Provider (SP). When using SAML, there is no need for user synchronization.
Before implementing SSO using SAML, there must be at least one user with system administrator privileges that matches an account on the domain. This user must have the same username as the one on the Server. This will allow access to the administrative functions. This is necessary to ensure an administrator can access uPerform after implementing SAML authentication. For more information, refer to Adding a User. Only one SAML User Information Source (UIS) can exist on the Server at any given time.
Upon escalation of roles for a user to a project author, administrator, or system administrator, the user will be required to log into the Server website prior to being able to authenticate via the Editor. We recommend that the user closes the browser, deletes cookies, and reauthenticates to the Server.
Verify the following items before configuring SAML Authentication:
- Ensure that SAML 2.0 is supported by the Identity Provider you are using
- Ensure that SHA-256 hash is supported by the Identity Provider
- Ensure that at least one X.509 certificate is registered within the Identity Provider
- Obtain the Identity Provider SAML Endpoint URL
- Ensure that there are SAML attributes in the Identity Provider that map to the following:
- User ID
- Unique Identifier or GUID
- Email Address
- First Name
- Last Name
- Identify SAML filter conditions that designate who does and does not get access to the uPerform Server.
- Register uPerform as a Service Provider within your IdP based on the documentation for your IdP.
|
NOTE:
|
In order to assist in registering the application as a Service Provider with your IdP, you can save SAML Metadata to be imported by your IdP. Refer to Saving SAML Metadata.
|
Configuring SAML on a New Server
It is necessary to create a SAML User information Source to map user details from an Identity Provider (IdP) to the application. Before delivering the identity assertion to the Service Provider (SP), the IdP may request some information, such as a user name and password, in order to authenticate the principal.
|
NOTE:
|
Before configuring SAML, you must register uPerform as a Service Provider within your IdP based on the documentation for your IdP.
|
|
NOTE:
|
Only one SAML UIS can be created and exist at a time on the same Server.
|
- Login to the Server as an administrator.
- Click Administration on the left menu.
- Click Users, Roles, and Groups in the Administration area.
- Click User Information Sources in the Users, Roles, and Groups area.
- Click Add User Source on the left menu.
- Complete the following fields:
|
Field
|
Description
|
|
Name
|
Title for the SAML User Information Source.
|
|
Description
|
Description of the SAML User Information Source.
|
|
Source
|
Select SAML Identity Provider from the drop-down list.
|
- Click Next.
- Complete the following fields:
|
Field
|
Description
|
|
Identity Provider SAML Endpoint
|
Your company’s identity provider (IdP) URL, which is a trusted provider that enables you to use single sign-on to access other websites.
For example:
ADFS: https://adfs.mycompany.com/adfs/ls
CA Siteminder: https://agfed.mycompany.com/affwebservices/public/saml2sso?SPID=[service provider URL]
Ping: https://fsso.mycompany.com/idp/startSSO.ping
OKTA: https://mycompany.okta.com/app/.../.../sso/saml
|
|
Identity Provider Error URL
|
You can enter a URL to redirect your users to an error page if they are unable to authenticate to the application using the IdP. The Server must have access to this page. If no unique URL is entered, then users will be directed to the default SAML error page.
|
|
Identity Provider Public Certificate
|
Certificate text for the x509 certificate registered within the IDP. You will need to remove the header and footer text.
|
|
Field Mapping: User ID
|
The name of the claim provided by the IdP which contains the User ID value to be used.
|
|
Field Mapping: Unique Identifier
|
The name of the claim provided by the IdP which contains the Unique Identifier value to be used. This value should remain unchanged for a specific user.
|
|
Field Mapping: Email Address
|
The name of the claim provided by the IdP which contains the Email address value of the user.
|
|
Field Mapping: First Name
|
The name of the claim provided by the IdP which contains the First Name value of the user.
|
|
Field Mapping: Last Name
|
The name of the claim provided by the IdP which contains the Last Name value of the user.
|
- Click OK. The SAML UIS summary will appear.
Saving SAML Metadata
SAML SSO includes support for a metadata specification that describes the various supported elements. The application creates this SAML metadata for importing configuration information into your Identity Provider (IdP). Please refer to the help documentation for your IdP for instructions on how to import the SAML metadata.
- Login to the Server as an administrator.
- Click Administration on the left menu.
- Click Users, Roles, and Groups in the Administration area.
- Click User Information Sources in the Users, Roles, and Groups area.
- Click the appropriate SAML User Information Source.
- Click Save SAML Metadata.
|
NOTE:
|
Depending on your browser settings, the file may open in the browser window. If this occurs, right-click Save SAML Metadata and select the Save as... option.
|
|
NOTE:
|
The Server can be configured with your IdP manually or by using the SAML metadata option.
|
Signing SAML Metadata
Some SAML Identity Providers support or require that the SAML Metadata be signed. If you have a private key and X509 Certificate, you can have the application sign the SAML Metadata that it generates. The following are requirements for signing the SAML metadata:
- Add the private key and certificate to a java keystore named [Install_Location]\java\jre\bin\samlkeystore.jks
- Open a command prompt on the server host machine.
- Navigate to the [Install_Location]\java\jre\bin\ folder.
- Run the following command: keytool -importkeystore -destkeystore samlkeystore.jks -srckeystore mycertificate.p12 -srcstoretype pkcs12 -alias saml
- Complete the following fields:
|
Field
|
Description
|
|
key alias
|
Set as saml.
|
|
keystore password
|
Set to changeit.
|
- Ensure the Sign SAML Metadata XML option is selected in the Global Settings.
- Save the signed SAML Metadata.
Creating a SAML Filter
Filters define which users have access and which content they have access to as an end user. Any users not associated with a filter will be identified as an anonymous user, if anonymous access is enabled. Anonymous users will not be able to take advantage of any named-user functionality. Users can belong to multiple filters as needed to be granted access to the proper content.
When creating a SAML filter all the conditions act as "and" when completed. This means that a user must meet all requirements of the filter to be granted access. When there are multiple filters, these filters act as "or" and the user must meet all conditions of one filter. If a user cannot be matched with a filter and the Server access policy settings do not allow for anonymous single-sign-on, the user will receive an error message. These settings can be reviewed in the Access Policy area in the Global Settings. Refer to Configuring Global Settings in the Administration manual. If the Allow Anonymous Access with Single Sign-On option is selected, all users can access all projects.
- Click Administration on the left menu.
- Click Users, Roles, and Groups in the Administration area.
- Click User Information Sources in the Users, Roles, and Groups area.
- Click the appropriate SAML User Information Source.
- Click Add Filter on the left menu.
- Complete the following fields:
|
Field
|
Description
|
|
Name
|
Title for the SAML filter.
|
|
Description
|
Description of the SAML filter.
|
|
Claim Type
|
Enter the name of the claim to check.
|
|
Condition
|
Select Contains or Equals from the drop-down list to define the condition for the Claim Type.
- Equals indicates that the term must exactly match the expected value.
- Contains indicates the claim can contain additional text, but it must include the expected value.
|
|
Value
|
Enter a value for the claim type.
|
|
NOTE:
|
SAML filter values are case sensitive. The claim name must be ALL CAPS, while the claim's value is case sensitive.
|
- Click Add to the right of Value.
|
NOTE:
|
Repeat steps 6-7 to add additional conditions to the filter.
|
|
NOTE:
|
If you want to delete a filter, click Delete to the right of the filter.
|
Assigning Filters to a Group
After adding users it is necessary to assign them to a group. Users are only granted access if they match a filter and that filter belongs to a group. Refer to Creating and Updating Groups.
Granting author and administrator rights still needs to be done manually.
Configuring SAML Authentication
- Locate the ConfigurationWizard.exe file on the Server in the [Install Location]\Collaboration\uPerform\ms folder.
- Double-click the ConfigurationWizard.exe file. If prompted, click to run.
- Select the Authentication Type radio button.
- Click Start.
- Select SSO using SAML from the Authentication Type drop-down list.
- Click Configure.
|
NOTE:
|
This process may take several minutes while the Server is being checked verify that SAML UIS has been setup before SAML conversion begins. This will prevent the Server from being improperly converted to SAML. If you receive an error that states: "A SAML User Information Source does not currently exist on the Server. Please create a SAML UIS to enable SAML authentication," this means that no SAML UIS exists on the Server. Repeat the steps listed under Configuring SAML on a New Server.
|
- Click Yes to make additional changes or configurations or click No to close the confirmation window.
|
NOTE:
|
After configuration is complete, when a user logs into the Server, he/she will be granted immediate access.
|
Verifying SAML Configuration
Verify that the SAML configuration is complete.
- Login to the Server.
- Click Administration on the left menu.
- Click Users, Roles, and Groups in the Administration area.
- Click User Information Sources in the Users, Roles, and Groups area. The SAML UIS Summary will appear.
|
NOTE:
|
The Delete User Source option is grayed out. A SAML UIS can only be deleted when SAML SSO is not configured.
|
SAML and Editor Login Information
Since the Editor does not use SAML authentication, authors still will need to login through the Editor using an application-specific password. Authors can configure their password on the "My Account" page. This password is ONLY used to connect through the Editor.
When users are first granted author or higher access, they will need to log onto the Server, change their password, and then they can login through the Editor. They do not need to log out of the Server, nor do they need to change their password in the IdP, they just need to configure a password in uPerform they can use to connect via the Editor.
Deleting a SAML User Information Source
|
NOTE:
|
After deleting a SAML UIS, users will need to have their accounts recreated within the application since their accounts cannot be mapped.
|
|
NOTE:
|
When deleting an UIS, all users attached to that UIS will be deleted as well (unless said user is associated with another UIS).
|
- Locate the ConfigurationWizard.exe file in the [Install Location]\Collaboration\uPerform\ms folder.
- Double-click the ConfigurationWizard.exe file.
- If prompted, click Yes to run.
- Select the Authentication Type radio button.
- Click Start.
- Select Basic Authentication (or another authentication type) from the Authentication Type drop-down list.
- Click Configure.
|
NOTE:
|
This process may take several minutes.
|
- Click Yes to make additional changes or configurations. Click No to close the window.
- Login to the Server.
- Click Administration on the left menu.
- Click Users, Roles, and Groups in the Administration area.
- Click User Information Sources in the Users, Roles, and Groups area. The SAML UIS Summary will appear.
- Click the SAML UIS to delete.
- Click Delete User Source on the left menu.
- Click OK.
Additional SAML Options
ANCILE uPerform's default SAML behavior can be changed by using advanced settings. For example, by default, uPerform requires a NameIDFormat policy of "persistent." This can be changed by modifying the "jaas.conf.saml" configuration file. ANCILE recommends working your organization's Authentication team when changing advanced settings.
|
Field
|
Description
|
|
NameID
|
If required, specify the NameIDFormat policy required by your SAML IDP.
|
|
SAMLVersion
|
If specifying a NameID format that is not within the SAML 2.0 specification, include the appropriate version here.
|
|
authComparison
|
Specify the minimum authentication comparison level for the SAML IDP.
|
|
authContext
|
If specifying an authComparison, you must also specify the acceptable authentication context.
|
Configuring the SAML Session Timeout Value
For Identity providers (IdP) that do not specify the SessionNotOnOrAfter assertion value, the default session timeout is set to a value of 2 hours. When this time has expired, the user must be re-authenticated with the IdP. To change this default value, configure your IdP to provide a value in the assertion, or modify the ANCILE.uPerform.ServerConfiguration.DLL.config file to specify a different default value.
- Navigate to the [Install Location]\folder.
- Open the ANCILE.uPerform.ServerConfiguration.DLL.config file using a text editor.
- Find the add key="SAMLSessionDuration" value=7200.
- Set the value (in seconds) to the desired value. For example, 24 hours would be 24 * 60 (minutes) * 60 (seconds) = 86400.
- Restart both the ANCILE Monitoring Service and the Vignette Collaboration Service.