Reveal Review Publication

Assignment Service

Assignment Status Service

Bulk Tag

Document Loader

Export Service

Index Batch Service

Index Server Service

Production Server Service

Search Service

Update the RevealPublish/Web.config file to add an SSO section within the appSettings area:

<!-- OAuthUserAccessCheckInterval is in seconds -->

<add key="OAuthCheckUserAccessInterval" value="180" />

<add key="LoginLandingPageLocation" value="/AuthorizationPages/ProjectSelect.aspx" />

<add key="LoginNotAuthorizedPageLocation" value=" /AuthorizationPages/LoginNotAuthorized.aspx" />

<add key="OAuthClientId" value="RevealWeb" />

<add key="OAuthRealm" value="000000" />

<add key="OAuthAuthorityBase" value="https://auth-us-east-1.revealdata.com/auth/realms" />

<!-- dev values -->

<!--<add key="OAuthClientId" value="RevealWebDev" />

<add key="OAuthRealm" value="Reveal Corp" />

<add key="OAuthAuthorityBase" value="http://10.0.4.124:8080/auth/realms" />-->

Editing the OAuthClientId, OAuthRealm, OAuthAuthorityBase to have the appropriate values based on the region/MSA.

Add the following to the web.config at the end below the DevExpress section:

<runtime>

<assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">

<dependentAssembly>

<assemblyIdentity name="Newtonsoft.Json" publicKeyToken="30 ad4fe6b2a6aeed" culture="neutral" />

<bindingRedirect oldVersion="0.0.0.0-12.0.0.0" newVersion ="12.0.0.0" />

</dependentAssembly>

<dependentAssembly>

<assemblyIdentity name="Microsoft.IdentityModel.Logging" publicKeyToken="31bf3856ad364e35" culture="neutral" />

<bindingRedirect oldVersion="0.0.0.0-6.8.0.0" newVersion="6.8.0.0" />

</dependentAssembly>

<dependentAssembly>

<assemblyIdentity name="Microsoft.IdentityModel.Tokens"

publicKeyToken="31bf3856ad364e35" culture="neutral" />

<bindingRedirect oldVersion="0.0.0.0-6.8.0.0" newVersion="6.8.0.0" />

</dependentAssembly>

<dependentAssembly>

<assemblyIdentity name="Microsoft.IdentityModel.

JsonWebTokens" publicKeyToken="31bf3856ad364e35" culture="neutral" />

<bindingRedirect oldVersion="0.0.0.0-6.8.0.0" newVersion="6.8.0.0" />

</dependentAssembly>

<dependentAssembly>

<assemblyIdentity name="Microsoft.IdentityModel.Protocols"

publicKeyToken="31bf3856ad364e35" culture="neutral" />

<bindingRedirect oldVersion="0.0.0.0-6.8.0.0" newVersion="6.8.0.0" />

</dependentAssembly>

<dependentAssembly>

<assemblyIdentity name="Microsoft.IdentityModel.Protocols.

OpenIdConnect" publicKeyToken="31bf3856ad364e35" culture="neutral" />

<bindingRedirect oldVersion="0.0.0.0-6.8.0.0" newVersion="6.8.0.0" />

</dependentAssembly>

<dependentAssembly>

<assemblyIdentity name="System.IdentityModel.Tokens.Jwt"

publicKeyToken="31bf3856ad364e35" culture="neutral" />

<bindingRedirect oldVersion="0.0.0.0-6.8.0.0" newVersion="6.8.0.0" />

</dependentAssembly>

</assemblyBinding>

</runtime>

Add targetFramework="4.8" to the httpRuntime section of both Web.config files. The line should read like:

<httpRuntime maxUrlLength="8192" maxQueryStringLength="20480" maxRequestLength="2097151" requestValidationMode="2.0" executionTimeout="1800" targetFramework="4.8" />

Verifies users have unique usernames and email addresses, and that email address is populated.

If any are not valid it stops and writes out an error.

Validates that the tool can connect to KC using the currently-configured UMDB system settings.

Run any Reveal-provided MSSQL schema/data upgrade scripts.

Run the SSO_UserUpgrade_Application upgrade tool in commit mode which does the following:

Tool is run as such:

.\SSO_UserUpgrade_Application.exe -s <Server Address> -c < UMDB> --commit

For example:

.\SSO_UserUpgrade_Application.exe -s ’127.0.0.1’ -c ’ User_Management’ --commit

Run any updates generated by Redgate.

Run the SSO_UserDataPurge_Run_After_User_Upgrade.sql script after the upgrade tool finishes and you’re comfortable with the results.

Assuming that tool ran without error, Review is now upgraded.

Each MSA will have its own realm named after its MSA number.

Configuration of KC will be limited to Reveal administrators. Clients will not be able to make edits to KC via the console.

Each region will have its own instance of KC.

Run the realm_instantiator tool with the following options:

The realm_instantiator tool is run similar to the below:

realm_instantiator.exe --msa_number ’MSA_NUMBER’ --msa_name ’ MSA_NAME’ --review_url ’URL’ --output ’C:\Some\Path\Here’ --auth_url ’KC URL’ --saas

For example:

realm_instantiator.exe --msa_number ’120000’ --msa_name ’Reveal Production Staging’ --review_url ’devstaging.revealdata.com’ -­output ’C:\Users\Administrator\Desktop’ --auth_url ’auth-us-east-1.revealdata.com’ –saas

This will write the following into your output directory:

::msa number::-review-update.sql This file will contain a list of SQL updates to run against review’s user management database. It will pre-generate config entries.

::msa number::-realm-importable.json This will be the file you use in KC to create your new realm.

As an administrator log into KC’s console interface.

Under the realms drop-down click Add Realm.

Click on Select File next to Import and select the ::msa_number::-realm-importable.json file above.

See Keycloak Server Setup (Domain mode/SaaS) section to set up KC servers initially.

Set up DNS record to point to HAProxies in the region with an appropriate naming scheme. For us-east-1 this name will be:

auth.us-east-1.revealdata.com

Create HAProxy Records:

...

acl auth-us-east-1 hdr(host) -i auth-us-east-1.revealdata.com

acl auth-us-east-1-protected path -i /auth

acl auth-us-east-1-protected path -i /auth/

acl auth-us-east-1-protected path -i -m sub /console/

...

use_backend auth-us-east-1 if auth-us-east-1 auth-us-east-1-

protected { src 10.0.0.0/16 }

use_backend auth-us-east-1 if auth-us-east-1 !auth-us-east-1-

protected

...

# auth.us-east-1.revealdata.com

backend auth-us-east-1

balance first

mode http

server node1 10.0.4.254:443 ssl verify none check

server node2 10.0.4.148:443 ssl verify none check

...

Create EC2 servers with AWS Linux 2.

Change hostname appropriately and install java:

hostnamectl set-hostname kc-master-0

yum install java-1.8.0-openjdk

Reboot.

Run realmjoin (see realmjoin.sh in scripts section).

Reboot.

Run retrofit.

wget https://revealdata-public.s3.amazonaws.com/linux_retrofit.tar.gz

Reboot.

Download keycloak distro:

cd /opt/

curl -XGET https://revealdata-software-public.s3.amazonaws.com/keycloak-11.0.3.tar.gz | tar -xvzf -

mv keycloak-11.0.3 keycloak

Create external managed database using Aurora w/postgresql compat­ibility here.

While setting up VPC and similar items, make sure to give Linux Admin access to DB via security group. Then tunnel thru the Linux admin to talk to the DB.

For postgres, run the following against the server:

create database keycloak with encoding ’UTF8’;

Go to this site and grab the newest JDBC driver. Here version 42.2.18:

https://jdbc.postgresql.org/download.html

Run the following:

mkdir -p /opt/keycloak/modules/system/layers/keycloak/org/

postgresql/main

cd /opt/keycloak/modules/system/layers/keycloak/org/postgresql/main

wget https://jdbc.postgresql.org/download/postgresql-42.2.18.jar

Follow directions here:

https://www.keycloak.org/docs/latest/server_installation/#_database

Create module.xml file with the following content:

<?xml version="1.0" ?>

<module xmlns="urn:jboss:module:1.3" name="org.postgresql">

<resources>

<resource-root path="postgresql-42.2.18.jar"/>

</resources>

<dependencies>

<module name="javax.api"/>

<module name="javax.transaction.api"/>

</dependencies>

</module>

Edit this file:

/opt/keycloak/domain/configuration/domain.xml

MAKE SURE THAT ALL EDITS ARE IN THE auth-server-clustered SECTION.

Add the postgresql driver in. Content should look like:

<drivers>

<driver name="postgresql" module="org.postgresql"> <xa-datasource-class>org.postgresql.xa.PGXADataSource </xa-datasource-class>

</driver>

<driver name="h2" module="com.h2database.h2"> <xa-datasource-class>org.h2.jdbcx.JdbcDataSource</xa-datasource-class>

</driver> </drivers>

Now, in the same file edit the KeycloakDS datasource:

<datasource jndi-name="java:jboss/datasources/KeycloakDS"

pool-name="KeycloakDS" enabled="true" use-java-context="true">

<connection-url>jdbc:postgresql://revealdata-keycloak-1a-001.cidxb3vnerlr.us-east-1.rds.amazonaws.com/keycloak

</connection-url>

<driver>postgresql</driver>

<pool>

<max-pool-size>20</max-pool-size>

</pool>

<security>

<user-name>USERHERE</user-name>

<password>PASSHERE</password>

</security>

</datasource>

Search for socket-binding-groups and alter the http and https to stan­dard ports, making sure to replace all instances of these (there are three including the load balancer):

<socket-binding name="http" port="${jboss.http.port :80}"/>

<socket-binding name="https" port="${jboss.https.port :443}"/>

In the same directory edit the host-master.xml.

Comment out the load-balancer server line.

Change the socket-bindings port-offset to 0. We want these servers running on standard ports.

Replace all instances of 127.0.0.1 with 0.0.0.0.

Run the following:

mkdir -p /opt/keycloak/domain/servers/server-one/configuration

cd /opt/keycloak

bin/add-user-keycloak.sh --sc domain/servers/server-one/configuration -r master -u revealadmin

/opt/keycloak/bin/domain.sh --host-config=host-master.xml -Djboss.node.name=node1 -Djboss.boot.server.log.level=DEBUG -Dkeycloak.profile.feature.upload_scripts=enabled -Dkeycloak.profile.feature.account_api=enabled &

Assuming things are configured correctly, the server should be running. Make sure to check the startup log information and look for errors. They will be printed in red so it should be obvious.

In the same directory edit the host-slave.xml.

Change the socket-bindings port-offset to 0. We want these servers running on standard ports.

Replace all instances of 127.0.0.1 with 0.0.0.0.

Search for jboss.domain.master.address and replace that address with the IP address of the master server.

For every worker, run the following on the master server:

/opt/keycloak/bin/add-user.sh

Follow the instructions here to add a user and configure properly in the worker: https://www.keycloak.org/docs/latest/server_installation/#_clustered-domain-example -- specifically the Setup Slave Connection to Domain Controller sec­tion.

When done, to start up:

cd /opt/keycloak

bin/domain.sh --host-config=host-slave.xml -Dkeycloak.profile. feature.upload_scripts=enabled

Assuming things are configured correctly, the server should be running. Make sure to check the startup log information and look for errors. They will be printed in red so it should be obvious. I’ve also seen yellow warnings be important, so keep an eye out for those as well.

Determine the following items with the client:

Download the following ZIP package onto each of the client’s web servers:

s3://revealdata-software-private-build-repository/Review/Keycloak/ Keycloak-OnPrem-Package.zip

Unzip the package and place under wherever the other Reveal services are installed. Normally we would expect this to be something like:

D:\Reveal\InControl\Keycloak

Install the Java 1.8.0 OpenJDK at this location:

C:\Reveal\InControl\Keycloak\installers\java-1.8.0-openjdk-1.8.0.292-2.b10.dev.redhat.windows.x86_64.msi

Create an empty database on the MSSQL server named keycloak. This database name is arbitrary and if desired can be changed in connection string of the below-described configuration files.

Edit the appropriate configuration file based on the Keycloak installation the client desires:

Domain Mode Keycloak\domain\configuration\domain.xml

Standalone Mode Keycloak\standalone\configuration\standalone-ha.xml

The main thing you want to edit are the connection details for where the database sits and what credentials to use while accessing it. By default you can search for this string to see the data to edit:

jdbc:sqlserver://

That should take you to a line containing a connection string. Edit this to point to the DNS Name, IP, etc. for the MSSQL server that KC will be using. If changing from MSSQL to some other database engine, make sure you also alter driver settings as described in KC’s documentation.

Note that if running in Domain mode there are additional edits to make to the Master and Slave configuration files. The necessary edits are described in Keycloak’s documentation here:

https://www.keycloak.org/docs/latest/server_installation/#_domain-mode

Edit the log location for the configuration file you’re using.

Run the following to install Keycloak as a service:

.\service.bat install /config standalone-ha.xml /name " RevealKeycloak" /display "Reveal Keycloak" /desc " Keycloak Server for Reveal"

This should install a service named Reveal Keycloak. Alter this service to log in as a service user that has administrative access to the keycloak database.

Start the service. At this point assuming no other alterations, the Key-cloak console should be accessible at this URL:

https://localhost:8443/auth/

From here set up a temporary admin user.

On one of the instances, run the realm instantiator as below:

& ’Keycloak\bin\Keycloak Realm Instantiation (On Prem)\Keycloak Realm Instantiation (On Prem)\realm_instantiator_onprem.exe’ --realm_id 000000 --realm_name ’Reveal Albany’ --review_url ’ https://albanyweb.revealdata.com’ --output Keycloak/realm_json/--auth_url ’https://albanyweb-auth.revealdata.com’

Replace the options as is pertinent to your setup. The tool will write output in the location pointed at by the --output option.

That will generate two sets of output at here:

Keycloak/realm_json/000000-realm-importable.json

Keycloak/realm_json/000000-review-update.sql

These will be used for creating a Keycloak realm and for setting system settings in review respectively.

By default, the server will likely be listening on only 127.0.0.1. This can be altered in the configuration file for the mode you’ve set up.

From here follow the normal realm creation steps. In summary, after this the steps are to run SQL in the Review UMDB to link Review into KC properly. Then take the realm-importable.json file and use that to create a realm within Keycloak.

Ensure that you’ve already set up a Keycloak administrator. The following reconfiguration will make KC unavailable from 127.0.0.1.

If it’s already running, turn off Keycloak.

Edit the config file Keycloak¹ and alter the listening ports for HTTP and HTTPS to be non-standard. In other words, search for the following section in this section at the bottom of the config and alter it so the ports are set to 8081 and 8444:

^[1]

<socket-binding-group name="standard-sockets" default-interface=" public" port-offset="${jboss.socket.binding.port-offset:0}"> <socket-binding name="ajp" port="${jboss.ajp.port:8009}"/> <socket-binding name="http" port="${jboss.http.port:8081}"/> <socket-binding name="https" port="${jboss.https.port:8444}"/> <socket-binding name="jgroups-mping" interface="private" multicast-address="${jboss.default.multicast.address:230.0.0.4}" multicast-port="45700"/>

Also edit the following chunk:

<properties>

<property name="frontendUrl" value="${keycloak.frontendUrl:}"/> <property name="forceBackendUrlToFrontendUrl" value="false"/

</properties>

To the following:

<properties>

<property name="frontendUrl" value="https://CLIENT.HOSTNAME.COM:8443/auth"/>

<property name="forceBackendUrlToFrontendUrl" value="true"/

</properties>

Replacing CLIENT.HOSTNAME.COM as before: What this does is force Keycloak to use a specific front-end hostname. This will mean that KC is no longer accessible via any other URL than the front-end configured there. This is mainly because IIS is re-writing the URL to its internal address, so what gets to IIS is CLIENT.HOSTNAME.COM but what hits KC is actually 127.0.0.1. Keycloak uses that hostname within internal scripts, so for it to work properly with external users it must be hardcoded in the config as above.

It is possible that we may be able to configure IIS to properly re-route traffic to make the above unnecessary, however we have not performed that research as of yet.

Start the Keycloak service so it picks up these new ports and settings.

Install the IIS Application Request Routing module: https://www.iis.net/downloads/microsoft/application-request-routing

The general setup for a reverse proxy is shown in this walkthrough:

https://docs.microsoft.com/en-us/iis/extensions/configuring-application-request-routing-arr/creating-a-forward-proxy-using-application-request-routing

We describe the required steps below.

On the IIS server level click into the Application Request Routing Cache page:

Click on Server Proxy Settings:

Check the Enable Proxy box and Apply the change:

Set up a website specific for Keycloak within IIS and give it the web.config shown on page 33.

Edit the web.config to properly represent the hostnames Keycloak expects to listen on. You can do this by replacing CLIENT.HOSTNAME.COM with the external hostname users will use when connecting to KC.

Back in IIS go into the website you created for Keycloak and give it an HTTPS binding on port 8443 with the SSL cert you’re using for Review.

On the website you set up for Keycloak click into the URL Rewrite module:

Click on View Server Variables:

Add two server variables for HTTP_ACCEPT_ENCODING and HTTP_X_ORIGINAL_ACCEPT_ENCODING:

Keycloak should now be accessible via that front-facing CLIENT.HOSTNAME.COM URL.

Figure out a realm that you want to export.

Use KC’s realm export feature to export it into a JSON file.

Open that JSON file and replace the following things:

Remove all groups

Remove all groups associated with any users.

Replace all instances of the realm ID with ::realm_id::

Replace the displayName for the realm with ::realm_name::

Replace all instances of the previous review URL with ::review_url::

So if we were doing prodstaging we’d replace:

prodstaging.revealdata.com

…such that the URLs in the config file should look like:

"redirectUris": [

"https://::review_url:::443/reveal/*"

],

Double-check the users in the export. Ideally you shouldn’t see any non-service account users.

Assuming this realm export JSON was generated from the us-east-1 region’s KC instance, replace all instances of corp from corp.revealdata.com with ::domain::

The current known locations to replace this for are in the customUserSearch-Filter and bindDn within the user federation settings.

Again assuming that this is from us-east-1 replace all instances of the do­main controller’s IP address with the following: ::domain_controller::

Manually review the config file and ensure that nothing else looks partic­ularly specific to the realm that it came from. As we add new things as realm defaults we’ll likely see previously unknown updates to this exported JSON that we should at least eyeball to make sure are good.

Prefix any template AI Keycloak client names with:

TEMPLATE-DO-NOT-USE-

All identity providers.

All user federation providers.

First Name

Last Name

Email Address

Username (optional)

Go to the client's Realm in Keycloak to broker identity providers based on the SAML v2.0 protocol.

To begin configuring an SAML v2.0 provider, go to the Identity Providers left menu item and select SAML v2.0 from the Add Provider drop down list to open the Add Identity Provider page.

Import this configuration data using the xml file that points to the SAML IDP entity descriptor of the external IDP, as provided by the client. This will upload all the required configurations needed and provided by the external IDP.

Click Save.

If you click on an identity provider listed in the Identity Providers page for your realm, you will be brought to the IDPs Settings tab. On this page there is also a Mappers tab. Click on that tab to start mapping your incoming IDP metadata.

There is a Create button on this page that allows you to create a broker mapper. Broker mappers can import SAML attributes or OIDC ID/Access token claims into user attributes and user role mappings.

Select a mapper from the Mapper Type list. Hover over the tooltip to see a description of what the mapper does. The tooltips also describe what configuration information you need to enter.

Default Mappers (Attributes):

Click Save and your new mapper will be added.

Log into Keycloak and identify the client for Review web. This will likely be named RevealWeb:

Click into this client and go to the bottom of the page. Under Authentication Flow Overrides double-check the Browser Flow being used. Note this down for the next step. If this combo box is empty, the name in the next step is Browser.

Navigate into the authentication area and find the authentication flow that Review web is using. Within this flow make sure the Identity Provider Redirector step is set to Alternative:

Browse to your login page for Review. This should redirect you into Keycloak with a long URL:

Copy this URL from your browser into a text editor. It should look something like this:

https://auth-us-east-1.revealdata.com/auth/realms/120000/protocol/ openid-connect/auth?client_id=RevealWeb&response_type=code& scope=openidY.20profileY.20emailY.20rolesY.20groups_scope&state= OpenIdConnect.AuthenticationPropertiesY.3D8iu5YK-6onncmR_8q-NulDSlAZCjC4-YPT75HZQgxzZvlQbj16Ty-O0ZQsXqkqwS7R8DddmeJfGbR1UZ-O0oASg_B5QiW4fd6S8lG2aV8xrAWv4OgSkamiDSYKO0nf1jXysdl_hd20un1lHLm0uApCN92cPo6iXxboKlABbsjuTP0-IEix4n5yoD5ZnQ&response_mode=form_post&nonce=637641312063628199.

NGZhNzU2OWYtNDczZC00ZmUyLTk4YzQtNzVhOTkwYWM0OWY0ZDMxMDIyMzktNDA3Yy00YjE0LTlhYzEtOWM4MzlhMDBj&redirect_uri=httpsY.3AY.2FY.2Fprodstaging.revealdata.comY.3A443Y.2 FRevealY.2FAuthorizationPagesY.2FProjectSelect.aspx&x-client-SKU= ID_NET461&x-client-ver=6.8.0.0

In this URL we want to delete the state and nonce URL parameters, so your URL should now look like this:

https://auth-us-east-1.revealdata.com/auth/realms/120000/protocol/ openidconnect/auth?client_id=RevealWeb&response_type=code&scope=openidY.20profileY.20emailY.20rolesY.20groups_scope&response_mode=form_post&redirect_uri=httpsY.3AY.2FY.2Fprodstaging.revealdata.comY.3A443Y.2FRevealY.2FAuthorizationPagesY.2 FProjectSelect.aspx&x-client-SKU=ID_NET461&x-client-ver=6.8.0.0

Finally, navigate in Keycloak to your Identity Provider and grab the alias:

Add this alias into your URL as a new parameter with the key kc_idp_hint:

https://auth-us-east-1.revealdata.com/auth/realms/120000/protocol/openid-connect/auth?client_id=RevealWeb&response_type=code&scope=openidY.20profileY.20emailY.20rolesY.20groups_scope&response_mode=form_post&redirect_uri=httpsY.3AY.2FY.2Fprodstaging. revealdata.comY.3A443Y.2FRevealY.2FAuthorizationPagesY.2 FProjectSelect.aspx&x-client-SKU=ID_NET461&x-client-ver =6.8.0.0&kc_idp_hint=reveal-corp

You can use this URL within your identity provider (e.g. Okta) as a bookmark to Review. In the background what’s actually happening is that the user is being sent to Keycloak with a hint that directs them immediately to your identity provider. The identity provider will automatically log the user in then return them to Keycloak, which in turn logs into Review.

Log into Keycloak. Usually the KC console will be listening at a URL like:

https://some.hostname.com:8443/auth/

Go to the master realm and click on the Users button.

Add a new user. Since these are super-admins, we recommend requiring two-factor authentication on their first login:

After adding the user, add a password for them or send them a credential reset email:

Finally, to make the user an actual administrator give them the admin role:

That user will now have the ability to log in to the Keycloak master realm and administer all realms. As mentioned before, it is possible in a similar manner to create realm-level administrators, however that is out of the scope of this document.

Create a testing client that allows all redirect URLs. In this case we’ll name it test.

Navigate to something like the following:

http://[host]:[port]/auth/realms/[realm]/protocol/openid-connect/auth?response_type=code&client_id=[client]&scope=openid&redirect_uri=http://localhost:8081/

Replace the boxed parts with the correct values based on your configu­ration. For example:

https://auth-us-east-1.revealdata.com/auth/realms/000001/protocol/openid-connect/auth?response_type=code&client_id=test&scope=openid&redirect_uri=http://localhost:8081/