Identity, Credential, and Access

Management (ICAM)
Implementation Guidance
Science and Technology Directorate
Primary Authors PUBLIC SAFETY COMMUNICATIONS
Christine Owen IDENTITY, CREDENTIAL, AND ACCESS MANAGEMENT
Larry Kroll
WORKING GROUP
Chris Price
Nyleena Roberts

Contributing Organizations
Oasys International Corporation
Department of Homeland
Security (DHS) Science and Identity, Credential, and Access
Technology Directorate
Partner Engagement-
Management (ICAM) Implementation
Information Sharing
Environment (PE-ISE)
Guidance
DHS Office of Emergency
Communications (OEC) February 2019
First Responder Network
Authority (FirstNet)
Federal Communication
Commission (FCC)
National Institute for Science Version 2
and Technology Public Safety
Communications Research
Division (NIST PSCR)
ICAM Implementation Guidance v.2

Dedicated to the memory of:

Tom Sorley
1965-2018

The Identity, Credential, and Access Management (ICAM) document series is dedicated to the memory of
Tom Sorley. Tom was a member of the executive leadership of the Public Safety Communications ICAM
Working Group, which sponsored this document. He was the Chief Information Officer and Deputy
Director of the Information Technology Department for Public Safety for the City of Houston, Texas, and
National Chair of the Public Safety Advisory Committee (PSAC). Tom was a thought leader in public
safety communications and his vision is reflected in this ICAM Educational Series.
ICAM Implementation Guidance v.2

DISCLAIMER OF LIABILITY
The Identity, Credential, and Access Management (ICAM) Educational Series is provided by the Public
Safety Communications ICAM Working Group (PSC ICAM WG) “as is” with no warranty of any kind,
either expressed or implied, including, but not limited to, any warranty of merchantability or fitness for a
particular purpose. This material is provided to support the efforts of public safety information sharing,
situational awareness and key decision making. These documents are intended to guide users for making
informed decisions on improving the security posture of their information systems by using ICAM
principles.
The ICAM Educational Series is intended to provide guidance for implementing ICAM principles, and
does not contain or infer any official requirements, policies, or procedures, nor does it supersede any
existing official emergency operations planning guidance or requirements documents. As a condition of
the use of the Series, the recipient agrees that in no event shall the United States Government or its
contractors or subcontractors be liable for any damages, including but not limited to, direct, indirect,
special or consequential damages, arising out of, resulting from, or in any way connected to the Series or
the use of information from the Series for any purpose. It is recommended that organizations align their
resources with tools that would best fit their infrastructure as well as their own standards and
requirements.
The PSC ICAM WG, and DHS S&T does not endorse any commercial product or service referenced in
the ICAM Educational Series, either explicitly or implicitly. Any reference herein to any specific
commercial product, process, or service by service mark, trademark, manufacturer, or otherwise, does
not constitute or imply its endorsement, recommendation, or favoring by the PSC ICAM WG. The views
and opinions of authors expressed herein do not necessarily state or reflect those of the PSC ICAM WG
and shall not be used for advertising or product endorsement purposes.

i
ICAM Implementation Guidance v.2

EXECUTIVE SUMMARY
The Department of Homeland Security (DHS) Science and Technology Directorate (S&T) created
systems by implementing Identity, Credential, and Access Management (ICAM) products within a
sandbox for the Public Safety Communications (PSC) ICAM Working Group (WG). This document
provides Implementation Guides for Public Safety Community (Community) solution architects to
enhance existing ICAM efforts. These Implementation Guides provide instructions for building individual
ICAM components within an organization’s system.
The Community’s goal is to have the ability to appropriately share critical information among its
members, which can aid in saving lives and protecting property. This critical information is at times
highly sensitive and can include law enforcement information, as well as personally identifiable
information (PII) and protected health information, so each organization must have assurance the right
person with the right credentials is accessing information at the right time. This is where ICAM comes in.
To support the Community with its mission-critical tasks, ICAM addresses the growing data
management, interoperability and cybersecurity challenges facing public safety today. ICAM solutions,
especially federated ones, align public safety communities around common identity and access
management practices.
It is essential for important for Community members who are sharing information between different
organizations to make sure the information does not fall into the wrong person’s hands. ICAM provides
identity proofing for an organization’s employees and volunteers, providing strong credentials for system
access and enabling the use of multifactor authentication, using attributes to provision resources, and
creating strong access management all help an organization ensure that the right person is accessing an
organization’s information through a secure and seamless federation.

Figure 1 - Steps to Secure and Seamless Information Sharing (Federation)

The intent of this document is to provide implementation guides for ICAM-enabled systems. This
document does not recommend specific ICAM products, but does strive to create useable aids for the
implementation of ICAM products and encourage the adoption of multifactor authentication with a focus
on the use of open source products. This document is paired with the ICAM Executive Primer, ICAM
Acquisition Guidance and ICAM Federation System Checklist.

ii
ICAM Implementation Guidance v.2

Intended Audience
This document provides guidance to implement ICAM products. The document teaches each of the
following stakeholders 1 about ICAM solutions:

Stakeholder Group Responsibilities Documents

to Read

Executive Leadership …is the responsible authority for the department, state or ICAM
agency’s fiscal and human resources for ICAM investments. Executive
This stakeholder group will use the document to understand the Primer
importance of ICAM investments, and to translate the value
proposition of ICAM solutions to their mission needs.
ICAM
Program Managers …are responsible for the operational implementation and
Executive
oversight of ICAM capabilities to ensure they meet the
Primer,
functional mission requirements defined by the intended users.
ICAM
They must communicate to both the executive leadership and
Acquisition
solutions architects to ensure understanding and expectations of
Guidance
the requirements for interoperable ICAM investments. Managers
& ICAM
are required to quantify the benefit and resource impacts,
Federation
including cost and integration savings, to executive leadership to
System
ensure continued support and resource sustainment. This
Checklist
document provides program managers with a description of the
key capabilities, processes, services, infrastructure, standards
and procurement language samples that are required of an
interoperable ICAM architecture solution.
This
Solution Architects …are responsible for acquisition requirements and the
document,
design/development/integration of ICAM solutions in
ICAM
accordance with their respective organization’s enterprise
Executive
architecture technical and management requirements. The
Primer,
solution architects will be required to compare and quantify the
ICAM
technical implementation options, alternatives and cost
Acquisition
constraints to the program managers. This document provides
Guidance
structured technical guidance and reference artifacts to assist in
& ICAM
achieving an ICAM-enabled system.
Federation
System
Checklist

1
Each stakeholder’s responsibilities were adopted from the Information Sharing Environment Geospatial
Interoperability Reference Architecture (GIRA), available at
https://www.dni.gov/files/ISE/documents/DocumentLibrary/GIRA.pdf.

iii
ICAM Implementation Guidance v.2

CONTENTS
Disclaimer of Liability .........................................................................................................................i
Executive Summary ............................................................................................................................ ii
Contents............................................................................................................................................ iv
Table of Figures .................................................................................................................................v
1 Introduction .................................................................................................................................1
1.1 Purpose............................................................................................................................1
1.2 Background .....................................................................................................................1
1.3 Approach .........................................................................................................................2
1.4 Enabling Multifactor Authentication ..................................................................................2
1.5 How to Use......................................................................................................................2
1.6 What is in this Document ..................................................................................................3
2 Active Directory Federated Services (ADFS) Implementation Guide ...............................................5
2.1 Prerequisites ....................................................................................................................6
2.2 Installing AuthLite on the AD FS system...........................................................................7
2.3 Enable AuthLite on AD FS ...............................................................................................9
2.4 Create AuthLite Groups in AD FS ................................................................................... 12
2.5 Logging in with AuthLite Multifactor Authentication ....................................................... 16
3 Shibboleth IdP 3 & SP 2 Implementation Guide........................................................................... 17
3.1 Prerequisites .................................................................................................................. 19
3.2 Configuring the IdP Server.............................................................................................. 22
3.3 Configuring the SP Server for the IdP Server ................................................................... 24
3.4 Final IdP Configuration .................................................................................................. 25
3.5 Installing and Configuring the Shibboleth SP ................................................................... 27
3.6 Configuring Duo as a Second Factor Credential for Shibboleth ......................................... 28
4 Keycloak Implementation Guide.................................................................................................. 31
4.1 Keycloak Install and Initial Configuration ........................................................................ 32
4.2 Keycloak User Federation and Configuration ................................................................... 33
4.3 Adding a Client to Keycloak ........................................................................................... 35
4.4 Configure Keycloak as the MFA Provider for Slack ......................................................... 36
4.5 Enabling Multifactor Authentication using Keycloak ........................................................ 37
5 Duo Access Gateway Implementation Guide ................................................................................ 39
5.1 Install and Configure DAG ............................................................................................. 40
5.2 Connect Cloud Applications............................................................................................ 40

iv
ICAM Implementation Guidance v.2

5.3 Configure DAG for Multifactor Authentication ................................................................ 40

5.4 Enable DAG launcher Application................................................................................... 40
6 Okta Identity Cloud Implementation Guide .................................................................................. 41
6.1 Service Provider Configuration ....................................................................................... 42
6.2 PIV-I Configuration........................................................................................................ 43

TABLE OF FIGURES
Figure 1 - Steps to Secure and Seamless Information Sharing (Federation) ............................................. ii
Figure 2 - System Configured for Multifactor Authentication Using Yubikey HMAC-based one-time
password, AuthLite & MS Windows Active Directory. .........................................................................5
Figure 3 - System Configured for Multifactor Authentication Using Duo TOTP (Time-based One-Time
Password), Shibboleth IdP, Shibboleth SP & MS Windows Active Directory. ...................................... 17
Figure 3 - System Configured for Multifactor Authentication Using Duo Google Authenticator, Keycloak
& MS Windows Active Directory. ..................................................................................................... 31
Figure 4 - Duo Access Gateway SSO ................................................................................................. 39
Figure 5 - Okta Identity Cloud SSO Build Architecture ....................................................................... 41

v
ICAM Implementation Guidance v.2

1 INTRODUCTION
This document serves as a source of Identity, Credential, and Access Management (ICAM)
Implementation Guides resulting from the evaluation of publicly available documents and the
implementation of ICAM-enabled systems in a sandbox. The ICAM landscape is complex and there are
many elements to consider, particularly when determining organizational policies and system
interoperability. ICAM policies are important to have in enabling technology to share data within a wide
variety of applications, including an organization’s existing legacy systems as well as emerging
nationwide initiatives, such as the Nationwide Public Safety Broadband Network (NPSBN), Next
Generation 911 services and the First Responder Network Authority (FirstNet).
While this document is focused on assisting state, local, tribal and territorial (SLTT) Public Safety
Community (Community) entities in improving their system’s security posture so they can safely and
securely share information with each other, this document can be used by any organization implementing
the products discussed within this document. Instead of considering both single and multifactor
authentication, this document focuses on implementing multifactor authentication on an organization’s
systems. Adopting multifactor authentication when upgrading an ICAM-enabled system is highly
recommended for any organization, but it is especially recommended based on a risk assessment of the
typical information stored in the Community’s systems. This document is the third of a series of ICAM
educational tools, including the ICAM Executive Primer, ICAM Acquisition Guidance and ICAM
Federation System Checklist.

1.1 PURPOSE
The goal of this document is to enable any organization, including the SLTT Community, to spend its
resources wisely on thoughtful and well-specified ICAM products to support information sharing and
fortified authentication capabilities. This document provides ICAM implementation guides for the
Community and seeks to leverage existing efforts to avoid duplication and maximize the value of existing
ICAM products and solutions. While it does use specific vendors to complete the builds, this document
does not endorse any specific vendor, technology or software. The implementation guidance within this
document aids the Community in creating ICAM-enabled systems and adopting multifactor
authentication. Further, each organization is responsible for its own cybersecurity measures, and they
should make decisions based on their own requirements, laws and expertise on the subject.

1.2 BACKGROUND
The Public Safety Communications Identity, Credential, and Access Management Working Group (PSC
ICAM WG) is a subsidiary group of the Information Sharing Council (ISC) with a Federal Advisory
Committee Act (FACA) exempt status under Section 1016(g)(4) of the Intelligence Reform and
Terrorism Prevention Act of 2004 (as amended). Its members include the Department of Homeland
Security (DHS) Science and Technology Directorate (S&T), Partner Engagement Information Sharing
Environment (PE-ISE), DHS Office of Emergency Communications (OEC), FirstNet, as well as National
Institute of Standards and Technology (NIST) Public Safety Communications Research Division (PSCR).
The PSC ICAM WG supports the ISC in fulfilling the ISC’s duties (with a focus on public safety)
pertaining to the interchange of information between public safety agencies by addressing policy,
governance, standards, technology and acquisition guidance on ICAM capabilities for the Community.

1
ICAM Implementation Guidance v.2

1.3 APPROACH
Through outreach to various communities (including FirstNet stakeholders, the Federal ICAM
Subcommittee, DHS Cybersecurity and the Office of the Director of National Intelligence’s Sensitive But
Unclassified [SBU] Technical Advisory Committee [STAC]) and utilization of the capabilities at the
DHS S&T, the PSC ICAM WG gathered existing ICAM-related documents, performed research and
collected information. This information provided the background for building ICAM-enabled systems in a
test environment (i.e., sandbox), the result of which was distilled into this implementation guide.

1.4 ENABLING MULTIFACTOR AUTHENTICATION

ICAM concepts appear in everyday life. When leaving our homes or cars, most of us choose to lock our
doors and restrict access only to those with a key. 2 Likewise, anyone who accesses the internet creates a
username and password to access a computer system, email or social network, which are examples of
single factor authentication.
Most people only use a username and password when accessing computer systems, likely due to a
perceived notion of convenience. Single factor authentication is a weaker form of protection for computer
systems and applications. A username and password combination or pin number are examples of single
factor authentication when they are not used on their own. While single factor authentication is simple
and easy to implement, the practice is akin to leaving a door unlocked for hackers. Since passwords are
easily obtained via email phishing, single factor credentials played a factor in 81 percent of the systems
that were hacked in 2016. 3
Multifactor authentication uses a combination of credentials to provide higher assurance that the
individual attempting to access a protected resource is that individual. To create this higher assurance,
multifactor authentication requires the use of two of three “factors.” The factors include something you
have (a credential), something you are (fingerprint or other biometric) and something you know
(password or personal identification number ([PIN]). Information breaches can be prevented by using
multifactor authentication to access your data. Implementing simple multifactor authentication methods
can help organizations prevent costly, time-consuming attacks.
When organizations connect their systems with others within their community of interest, the
organizations will need to know who is accessing which pieces of information at what times to ensure
only authorized users are within the system. Multifactor authentication becomes useful in information
sharing scenarios. After performing a risk assessment based on the type of information held in the SLTT
Community’s systems, it was determined that multifactor authentication would reduce the risk of a
system intrusion. As a result, this document, as well as the Executive Primer and Acquisition Guidance,
are all tailored towards ICAM systems with multifactor authentication.

1.5 HOW TO USE

The content within this document provides a deeper view for solutions architects into an ICAM-enabled
system configured with multifactor authentication through implementation guides. This document is part
of a progressive series that begins with the ICAM Executive Primer, a high-level, educational dive into
ICAM for executive leadership and others through ICAM concepts and real-world scenarios. The ICAM

2
Most public safety communications systems, radio sites, public safety facilities, data centers and radios are
physically secured against internal and external threats.
3
Verizon Enterprise Solutions, 2017 Data Breach Investigations Report, which can be found at
http://www.verizonenterprise.com/verizon-insights-lab/dbir/2017/.

2
ICAM Implementation Guidance v.2

Acquisition Guidance is the second in the series. It gives an overview to program managers of what to
look for while acquiring ICAM products and advises solutions architects about lessons learned from
sandbox builds of ICAM-enabled systems with multifactor authentication. The series ends with an ICAM
Federation System Checklist, which includes five topics that should be addressed by a system owner
before federating a system. This series also contains several helpful sections and appendices, including
reference architecture, implementation guidance and procurement language.
This document was developed by the DHS-established PSC ICAM WG; questions and comments can be
sent to DHS S&T at: [email protected].

1.6 WHAT IS IN THIS DOCUMENT

To collect data for these Implementation Guides, DHS S&T created ICAM-enabled systems configured
with multifactor authentication in a sandbox, producing ample data to create them. Each build used
different software and credentials Community members could use in a build. The

3
ICAM Implementation Guidance v.2

Active Directory Federated Services (ADFS) Implementation Guide used low-cost products. The
Shibboleth IdP 3 & SP 2 used a free, open source product that was mentioned on the Global Federation
Identity and Privilege Management (GFIPM) website. The Duo Access Gateway (DAG) and Okta IdP
Implementation Guides are both cloud-based commercial products.
Based on the installation procedures and associated outcomes of these builds, PSC ICAM WG created the
below reference architecture and Implementation Guides. In no way does the PSC ICAM WG endorse or
favor the vendors and software implemented below. These guides are for educational purposes only. And
as such, each organization is responsible for its own cybersecurity measures, and should make decisions
based on the requirements, laws and expertise of the organization.

4
ICAM Implementation Guidance v.2

2 ACTIVE DIRECTORY FEDERATED SERVICES (ADFS)

IMPLEMENTATION GUIDE

Figure 2 - System Configured for Multifactor Authentication Using Yubikey HMAC-based one-time password,
AuthLite & MS Windows Active Directory.

AuthLite is a two-factor authentication tool that can operate on Windows and Active Directory (AD).
This build was conducted in an Amazon Web Services (AWS) environment and, as such, its guide
contains implementation instructions specific to AWS. This build was configured in conjunction with
Active Directory Federated Services (AD FS) to extend AuthLite’s federation capabilities. AD FS is a
Microsoft component that can be installed to provide Simplified Sign-on (SSO) to applications across
organizational boundaries. AD does not natively support multifactor authentication, so AuthLite was used
as a middleware to provide multifactor authentication.
For the purposes of this guide, we used Google Authenticator as a one-time password (OTP) token for the
second factor. AuthLite can also be configured to use a Yubikey as a credential. The Yubikey, a FIDO
Alliance-approved credential, is a hard token that can be plugged into a universal serial bus (USB) port or
used with another near field communication (NFC) device and touched to release a certificate. Its cost
varies on the type of Yubikey chosen and the device can be configured several different ways – it could
be used as a single-factor authenticator, as an OTP device, or even as a public key infrastructure token. In
this build, the Yubikey is configured for two-factor authentication as a keyed-hash message authentication
code (HMAC)-based one-time password.
To use the Yubikey in an AWS environment, USB hardware needs to be accessible by the Amazon
Elastic Compute Cloud (EC2) instances. One way to accomplish this is by setting up a publicly accessible
virtual private network (VPN) tunnel into AWS. Because USB credentials cannot be passed through

5
ICAM Implementation Guidance v.2

directly to EC2 instances, this allows the user to provide two authentication factors to gain access to the
VPN (or virtual private cloud (VPC) in this case). In this build, OpenVPN was chosen for this purpose
and setup to use a Microsoft domain controller as its user directory. AuthLite is relatively inexpensive and
interacts seamlessly with the Yubikey and AD. In this build, Yubikey and AD username/password
provide the two factors needed to access the VPC via the OpenVPN (and AuthLite) software.

2.1 PREREQUISITES
• Register your Windows Server 2012 server as a member server on a preexisting domain.

• The AD deployment engineer should have domain administrator privileges.

• The ADFS configuration requires a publicly trusted certificate for secure sockets layer (SSL)
server authentication according to the following guidelines located here on the Microsoft
website.

• Follow Microsoft’s installation guide to deploy ADFS and configure it for your domain.

6
ICAM Implementation Guidance v.2

2.2 INSTALLING AUTHLITE ON THE AD FS SYSTEM

Note: The deployment engineer must have the Schema Admin role in AD. AuthLite must be installed on
a Domain Controller.

1. Download and/or copy the most recent version of AuthLite to a folder located on the local server.

2. Open Command Prompt as an administrator and run the installer through the command line.

3. Click Next on the AuthLite Welcome window.

4. Accept the license agreement then click Next.

7
ICAM Implementation Guidance v.2

5. Click Install on the Product features page.

6. Click Finish once the install has completed.

7. Click Yes in the AuthLite modal window to restart the server.

8
ICAM Implementation Guidance v.2

2.3 ENABLE AUTHLITE ON AD FS

1. Login to the server once the restart is completed. The AuthLite configuration tool should open
automatically.

2. Click on License Information from the Left Navigation. Request an AuthLite License Key.

a. Go to authlite.com/license to request a temporary evaluation license key

OR

b. Go to authlite.com/store to purchase a permanent license for your deployment.

9
ICAM Implementation Guidance v.2

3. Click on Forced 2-Factor Processes under Local Machine Config.

4. Click the Add process button. Enter IdentityServer in the text box. Click OK.

10
ICAM Implementation Guidance v.2

5. Click Apply Changes.

11
ICAM Implementation Guidance v.2

2.4 CREATE AUTHLITE GROUPS IN AD FS

The creation of AuthLite groups in AD is required for AuthLite to enforce multifactor authentication in
AD FS.

1. Open Active Directory Users and Computers. This can be opened from the Tools menu in the
Server Manager. Select Active Directory Users and Computers from the dropdown.

2. Create the following three Global Security Groups in your Domain. The Security Group names are
specific and case sensitive:

a. AuthLite Users
b. AuthLite 1F Tag
c. AuthLite 2F Tag

3. Add any Users you wish to be managed by AuthLite to the AuthLite Users group.

4. Users in the AuthLite Users group must be provided with a multifactor token. Multifactor tokens can
be created from Setup an OATH Token under Management Tasks in the left navigation pane.
Note: Users can be managed within the AuthLite Token Manager tool.

12
ICAM Implementation Guidance v.2

5. Add the AuthLite Users group as a Member of the AuthLite 1F Tag group. This ensures that all
members of the AuthLite users group are also members of the AuthLite 1F Tag group.

6. Set the domain administrators group to Deny on Write for both the AuthLite 1F Tag and AuthLite 2F
Tag groups. This is preventative but not required. AuthLite should be allowed to assign these
permissions dynamically.

7. Configure the 1F and 2F Group Pair in the AuthLite Configuration Tool.

a. Click the AuthLite User Group Pairs item on the left navigation panel

13
ICAM Implementation Guidance v.2

b. Click Add Group Pair

c. Add the previously created AuthLite 1F and 2F Tag Security Groups to their relevant fields. Click
OK

d. Click Apply changes

14
ICAM Implementation Guidance v.2

15
ICAM Implementation Guidance v.2

2.5 LOGGING IN WITH AUTHLITE MULTIFACTOR AUTHENTICATION

Note: Now any AuthLite users who are authorized into the AD FS environment will be required to use
two-factor authentication for specified activities. To verify, attempt to use one-factor authentication and
ensure that those requests are blocked.

To log in with AuthLite multifactor authentication, do the following:

1. Get an OTP token code.

2. Append the code to our name as seen in the figure below.
3. Enter your password.

References
AD FS Requirements. (2018, March 05). Retrieved from Microsoft.com: https://docs.microsoft.com/en-
us/windows-server/identity/ad-fs/overview/ad-fs-requirements#BKMK_1
Certificate Requirements for Federation Servers. (2017, May 30). Retrieved from Microsoft.com:
https://docs.microsoft.com/en-us/windows-server/identity/ad-fs/design/certificate-requirements-
for-federation-servers
Use Group Policy to enforce 2-factor on Windows servers/workstations. (2018). Retrieved from
AuthLite.com: https://www.authlite.com/docs/2_3/id_1587484890/

16
ICAM Implementation Guidance v.2

3 SHIBBOLETH IDP 3 & SP 2 IMPLEMENTATION GUIDE

Figure 3 - System Configured for Multifactor Authentication Using Duo TOTP (Time-based One-Time
Password), Shibboleth IdP, Shibboleth SP & MS Windows Active Directory.
Shibboleth is a federated identity solution that provides simplified sign-on (SSO) capabilities, along with
multifactor authentication. Because the GFIPM website provides a link to implementation documentation
for Shibboleth (a free, open source product), in this build Shibboleth was used as an identity provider and
simplified sign-on solution, as well as a service provider.
This build includes a time-based one-time password (TOTP) credential on your phone. Duo was chosen
as the credential provider because it interoperates with Shibboleth and is free for up to 10 users. Duo’s
mobile phone TOTP application allows for a six-digit number found on the phone, a phone call, or a
button that pops up on your phone to prove you with the credential.

17
ICAM Implementation Guidance v.2

ABOUT
This implementation guide has been created to assist organizations with installing and configuring
Shibboleth IdP 3 and SP 2 to authenticate users over Lightweight Directory Access Protocol (LDAP)
against Microsoft AD. Additionally, it outlines how to add a second factor to authentication using Duo
TOTP. While researching Shibboleth, it was found that much of the publicly available documentation for
installing and configuring Shibboleth was not straightforward, especially for those who may be unfamiliar
with the software. This guide is for implementation of Shibboleth software in an AWS cloud
environment, and should be used as a reference in conjunction with the current publicly available
Shibboleth documentation. Throughout this guide, links have been provided to offer additional assistance
and information.
WHAT IS THE SHIBBOLETH SOFTWARE?
This step-by-step guide provides detailed instructions on how to successfully implement the Shibboleth
software components in an AWS cloud environment. The Shibboleth software is a web-based SSO
system made up of three components:
• The IdP is responsible for user authentication and providing user information to the SP. It is
located at the home organization, which is the organization that maintains the user’s account.
• The SP is responsible for protecting an online resource and consuming information from the IdP.
It is located at the resource organization, which is the organization that keeps records that will be
shared.
• The Discovery Service (DS) helps the SP discover the user’s IdP. It may be located anywhere on
the web and is not required in all cases. 4

Shibboleth has two major halves: an IdP and a SP. The IdP supplies information about users to
applications, and the SP gathers information about users to protect resources. In the typical use case, a
web browser accesses a protected resource, authenticates at the identity provider and once authenticated,
is logged into the resource. 5

• Web Browser – represents the user within the SSO process.

• Resource – contains restricted access content that the user wants to access.
• IdP – authenticates the user.
• SP – performs the SSO process for the resource. 6

4
Shibboleth Concepts, available at https://wiki.shibboleth.net/confluence/display/CONCEPT.
5
Shibboleth Wiki: Flows and Configs, https://wiki.shibboleth.net/confluence/display/CONCEPT/FlowsAndConfig.
6
How Shibboleth Works: Basic Concepts, https://www.shibboleth.net/index/basic.

18
ICAM Implementation Guidance v.2

BEFORE YOU BEGIN – A LIST OF HELPFUL TIPS :

• Although it is encouraged to do so, always be careful when/if copy and pasting code from this
guide, and double-check that you have substituted the correct values.
• Always double-check that you are downloading the correct version of any software.
• Sometimes simple missteps can cause big problems; remember to check the logs included with all
software utilized during this process to determine the cause of any issues you encounter.
• There are multiple ways to configure Shibboleth depending on what you are doing – one
configuration/integration will not necessarily work for everyone.
• There is very limited documentation available for troubleshooting.
• Document the steps you have taken as you go, just in case a component breaks – this will allow
you to compare the documentation of your build with the documentation of this guide.
• Setting up a system that utilizes the Shibboleth IdP and/or SP is a long process. It will take a lot
of time and resources and will require the assistance of senior-level engineers.
• Remember that https://www.testshib.org/ is a very useful troubleshooting tool during the latter
steps of the Shibboleth software configuration.

3.1 PREREQUISITES
You will need to create at least a three server networks for this configuration – an IdP, an SP, and an AD
server. The servers should have a base hardware spec of 2GB+ of RAM and 160GB of Storage. All
guides are written using Windows Server 2012 as the Operating System.

• Disable both Internet Explorer Enhanced Security and Windows Firewall.

• Download and Install Chrome and Notepad++ on both the IdP and SP servers.

ADD ACTIVE DIRECTORY CERTIFICATE SERVICES

Follow Microsoft’s installation guide to add the Certificate Services role to your AD server.

EXPORT CERTIFICATE TO IDP

1. Open Run and use the mmc.exe command to open the Microsoft management console (MMC).
2. Open File, select Add or Remove Snap In and select Certificate Snap In. Click OK .

19
ICAM Implementation Guidance v.2

3. Select the Certificate that has the name of your AD Domain. Right click and select Export from
All Tasks.

20
ICAM Implementation Guidance v.2

4. Press Next and save the certificate (Choose a name easy to remember and find, i.e., ADCERT).

5. Copy the newly created file to the IdP desktop through the Remote Desktop clipboard
functionality.

21
ICAM Implementation Guidance v.2

3.2 CONFIGURING THE IDP SERVER

DOWNLOAD AND INS TALL J AVA 8
1. Follow the hyperlink above to download Java Development Kit (JDK) for Windows 64 bit
and run the installer.
2. Set the JAVA_HOME system variable to JDK install path (i.e., c:\Program Files\Java\jdkxx).
a. From the Start Menu right click computer.
b. Click Properties.
c. Click Advanced System Settings.
d. Click Environment Variables.
e. Under System Variables, click New…”
f. Name the variable JAVA_HOME and point it to your JDK install directory.
DOWNLOAD AND INS TALL TOMCAT 8.5
The identity provider is a standard Java web application and runs on a compatible servlet container.
Tomcat 8.5 is the container documented in this guide to deploy and run the IdP within our environment.
1. Follow the hyperlink above to download Tomcat 8.5 32-bit/64-bit Windows Service
Installer.
2. Run the installer, set administrator username/password, and accept all other defaults.
3. Navigate to your Tomcat 8.5 install directory (default is C:\Apache Software Foundation).
4. Click the checkbox that enables Tomcat to run immediately after install.
5. Open http://localhost:8080/ with your browser (if you can see the Tomcat homepage, then
you have successfully installed Tomcat 8.5).
INSTALLING THE SHIBBOLETH IDP V3
1. Download Shibboleth IdP v3 onto your IdP server instance with Tomcat 8.5 installed on it.
2. Run the IdP Windows Installer. Set the install path to C:\opt\shibboleth-idp./

3. Check the Configure for Active Directory checkbox.

4. Specify the DNS name for your IdP (i.e., SHIB-IDP.dhs-st-lab.local).
5. Specify the scope (i.e. dhs-st-lab.local).

22
ICAM Implementation Guidance v.2

6. Click Next.

7. Specify the Active Directory Domain (i.e., dhs-st-lab.local).

8. Leave the Use Global Catalog checkbox unchecked.
9. Enter the credentials for the Active Directory Admin account that will be used to perform
LDAP lookups.
10. Click Next.
CONFIGURING SSL ON TOMCAT
1. Create and initialize Java keystore.
a. Open cmd (Command Prompt) as Administrator and run the following keytool command:
%JAVA_HOME%\bin\keytool” -genkey -alias tomcat -keyalg RSA
b. Set a password.

2. Provide answers to the questions asked when creating the certificate store.
a. Enable secure sockets layer (SSL) by adding the following connector to server.xml:
<Connector
protocol="org.apache.coyote.http11.Http11NioProtocol"
port="8443" maxThreads="200"
scheme="https" secure="true" SSLEnabled="true"
keystoreFile="<PATH TO KEYSTORE>" keystorePass="<PASSWORD>"
clientAuth="false" sslProtocol="TLS"/>

b. Open Services and restart Tomcat.

c. To check if https is enabled, navigate to https://localhost:8443.

CONFIGURING THE SHIBBOLETH IDP V3

1. Create an xml file named idp.xml used to dynamically deploy the idp.war file when it is
rebuilt.
a. Copy and paste the following into idp.xml
<Context docBase="C:/opt/shibboleth-idp/war/idp.war"
privileged="true"
antiResourceLocking="false"

23
ICAM Implementation Guidance v.2

swallowOutput="true">

<!-- Work around lack of Max-Age support in IE/Edge -->

<CookieProcessor alwaysAddExpires="true" />

</Context>
b. Save idp.xml into <tomcat dir>/conf/Catalina/localhost/.
2. Open the ldap.properties files and update the AD server name and ldapURL to reflect your
instance. Verify that the other values are correct.
3. Modify C:\opt\shibboleth-idp\webapp\WEB-INF\web.xml to include:
<context-param>
<param-name>idp.home</param-name>
<param-value>/opt/shibboleth-idp</param-value>
</context-param>
4. Add JavaServer Pages Standard Tag Library (JSTL) Libraries to Tomcat.
a. Download the latest .jar files:
• Impl: taglibs-standard-impl-1.2.5.jar (pgp, md5)
• Spec: taglibs-standard-spec-1.2.5.jar (pgp, md5)
• EL: taglibs-standard-jstlel-1.2.5.jar (pgp, md5)
• Compat: taglibs-standard-compat-1.2.5.jar (pgp, md5)

b. Copy .jar files to opt/shibboleth-idp/edit-webapp/web-inf/lib.

c. Open a command prompt window as an administrator.
d. Navigate to the Shibboleth bin/directory and run build.bat to generate a new war file.
e. Open Services, restart the Tomcat service.
f. Navigate to https://<server URL>:8443/idp/shibboleth. The IdP metadata page should
now display.Configuring the SP Server for the IdP Server

3.3 CONFIGURING THE SP SERVER FOR THE IDP SERVER

DOWNLOAD AND INS TALL APACHE (ON SP S ERVER)
Apache is an open-source HyperText Transfer Protocol (HTTP) server for modern operating systems,
including UNIX and Windows. The SP is a web server module (installed and configured to work with a
web server, such as Apache) that intercepts the user’s request to access a protected resource. Windows
may present an error stating that the version of the software is not compatible with your system. If this
happens and you have already verified the version downloaded, then re-download it and try installing it
again.
1. Install Apache from Apache Lounge (Apache Lounge is an organization that provides pre-
package installation bundles for Windows systems; this download of Apache will include
openssl).
2. Download and install C++ redistributable library.
3. Extract the folder to C:/Apache24.
a. Run cmd (Command Prompt) as an Administrator and install Apache 2.4 as a service.
httpd.exe -k install
b. Create an OPENSSL_CONF Windows System environment variable to point to
openssl.cnf (located within the Apache bin/install directory).
i. From the Start Menu, right click Computer.
ii. Click Properties.
iii. Click Advanced System Settings.
iv. Click Environment Variables.

24
ICAM Implementation Guidance v.2

v. Under System Variables, click New...

c. Create an SSL self-signed certificate using the following Openssl commands (use “changeit”
as a password where needed). Make sure that you input your fully qualified domain name as
the common name when you respond to the prompts to create your ssl certificate information:
openssl genrsa -des3 -out server.key 1024
openssl req -new -key server.key -out server.csr
copy server.key server.key.org
openssl rsa -in server.key.org -out server.key
openssl x509 -req -days 365 -in server.csr -signkey server.key
-out server.crt
d. Create a folder within the Apache install directory named Certificates. Move the four files
that you just created into this directory from the conf folder (if you sort the conf folder by
date modified, these files should come to the top).
e. Open conf/http.conf and modify virtual host at port 553 where the SP is called to resemble
the following:
<VirtualHost *:553>
ServerName <SERVERNAME>
# Include C:\opt\shibboleth-sp\etc\shibboleth\apache24.config
DocumentRoot C:/Apache24/htdocs
ErrorLog C:/Apache24/logs/error_ssl.log
CustomLog C:/Apache24/logs/access_ssl.log combined
SSLEngine on
SSLCertificateFile "C:/Apache24/certificates/server..crt"
SSLCertificateKeyFile "C:/Apache24/certificates/server.key"
</VirtualHost>
f. Enable the mod_ssl.so module in httd.conf:
LoadModule ssl_module modules/mod_ssl.so
(uncomment the corresponding LoadModule line )
g. Setup to listen on port 553
By adding Listen 553
h. Now create a folder within htdocs named Secure and place a protected resource within it (in
our example, we created secure.html within the folder).
i. Restart Apache. At this point, Apache should start without error and you should be able to
access the webpage by navigating to:
http://localhost/secure/secure.html
https://localhost:553/secure/secure.html
Now you can access secure.html page without logging in because it is not protected by Shibboleth.

3.4 FINAL IDP CONFIGURATION

1. Navigate to the IdP metadata folder (the default path to
C:\<shibboleth install directory>\metadata).
2. Modify idp-metadata.xml.
3. If necessary, edit all the Location= attributes point to IdP app on Tomcat 8 (port 8443)
(https://<idp server>:8443/idp...).
4. Modify conf/metadata-providers.xml.
a. Add a similar metadata-provider to the one below for SP metadata provider:
<MetadataProvider xsi:type="FilesystemMetadataProvider"
xmlns="urn:mace:shibboleth:2.0:metadata"
id="MyMetadata1"

25
ICAM Implementation Guidance v.2

metadataFile="C:/opt/shibboleth-idp/metadata/<sp servername>-
metadata.xml" />
5. From your browser, launch https://<sp server>/Shibboleth.sso/Metadata.
6. Save the xml content that is returned to C:/opt/shibboleth-idp/metadata/<sp server>-
metadata.xml.
7. Add connection to your SSL certificate in the ldap.properties file on the IdP server, add
certificate file we previously placed on the desktop, and make sure the user and password in
the file are the AD Admin user we created in the previous steps.
8. Rebuild the WAR by running build.bat again.
9. Restart Tomcat service.

26
ICAM Implementation Guidance v.2

3.5 INSTALLING AND CONFIGURING THE SHIBBOLETH SP

1. Download and install Shibboleth SP onto your SP server instance with Apache installed on
it as instructed by its msi (shibboleth-sp-2.4.2-win32.msi).
2. Install to default location (C:\opt\shibboleth-sp).
3. Navigate to the Shibboleth directory in your file explorer.
4. Modify the shibboleth2.xml file.
a. Remove or comment the "<InProcess
logger="native.logger">…</InProcess>" block.
b. Modify <Host> to include hostname
<Host name="<SP SERVERNAME>">
<Path name="secure" authType="shibboleth" requireSession="true"/>
</Host>
c. Provide Application Defaults by modifying the entityID portion of that tag to be the
FQDN (Fully Qualified Domain Name).
d. Provide SSO attributes (do not add port 553 to the following entry)
<SSO entityID="https://<IdP SERVERNAME>/idp/shibboleth">
SAML2 SAML1
</SSO>
e. Enter MetaData provider
<MetadataProvider type="XML" file="<IdP SERVERNAME>-
metadata.xml"/>
Once the IdP is a running file, you should be able to navigate to this address and it will
return a metadata file: https://<IdP SERVERNAME>:8443/idp/shibboleth
f. Save the metadata (i.e., C:\opt\shibboleth-sp\etc\shibboleth\metadata\my-
metadata.xml).
5. Change showAttributeValues="true".
6. Modify the apache24.config file. This way you will be able to test the header content.
a. Replace
<Location /secure>
AuthType shibboleth
ShibRequestSetting requireSession 1
require valid-user
</Location>
with
<Location /secure>
AuthType shibboleth
ShibRequestSetting requireSession 1
require shib-session
ShibRequireSession On
ShibUseHeaders On
</Location>
7. Modify the attribute-map.xml file.
a. Add an entry for uid similar to the following (you can copy it from under the LDAP
examples)
<Attribute name="urn:oid:0.9.2342.19200300.100.1.1" id="uid"/>
8. Uncomment the following line from httpd.conf:
Include C:\opt\shibboleth-sp\etc\shibboleth\apache24.config
9. Go to Windows services and restart the Shibboleth 2 Daemon(Default).
10. Restart the Apache 2.4 service.

27
ICAM Implementation Guidance v.2

TESTING YOUR CONFIGURATION

1. Once the IdP and SP have been configured, navigate to https://<your
hostname>:553/secure/secure.html. You should see a login screen if it has been configured
correctly.
2. Enter Active Directory account credentials for a valid user.
3. If you can see the secure.html webpage, then you have successfully installed and configured
the Shibboleth IdP and SP.

3.6 CONFIGURING DUO AS A SECOND FACTOR CREDENTIAL FOR SHIBBOLETH

1. Sign up for a Duo account.
2. Log in to the Duo Admin Panel and navigate to Applications.
3. Click Protect an Application and locate Shibboleth in the applications list.
4. Click Protect this Application to get your integration key, secret key and API hostname.
5. Generate an akey. Your application secret key or akey is a string that you should generate
and keep secret from Duo. It should be at least 40 characters long and stored alongside your
integration key and secret key.
a. Create a random string of 40 characters (akey value).
6. Configure [idp]/conf/authn/duo.properties
a. Input the following keys and the API unique to your install.
i.ikey (idp.duo.integrationKey)
ii.skey (idp.duo.secretKey)
iii.akey (idp.duo.applicationKey)
iv.API hostname (idp.duo.apiHost)
7. Use NTP to ensure that your server’s time is correct.
8. Verify that the properties file is being referenced by the top level [idp]/conf/idp.properties.
The variable idp.additionalProperties should contain /conf/authn/duo.properties.
9. Set idp.authn.identitySwitchIsError = true in idp.properties.
10. Within idp.properties set idp.authn.flows = MFA
11. Navigate to the [idp]/conf/authn/mfa-authn-config.xml file and replace the current content
with the following:

<util:map id="shibboleth.authn.MFA.TransitionMap">
<!-- First rule runs the Password login flow. -->
<entry key="">
<bean parent="shibboleth.authn.MFA.Transition"
p:nextFlow="authn/Password" />
</entry>
<!-- Second rule runs a function if Password succeeds, to determine
whether an additional factor is required. -->
<entry key="authn/Password">
<bean parent="shibboleth.authn.MFA.Transition" p:nextFlowStrategy-
ref="checkSecondFactor" />
</entry>
<!-- An implicit final rule will return whatever the final flow returns.
-->
</util:map>
<!-- Example script to see if second factor is required. -->
<bean id="checkSecondFactor"
parent="shibboleth.ContextFunctions.Scripted" factory-
method="inlineScript">

28
ICAM Implementation Guidance v.2

<constructor-arg>
<value>
<![CDATA[
nextFlow = "authn/Duo";
nextFlow; // pass control to second factor or end with the first
]]>
</value>
</constructor-arg>
</bean>

12. Place the following beans into idp]/conf/authn/general-authn.xml:

<bean id="authn/Duo" parent="shibboleth.AuthenticationFlow"

p:forcedAuthenticationSupported="true" p:nonBrowserSupported="false">
<!--
The list below should be changed to reflect whatever locally- or
community-defined values are appropriate to represent MFA. It is
strongly advised that the value not be specific to Duo or any
particular technology.
-->
<property name="supportedPrincipals">
<list>
<bean parent="shibboleth.SAML2AuthnContextClassRef"
c:classRef="http://example.org/ac/classes/mfa" />
<bean parent="shibboleth.SAML1AuthenticationMethod"
c:method="http://example.org/ac/classes/mfa" />
</list>
</property>
</bean>

<bean id="authn/MFA" parent="shibboleth.AuthenticationFlow"

p:passiveAuthenticationSupported="false"
p:forcedAuthenticationSupported="true" p:nonBrowserSupported="false">
<!--
The list below almost certainly requires changes, and should generally
be the
union of any of the separate factors you combine in your particular MFA
flow
rules. The example corresponds to the example in mfa-authn-config.xml
that
combines IPAddress with Password.
-->
<property name="supportedPrincipals">
<list>
<bean parent="shibboleth.SAML2AuthnContextClassRef"
c:classRef="urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTran
sport" />
<bean parent="shibboleth.SAML2AuthnContextClassRef"
c:classRef="urn:oasis:names:tc:SAML:2.0:ac:classes:Password" />
<bean parent="shibboleth.SAML1AuthenticationMethod"
c:method="urn:oasis:names:tc:SAML:1.0:am:password" />
<bean parent="shibboleth.SAML2AuthnContextClassRef"
c:classRef="http://example.org/ac/classes/mfa" />
<bean parent="shibboleth.SAML1AuthenticationMethod"
c:method="http://example.org/ac/classes/mfa" />
</list>
</property>
</bean>

29
ICAM Implementation Guidance v.2

13. Download the Duo Mobile application onto a mobile device and configure your Duo account
for TOTP/push usage.
14. Rebuild the WAR by running build.bat again.
15. Restart the Tomcat service.
16. Try to access the protected resource again. This time, there should be a second factor prompt
using Duo.
Duo configuration is now complete. Refer to this page on the Shibboleth wiki for additional
information.

STILL NOT SEEING A LOGIN SCREEN?

• Ensure that all entity IDs match up in metadata files.
• Use Test-Shib.org to verify the operation of both SP and IdP.
• We have found that sometimes Java and Tomcat do not automatically install system level
variables, and this can cause many issues during the Shibboleth install.
o Within this guide, we tell you to self-install system level variables.
o If you may have forgotten to do this, double check that you have followed these steps
and/or have the correct variable name/path inputted.
• Use Tomcat 8.5 as opposed to Tomcat 9 (Tomcat 9 appears to have bugs that prevent
Shibboleth from working properly).

RESOURCES
Baker, C. (2017, March 10). Implementing MFA Using Native IDPv3.3 Duo Plugin (for IDPs who
upgraded from 2.x). Retrieved from wiki.shibboleth.net:
https://wiki.shibboleth.net/confluence/pages/viewpage.action?pageId=32112643
Duo for Shibboleth Identity Provider v3. (n.d.). Retrieved from duo.com:
https://duo.com/docs/shibboleth
How Shibboleth Works: Basic Concepts. (n.d.). Retrieved from www.shibboleth.net:
https://www.shibboleth.net/index/basic/
User, U. (2017, 8 May). FlowsAndConfig. Retrieved from wiki.shibboleth.net:
https://wiki.shibboleth.net/confluence/display/CONCEPT/FlowsAndConfig
User, U. (2017, May 8). Home. Retrieved from wiki.shibboleth.net:
https://wiki.shibboleth.net/confluence/display/CONCEPT

30
ICAM Implementation Guidance v.2

4 KEYCLOAK IMPLEMENTATION GUIDE

Figure 4 - System Configured for Multifactor Authentication Using Duo Google Authenticator, Keycloak
& MS Windows Active Directory.

SUMMARY
Keycloak is an open-source ICAM solution that can facilitate the management and security of users with
little to no cost. Keycloak allows for several ICAM methodologies, depending on the needs of your
business. It can manage SSO for your business applications and social networks. It can seamlessly
connect to existing LDAP and AD servers for federation purposes. It can even serve as a user store to
manage the fine-grained authorization policies your organization enacted.
For the purposes of this build, we used Keycloak to establish multifactor authentication and SSO with
Google Apps and Slack as the SPs. Although Keycloak can be used for a variety of different SPs, this
guide focuses on Slack. The build criteria area is to connect Keycloak via SSO to Slack utilizing Google
Authenticator for multifactor authentication.
BEFORE YOU BEGIN – A LIST OF HELPFUL TIPS
• Make sure you have Java installed and your JAVA_HOME variable is set
o Open the start menu and select “View Advanced System Settings”
o Select environment variables and create/edit JAVA_HOME to point to where your JDK
is located.
• Keycloak and Commercial SPs require HTTPS communication. Before starting, obtain a
certificate for the host name you are utilizing and create a JKS file for it. Instructions for this
procedure is here.

31
ICAM Implementation Guidance v.2

• Create a cname DNS entry that points to your Keycloak server IP Address. This will allow you to
access the Administration Console from your computer after initial configuration.
• Install either Firefox or Chrome on the Keycloak server. The admin console interface does not
work with IE.

4.1 KEYCLOAK INSTALL AND INITIAL CONFIGURATION

1. Download the Keycloak Server software from here. The software is delivered as a .zip file and
contains both the IdP software and the server component that hosts it.
2. Unzip the Keycloak file to a directory of your choice.
3. Edit the configuration file standalone.xml located in the [Keycloak]/standalone/configuration
directory.
4. If you are hosting the system in a cloud platform, you will need to update the jboss.bind.address
value. Locate the code snippet and update that value with the VM instance IP address. Example
below:

Original:
<interface name="public">
<inet-address value="${jboss.bind.address:127.0.0.1}"/>
</interface>
Updated:
<interface name="public">
<inet-address value="${jboss.bind.address:10.10.10.10}"/>
</interface>
5. If you are using an external DNS you will need to change 3 lines of code
a. Change the “property name” value from “localhost” to your specific hostname
i. Ex: <property name="hostname" value="<enter your hostname>"/>
b. Change the “host name” alias from “localhost” to your specific hostname
i. Ex: <host name="default-host" alias="<enter your hostname>">
c. Change the “remote destination host” from localhost to your hostname
i. Ex: <remote-destination host="<enter your hostname>" port="25"/>
6. Using the command prompt, navigate to the Keycloak/bin folder. Run the standalone.bat
command to start the server. Keycloak does not have a built-in shutdown script. To shut down the
Keycloak server, you will need to Ctrl-C in the command prompt window.

32
ICAM Implementation Guidance v.2

7. You will need to create an admin account to access the admin console. Open a new command
windows and navigate to the Keycloak\bin folder. Run the below script with the required
username and password:
add-user-keycloak.bat -r master -u <username> -p <password>
8. Verify access to admin console by logging in at URL *YourLocalIP*:8080/auth from the server.

4.2 KEYCLOAK USER FEDERATION AND CONFIGURATION

The Keycloak configuration and administration console is where all configurations are stored. The admin
console can be accessed on the server using the URL *YourLocalIP*:8080/auth/admin. The Keycloak
admin console can be accessed externally from https://*Hostname*:8443/auth/admin.
To configure a User Federation and import its LDAP users:
1. Log into the Admin Console and click User Federation from the left navigation.
2. Click the Add Provider button on the top right of the console and select ldap. The window will
refresh and display all the fields necessary to configure access to the LDAP.

33
ICAM Implementation Guidance v.2

3. Configure the fields to access your LDAP service. An example is given below to connect to a
Microsoft AD instance for an AD forest named keycloakst.
• Set Sign Assertions: ON
• Set Force Name ID Format: ON
• Set Name ID Format: email
• Username LDAP attribute: cn
• RDN LDAP attribute: cn
• UUID LDAP attribute: objectGUID
• User Object Classes: person, organizationalPerson, user
• Connection URL: <URL to your AD server> ex: ldap://10.0.X.XXX:389
• Users DN: CN=Users, DC=keycloakst, DC=org
• Authentication Type: simple
• Bind DN: distinct name of your LDAP admin ex: [email protected]
• Bind Credential: <password of admin account>
All other fields can be left as default. There are test buttons associated with the Connection URL
and Bind Credential fields to verify connection to the LDAP.

4. Press Save at the bottom when finished the page will reload.
5. Scroll to the bottom of the page and click Synchronize all users. You will see a confirmation
message when the process is complete
6. Click Users from the left navigation
7. Click View All Users to ensure that the User Federation has updated the user store appropriately

34
ICAM Implementation Guidance v.2

4.3 ADDING A CLIENT TO KEYCLOAK

Keycloak refers to service providers as “Clients.” In our case the SP we are using is Slack utilizing
SAML for our client protocol.
Part 1 on Keycloak
1. Log into Keycloak with an administrator account
2. Create a new Realm to manage your clients and associated users.
3. Roll over Master in the top left corner and click Add Realm.
4. Give the Realm a Name. Realm names must not contain spaces. Click Create. The page will
reload.
5. Select the Login tab on the top navigation.
6. Set User Registration to ON. Set Require SSL to none. Click Save.
7. Select the Tokens tab from the top navigation.
8. Change Default Signature Algorithm to RS256. Click Save.
9. Select the Client Registration tab from the top navigation.
10. Click Create in the Initial Access Tokens tab.
11. Leave the fields as default. Click Save.
12. Click Client from the left navigation and click Create.
13. Fill in the Client ID section with the URL of your service provider (e.g. https://wso2st.slack.com)
and specify the client protocol (saml) from the dropdown menu. Leave the Client SAML
Endpoint blank.
14. Click Save. The page will refresh automatically with additional fields.
15. Verify that the Signature Algorithm field matches the Default Signature Algorithm you
configured earlier. This can be checked under Realm Settings.
16. Change SAML Signature Key Name to NONE.
17. Update Name ID Format to email.
18. Fill in the Valid Redirect URI field. This should be the same URL as your service provider. See
the example below. The /* at the end of the URL is required.
Ex: https://wso2st.slack.com/*
19. Specify a Master SAML Processing URL. This should be your client url followed by /sso/saml.
Ex: https://wso2st.slack.com/sso/saml
20. Click Save.
21. Select the Mappers tab from the top navigation. Click Create to configure the user attributes.
22. Click on the Mapper Type field and select User Property from the dropdown. New fields will
appear.
23. Configure the new fields as indicated below:
Property: email
SAML Attribute Name: User.Email
SAML Attribute NameFormat: Unspecified

35
ICAM Implementation Guidance v.2

4.4 CONFIGURE KEYCLOAK AS THE MFA PROVIDER FOR SLACK

1. Sign into your Slack instance with an administrator account.
2. Navigate to Administration - Workplace settings.
3. Select the Authentication tab.
4. Click Configure next to the SAML Authentication option.
5. For SAML 2.0 Endpoint (HTTP) enter in the public URL for your Keycloak instance followed
by /auth/realms/<the realm you created>/protocol/saml/
6. For Identity provider Issuer enter the URL of Keycloak followed by /auth/realms/<realm you
created>
7. Obtain the public certificate from Keycloak. Log in to the Keycloak admin console and navigate
to the Keys tab from the top navigation of the Realm Settings.
8. Click Certificate. Copy and Paste the certificate data into the Public Certificate field in Slack.

9. Under the Advanced Options tab, click Expand and unselect Sign Authnrequest and Sign
Responses. The Service Provider Issuer URL should be the URL of your Slack instance (e.g.
wso2st.slack.com).

36
ICAM Implementation Guidance v.2

4.5 ENABLING MULTIFACTOR AUTHENTICATION USING KEYCLOAK

1. Open Keycloak admin page.
2. Click on Authentication from the left navigation.
3. In the default Flows tab, set OTP form to Required.
4. Click on the OTP Policy tab from the top navigation.
5. Set OTP Type to Time Based and update Look Ahead Window to 3.
6. Click Save.
Multifactor authentication will now be required for all users accessing the Service Provider (e.g. Slack).
See below for instructions on configuring Google Authenticator as the second factor.

Configure Google Authenticator for User in Slack

1. Download Google Authenticator onto the user’s phone.
2. Follow the screen prompts.
3. Log into Slack. If you are already logged in, sign out and sign back in.

37
ICAM Implementation Guidance v.2

4. After signing in with the username and password, have the user scan the one-time Keycloak QR
code via Google Authenticator.

5. Enter the code provided by Google Authenticator into Keycloak.

The user will now be prompted to provide a Google Authenticator token upon signing into SP.

38
ICAM Implementation Guidance v.2

5 DUO ACCESS GATEWAY IMPLEMENTATION GUIDE

Figure 5 - Duo Access Gateway SSO

Duo Access Gateway (DAG) adds two-factor authentication, complete with inline self-service enrollment,
to popular cloud services. DAG’s capabilities include SSO and Microsoft AD/LDAP integration. This
build was performed in an AWS environment and used AD as its connected user source. For the purposes
of this build, DAG facilitated multifactor authentication and provided a user-friendly SSO dashboard with
access to Slack, Dropbox and G Suite SPs. Duo Mobile was used for the second authentication factor and
each SP was configured for SSO using security assertion markup language (SAML) 2.0 protocol.
Because DAG has robust, publicly available documentation, this Implementation Guide provides links
that send the reader to the Duo website as a reference for most of the build steps.

39
ICAM Implementation Guidance v.2

BEFORE YOU BEGIN – A LIST OF HELPFUL TIPS

 Ensure that all pre-configuration is accurate to avoid errors throughout setup process.
 For many commercial applications, organizations need to have the right commercial plan to
implement SSO.
 Remove any conflicting metadata that may interfere with configuration.
TO BEGIN
Before setting up DAG, organizations should first review all documentation to fully understand the
system requirements and prerequisites required for a successful implementation of the software. A good
starting point can be found on the Duo Access Gateway for Windows Overview page.

5.1 INSTALL AND CONFIGURE DAG

Before installation, DAG installer verifies the system prerequisites and exits if any are missing.
Installation and configuration documentation, including steps for configuring the organization’s
authentication source, can be found under the Install Duo Access Gateway header, on the Duo Access
Gateway for Windows page.

5.2 CONNECT CLOUD APPLICATIONS

Create, add and configure your cloud applications to the DAG.

5.3 CONFIGURE DAG FOR MULTIFACTOR AUTHENTICATION

DAG allows for an organization’s users to self-enroll in multifactor authentication with their own factors.
An organization must first enable the self-service portal. Once enabled, an organization’s users can
register their devices and other factors for multifactor authentication; documentation can be found on the
Duo Guide to Two-Factor Authentication page under the Adding a new device header.

5.4 ENABLE DAG LAUNCHER APPLICATION

Duo Access Gateway Launcher is an application internal to DAG that, when enabled, provides a user-
friendly SSO portal from which users can access their personal DAG-protected service provider
applications. The Launcher itself can also be configured to require multifactor authentication. The
Launcher was set up and used as part of this build. Specific information on the configuration of DAG
Launcher can be found on the Duo Access Gateway for Windows Overview page under the Enable the
Duo Access Gateway Launcher.

40
ICAM Implementation Guidance v.2

6 OKTA IDENTITY CLOUD IMPLEMENTATION GUIDE

Figure 6 - Okta Identity Cloud SSO Build Architecture

Okta Identity Cloud (Okta) is a cloud-based IdP that integrates with on-premises and other cloud-based
applications. Okta’s capabilities include provisioning, SSO and Microsoft AD/LDAP integration. The
build created by our engineering team used AD within an AWS environment as its user source. The users
on the domain controller were synced to Okta Identity Cloud via the Okta agent software. Okta facilitated
multifactor authentication and provided an SSO dashboard with user access to Slack, Dropbox and G
Suite SPs. A personal identity verification interoperable (PIV-I) card with a PIN was used as the second
authentication factor, and each SP was configured for SSO using SAML 2.0 protocol.
Okta has a robust library of documentation, so instead of specifying every detail, this implementation
guide discusses the proper order for installation and configuration, with supplemental links to the relevant
Okta pages.

41
ICAM Implementation Guidance v.2

BEFORE YOU BEGIN – A LIST OF HELPFUL TIPS

 Familiarize yourself with Okta terminology through the Okta Help Center, Okta Terminology
page.
 Remove any conflicting metadata that may interfere with configuration.
 Customize your organization’s parameter values before configuring SAML 2.0.
 Enable the “Multiple Sign-In” feature in G-Suite and use a “Backdoor URL” to allow the
administrator access without a SAML assertion. 7
 Okta supports PIV and PIV-I cards, but that feature needs to be enabled by Okta.

TO BEGIN
Okta is a cloud-based identity management solution. Once a plan is purchased, Okta sends the
organization’s administrator a link to the application. A good place to begin is on the Okta Help Center's
Getting Started as a New Okta Administrator page.
CONNECTING A DOMAIN CONTROLLER
If you do not already have a domain controller installed and configured, follow Microsoft’s instructions
on how to configure the domain controller.
Once your domain controller is configured and installed for your organization, follow Okta’s installation
and configuration guide for the Okta Active Directory Agent, found on the Okta Help Center's Install and
Configure the Okta Active Directory Agent page.

6.1 SERVICE PROVIDER CONFIGURATION

Now that Okta is connected to your domain controller, you need to configure your service providers. The
three selected below are available, along with thousands of pre-integrated apps.
1. Slack Configuration
a. Configure Slack for SAML 2.0. Documentation can be found on Okta's How to Configure
SAML 2.0 for Slack page.
b. Configure provisioning within Okta for Slack. Documentation can be found on Okta's
Configuring Provisioning for Slack page.
2. Dropbox Configuration
a. Configure Dropbox. Documentation can be found on Okta's Configuring Provisioning for
Dropbox Business page.
3. G Suite Configuration
a. Configure G Suite for SAML 2.0. Documentation can be found on Okta's How to Configure
SAML 2.0 for G Suite.
b. Configure provisioning within Okta for G Suite. Documentation can be found on Okta Help
Center's Configuring Provisioning for G Suite page.

7
https://support.okta.com/help/Documentation/Knowledge_Article/Google-Apps-Deployment-Guide

42
ICAM Implementation Guidance v.2

Once everything is properly configured, your Okta dashboard will look like this:

6.2 PIV-I CONFIGURATION

Once your service providers are configured, the addition of a second authentication factor is strongly
recommended before users obtain access to Okta. We used a PIV-I card. Steps for PIV configuration can
be found on Okta's Identify Providers page (click on “Add a PIV card”).

CHANGE MANAGEMENT
Okta Help Center's End User Adoption Toolkit provides helpful information to download the End User
Adoption kit.

43