SAML Access

The SAML authentication allows to rely on a federated identity repository. In this case, Tomcat will delegate the authentication and the authorization mechanism to a third party (the Identity Provider).

This use case is very interesting when an Identity Provider has been deployed in the company or if the solution aims to be used from a Cloud based environment. It will literally rely on the Identity Provider for such purposes.

What's interesting here is that the Identity Provider does not need to be installed on the Tomcat server, it is another server.

Here is how it works:

• The User Agent (UA) is the end user web browser
• The Service Provider (SP) is the Brainwave tomcat web server
• The Identity Provider (IdP) is the third party accountable for authentication and authorization

As you can see here, everything is done through the HTTP/HTTPS protocol with simple HTTP redirects and HTTP forms.
When the user attempts to connect to the service provider, it detects that the user is not authenticated, generates a challenge in SAML format and redirects the user to the identity provider with this challenge.
The identity provider analyses the challenge, authenticates the user and redirects him to the service provider with a response. The response contains all the required information regarding the user and his roles.

The SAML challenge/response mechanism involves XML, time stamping and XML digital signature (at a glance, a challenge is sent to the identity provider, a response is built by the identity provider, it contains the user identity, his roles, the initial challenge and a validity time frame. The response is digitally signed by the identity provider. The response is sent back to the service provider which verifies the digital signature, the challenge, the validity time frame and acts accordingly).

Almost all major players are now leveraging the SAMLv2 protocol to authenticate users and are acting as Identity providers (Idp):

• Microsoft ADFS
• Google G suite
• Sales force

You can also delegate authentication and authorization to best of breed solutions through the SAMLv2 protocol:

• Okta
• InWebo
• LastPass
• OneLogin
• Forgerock
• ...

Brainwave is providing a sample implementation of the SAMLv2 protocol for Tomcat 8/9. You will find here all the information needed to configure SAMLv2 support for authentication and authorization with a third party Idp.

This implementation is SAMLv2 compliant and should be used with any identity providers SAMLv2 compliant.

Step 1: Declare the Brainwave application in IdP

First step is to declare your Brainwave Web application in order for the IdP to recognize it and perform AuthN/AuthZ process for User Agent request coming from the application.

Brainwave provides some samples regarding some IdP:

• Okta
• InWebo
• G-Suite
• ADFS

At the end, no matter the IdP solution, a XML metadata file that represents this SP configuration should be generated and provided by the IdP to be deployed in SP side (see later in this article).

Step 2: Deploy SAML configuration in Tomcat

In the following procedure, we will use below variables:

Prerequisites

To ensure this installation procedure, you should first download some required <SAML_BW_ARCHIVE> and <SAML_BW_LIB> Brainwave libraries available here depending on the Tomcat version installed:

• Tomcat 8 (tested with Tomcat 8.5.9)
  • bw-tomcat-8.5-saml-libs.zip
  • bw-tomcat-8.5-addons.jre8-X.jar
• Tomcat 9 (tested with Tomcat 9.0.53)
  • bw-tomcat-9.0-saml-libs.zip
  • bw-tomcat-9.0-addons.jre8-X.jar

It is also admitted that:

• Tomcat instance is installed and available
• The operator has RW privileges in needed files and folders to proceed to the installation

Tomcat configuration

First step is to deploy Brainwave SAML libraries, JDBC driver and Authenticators in Tomcat:

Under the <TOMCAT_LIB_FOLDER_HOME> folder.

• Add following files: <SAML_BW_ARCHIVE>
• Unzip the archive in this folder: <SAML_BW_LIB>
• Create a folder org/apache/catalina/startup. In this folder, create a Authenticators.properties file with below content

# Licensed to the Apache Software Foundation (ASF) under one or more
# contributor license agreements.  See the NOTICE file distributed with
# this work for additional information regarding copyright ownership.
# The ASF licenses this file to You under the Apache License, Version 2.0
# (the "License"); you may not use this file except in compliance with
# the License.  You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

BASIC=org.apache.catalina.authenticator.BasicAuthenticator
CLIENT-CERT=org.apache.catalina.authenticator.SSLAuthenticator
DIGEST=org.apache.catalina.authenticator.DigestAuthenticator
FORM=org.apache.catalina.authenticator.FormAuthenticator
NONE=org.apache.catalina.authenticator.NonLoginAuthenticator
SPNEGO=org.apache.catalina.authenticator.SpnegoAuthenticator
SAML=com.brainwave.tomcat.authenticator.saml.SAMLAuthenticator

Next step is to create and configure the SAMLAuthenticator.properties file. Under the <TOMCAT_CONF_FOLDER> folder, Create a SAMLAuthenticator.properties file with below content.

# SAML Authenticator property file
# copyright Brainwave

# idpMetadata: Identity Provider Metadata as an XML file located in the /conf subdirectory by default
# spMetadata: Service Provider Metadata as an XML file located in the /conf subdirectory by default
# roleMapping: contains a properties file name, located in /conf. It converts a dynamic role name provided by the Identity Provider to a local role name,
# the property file is on the form idprolename=localrolename
# defaultRoleList: Roles associated to the user by default as a comma separated string
# staticRole: contains a properties file name, located in /conf. It lists all the roles per principal, the property file si in the form login=roleList where roleList is in the form role1,role2,role3
# checkRealm: Once authenticated through SAML, do we test the 'user' against the configured Realm? (this can be useful if you want to configure user roles locally or with a third party Realm).
# Note: The test is done with the user login and a blank password.
# roleAttribute: If any, the name of the SAML response attribute which contains the list of the dynamic roles for the user (most of the time groups names)
# genericUsers: If any, the name of the roles names who will be used as user names: if the user is a member of such group, the group becomes the user name. It is used to convert single
# authentications to generic accounts where the
#               account name represents a profile such as "standard user", "power user", "admin user"
# genericUserPattern: when a genericUser is found, this optional parameter can be used to format the user login. {login} and {generic} can be used and will be dynamically replaced by their
# corresponding value. For instance: {login}({generic})
# defaultURI: The URI where the user will be redirected once the authentication is done. This is used for "Idp initiated use cases" only, when dealing with "SP initiated use cases", the user is redirected
# to the initial URL in any case
# forceURI: The URI where the user will be redirected once the authentication is done in any case, except when dealing with "SP initiated use cases"
#
# To add debugging infos, please add the following line at the end of the /conf/logging.properties file:
# com.brainwave.tomcat.authenticator.saml.SAMLAuthenticator.level = ALL

idpMetadata=<SAML_IDP_METADATA_FILE>
spMetadata=<SAML_SP_METADATA_FILE>
roleMapping=<SAML_ROLE_MAPPING_FILE>
defaultRoleList=user
staticRole=<SAML_STATIC_ROLE_FILE>
checkRealm=false
roleAttribute=groups
genericUsers=user
genericUserPattern={login} ({generic})
defaultURI=<WEBAPP_URI>
forceURI=<WEBAPP_URI>

Above fields should be set accordingly to your project context. Here is a short description of those configuration attributes.

For each property, you can find more details [here]({{ site.baseurl }}{% link docs/igrc-platform/installation-and-deployment/brainwaves-web-portal/portal-access/saml/saml-authenticators-properties.md %}).

Step 3: Brainwave Portal generation

From your Studio, in the Export tab of your project technical configuration:

• Select SAML authentication

• Save your technical configuration
• Generate the <WEBAPP_NAME> web portal using igrc_portal command line or from the Studio

Once configured, a new SAML authentication method is available.

<login-config>
<auth-method>SAML</auth-method>
</login-config>

If you don't setup SAML authentication schema from technical configuration, you won't be able to authenticate via SAML.

Step 4: Deploy Brainwave Portal

Once your <WEBAPP_NAME> webapp is generated, the last step is to:

• Deposit it under <TOMCAT_INSTALL_FOLDER>/webapps folder
• Start the Tomcat

The Portal should be accessible from your browser using <WEBAPP_URL>/<WEBAPP_URI>.

To activate traces, add the following line at the end of the /conf/logging.properties. Do not use this in production. This is just for troubleshooting SAML request/response.

com.brainwave.tomcat.authenticator.saml.SAMLAuthenticator.level = ALL  

SAMLAuthenticator.properties
idp-metadata.xml
rolemapping.properties
sp-metadata.xml
staticroles.properties