erwin Evolve 2023.1.0 - User Guide

Configure SAML2 Authentication and SSO

Authentication and SAML 2

SAML2 is a commonly used, standardized approach of securing logon to web based systems, where the authentication is delegated to another system or third party. The following section will describe both the pre-requisites and the Evolve configuration required to enable SAML2 as your authentication provider. It is largely assumed that you are knowledgeable about the configuration of your SAML2 authority.

The instructions below explain how to configure your Evolve Server so that you can use SAML2 as an authentication method to access your sites.

Pre-requisites for SAML2 authentication:

Firstly it is a requirement to have a SAML2 authentication provider. This is the service that will provide both authentication responses and offer users a means to logon. One common example is Microsoft Active Directory, which can be configured natively, or through SAML2.

The authentication provider will be able to supply the following:

• Either a SAML2 metadata file, or a URL that links to a SAML2 metadata file

• An EntityID – this is the URL that points to the authentication provider (this may often be found in the SAML2 metadata file)

The Evolve web site will need to be operated over a Secure HTTP protocol (HTTPS). This will mean you are also in possession of:

• An SSL certificate to ensure both end-user clients and the authentication provider can trust Evolve.

Preparing the SSL certificate:

Since Evolve needs to be able to communicate securely with the SAML2 Auth provider, it will need to use an SSL certificate. The certificate which is validating the Evolve site (SSL domain certificate) can be used, however it is necessary to change the password on the certificate to make is usable by Evolve. In order to achieve this:

1. If you have not done so already, import the domain SSL certificate into Windows

2. Export the certificate to a new *.PFX file

3. Use the following password to secure the certificate : 
   
   LQMrnsuLpVAZ9ePd
   
   Note that it is not currently possible to choose an alternative password. However the certificate is stored securely on your server, and is not made available externally, so this should not pose a concern.

4. Save the filename: CasewiseAuth.pfx
   
   in the folder: c:\Casewise\Evolve\Site\bin

To configure SAML2 on your Evolve server:

1. Run Evolve Designer.

2. On the Evolve Designer Models launcher dialog, click the Server Configuration button.

The Server Configuration dialog opens.

3. Configure the settings according to the table below:

Authentication

4. Click Save to save your configuration.

At this point it will no longer be possible to logon to Evolve, as the final steps are to configure the permissions based on Claims configured on the Authentication Server, and their mapping to groups on the Evolve server.

To configure Groups and Roles on your Evolve server:

Groups and Roles for SAML2 are configured in exactly the same way as they are for Active Directory. Take a look at this to see how they work. You will find this detail in the "AD Mapping" details of the "Site Level Settings" - "Deployment Node Settings". 

Further instructions for specific Identity Providers:

See here for help on Integrating with Okta Identity Provider

Configuring SAML2 Authentication and SSO with Google Suite

If your organization uses Google (gsuite.google.com) as an Identity provider, these instructions will help you to configure Single Sign On, between Evolve and your IdP.

Create new Application in G Suite

1. Go to the homepage of your G Suite Admin Console.

Choose Apps (top right icon in below screenshot).

2. Choose SAML Apps (top right icon in below screenshot).

3. Press the Yellow (+) button at the bottom right of the window (see below).

This will create a new App in your G Suite.

4. Choose "SETUP MY OWN CUSTOM APP" at the bottom of the list (see below).

SAML Meta Data - Part 1

1. Download the IDP metadata file, using the "DOWNLOAD" button in Option 2 (see below).

Select this link and download it to your evolve server. (Saving the File as an XML file).

2. Press NEXT.

Configure the Application

Provide App name, Description and provide a Picture to represent it.

Then press NEXT.

1. Configure the Settings.

Set the ACS URL to:

https://{your-domain}/evolve/AuthServices/Acs

e.g. https://evolvemain.host.casewise.com/evolve/AuthServices/Acs

Set the Entity ID to:

https://{your-domain}/evolve/AuthServices

e.g. https://evolvemain.host.casewise.com/evolve/AuthServices

Set the Start URL to:

https://{your-domain}/evolve/

e.g. https://evolvemain.host.casewise.com/evolve/

Set Name ID Format to:

EMAIL

2. Press NEXT.

3. Set the Attributes.

Using the "ADD NEW MAPPING" button add attribute mappings for the following 4 attributes:

Add 4 new Attributes

Application Attribute: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress

Category: Basic Information

User Field: Primary Email

Application Attribute: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname

Category: Basic Information

User Field: Last Name

Application Attribute: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname

Category: Basic Information

User Field: First Name

Application Attribute: http://schemas.xmlsoap.org/claims/Group

Category: Employee Details

User Field: Department

Accept all other defaults

SAML Meta Data - Part 2

1. Taking the file you downloaded in SAML Meta Data (Part 1)

2. Place your metadata file on the Evolve server in the following location “C:\Casewise\Evolve\Site” (ensure it’s an XML file)

3. Now in Evolve Designer under server Configuration/Authentication tab

i. Select Authentication mode to “Saml2”

ii. SAML2 Entity id = taken from your Metadata xml File

iii. SAML2 Meta url = “~/NAME OF YOU METADATA FILE.xml”

e.g. ~/GoogleIDPMetadata-erwingsuite.net.xml

4. Evolve’s url = YOUR EVOLVE URL

5. Save and Configure IIS.

Publishing Evolve Site

1. For each model you publish under the deployment of the model you must specify the Department names in the “AD Group” Fields this must Match the G Suite Department Names you have set up along with the Values you specified in the attribute statement.

2. Once set you must save. Then deploy the full site.

Configuring SAML2 Authentication and SSO with Okta

Configuring SAML2 Authentication and SSO with Okta

If your organization uses Okta (www.okta.com) as an Identity provider, these instructions will help you to configure Single Sign On, between Evolve and your IdP. 

Create new Application in Okta

1. Select Create new App

2. Platform = Web

3. Sign on Method = SAML2.0

4. Click create

Configure the Application

1. Provide app name

2. General

1. Single Sign on URL: Your Evolve URL followed by “/AuthServices/Acs”

   Example https://EvolveTest/evolve/AuthServices/Acs

2. Ensure “Use this for Recipient URL and Destination UR” is checked

3. Audience URI (SP Entity ID): Your Evolve URL followed by “/AuthServices”

   Example https://EvolveTest/evolve/AuthServices

4. Name ID format: EmailAddress

5. Application username: Email

3. ATTRIBUTE STATEMENTS

Add 4 new Attributes

Name: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress

Name Format: URI Reference

Value: user.emailaddress

Name: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname

Name Format: URI Reference

Value: user.surname

Name: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname

Name Format: URI Reference

Value: user.givenname

Name: http://schemas.xmlsoap.org/claims/Group

Name Format: URI Reference

Value: isMemberOfGroupName("Evolve Contributor") ? "Evolve Contributor" : (isMemberOfGroupName("Evolve Social") ? "Evolve Social" : "NO")

Accept all other defaults

SAML Meta Data

1. In the Okta Admin Page under “Sign On” you will find the “Identity Provider metadata” link to download you’re the metadata.

Select this link and download it to your evolve server. (Saving the File as a XML file)

2. Place your metadata file on the Evolve server in the following location “C:\Casewise\Evolve\Site” (ensure it’s a XML file)

3. Now in Evolve Designer under server Configuration/Authentication tab

1. Select Authentication mode to “Saml2”

2. SAML2 Entity id = taken from your Metadata xml File

3. SAML2 Meta url = “~/NAME OF YOU METADATA FILE.xml”

4. Evolve’s url = YOUR EVOLVE URL

   

4. Save and Configure IIS

Publishing Evolve Site

1. For each model you publish under the deployment of the model you must specify the Okta group names in the “AD Group” Fields this must Match the Okta group Names you have set up along with the Values you specified in the attribute statement

2. Once set you must save. Then deploy the full site.

Configuring SAML2 Authentication and SSO in Azure AD

Prerequisites for SAML2 authentication:

If you have Evolve configured for HTTPS, you need to create three URLs in Azure:

• Mail URL: https://YOURURL/evolve/

• Entity ID URL: https://YOURURL/evolve/AuthServices

• Assertion Consumer Service (ACS) URL: https://YOURURL/evolve/AuthServices/Acs

Setting up Single sign-on in Azure:

1. In Azure's Enterprise application, select Single sign-on and SAML.

2. Enter your Entity ID and Assertion Consumer Service (ACS) URLs in the "Basic SAML Configuration" below.

Now you can change your Attributes and Claims. Mail, Given name, Surname, and Principal name are already set up.

To change Attributes and Claims:

1. Click Add new claims.

2. Under Group Claims, click Groups assigned to the application to limit the list of AD groups assigned to this Azure application.

3. Under Advanced option, select Customize the name of the group claim check box.

4. In the Name box, enter the name of the group claim. For example, Group.

5. In the Namespace box, enter the namespace. For example, http://schemas.xmlsoap.org/claims.

6. Click Save.

Federation Metadata XML is now available for download. Copy the downloaded XML to Evolve Web Server (C:\Casewise\Evolve\Site).

To configure Evolve and Evolve Model:

1. Start Evolve Designer.

2. On the Evolve Designer Models launcher dialog box, click the Configure Evolve Server button.

3. Under Authentication, click Authentication Mode drop down and select saml2.

4. In the SAML2 Entity Id box, enter the entity id.

5. In the SAML2 MetaUrl box, enter the meta url.

6. In the The Evolve Web Platform url box, enter the evolve url.

7. Click Save.

8. Click Configure IIS and perform full deployment.

To configure Model in Evolve Designer:

1. Start Evolve Designer.

2. Click a model. For example, EA Foundation – Sample Model.

3. Click Site.

4. Expand Site > Deployment > evolve-with-sam.

5. Click EASAMP14.

6. Under AD Mapping, enter AD group ID.

7. Click Save.

8. Click Dynamic Site.

   You can now test and access the site https://YOURURL/evolve/ by following the above steps (as long as you are granted access within Azure AD). When you access the evolve site, the Azure Auth provider will redirect you to Evolve after authentication.

Authentication and Active Directory

Configure Active Directory Authentication and SSO

Active Directory is a commonly used Microsoft standard approach to securing logon to Windows and Web systems. The following section will describe both the pre-requisites and the Evolve configuration required to enable Active Directory (AD) as your authentication provider. It is largely assumed that you are knowledgeable about the configuration of Active Directory.

The instructions below explain how to configure your Evolve Server so that you can use AD as an authentication method to access your sites.

Pre-requisites for AD authentication:

Before proceeding with the connection, there are some preparatory steps you need to complete, in Modeler, Evolve and in the client’s Active Directory configuration in order for the synchronisation to work.

First let's setup the CW Roles:

1. Launch Model Explorer and create two (2) distinct objects within the CW Role object.

2. 
   You can create as many roles as you want, but make sure that two of them can be used as generic roles for all incoming users.  For example, you can create a role named “Read-Only Users” (which will ultimately contain all Social Users) and another called “Administrators” (or “Contributors”) (which will ultimately contain all Normal Users).

3. Connecting Roles to CW Views.

At this point, you should connect those default roles to the appropriate views to define which pages each user group will be able to access once logged in.  To do this please refer to the appropriate section of the Evolve user guide (here).

If you choose not to connect any views to the roles, then both roles will be able to view the exact same pages.

Next configure the Client Active Directory:

1. Creating new AD Groups:
   You need to arrange with your customer’s system administrator to create two (2) distinct groups within their Active Directory. They can choose to name them anything they want, but should keep those names distinct and recognizable so they can then be connected to Evolve.

2. Adding users to the AD Groups:

The client system administrator should then, in conjunction with your main contact within the client, ensure that the appropriate number of users is added in each group.

 Configure the Active Directory Connection:

1. Change Authentication Mode:
   Launch Evolve Designer (in Administrator mode) and choose "Server Configuration". Navigate to the "Authentication" tab. In the Authentication Mode drop-down list, switch the default value (CwAuthentication) to ActiveDirectoryAuthentication.

   Configuring the AD Connection Path:

1. If you have not done so already, import the domain SSL certificate into Windows

2. Export the certificate to a new *.PFX file

3. Use the following password to secure the certificate : 
   LQMrnsuLpVAZ9ePd
   Note that it is not currently possible to choose an alternative password. However the certificate is stored securely on your server, and is not made available externally, so this should not pose a concern.

4. Save the filename: CasewiseAuth.pfx
   in the folder: c:\Casewise\Evolve\Site\bin 

To configure SAML2 on your Evolve server:

1. Run Evolve Designer.

2. On the Evolve Designer Models launcher dialog, click the Server Configuration button.

The Server Configuration dialog opens.

3. Configure the settings according to the table below:

Authentication

4. Click Save to save your configuration.

At this point it will no longer be possible to logon to Evolve, as the final steps are to configure the permissions based on Claims configured on the Authentication Server, and their mapping to groups on the Evolve server.

To configure Groups and Roles on your Evolve server:

Groups and Roles for SAML2 are configured in exactly the same way as they are for Active Directory. Take a look at this to see how they work. You will find this detail in the "AD Mapping" details of the "Site Level Settings" - "Deployment Node Settings".

 Further instructions for specific Identity Providers:

See here for help on Integrating with Okta Identity Provider.