STEP Authentication

External authentication of STEP users

Version 1.0.0
Table of Contents
Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
 

LDAP integration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1  

Basic usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
 

User Authentication via LDAP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1  

Groups and attributes synchronization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2  

Group synchronization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3  

Attributes Synchronization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4  

Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
 

Password expiration warning. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5  

Communication with the LDAP server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5  

Authentication via GSSAPI/Kerberos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5  

Authentication via LDAP over SSL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6  

Support for connecting to multiple LDAP servers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6  

The STEP search mechanism for LDAP directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6  

Support for multiple LDAP domains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7  

Inserting the ldap domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9  

Configuring login patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9  

LDAP configuration properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9  

Global properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 

LDAP Server specific properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10  

Properties used for synchronization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11  

Properties used for changing LDAP passwords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12  

LDAP configuration examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12  

Simple authentication, no SSL, multiple search queries, user synchronization . . . . . . . . . . . . . . . . . . . 12  

STEP Single Sign On solutions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17  

Enabling and configuring SSO solutions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17  

Kerberos Single Sign On . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18  

Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
 

Setting up Kerberos SSO, client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19  

Setting up Kerberos SSO, LDAP server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20  

Kerberos SSO and multiple LDAP domains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21  

Example for setting up SSO, STEP application server and LDAP servers . . . . . . . . . . . . . . . . . . . . . . . . . 22  

Trusted Headers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25  

Trusted Headers Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26  

STEP Settings for Trusted Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26  

Trusted headers and LDAP integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27  

 Trusted headers and Excel Smartsheets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27  

Auth 2.0 with Google Accounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29  

OAuth Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
 

OAuth configuration properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30  

OAuth configuration example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31  

Configuration examples for multiple authentication mechanisms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31  

Kerberos SSO + Trusted headers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31  

Workbench Expiry Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32  

IMPORTANT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32  

Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
 

SAML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
 

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
 

Usage flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
 

User synchronization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34  

Logout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
 

Usage with other authentication plugins. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36  

Skipping Web UI SAML Authentication. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37  

Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 

Example settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49  

Workbench SSO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50  

Smartsheet SSO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51  

STEP Logout behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51  

Workbench 3rd Party Proxy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52  

Use browser settings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52  

Use proxy server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52  

OAuth2-Based Authentication for SaaS customers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52  

User Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 

HTTP-Based APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53  

Integrations from 3rd Party User Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53  

Machine to Machine Integrations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53  

User Federation and Identity Brokering. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53  

Http Authentication Test Tool. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54  

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
 

Tool access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
 

Test configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54  

Test Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
 

User not automatically authenticated . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55  

User automatically authenticated as “username” . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55  

 “message” returned ‘Responded’ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55  

Fatal error occurred | No state | No session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55  

HTTP ERROR 401 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55  

Limitations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
 

User Synchronization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55  

Caveats. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
 

Appendix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
 

Deprecated LDAP configuration properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56  

Basic properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56  

Basic properties (SSL) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57  

Basic properties (Kerberos) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57  

User Synchronization properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57  

Additional features properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58  

Single-Sign-On properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58  

Additional seldom used properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58  

Configuration examples for the deprecated configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58  

Kerberos configuration - LegacySSO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58  

OAuth configuration properties – LegacyGoogleAccountOAuth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60  

Auth configuration example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60  

Setting up SSO, LDAP server, using the deprecated configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61  

Setting up SSO, STEP application server, using the deprecated configuration . . . . . . . . . . . . . . . . . . . . . . 62  

Trusted Headers – deprecated configuration and behavior (LegacyTrustedHeaders) . . . . . . . . . . . . . . . . 62  

About Stibo Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63  

Introduction
Step offers the option to delegate the maintenance of user passwords from the Step database to LDAP
repositories or authentication proxies, as well as Single Sign On solutions.

This document describes how Step functionality for LDAP integration (authentication and user
synchronization) and the Single Sign On solutions supported by Step work, and how they can be
configured.

LDAP integration
Basic usage
STEP offers the option to validate passwords in one or more LDAP repositories like Microsoft Active
Directory, for example. This means that users can use the same password for STEP as they use for logging
on to their computer and in other applications.

Once the connection to an LDAP server has been set up and configured in STEP, the users must use the
user name and password registered in the LDAP server when logging on to STEP. Users must still be
created as users in STEP and placed in STEP user groups before they can log on. If preferred, users can be
created automatically based on synchronization of group associations, as described below. It is not
sufficient to have users in the LDAP repository since that would not provide any information about STEP
user groups or privileges.

When using STEP LDAP, access to password maintenance must take place in the LDAP repository,
according to the rules set up there.

User Authentication via LDAP

In order to authenticate against an LDAP server, the LDAP integration has to be enabled via the property
“LDAP.Enabled” and the necessary configuration must be set (further explanation can be found in
properties description and examples).

When authenticating a user, STEP will first search for the user ID provided at login. If the user is found,
STEP will retrieve the user distinguished name (UDN) and use this in order to perform authentication.

If multiple users are found by the search, STEP will throw an exception and forbid connection. If no users
are found by the search, STEP will throw an exception and forbid connection. The query used for this
search is configurable, so it can be written to only return users that are not disabled.

The diagram below illustrates the sequence flow in a use case scenario for authentication and user
synchronization, which involves two LDAP servers configured, with multiple search queries for the first
server.

© Stibo Systems - Confidential 1

Groups and attributes synchronization
STEP offers a feature that enables synchronization of users and user attributes from LDAP to STEP,
meaning that users that only exist in LDAP can be automatically created in STEP during logon - so long as
the associated STEP user groups can be determined.

Once the user has been found in LDAP and authentication was successful, STEP will attempt to
synchronize the user’s group memberships and attributes.

NOTE Groups and attribute synchronization are both optional.

2 © Stibo Systems - Confidential

Group synchronization

After successfully authenticating the user, STEP will attempt to perform group synchronization.

In order for it to happen, group synchronization must be enabled using the

“LDAP.Resource.n.Synchronize.GroupMembership” configuration property.

If group synchronization is enabled, then the user’s STEP group memberships are synchronized to the
LDAP group memberships. If the user doesn’t exist in STEP, he/she will be created as part of the
synchronization process.

If group synchronization is disabled, the user must have already been created in STEP in
NOTE
order to log in. Otherwise, the user’s login will be rejected.

Once the user is found and authenticated, the user’s LDAP group memberships are determined. If the
user is not a member of any LDAP groups, the user’s login attempt is rejected.

The next step is to lookup all STEP groups. For each STEP group that has a value in the LDAP
Synchronization ID attribute, the value of LDAP Synchronization ID is matched against the list of LDAP
groups. If a match is found, the user will be created in this STEP group if not already there. If no match is
found, the user is removed from that STEP group.

If the group that the user belongs to in LDAP has no mapping in STEP (there are no STEP groups with that
synchronization ID), the login attempt is rejected unless one or more ‘default groups’ are setup for LDAP
synchronization. A default group is just a user group that is marked as “Default LDAP group”. If such
groups are configured, then the users that cannot be placed in any other groups will be added to the
default groups and will get the privileges set up for those groups.

© Stibo Systems - Confidential 3

Group attribute "LDAP Synchronization ID" - groups that should be subject for synchronization with
LDAP, MUST have a value in the LDAP Synchronization ID attribute. The value of LDAP Synchronization ID
must match the desired name or the fully qualified distinguished name of the LDAP group.

Group attribute "Default LDAP group" - groups that will be used as default synchronization groups, i.e.
if a user is attempting to login with valid credentials, but the groups he belongs to are not mapped in
STEP, he will then be added to the default groups.

Attributes Synchronization

Step has the capability of synchronizing a user’s STEP attributes from his/her attributes in LDAP. In order
to enable this functionality, the attributes that should be synchronized have to be configured in the
LDAP.Resource.n.Synchronize.Attributes property.

E.g.: LDAP.Resource.n.Synchronize.Attributes=%email=mail,?common_name=cn

In the above example, the key (%email) is the Step attribute ID and the second value (mail) is the name of
the LDAP attribute where the value should be taken from. Using this configuration, STEP will synchronize
the user’s email in STEP with the value in LDAP.

“common_name” is marked with a question mark, meaning that STEP will only synchronize it if the STEP
user object has the “common_name” STEP attribute.

If attribute synchronization is not desired, leave this configuration out.

4 © Stibo Systems - Confidential

Limitations

The synchronization solution does not take privileges into account. Even though the company’s LDAP may
be set up to handle a set of privileges, synchronization of group membership ONLY considers group
names. If additional privileges need to be added to a STEP group, this must be done manually. This
solution is a one-time synchronization on login from a STEP Web Ui application or STEP Workbench.

The LDAP user synchronization is only supported through STEP Workbench and STEP Web Ui.

Password expiration warning

It is possible to enable warnings during login when the LDAP password of the user is about to expire, and
to allow changing it from STEP Workbench and Web UI (after the password has expired this is no longer
possible).

Password expiration notification is supported by default only for Microsoft Active

NOTE
Directory.

Communication with the LDAP server

In order to set up STEP LDAP access, there must be a network connection from the STEP application
servers to the LDAP server which enables the STEP application server to validate passwords with the LDAP
repository (typically port 389).

Authentication on the LDAP server may be configured to take place using the following mechanisms
supported by the Simple Authentication and Security Layer (SASL) Internet standard (RFC 2222): .
GSSAPI/Kerberos v5 (also requires access from the application server to a Kerberos Key Distribution
Center) . LDAP over SSL (Secure Socket Layer [TLS/SSL] using x.509 type certificates). . Plain LDAP (not
recommended - for testing only)

Authentication via GSSAPI/Kerberos

The system uses JAAS (Java™ Authentication and Authorization Service) to authenticate a principal to
Kerberos and obtain credentials (a trusted ticket) that proves the user’s identity. This ticket is used with
GSS-API (Generic Security Service API) to establish a secure context to the LDAP server.

Regardless if the user is known in STEP, the user ID and password from the login dialog is used for
authentication against Kerberos and LDAP.

Kerberos configuration - if the customer has used LDAP Authentication before, two necessary
configuration files step-jaas.conf and krb5.conf must be in place:

1. step-jaas.conf: This file specifies which Kerberos plugin to use. Normally, it would be
com.sun.security.auth.module.Krb5LoginModule, but on IBM Websphere systems, it should point out
com.ibm.security.auth.module.Krb5LoginModule. The entries “spnego-client” and “spnego-server” are
used by the STEP standard web ui Single-Sign-On (SSO) solution. If SSO is enabled, this file would

© Stibo Systems - Confidential 5

 normally have these 2 entries and an additional one for non-Single-Sign-On LDAP usage.

2. krb5.conf: The Kerberos configuration file.

The preferred location for these files is: /workarea/ldap. An example for these files can be
NOTE
found in the Configuration examples section.

Authentication via LDAP over SSL

STEP must be configured with information about the LDAP server’s certificate in order to establish secure
transport ("LDAPS"). It is the customer’s responsibility to provide a certificate for the LDAP server and to
provide a keystore/truststore to install on the STEP server. Typically, a client-truststore file will be
generated and put on the file system, reachable from the STEP application.

When using Secure Socket Layer for communication, an X.509 compliant certificate must be provided
from the LDAP server and included in the STEP server’s truststore.

Support for connecting to multiple LDAP servers

STEP can be configured to connect to multiple LDAP servers in order to perform LDAP operations. This is
done by configuring a set of properties for each LDAP server that STEP should connect to. The set of
properties will be referred to as “an LDAP resource”.

The configuration names that STEP should use have to be configured in the property
LDAP.ResourceNames.

Example 1: LDAP.ResourceNames=devConfig,testConfig Example 2:

LDAP.ResourceNames=server1,server2

STEP will only read the configurations for the resources mentioned in that property (server1 and server2
for example), even though the configuration file contains configurations for more than those two
resources. This makes it easy to enable or disable an LDAP configuration – just remove its name from that
list. The rest of the configuration for that resource can be left in the configuration file without affecting
anything since it will not be read by STEP.

When STEP is searching for a user, it will iterate through the resources (in the order mentioned in the
LDAP.ResourceNames) and search in each LDAP server until the user is found. Using the above example,
STEP will try “server1” first and if the user is not found, it will try “server2”. Once the user is found, it is
added to a cache together with a reference to the LDAP server so that, next time STEP needs to perform
an operation for that user (authentication, synchronization), it will connect directly to the LDAP server that
has the user.

The STEP search mechanism for LDAP directories

The LDAP directory model is different from company to company. To be independent of the model, the
search mechanism is made configurable.

6 © Stibo Systems - Confidential

STEP can be configured to use multiple search queries when searching for a user.

When searching, STEP will iterate through the list of queries configured in the
LDAP.Resource.n.QueryNames property (same principle as for the LDAP.ResourceNames). These queries
will be used in the order in which they were configured, and when the user is found, the search is
stopped, even though not all the queries were used. STEP will use only the queries specified in the
QueryNames property. Queries can be left out by removing them from that list. For each search query
that STEP should use, a UserFilter and a UserBaseDN need to be configured. If one of them is missing, or
if no search queries can be used for searching, STEP will throw a configuration error.

E.g.: LDAP.Resource.server1.QueryNames=query1,query2

LDAP.Resource.server1.Query.query1.UserBaseDN=DC=domaintest,DC=corp LDAP.Resource.
server1.Query.query1.UserFilter=(&(sAMAccountName=%u)(userAccountControl=512))

LDAP.Resource. server1.Query.query2.UserBaseDN=DC=domaintest,DC=corp LDAP.Resource.

server1.Query.query2.UserFilter=(userPrincipalName=%u)

In the above example, query1 will search for the user that has the same sAMAccountName as the login ID
and has a normal account (not expired, not disabled, etc.), and query2 will search for a user that has the
same userPrincipalName as the login ID.

Support for multiple LDAP domains

STEP can be configured to use multiple LDAP domains when searching for the user.

When multiple domains are configured, the login interface will have a dropdown menu allowing the user
to select which domain to be used for the search queries. The user also has the option to enter a domain,
if there is a login pattern that will match the input.

If Step is configured with only one LDAP server configuration and multiple ldap domains
NOTE for that configuration (See example Simple authentication – multiple ldap domains), the
LDAP servers must use a global catalogue, which will be the entry point for STEP.

To use multiple ldap domains, the LDAP.Resource.n.DomainIDs property has to be configured.

Example: LDAP.Resource.multi-domains.DomainIDs=D2,ST,test

LDAP.Resource.multi-domains.Domain.D2.Name=domain2,DC=mydomain LDAP.Resource.multi-
domains.Domain.D2.DisplayName=domain2

LDAP.Resource.multi-domains.Domain.ST.Name=steptest

In the above example, there are three domains configured: domain2, steptest and test.

The DomainIDs list contains three IDs: D2, ST and test. These IDs will be used for generating the STEP
user ID, which will have the following format: USER@DOMAINID. Using the above configuration, the users

© Stibo Systems - Confidential 7

from these domains will have the following STEP user IDs: * Domain2: USER@D2 * Steptest: USER@ST *
TEST: USER@TEST

Using domain IDs when creating the STEP user ID removes the problem caused by very long domain
names. For example, when appended to the user ID, the STEP user ID becomes very long and might
exceed the limit in the database.

When the user logs in to STEP (either workbench or web ui), he/she selects the domain to be used from a
dropdown list, which contains the domain display name. If the domain display name is not configured,
then the list will contain the domain name. If there is no domain name, the list will contain the ID. The list
will also contain an empty line, which can be used when there is no domain to be used for the user (e.g.
step service- or superusers such as stepsys or dba). The above example illustrates all three cases:

The selected domain is used depending on how the search queries have been configured. Below are two
examples of search queries using the domain chosen during login.

Example 1: LDAP.Resource.multi-domains.QueryNames=query1

LDAP.Resource.multi-domains.Query.query1.UserBaseDN=DC=%d,DC=corp LDAP.Resource.multi-
domains.Query.query1.UserFilter=(sAMAccountName=%u)

In this example, the domain is used for the UserBaseDN. %d will be replaced with the name of the
selected domain.

For domain2, the UserBaseDN value will be “DC=domain2,DC= mydomain,DC=corp”. For steptest it will be
“DC=steptest,DC=corp”. For test it will be “DC=test,DC=corp”.

Example 2: In this example, the domain is used in order to construct the user principal name.

LDAP.Resource.multi-domains.DomainIDs=D2,ST,test LDAP.Resource.multi-
domains.Domain.D2.Name=domain2.mydomain.corp LDAP.Resource.multi-
domains.Domain.D2.DisplayName=domain2 LDAP.Resource.multi-
domains.Domain.ST.Name=steptest.corp

LDAP.Resource.multi-domains.QueryNames=query

8 © Stibo Systems - Confidential

LDAP.Resource.multi-domains.Query.query.UserBaseDN=DC= mydomain,DC=corp LDAP.Resource.multi-
domains.Query.query.UserFilter=(userPrincipalName=%u@%d)

In this configuration, the user principal name will be equal to:

For domain2: userPrincipalName = user@domain2.mydomain.corp For steptest: userPrincipalName =

user@steptest.corp

Inserting the ldap domain

As mentioned above, STEP can also be configured to allows users to type the domain name manually, as
part of their login username. For this to work, login patterns have to be configured so STEP knows how to
extract the username and the domain from the input provided by the user.

Example: LDAP.Resource.multi-domains.LoginIdPatterns=(?<domain>.?)\\\\(?<user>.?),(?<user>.*?)

This pattern will match the following input: domain\user. If the user inserts a domain, this will be used
instead of the one selected in the dropdown menu.

Configuring login patterns

STEP has the option of configuring login patterns for each LDAP resource. When searching for the user, if
the input does not match the configured login patterns for that resource, STEP won’t contact the LDAP
server. Instead, it will try to match the username to the next resource configured. If the username does
not match any login patterns, login is forbidden.

STEP uses regular expressions with named groups for the login patterns.

The names of the groups are “user” and “domain”. The “user” group is required.

Example for configuration: LDAP.Resource.multi-domains.LoginIdPatterns=(?<domain>.

?)\\\\(?<user>.?),(?<user>.*?)

1. (?<domain>.?)\\\\(?<user>.?) This pattern uses both a user and a domain group. Both of these will
accept any character and are separate by a backslash. Note that there’s four backslashes, as the
“backslash” character in properties files and regular expressions is a reserved character that needs to
be “escaped”. This pattern will match any input of type “domain\user” e.g. “steptest\user”. STEP will
extract the domain value and the user id value from the input based on the groups configured. These
values are then used in search queries.

2. (?<user>.*?) This pattern will accept any kind of input from the user, but it will be treated as a user ID.
STEP will not attempt to extract a domain, since this group is not configured.

LDAP configuration properties

There are 2 different types of properties: global properties (they apply for all the LDAP servers configured)
and properties specific for each LDAP server.

© Stibo Systems - Confidential 9

 Single Sign On is only supported by the deprecated configuration properties. Please see
NOTE the Single Sign On (SSO) and the Deprecated configuration properties for how to
configure Single Sign On.

Global properties

Property Description

LDAP.Enabled Enable LDAP authentication of all requests

LDAP.InitialContextfactory The fully qualified name of the Initial Context factory to use for LDAP
JNDI lookup. Default is "com.sun.jndi.ldap.LdapCtxFactory", which
will be the typical value to use.

LDAP.Timeout The time in minutes to cache the authentication of a user. This is

optional and defaults to 15 minutes.

LDAP.KerberosConfigurationFile Location for the Kerberos configuration file.

LDAP.JAASConfigurationFile Location of the JAAS configuration file

SSL.TruststorePassword The password to use for accessing the truststore.

LDAP.ResourceNames A comma separated list of strings. It contains the names of the ldap
connections that STEP should use. STEP will connect to the servers in
the order they have been added to this list.

Global SSO properties

Property Description

LDAP.Preauthentication.UserName Property used with the SPNEGO Kerberos single-sign web ui solution
to specify the Principal used for pre-authentication. Not used at all
for ordinary LDAP operations.

LDAP.Preauthentication.Password Property used with the SPNEGO Kerberos single-sign web ui solution
to specify the Password used for pre-authentication.

LDAP Server specific properties

In the properties names below, “n” represents the LDAP configuration name, which has to
NOTE
be present in the “LDAP.ResourceNames” list in order to be used.

“m” represents the query name, which needs to be present in the “LDAP.Resource.n.QueryNames” list in
order to be used.

Property Description

LDAP.Resource.n.ServerURL The URL of the company’s LDAP server, e.g.:

ldap://ad‑server.mycompany.com:389.

LDAP.Resource.n.BindAccount.DN The bind account used when searching after users, user groups,
attributes and changing passwords. It is NOT used for Web UI SSO
authentication mechanisms. The Web UI standard SSO has its own
property LDAP.Preauthentication.UserName which it uses as Bind
account. The format should always be: user@realm for Kerberos,
UDN for simple authentication

10 © Stibo Systems - Confidential

Property Description

LDAP.Resource.n.BindAccount.Password The password for the bind account.

LDAP.Resource.n.AuthenticationMechanism Default is "simple", which will typically be used with SSL. Alternatively
use “GSSAPI” (Kerberos).

LDAP.Resource.n.SecurityProtocol The protocol to use for communicating with the LDAP server. Set this
to ssl if you wish to communicate via secure socket layer. Otherwise
leave blank (which is the default).

LDAP.Resource.n.JAASConfigurationEntryName Name of the entry in the JAAS configuration file to use. Typical value
is "STEP".

LDAP.Resource.n.QueryNames A comma separated list of strings. Used for specifying the search
query names. The names will be referenced by the
“LDAP.Resource.n.Query.m” properties.

LDAP.Resource.n.Query.m.UserBaseDN The DN base used for searches specific for user attributes. The value
may contain a “%d” which will be replaced with the domain entered
by users at login time when using multi domains.

LDAP.Resource.n.Query.m.UserFilter The filter to use for looking up a user in LDAP. This filter may contain
the attribute to use for locating a userid. %u (e.g.:
"(sAMAccountName=%u)"). At runtime it will be replaced by
username from login. It may also contain a “%d” which will be
replaced with the domain entered by users during login.

LDAP.Resource.n.LoginIdPatterns A comma separated list of regular expressions with named groups

representing the patterns used for the login ID. For the pattern
describing the user, use "user" as the group name. For the pattern
describing the domain, use "domain" as the group name. Default is
(?<user>.*?) – this allows any kind of user ID to be used for login. If
the login ID does not match the login patterns, login is not
permitted.

LDAP.Resource.n.DomainIDs A comma separated list of strings. Used for specifying the IDs of the
login domains. If only one domain, leave out (default).

LDAP.Resource.n.Domain.d.Name The name of the domain. “d” represents the ID configured in the
LDAP.Resource.n.Domains. Used to replace “%d” in the search
queries. If blank, it will be replaced by the domain ID.

LDAP.Resource.n.Domain.d.DisplayName The text that will be used in order to display the domain in the GUI.
“d” represents the domain ID configured in
LDAP.Resource.n.Domains. If blank, it will be replaced by the
LDAP.Resource.n.Domain.d.Name

Properties used for synchronization

Property Description

LDAP.Resource.n.Synchronize.GroupMembership Set this to true to synchronize the group memberships of the user.
I.e. if the user is member of a LDAP group that is marked in STEP as
LDAP managed, this membership will be inherited in STEP. In fact,
this allows an unknown STEP user to be automatically created in
STEP if he is authorized against LDAP and at least one LDAP group
membership matches a STEP group. Default set to false.

LDAP.Resource.n.Synchronize.GroupMembership.Attribute This is the name of the attribute in LDAP that contains membership.
If this property is blank or doesn’t exist, and group synchronization is
enabled, STEP will throw an error.

© Stibo Systems - Confidential 11

Property Description

LDAP.Resource.n.Synchronize.Attributes A comma separated list of LDAP attributes that should be

synchronized into STEP. The values configured are “key=value” pairs
where the key is the STEP attribute ID and the value is the name of
the ldap attribute that should be synchronized with that Step
attribute. e.g.: title=userTitle ,%email=mail (title is the STEP attribute
ID, userTitle is the LDAP attribute). There are 2 special types of STEP
attributes: email and name. These have to be configured with “%” in
front of the step attribute. It also supports adding a “?” before the
step attribute to mark that the attribute should be synchronized only
if it exists for the user.

LDAP.Resource.n.Synchronize.GroupMembership.Revoke Control whether STEP will remove the users from STEP groups not
contained in the ldap group query. Default set to true, meaning the
group membership in STEP will always mirror the group membership
from LDAP. Please note that if disabled, the group membership from
ldap is not reflected in STEP and this can lead to users having more
privileges than intended!

Properties used for changing LDAP passwords

Property Description

LDAP.Resource.n.AllowChangePassword Set this to true to be able to change passwords in LDAP. For some
ldap servers, it will only work if the security protocol is ssl. Default set
to false.

LDAP.Resource.n.PasswordPolicy.DN The distinguished name for which the password policy is enabled

LDAP.Resource.n.ChangePasswordAttributeName The name of the attribute for the user password in ldap.

LDAP.Resource.n.ServerType The name of the ldap server type (e.g: MicrosoftAD). To be used
when performing server specific operations like getting the
password expiration date. STEP will use this server type ID in order to
determine how to handle the specific operations. Server type IDs
currently supported: MicrosoftAD

LDAP.Resource.n.NotifyDaysBeforeExpire Upon login, the user will be notified about his LDAP password expiry
the specified number of days before. Default set to 10.

LDAP configuration examples

Simple authentication, no SSL, multiple search queries, user synchronization

12 © Stibo Systems - Confidential

 LDAP.Enabled=true
LDAP.ResourceNames=simple-auth
LDAP.Timeout=15
LDAP.InitialContextfactory=com.sun.jndi.ldap.LdapCtxFactory
LDAP.Resource.simple-auth.ServerURL= ldap://ldapserver.company.com:389 LDAP.Resource.simple-auth.BindAccount.DN=
CN=TestUser,CN=Users,DC=company,DC=com

LDAP.Resource.simple-auth.BindAccount.Password=password
LDAP.Resource.simple-auth.AuthenticationMechanisms=simple
LDAP.Resource.simple-auth.SecurityProtocol=simple

LDAP.Resource.simple-auth.QueryNames=query1,query2

LDAP.Resource.simple-auth.Query.query1.UserBaseDN=DC=company,DC=com
LDAP.Resource.simple-auth.Query.query1.UserFilter=(&(sAMAccountName=%u)(userAccountControl=512))

LDAP.Resource.simple-auth.Query.query2.UserBaseDN=DC= company-fr,DC=com
LDAP.Resource.simple-auth.Query.query2.UserFilter=(sAMAccountName=%u)

LDAP.Resource.simple-auth.Synchronize.GroupMembership.Attribute=memberOf
LDAP.Resource.simple-auth.Synchronize.GroupMembership=true
LDAP.Resource.simple-auth.Synchronize.Attributes=%email=mail

SSL authentication, no user synchronization, change password enabled

LDAP.Enabled=true
LDAP.ResourceNames=ssl-auth
LDAP.Timeout=15
LDAP.InitialContextfactory=com.sun.jndi.ldap.LdapCtxFactory
SSL.Truststore=path to truststore
SSL.TruststorePassword=password

LDAP.Resource.ssl-auth.ServerURL=ldaps://ldapserver.company.com:636
LDAP.Resource.ssl-auth.BindAccount.DN= CN=TestUser,CN=Users,DC=company,DC=com
LDAP.Resource.ssl-auth.BindAccount.Password=password
LDAP.Resource.ssl-auth.AuthenticationMechanisms=simple
LDAP.Resource.ssl-auth.SecurityProtocol=ssl

LDAP.Resource.ssl-auth.QueryNames=query1
LDAP.Resource.ssl-auth.Query.query1.UserBaseDN=DC=company,DC=com
LDAP.Resource.ssl-auth.Query.query1.UserFilter=(&(sAMAccountName=%u)(userAccountControl=512))

LDAP.Resource.ssl-auth.Query.query2.UserBaseDN=DC=company-fr,DC=com
LDAP.Resource.ssl-auth.Query.query2.UserFilter=(sAMAccountName=%u)

LDAP.Resource.ssl-auth.AllowChangePassword=true
LDAP.Resource.ssl-auth.PasswordPolicy.DN=DC=company,DC=com
LDAP.Resource.ssl-auth.ChangePasswordAttributeName=unicodePwd
LDAP.Resource.ssl-auth.NotifyDaysBeforeExpire=10
LDAP.Resource.ssl-auth.ServerType=MicrosoftAD

© Stibo Systems - Confidential 13

GSSAPI (Kerberos) authentication

LDAP.Enabled=true
LDAP.ResourceNames=gssapi-auth
LDAP.Timeout=15
LDAP.InitialContextfactory=com.sun.jndi.ldap.LdapCtxFactory
LDAP.KerberosConfigurationFile=../ldap/krb5.conf
LDAP.JAASConfigurationFile=../ldap/step-jaas.conf

LDAP.Resource.gssapi-auth.ServerURL=ldap://ldapserver.company.com:389
LDAP.Resource.gssapi-auth.BindAccount.DN=binduser@company.com
LDAP.Resource.gssapi-auth.BindAccount.Password=password
LDAP.Resource.gssapi-auth.AuthenticationMechanisms=GSSAPI
LDAP.Resource.gssapi-auth.SecurityProtocol=simple
LDAP.Resource.gssapi-auth.JAASConfigurationEntryName=STEP
LDAP.Resource.gssapi-auth.QueryNames=query1

LDAP.Resource.gssapi-auth.Query.query1.UserBaseDN=DC=comapny,DC=com
LDAP.Resource.gssapi-auth.Query.query1.UserFilter=(sAMAccountName=%u)

LDAP.Resource.gssapi-auth.Synchronize.GroupMembership.Attribute=memberOf
LDAP.Resource.gssapi-auth.Synchronize.GroupMembership=true
LDAP.Resource.gssapi-auth.Synchronize.Attributes=%email=mail

Multiple ldap servers, GSSAPI authentication

14 © Stibo Systems - Confidential

 LDAP.Enabled=true
LDAP.ResourceNames=gssapi-auth,server2-gssapi
LDAP.Timeout=15
LDAP.InitialContextfactory=com.sun.jndi.ldap.LdapCtxFactory
LDAP.KerberosConfigurationFile=../ldap/krb5.conf
LDAP.JAASConfigurationFile=../ldap/step-jaas.conf

#----------------------------------------------------
#LDAP Settings - gssapi-auth configuration
#----------------------------------------------------
LDAP.Resource.gssapi-auth.ServerURL=ldap://ldapserver.company.com:389
LDAP.Resource.gssapi-auth.BindAccount.DN=binduser@company.com
LDAP.Resource.gssapi-auth.BindAccount.Password=password
LDAP.Resource.gssapi-auth.AuthenticationMechanisms=GSSAPI
LDAP.Resource.gssapi-auth.SecurityProtocol=simple
LDAP.Resource.gssapi-auth.JAASConfigurationEntryName=STEP
LDAP.Resource.gssapi-auth.QueryNames=query1

LDAP.Resource.gssapi-auth.Query.query1.UserBaseDN=DC=comapny,DC=com
LDAP.Resource.gssapi-auth.Query.query1.UserFilter=(sAMAccountName=%u)

LDAP.Resource.gssapi-auth.Synchronize.GroupMembership.Attribute=memberOf
LDAP.Resource.gssapi-auth.Synchronize.GroupMembership=true
LDAP.Resource.gssapi-auth.Synchronize.Attributes=%email=mail

#----------------------------------------------------
#LDAP Settings - server2-gssapi configuration
#----------------------------------------------------
LDAP.Resource.server2-gssapi.ServerURL=ldap://ldap-anotherserver.ldaptest.corp:389
LDAP.Resource.server2-gssapi.BindAccount.DN=user@ldaptest.corp
LDAP.Resource.server2-gssapi.BindAccount.Password=mypass
LDAP.Resource.server2-gssapi.AuthenticationMechanisms=GSSAPI
LDAP.Resource.server2-gssapi.SecurityProtocol=simple
LDAP.Resource.server2-gssapi.JAASConfigurationEntryName=GSSApiEntry2
LDAP.Resource.server2-gssapi.QueryNames=findUser

LDAP.Resource.server2-gssapi.Query.findUser.UserBaseDN=DC=steptest,DC=corp
LDAP.Resource.server2-gssapi.Query.findUser.UserFilter=(sAMAccountName=%u)

LDAP.Resource.server2-gssapi.Synchronize.GroupMembership.Attribute=memberOf
LDAP.Resource.server2-gssapi.Synchronize.GroupMembership=true
LDAP.Resource.server2-gssapi.Synchronize.Attributes=%email=mail

krb5.conf file

© Stibo Systems - Confidential 15

 [libdefaults]
  default_realm = COMPANY.COM
  default_tkt_enctypes = aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha1-96 rc4-hmac
  default_tgs_enctypes = aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha1-96 rc4-hmac
  udp_preference_limit = 1

[realms]
  COMPANY.COM = {
  kdc = ldapserver.company.com:88
  default_domain = COMPANY.COM
  }
  LDAPTEST.CORP = {
  kdc = ldap-anotherserver.ldaptest.corp:88
  default_domain = LDAPTEST.CORP

  }

[domain_realm]
  .company.com = COMPANY.COM
  company.com = COMPANY.COM
  .ldaptest.corp = LDAPTEST.CORP
  ldaptest.corp = LDAPTEST.CORP

[logging]
  kdc = FILE:krb5kdc.log
  default = FILE:krb5lib.log

Simple authentication – example using IBM Tivoli server

LDAP.Resource.tivoli.ServerURL=ldap://tivoli-ldap:389
LDAP.Resource.tivoli.BindAccount.DN=cn=root
LDAP.Resource.tivoli.BindAccount.Password=pass
LDAP.Resource.tivoli.AuthenticationMechanisms=simple
LDAP.Resource.tivoli.SecurityProtocol=simple
LDAP.Resource.tivoli.Synchronize.GroupMembership.Attribute=ibm-allgroups
LDAP.Resource.tivoli.Synchronize.GroupMembership=true
LDAP.Resource.tivoli.QueryNames=simple-tivoli

LDAP.Resource.tivoli.Query.simple-tivoli.UserBaseDN=cn=Realm1,dc=domaintest,dc=corp
LDAP.Resource.tivoli.Query.simple-tivoli.UserFilter=(uid=%u)

#---------------------change password configuration--------------------#

LDAP.Resource.tivoli.PasswordPolicy.Domain=cn=Realm1,DC=domaintest,DC=corp
LDAP.Resource.tivoli.ChangePasswordAttributeName=userPassword
LDAP.Resource.tivoli.NotifyDaysBeforeExpire=10
LDAP.Resource.tivoli.AllowChangePassword=true

Using this configuration, the user will not receive a notification about password expiration
NOTE
–it is currently supported only for Microsoft AD

16 © Stibo Systems - Confidential

Simple authentication – multiple ldap domains

LDAP.Resource.multi-domains.ServerURL=ldap://ldap-windev2.domain2.steptest.corp:3268
LDAP.Resource.multi-domains.BindAccount.DN=testuser@steptest.corp
LDAP.Resource.multi-domains.BindAccount.Password=pass
LDAP.Resource.multi-domains.AuthenticationMechanisms=simple
LDAP.Resource.multi-domains.SecurityProtocol=simple

LDAP.Resource.multi-domains.DomainIDs=D2,ST,test

LDAP.Resource.multi-domains.Domain.D2.Name=domain2,DC=steptest
LDAP.Resource.multi-domains.Domain.D2.DisplayName=domain2

LDAP.Resource.multi-domains.Domain.ST.Name=steptest

LDAP.Resource.multi-domains.LoginIdPatterns=(?<domain>.*?)\\\\(?<user>.*?),(?<user>.*?)

LDAP.Resource.multi-domains.QueryNames=query1

LDAP.Resource.multi-domains.Query.query1.UserBaseDN=DC=%d,DC=corp
LDAP.Resource.multi-domains.Query.query1.UserFilter=(sAMAccountName=%u)

LDAP.Resource.multi-domains.Synchronize.GroupMembership.Attribute=memberOf
LDAP.Resource.multi-domains.Synchronize.GroupMembership=true
LDAP.Resource.multi-domains.Synchronize.Attributes=%email=userPrincipalName

STEP Single Sign On solutions

STEP offers four Single Sign On solutions out of the box. These solutions can be enabled together without
being mutually exclusive. This means that some users can login manually (e.g. internal users), while
others can login using Trusted Headers (e.g. external users).

Unless specifically disabled, manual login is possible when SSO solutions are used – if no
NOTE
SSO plugin can authenticate the user, the manual login page will be presented.

Enabling and configuring SSO solutions

General configuration properties

In the properties names below, “n” represents the authentication plugin configuration
NOTE name, which has to be present in the “HttpAuthentication.ResourceNames” list in order to
be used.

Property Description

HttpAuthentication.ResourceNames A comma separated list of strings. It contains the names of the

authentication plugin configurations that Step should use. Defaults
to LegacyTrustedHeaders,LegacySSO,LegacyGoogleAccountOAuth

© Stibo Systems - Confidential 17

Property Description

HttpAuth.Resource.n.Type The type of authentication plugin to use (the plugin ID). Available
types: TrustedHeaders, KerberosSSO, GoogleAccountOAuth, Blocker
(prevents initial manual login), LegacyTrustedHeaders, LegacySSO,
LegacyGoogleAccountOAuth. NOTE: If the resource names match the
types exactly, then this configuration is not needed.

HttpAuthentication.Resource.n.DisableUserSynchronization Boolean value. Used for disabling or enabling user synchronization

for a specific authentication plugin. Default set to false, meaning that
all plugins will attempt user synchronization.

The authentication plugins are invoked in the order they were added to the
HttpAuthentication.ResourceNames list. If one of the plugins cannot authenticate the user, the process
will continue until one of the plugins can authenticate. If none of them can, the user will be presented
with the login page for manual login.

Out of the box, user synchronization is possible only when LDAP is enabled. If LDAP is not
NOTE
enabled, disabling or enabling the “DisableUserSynchronization” property has no effect.

In order to disable SSO solutions, either do not configure the HttpAuthentication.ResourceNames so it

defaults to the legacy plugins (these plugins require explicit enabling and configuration in order to be
enabled) or set the configuration to an empty list.

#--some other configurations---#

HttpAuthentication.ResourceNames=
#--some other configurations---#

Kerberos Single Sign On

The Web UI offers the possibility for using Kerberos Single Sign On (SSO) when users log on to a domain.

The solution only works for STEP systems running "Stand Alone", and which don’t use
NOTE
application servers such as Websphere or Weblogic.

When the Web UI has Kerberos SSO enabled, users who are logged on to a domain with a Windows
computer should not have to provide a username and password when accessing the Web UI. When using
Kerberos SSO, the LDAP users are also synchronized in the STEP database following the same rules as
described in Group Synchronization section.

Configuration

In order for the Kerberos SSO solution to work, the following configuration needs to be in place:

HttpAuthentication.ResourceNames=KerberosSingleSignOn
HttpAuthentication.Resource.KerberosSingleSignOn.Type=KerberosSSO

<LDAP configuration, please see examples>

18 © Stibo Systems - Confidential

NOTE:If the resource name matches the plugin type (e.g:
HttpAuthentication.ResourceNames=KerberosSSO), there is no need for
HttpAuthentication.Resource.KerberosSingleSignOn.Type=KerberosSSO.

Setting up Kerberos SSO, client

In order to enable Kerberos SSO, the user and the user’s computer need to be authorized against an LDAP
server like Microsoft Active Directory (AD) or something similar. When accessing the Web UI, the browser
must be set up to allow Kerberos SSO on the Web UI server. In order to enable Kerberos SSO, the browser
must be told to allow automatic login for the Web UI website.

Internet Explorer

• Go to "Internet Options" → open the "Security" tab → select "Local intranet" → click the "Sites" button.

• In the popup box, check the "Automatically detect intranet network" → Click the "Advanced" button.

• In the new popup box, enter the URL of the server where the Web UI is hosted. E.g. if the Web UI is
hosted at "http://portalserver.stibo.com/webui/someportal/index.html", you can enter
"http://portalserver.stibo.com".

• Port numbers are not important in this setting. If your browser is already pointed to the Web UI URL,
the address will be pre-populated in the text field.

• Click the "Close" button → Click the "OK" button in the underlying popup.

• Also, make sure that authentication is enabled.

• In Advanced tab, check the “Enable Integrated Windows Authentication”.

• In the Security tab and click Local Intranet → Custom Level and select “Automatic log-on with current
user name and password” (under User Authentication, Log-on).

• These settings can also be found in the Control Panel under "Change security settings" (Windows 7).

Older versions of Internet Explorer contain a bug which will sometimes cause all requests
sent after the first authentication request to have an empty body. This empty body will
cause this GWT error: java.lang.IllegalArgumentException: encodedRequest cannot be
empty. A very nice explanation of the bug can be found here: http://stackoverflow.com/
NOTE
questions/18990109/exception-while-dispatching-incoming-rpc-call-encodedrequest-
cannot-be-empty Microsoft has made a hotfix for this bug, compatible with all versions of
Internet Explorer, but this hotfix is disabled by default. If needed, further information
about the hotfix can be found here: https://support.microsoft.com/da-dk/kb/895954

Firefox (Not supported)

• Enter the URL "about:config" and hit enter.

• Type "ntlm" in the Filter text field.

• Double-click the entry "network.automatic-ntlm-auth.trusted-uris" (may also need to add the URL to
"network.negotiate-auth.trusted-uris").

© Stibo Systems - Confidential 19

 • Add the URL of the server (multiple values may be delimited by comma).

• Click OK.

• The name of the setting is a little misleading because we are actually not using NTLM, but Kerberos
for the authentication and NTLM is not supported. However, this setting applies for both scenarios.

Chrome (Not supported)

• Chrome will use the Windows security settings mentioned in the "Internet Explorer" section above.
NOTE: In order to make Kerberos SSO work, the fully qualified URL must be used for accessing the
Web UI, e.g. http://portalserver.stibo.com/webui/someportal/login.html and NOT http://portalserver/
webui/someportal/index.html

Setting up Kerberos SSO, LDAP server

The STEP server of a Web UI application must also be authorized to access the LDAP Server(s) and must
have an account that is allowed to look up and authenticate other users. The STEP server does not
necessarily have to be logged on to the domain in order to perform authentication.

The preauthentication user settings are global, which means that this user must be created on all the
LDAP servers used for Kerberos SSO, and an SPN must be setup for STEP, using that account.

It is necessary to setup a Service Principal Name (SPN) for the Web UI service. An SPN is used for mapping
the Web UI service to a user so that the AD knows that the Web UI server is allowed to authenticate users
for the Web UI. If multiple LDAP servers are used for Kerberos SSO, the spn must be created for all the
LDAP servers, using the same preauthentication username.

If the SPN is not created for the preauthentication user, then login will fail with a
NOTE
“Checksum failed” error.

To see which servers are already configured for a specific preauthentication user:

• setSPN -L [preauthentication user] To add an SPN for Web UI located at http://portalserver.stibo.com/

webui, run the setSPN command on the LDAP Server (instructions apply for Windows ADs only):

• setSPN -a http/[server] [preauthentication user] e.g.: setSPN -a http/portalserver.stibo.com

preauthUser

The Web UI URL used in this command must be the fully qualified URL, even if the server can be reached
by its short name (e.g. http://portalserver). Note that it is NOT supposed to be http:// but just http/

If the Web UI is hosted on a port different from the default port 80, the port number must also be
specified in the setSPN command, e.g. http/portalserver.stibo.com:8080 (i.e. both with and without port
number)

Web UI SSO uses kerberos tokens for secure communication, which means that the LDAP Server must
support Kerberos. Kerberos has been the standard recommended by Microsoft since Windows 2000
server, and it has been the default on Windows servers ever since.

20 © Stibo Systems - Confidential

 NOTE NTLM is NOT supported!

If LDAP is enabled for the workbench, but Kerberos SSO is not wanted for the Web UI, use this setting: *
Portal.UseSSO=false

The LDAP.JAASConfigurationFile file must contain entries spnego-client and spnego-server,

NOTE
which are used by this standard SSO mechanism.

Kerberos SSO and multiple LDAP domains

The Kerberos SSO solution can be used together with multiple LDAP domains. For information on how to
configure multiple LDAP domains, please see Support for multiple LDAP domains and Simple
authentication – multiple ldap domains.

Besides the requirements described in the Setting up Kerberos SSO, LDAP server and Support for multiple
LDAP domains, the SSO solution adds new requirements both to the LDAP server configuration and the
STEP configuration.

As mentioned in the referenced sections, the LDAP servers must be setup with a global catalogue.
Furthermore, the servers running the domains for which SSO is desired must have an SPN for the service
account, as described the Setting up Kerberos SSO, LDAP server section. If an SPN is not created, the user
authentication will fail with the “Checksum failed” error.

When configuring the multiple domains on the Step server, the LDAP.Resource.n.Domain.d.DisplayName
must match the Kerberos realm. The login patters configured must also contain the simple pattern that
matches the user id (?<user>.*?), else the login will not work for SSO users.

E.g.:

LDAP.Resource.sso-multi-domains.DomainIDs=D2,ST
LDAP.Resource.sso-multi-domains.Domain.D2.Name=domain2,DC=steptest
LDAP.Resource.sso-multi-domains.Domain.D2.DisplayName=domain2.steptest.corp
LDAP.Resource.sso-multi-domains.Domain.ST.Name=steptest
LDAP.Resource.sso-multi-domains.Domain.ST.DisplayName=steptest.corp
#for sso, we need (?<user>.*?), else it won't match
LDAP.Resource.sso-multi-domains.LoginIdPatterns=(?<domain>.*?)\\\\(?<user>.*?),(?<user>.*?)

If unsure what the correct realm name is, you can enable finest logging on the SSO plugin and then try to
login with SSO. The realm and username used for authentication will be logged in the STEP logs.

E.g.:

Log.Level.com.stibo.sso.provider.KerberosSSOProviderPlugin=FINEST

© Stibo Systems - Confidential 21

Example for setting up SSO, STEP application server and LDAP servers

The ldap servers used in this configuration example are dc1-auth.domain1.local and dc2-
auth.domain1.local.

Setting for dc1-auth.domain1.local

Preauthentication user and password: stibosw / stibosw setSPN -a http/portalserver.stibo.com stibosw

Setting for dc2-auth.domain2.local

Preauthentication user and password: stibosw / stibosw setSPN -a http/portalserver.stibo.com stibosw

Settings needed in the config.properties file for Kerberos SSO to work (using synchronization)

22 © Stibo Systems - Confidential

 HttpAuthentication.ResourceNames=KerberosSingleSignOn
HttpAuthentication.Resource.KerberosSingleSignOn.Type=KerberosSSO
LDAP.Enabled=true
LDAP.ResourceNames=sso,sso-2
LDAP.KerberosConfigurationFile=../ldap/krb5.conf
LDAP.JAASConfigurationFile=../ldap/step-jaas.conf
LDAP.Timeout=15
LDAP.Preauthentication.UserName=stibosw
LDAP.Preauthentication.Password=stibosw

#----------------------------------------------------
#LDAP Settings - sso configuration
#----------------------------------------------------

LDAP.Resource.sso.ServerURL=ldap://dc1-auth.domain1.local:389
LDAP.Resource.sso.BindAccount.DN=stepbind@domain1.local
LDAP.Resource.sso.BindAccount.Password=Abcd1234!
LDAP.Resource.sso.AuthenticationMechanisms=GSSAPI
LDAP.Resource.sso.SecurityProtocol=simple
LDAP.Resource.sso.JAASConfigurationEntryName=GSSApi
LDAP.Resource.sso.QueryNames=query2

LDAP.Resource.sso.Query.query2.UserBaseDN=DC=domain1,DC=local
LDAP.Resource.sso.Query.query2.UserFilter=(sAMAccountName=%u)

LDAP.Resource.sso.Synchronize.GroupMembership.Attribute=memberOf
LDAP.Resource.sso.Synchronize.GroupMembership=true
LDAP.Resource.sso.Synchronize.Attributes=%email=userPrincipalName

#----------------------------------------------------
#LDAP Settings – sso-2 configuration
#----------------------------------------------------

LDAP.Resource.sso-2.ServerURL=ldap://dc2-auth.domain2.local:389
LDAP.Resource.sso-2.BindAccount.DN=bindUser@domain2.local
LDAP.Resource.sso-2.BindAccount.Password=Test1234!
LDAP.Resource.sso-2.AuthenticationMechanisms=GSSAPI
LDAP.Resource.sso-2.SecurityProtocol=simple
LDAP.Resource.sso-2.JAASConfigurationEntryName=GSSApi2
LDAP.Resource.sso-2.QueryNames=query2

LDAP.Resource.sso-2.Query.query2.UserBaseDN=DC=domain2,DC=local
LDAP.Resource.sso-2.Query.query2.UserFilter=(sAMAccountName=%u)

LDAP.Resource.sso-2.Synchronize.GroupMembership.Attribute=memberOf
LDAP.Resource.sso-2.Synchronize.GroupMembership=true
LDAP.Resource.sso-2.Synchronize.Attributes=%email=userPrincipalName

krb5.conf and step-jaas.conf files

krb5.conf:

© Stibo Systems - Confidential 23

 [libdefaults]
  default_realm = DOMAIN1.LOCAL
  default_tkt_enctypes = aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha1-96 rc4-hmac
  default_tgs_enctypes = aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha1-96 rc4-hmac

[realms]
  DOMAIN1.LOCAL = {
  kdc = dc1-auth.domain1.local:88
  default_domain = DOMAIN1.LOCAL
  }
  DOMAIN2.LOCAL = {
  kdc = dc2-auth.domain2.local:88
  default_domain = DOMAIN2.LOCAL

  }

[domain_realm]
  .domain1.local = DOMAIN1.LOCAL
  domain1.local = DOMAIN1.LOCAL
  .domain2.local = DOMAIN2.LOCAL
  domain2.local = DOMAIN2.LOCAL

[logging]
  kdc = FILE:krb5kdc.log
  default = FILE:krb5lib.log

step-jaas.conf :

spnego-client {
  com.sun.security.auth.module.Krb5LoginModule required;
};

spnego-server {
  com.sun.security.auth.module.Krb5LoginModule required
  storeKey=true;
};

STEP {
 com.sun.security.auth.module.Krb5LoginModule required;
};

GSSApi {
  com.sun.security.auth.module.Krb5LoginModule required;
};

GSSApi2 {
  com.sun.security.auth.module.Krb5LoginModule required;
};

24 © Stibo Systems - Confidential

Trusted Headers
The Web UI supports login by users who have been pre-authenticated by an authentication proxy.
Authentication proxies must add one or more headers to all subsequent requests to indicate to the Web
UI that the current user has been authenticated to access the Web UI.

The use of Trusted Headers as authentication method does not require any settings on the client’s
browser but relies on the trust relationship between the authentication proxy and STEP, where STEP will
trust that any request, which contains the specified header, has been authenticated.

All requests coming to STEP from the web UI need to have trusted headers in the
NOTE
requests!

If the requests do not have headers present, the user will be prompted with the Login
NOTE
page to manually authenticate to STEP.

When using Trusted Headers with STEP, unless it is used together with LDAP (see below), the user can
only log in if they already exist in STEP.

© Stibo Systems - Confidential 25

Trusted Headers Flow

STEP Settings for Trusted Headers

HttpAuthentication.ResourceNames=TH
HttpAuthentication.Resource.TH.Type=TrustedHeaders

HttpAuthentication.Resource.TH.TrustedHeaders.Header.Username=[Name of the header which contains the user name]

HttpAuthentication.Resource.TH.TrustedHeaders.Header.SessionId=[Name of the header which contains the user Session ID from the
authentication server]

26 © Stibo Systems - Confidential

Trusted headers and LDAP integration

The Trusted Headers authentication can be used together with LDAP in order to synchronize users and
their group memberships to STEP before logging them in.

In order for LDAP integration to work, this needs to be enabled and configured:

LDAP.Enabled=true
<the rest of the ldap configuration>

(See LDAP configuration for more properties related to LDAP integration and synchronization)

Trusted headers and Excel Smartsheets

When a user wants to use a smartsheet (or a quicksheet), he/she is prompted for their username and
password. These credentials are then sent to STEP as basic authentication, as part of the Authorization
request header. STEP will then extract those credentials and validate them against the STEP database or
the ldap server.

NOTE Smartsheets and quicksheets only support basic authentication!

When trusted headers authentication is enabled, the authentication for the smartsheet will fail if the user
is not maintained in an LDAP server integrated with STEP. In order to avoid this situation, STEP can be
configured to authenticate the smartsheet requests using trusted headers, making it possible to
authenticate users who are maintained in a database that cannot be accessed by STEP.

In order for the STEP to verify the trusted headers instead of the basic authentication headers when using
smartsheets, the following configurations need to be set:

Excel.UseTrustedHeaders=true
Excel.TrustedHeaders.Username= [Name of the header which contains the User ID]

Excel will send the username and password as basic authentication along with each request. For that
reason it is necessary to have an authentication proxy which can:

• Extract the User ID and password from the basic authentication request header

• Add a header to all requests to STEP containing the user ID

• Forward all requests including all payloads from Excel to STEP if the request is authenticated 

Smartsheet request destination

The url to which the smartsheet requests are sent depends on this configuration property:

SmartSheet.ValidationService.URL=the URL that the Excel applications will use for validation

© Stibo Systems - Confidential 27

If smartsheet authentication should use trusted headers, then this url must be configured to point to a
proxy that can extract the basic authentication credentials, authenticate the user, add the trusted header
to the request, and then forward the request to STEP.

Configuration example and sequence flow

Excel.UseTrustedHeaders=true
Excel.TrustedHeaders.Username=sm_user

SmartSheet.ValidationService.URL= http://authproxy.company.corp/smartsheet

28 © Stibo Systems - Confidential

Auth 2.0 with Google Accounts
The Web UI supports a reference implementation of OAuth, based on Google Accounts. This means that
the Web UI can be configured to permit access for users authorized via a google account. The STEP server
must have a global URL which Google Accounts requires for OAuth communication.

© Stibo Systems - Confidential 29

OAuth Flow

OAuth configuration properties

All the following properties needs to be prepended with HttpAuthentication.Resource.n ,

NOTE
where “n” is the specific resource name.

Property Description

.GoogleAccountOAuth.Redirect.Url URL that is used for the purpose of basic callback-redirection. This
should be a globally accessible url in the form
of:http://step.system.hostname

.GoogleAccountOAuth.Resource.Server.Key Server key used for authentication-step process.

.GoogleAccountOAuth.Resource.Server.Secret Server secret key.

.GoogleAccountOAuth.Authenticating.Endpoint Authenticating endpoint.

.GoogleAccountOAuth.Token.Endpoint Token request endpoint.

.GoogleAccountOAuth.Validation.Endpoint Token validation endpoint.

30 © Stibo Systems - Confidential

.GoogleAccountOAuth.Client.Id Client identifier.

.GoogleAccountOAuth.Client.Secret Client secret key.

.GoogleAccountOAuth.Authenticating.Scope Authentication scope.

.GoogleAccountOAuth.Authenticating.Hint Authentication user hint.

OAuth configuration example

HttpAuthentication.ResourceNames=OAuth
HttpAuthentication.Resource.OAuth.Type=GoogleAccountOAuth

# Authentication endpoint url (OAuth 1st step - request token)

HttpAuthentication.Resource.OAuth.GoogleAccountOAuth.Authenticating.Endpoint=https://accounts.google.com/o/oauth2/auth

# Token exchange endpoint url (OAuth 2nd step - token exchange)

HttpAuthentication.Resource.OAuth.GoogleAccountOAuth.Token.Endpoint=https://accounts.google.com/o/oauth2/token

# Token validation endpoint url (OAuth 3d step - token validation)

HttpAuthentication.Resource.OAuth.GoogleAccountOAuth.Validation.Endpoint=https://www.googleapis.com/oauth2/v1/tokeninfo

# Account access scope (it is used to allow the application some scope of user data)
HttpAuthentication.Resource.OAuth.GoogleAccountOAuth.Authenticating.Scope=profile

# This is the hint displayed at the 1st step at provider side (Google will show "email" in the appropriate fields for typing the account
credentials)
HttpAuthentication.Resource.OAuth.GoogleAccountOAuth.Authenticating.Hint=email

# This is the global url of the STEP server.

HttpAuthentication.Resource.OAuth.GoogleAccountOAuth.Redirect.Url=http://stibo.system.hostname

# OAuth Provider client identifier

HttpAuthentication.Resource.OAuth.GoogleAccountOAuth.Client.Id=449161492363-
1bopd4q69vb43p6j660lndpdtvnjq8ea.apps.googleusercontent.com

# OAuth Provider client secret code

HttpAuthentication.Resource.OAuth.GoogleAccountOAuth.Client.Secret=YSsl_Nl7nfnnu815UG-NUX6k

Configuration examples for multiple authentication

mechanisms
Kerberos SSO + Trusted headers

© Stibo Systems - Confidential 31

 HttpAuthentication.ResourceNames=KerberosSingleSignOn,TH

HttpAuthentication.Resource.TH.Type=TrustedHeaders
HttpAuthentication.Resource.TH.TrustedHeaders.Header.Username=sm-account
HttpAuthentication.Resource.TH.TrustedHeaders.Header.SessionId =sm-sessionID

HttpAuthentication.Resource.KerberosSingleSignOn.Type=KerberosSSO

<LDAP configuration, please see examples for ldap with GSSAPI>

Workbench Expiry Time

IMPORTANT

Raising this value will REDUCE the security provided by steptokens, and we recommend that STEP servers
are always configured with the default value of this property.

Description

It is possible to raise the expiry time value for renew tokens in hours. This config property will extend the
time frame in which workbench renew tokens will be valid. The workbench won’t timeout as long as it is
able to communicate with the STEP server before this time frame is exceeded. Raising this value makes it
possible for the workbench to survive longer periods of time without server connectivity, but at the cost of
REDUCED security.

Step.Token.ExpiryTimeInHours=4

SAML
Introduction

SAML (Security Assertion Markup Language) is a standard for exchanging authentication and
authorization data between different security domains. SAML SSO solution for STEP allows for the access
to STEP (the Service Provider) to be controlled by any external Identity Provider (IDP). STEP is compatible
with SAML in version 2.0.

Usage flow

There are two main authentication flows available when working with SAML: one for authentication
requests initialized by the Service Provider (STEP in this case), and another for requests initiated by
IdentityProvider, where the user then selects the Service Provider for connection. Below, sequence
diagrams and descriptions are presented for each flow.

Authentication initiated by Service Provider

32 © Stibo Systems - Confidential

With STEP, the flow presented above could progress as follows:

1. User opens the WebStart page in browser and clicks a link to a specific Web UI configuration.

2. STEP checks if the user is already authenticated. If not, STEP prepares a request for the configured
Identity Provider. STEP encodes this request in Base64 format and returns it as part of a redirect URL
for the Identity Provider.

3. Browser redirects user to the Identity Provider.

4. Identity Provider prompts user for credentials (given that the user is not already authenticated).

5. After passing valid credentials, the Identity Provider redirects user back to STEP. Response containing
additional information about the user (SAML token) is returned as part of the HTML form that is
automatically submitted to a STEP servlet.

6. STEP validates the response from the Identity Provider, and if successful, returns the requested
resource to the user.

Authentication initiated by Identity Provider

© Stibo Systems - Confidential 33

The flow presented above, could progress as follows:

1. User accesses intranet page that provides access to multiple different Service Providers and for which
Identity Provider authentication is required.

2. User chooses to access STEP Web UI from a page presenting available Service Providers.

3. Identity Provider prompts user for credentials (given that the user is not already authenticated).

4. User submits credentials and Identity Provider (after successful user authentication) sends request to
STEP assertion consumer servlet, which is then parsed and validated by STEP.

5. Upon success, user gains access to the requested resource.

Notice, that by default, STEP only allows for Identity Provider-initiated access to Web UIs. To work for the
workbench client as well, additional configuration is required, namely relative paths to allowed resources
must be defined for the property:

SAML.ServiceProvider.Step.RelayState.SupportedPathsForIDPInitiatedAuthentication.

User synchronization

User synchronization is turned on by default. This means that during authentication, user information will
be synchronized between the STEP system and the corresponding Identity Provider. The synchronization
mechanism works similarly to the LDAP mechanism. Without additional configuration, only user groups
and attributes received from IDP assertion responses are synchronized. During user groups

34 © Stibo Systems - Confidential

synchronization, the system does not create new groups, instead, it only assigns users to existing one.
Please remember that if none of the groups sent in an IDP assertion exist in STEP, the user will be
assigned to default user group (which is configurable through properties and has to exist in STEP). If the
user cannot be assigned to any group, an exception is thrown, and the user is prevented from accessing
STEP.

Let’s take a look at an example to understand group synchronization.

1. STEP receives an assertion containing three groups "GROUP_A", "GROUP_B", "GROUP_C" (they are
retrieved from assertion XML from an attribute with ID defined in configuration property:
SAML.IdentityProvider.n.Assertions.Attribute.Groups).

2. STEP prepares a list of existing groups in STEP, based on a collection from point 1.

3. If any of the groups exist in STEP, go to point 6.

4. System tries to retrieve default SAML user group (defined by property

SAML.ServiceProvider.Step.Users.DefaultUserGroupID).

5. If a default user group cannot be found, an exception is thrown, and processing is stopped (user will
be prevented from accessing STEP).

6. Assign user to groups if he/she does not exist in those groups.

7. If property (SAML.ServiceProvider.Step.Users.RevokeAccess) is set to true, remove user from groups

that are not present in received collection from point 6.

8. Finish synchronization.

Apart from group synchronization, STEP also synchronizes user attributes. Two user attributes,
DisplayName and Email, are always synchronized. Values are retrieved from the assertion XML attributes
with IDs specified by the properties:

SAML.IdentityProvider.n.Assertions.Attribute.Email
SAML.IdentityProvider.n.Assertions.Attribute.DisplayName

STEP can also synchronize additional user properties. To do so, mappings between assertion and the STEP
system are required. You are not allowed to map base attributes representing groups, display name, and
email. Mappings are defined with the configuration property:

SAML.IdentityProvider.n.Assertions.Attributes.Mappings=IDPPhone=phone,IDPCompany=company

• IDPPhone, IDPCompany - represent attribute IDs from assertion XML.

• phone, company - represent attribute IDs from STEP.

Similarly to the LDAP approach, if an attribute does not exist in STEP and is present in assertion, an
exception will be thrown. To avoid that, mark the STEP attribute as optional. This means that property
values will only be synchronized if the attributes exist in STEP. In this case, STEP attribute IDs should be
prefixed with a question mark, as presented on example below.

© Stibo Systems - Confidential 35

 SAML.IdentityProvider.n.Assertions.Attributes.Mappings=IDPPhone=?phone,IDPCompany=?company

STEP also allows for users to be automatically created if they do not exist. This functionality is turned off
by default but can be enabled with the property:

SAML.ServiceProvider.Step.Users.AutoProvision

If set, when processing assertions, a user will be created in STEP and assigned to the groups defined in
the assertion or to the default group.

Logout

If SAML is enabled, when a user logs out of Web UI, a request is sent to the Identity Provider to log user
out from IDP as well. After logout, the user is redirected to either the STEP WebStart page (on success) or
the STEP SAML error page (if an error occurs).

NOTE Currently it is not possible to perform complete logout from Workbench.

Usage with other authentication plugins

The SAML authentication plugin works differently from the other authentication options described in this
document. This is due to the fact that full responsibility for authentication is delegated to an external
system (Identity Provider), meaning that STEP is not able to determine whether or not the user is valid
until a result has been received from the Identity Provider. For this reason, SAML authentication is
restricted from use with the other plugins presented in this document as defined below.

SAML authentication plugin does not invoke other plugins if any failure occurred during Workbench SSO
and Smartsheets SSO authentication. However, it is fully compliant with other plugins while performing
the authentication process in Web UI (it requires enabling an additional property - see the general
configuration table for more details). This means that if the SAML authentication process failed, the user
will be allowed to skip it and try logging in with another enabled plugin (like Kerberos or Trusted
Headers). The image below is the error message with an optional button for skipping SAML
authentication process.

Be aware that skipping SAML authentication will result in omitting the SAML
NOTE
authentication plugin until browser has been closed.

36 © Stibo Systems - Confidential

Skipping Web UI SAML Authentication

Skipping Web UI SAML Authentication is possible by adding following parameter to the request:

skipSAMLLogin=true

To authenticate again with SAML it is necessary to either clear browser cookies or close the browser.

Configuration

Details about the available configuration properties can be found in table below. As shown in the table
below, some of the properties are cluster node specific, while others are system wide. Cluster node
specific properties should be set in [STEP_HOME]/config.properties while system wide properties should
be set in [WORKAREA]/sharedconfig.properties.

General configuration properties

In the properties' names below, “n” represents the identity provider name, which has to be
NOTE present in the “SAML.IdentityProviders.Names” property. Currently only one Identity
Provider with which ServiceProvider will communicate is supported.

Property Default Value Cluster Node Description

Specific

SAML.Enabled false No Enable SAML on this

system. This effectively
sets this STEP instance to
act as a SAML Service
Provider (SP). Must be set
to true to enable SAML on
the system.

© Stibo Systems - Confidential 37

SAML.CertificatesAndKeys.Storage FILE No Specifies how private keys
and certificates used for
signing and message
encryption are stored.
Possible values are FILE
and KEYSTORE.

SAML.ServiceProvider.Step. stepSAMLSigningCert No Alias for certificate used

Signing.Certificate.Alias for signing SAML
assertions if stored in
keystore. Must be
provided when using
KEYSTORE as storage type.
Certificate must be in the
PEM X509 format.

SAML.ServiceProvider.Step. ${SHARED_DIR}/signing/ No File containing the

Signing.Certificate.File stepSAMLSigning.cert certificate used for signing
SAML assertions.
${SHARED_DIR} is a
variable that, in a
clustered setup, points to
a directory accessible from
all app servers (value of
System.SystemShare.Root)
. ${SHARED_DIR} must be
used as the prefix for
property value followed by
relative path to the
certificate file. Must be
provided when using FILE
as a storage type.

SAML.ServiceProvider.Step. stepSAMLEncryptionCert No Alias of certificate used for

Encryption.Certificate.Alias SAML assertion encryption
if stored in keystore. Must
be provided when using
KEYSTORE as storage type.
Certificate must be in the
PEM X509 format.

SAML.ServiceProvider.Step. ${SHARED_DIR}/encryption/ No File containing certificate

Encryption.Certificate.File stepSAMLEncryption.cert used for SAML assertion
encryption.
${SHARED_DIR} is a
variable that, in a
clustered setup, points to
a directory accessible from
all app servers (value of
System.SystemShare.Root)
. ${SHARED_DIR} must be
used as the prefix for
property value followed by
relative path to the
certificate file. Must be
provided when using FILE
as a storage type.
Certificate must be in the
PEM X509 format.

38 © Stibo Systems - Confidential

SAML.ServiceProvider.Step. stepSAMLSigning No Alias of private key for
Signing.PrivateKey.Alias signing SAML assertions if
stored in keystore. Must
be provided when using
KEYSTORE as storage type.
Key should be in PEM X509
format and secured with
password.

SAML.ServiceProvider.Step. ${SHARED_DIR}/signing/ No File containing private key

Signing.PrivateKey.File stepSAMLSigning.pkcs8 for signing SAML
assertion. ${SHARED_DIR}
is a variable that, in a
clustered setup, points to
a directory accessible from
all app servers (value of
System.SystemShare.Root)
. ${SHARED_DIR} must be
used as the prefix for
property value followed by
relative path to the key
file. Must be provided
when using FILE as a
storage type. Key should
be in PEM X509 format
and secured with
password.

SAML.ServiceProvider.Step. changeit No Password for signing

Signing.PrivateKey.Password private key (if none is
provided, it is assumed
that the private key FILE is
not encrypted) or
password for key saved in
keystore. Must be used for
both FILE/KEYSTORE
storage type only if
password is encrypted.

SAML.ServiceProvider.Step. stepSAMLEncryption No Alias of private key for

Encryption.PrivateKey.Alias signing SAML assertions if
stored in keystore. Must
be provided when using
KEYSTORE as storage type.
Key should be in PEM X509
format and secured with
password.

SAML.ServiceProvider.Step. ${SHARED_DIR}/encryption/ No File containing private key

Encryption.PrivateKey.File stepSAMLEncryption.pkcs8 for encrypting SAML
assertions. ${SHARED_DIR}
is a variable that, in a
clustered setup, points to
a directory accessible from
all app servers (value of
System.SystemShare.Root)
. ${SHARED_DIR} must be
used as the prefix for
property value, followed
by relative path to the key
file. Must be provided
when using FILE as a
storage type. Key should
be in PEM X509 format
and secured with
password.

© Stibo Systems - Confidential 39

SAML.ServiceProvider.Step. changeit No Password for encrypting
Encryption.PrivateKey.Password private key (if none is
provided, it is assumed
that the private key file is
not encrypted) or
password for key saved in
keystore. Must be used for
both FILE/KEYSTORE
storage type only if
password is encrypted.

SAML.ServiceProvider.Step.KeyStore.File ${SHARED_DIR}/keystore.store No File containing keystore

for SAML purpose.
${SHARED_DIR} is a
variable that, in a
clustered setup, points to
a directory accessible from
all app servers (value of
System.SystemShare.Root)
. ${SHARED_DIR} must be
used as the prefix for
property value followed by
relative path to the
KeyStore file. Must be
provided when using
KEYSTORE as a storage
type.

SAML.ServiceProvider.Step. changeit No Password to provided

KeyStore.Password keystore. Must be
provided when using
KEYSTORE as a storage
type.

SAML.ServiceProvider.Step.EntityID Step-SP No The value of the "entityID"

element for the entity
descriptor of the Service
Provider metadata. To be
used when generating the
STEP metadata file. Entity
ID cannot contain more
than 1024 characters.

SAML.ServiceProvider.Step. No The value of the "Location"

AssertionConsumerService.Location parameter of the prefix for
the
"AssertionConsumerServic
e" element for the entity
descriptor of the Service
Provider metadata.
Cannot be null or empty.

SAML.ServiceProvider.Step. No The value of the "Location"

SingleLogoutService.Location parameter of the prefix for
the "SingleLogoutService"
element for the entity
descriptor of the service
provider metadata.
Cannot be null or empty.

SAML.ServiceProvider.Step. true No When true, the STEP

Emit.Entity.Certificate certificate will be emitted
in the metadata.

40 © Stibo Systems - Confidential

SAML.ServiceProvider.Step. true No Indicates a requirement
WantAssertionsSigned for the SAML Assertion
elements received by the
STEP Service Provider to
be signed.

SAML.ServiceProvider.Step. true No When set to true, the Auth

AuthRequestSigned Request messages sent by
the STEP Service Provider
will be signed.

SAML.ServiceProvider.Step. 300000 No The timeout (in

Assertion.Request.Timeout milliseconds) for when a
request must be closed.
Controls how long the IDP
has to respond with an
assertion. Default is set to
300000 (five minutes).

SAML.ServiceProvider.Step. true No When set to true, the STEP

Assertions.ValidateSignatures Service Provider validates
the signature of incoming
responses received from
IDP. Cannot be null or
empty.

SAML.ServiceProvider.Step.Users.Synchronize true No When set to true,

synchronizes logging in
user data with the STEP
system (user attributes,
groups, etc.). When set to
false and user does not
exist in STEP, an
authentication exception
will be thrown during
authentication process.

SAML.ServiceProvider.Step. false No When set to true,

Users.Synchronize.Attributes synchronizes user
attributes from Identity
Provider to STEP system
(in case groups
synchronization should be
omitted). Please be aware
that if full synchronization
is enabled
("SAML.ServiceProvider.Ste
p.Users.Synchronize"), this
property will be omit.
When user does not exist
in STEP, an authentication
exception will be thrown
during authentication
process. By default it’s
disabled to support
backward compatibility
(when full synchronization
is turned off user
attributes won’t be
synchronized unless this
property is enabled).

SAML.ServiceProvider.Step. false No When set to true,

Users.AutoProvision automatically creates
SAML-authenticated users,
if they do not exist in STEP.

© Stibo Systems - Confidential 41

SAML.ServiceProvider.Step. false No When set to true, STEP will
Users.RevokeAccess remove the user from all
user groups not contained
in the SAML Assertion.

SAML.ServiceProvider.Step. No ID of the default SSO user

Users.DefaultUserGroupID group in STEP.

SAML.ServiceProvider.Step. false No When set to true, for Web

AllowSkippingSAMLAuthentication UI login only, if any
exception occurs during
the SAML authentication
process, SAML
authentication is skipped
and other authentication
plugins are used.

SAML.ServiceProvider.Step. rsa-sha256 No Signature algorithm with

Request.SignatureAlgorithm which the Service Provider
is signing requests.
Allowed values are: "rsa-
sha1", "rsa-sha256", "rsa-
sha384", "rsa-sha512",
"ecdsa-sha1", "ecdsa-
sha256", "ecdsa-sha384",
"ecdsa-sha512", "dsa-
sha1", "dsa-sha256".

SAML.ServiceProvider.Step. urn:oasis:names:tc:SAML:2.0:nameid- No Comma separated list of

SupportedNameIDsFormats format:persistent supported name IDs
formats by Service
Provider.

SAML.ServiceProvider.Step. No List of additionally

RelayState.SupportedPathsForIDPInitiatedAu supported relay state
thentication relative paths if IDP
initiated phase is
processed. By default only
Web UIs are allowed to be
used.

SAML.IdentityProviders.Names No Name of used IDP. Must

correspond to name used
for the other “Identity
Provider” configuration
properties. Cannot be null
or empty.

SAML.IdentityProvider.n.Metadata.Endpoint No The URL for the IDP

metadata endpoint.
Cannot be null or empty.
"n" must be substituted
with the Identity Provider
name and it must be
present in the
SAML.IdentityProviders.Na
mes property to be used.

42 © Stibo Systems - Confidential

SAML.IdentityProvider.n. 60000 No The timeout (in
Metadata.Request.Connection.Timeout milliseconds) for an IDP
metadata request
connection. Controls the
timeout for establishing a
connection. Default is set
to 60000 (one minute). "n"
must be substituted with
the Identity Provider name
and it must be present in
the
SAML.IdentityProviders.Na
mes property to be used.

SAML.IdentityProvider.n. 60000 No The timeout (in

Metadata.Request.Socket.Timeout milliseconds) for an IDP
metadata request socket.
Controls the timeout
between data
transmissions. Default is
set to 60000 (one minute).
"n" must be substituted
with the Identity Provider
name and it must be
present in the
SAML.IdentityProviders.Na
mes property to be used.

SAML.IdentityProvider.n. true No When set to true, STEP

Require.Valid.Metadata requires valid metadata
from the IDP. Valid
metadata either has no
"validUntil" or "validUntil"
time > now. "n" must be
substituted with the
Identity Provider name
and it must be present in
the
SAML.IdentityProviders.Na
mes property to be used.

SAML.IdentityProvider.n.EntityId No The value of the "entityID"

element for the entity
descriptor of the IDP
metadata. Cannot be null
or empty. "n" must be
substituted with the
Identity Provider name
and it must be present in
the
SAML.IdentityProviders.Na
mes property to be used.

SAML.IdentityProvider.n. SAML_IDP_metadata_cache.xml Yes Path to offline copy of IDP

Metadata.OfflineCache.Path metadata. "n" must be
substituted with the
Identity Provider name
and it must be present in
the
SAML.IdentityProviders.Na
mes property be used.

© Stibo Systems - Confidential 43

SAML.IdentityProvider.n.Assertions.Encrypt true No When set to true, IDP
assertions are encrypted.
Cannot be null or empty.
"n" must be substituted
with the Identity Provider
name and it must be
present in the
SAML.IdentityProviders.Na
mes property to be used.

SAML.IdentityProvider.n. No Expected nameID policy

Request.NameIDPolicyFormat format in the
authentication request. If
not set, the nameID policy
format is not required for
building an authentication
request. "n" must be
substituted with the name
of the configuration and it
must be present in the
SAML.IdentityProviders.Na
mes property to be used.

SAML.IdentityProvider.n. email No ID of XML-element in

Assertions.Attribute.Email assertion that contains the
"email" attribute of the
user. "n" must be
substituted with the name
of the configuration and it
must be present in the
SAML.IdentityProviders.Na
mes property to be used.

SAML.IdentityProvider.n. http://schemas.microsoft.com/identity/ No ID of XML-element in

Assertions.Attribute.DisplayName claims/displayname assertion that contains the
"DisplayName" attribute of
the user. "n" must be
substituted with the name
of the configuration and it
must be present in the
SAML.IdentityProviders.Na
mes property to be used.

SAML.IdentityProvider.n. http://schemas.microsoft.com/ws/2008/06/ No ID of XML-element in

Assertions.Attribute.Groups identity/claims/groups assertion that contains the
"Groups" attribute of the
user. "n" must be
substituted with the name
of the configuration and it
must be present in the
SAML.IdentityProviders.Na
mes property to be used.

44 © Stibo Systems - Confidential

SAML.IdentityProvider.n. No Mapping between
Assertions.Attributes.Mappings attributes received from
IDP and STEP, where key is
the ID of XML-element in
assertion that contains the
IDP attribute, and value is
the ID of the attribute
from STEP (like key=value).
Each pair has to be
separated with a comma.
By default, if an attribute
received from an assertion
does not exist in STEP, an
exception will be thrown,
unless the STEP attribute
has been marked as
optional (meaning it will
only be synchronized if it
exists in STEP). To mark
attribute as optional, add
a question mark to the
beginning of STEP
attribute ID (for example
key=?value).

SAML.IdentityProvider.n.LogoutStrategy DEFAULT No Property allows to choose

the logout strategy for
specified identity provider.
Logout strategy is used to
properly create SAML
logout request. Possible
values: ANONYMOUS,
DEFAULT. Available since
7.0.8 version of SAML
component.

SAML.IdentityProvider.n. false No Allows to disable the IDP

GlobalLogoutDisabled global logout. When this
property is set to true
STEP will no longer send
IDP logout requests and
instead it will invalidate
session on STEP side and
present a successful
logout page on STEP side.
This means that until the
session on IDP side is
valid, user will not have to
provide credentials next
time he/she accesses
STEP. Available since
7.0.17 version of SAML
component.

STEP Certification Generation Tool

The current version of the SAML component allows for auto-generating self-signed certificates used for
signing and encrypting requests/assertions sent between Service Provider and Identity Provider. It is not
required to use this mechanism for generating the certificates. If external certificates are used, it is
required only to pass paths to file/keystore, add an additional passphrase (for keystore/file and private
key/certificate), and optionally aliases (if keystore is used). All certificate-generation related properties are
global and must be the same among all cluster nodes.

© Stibo Systems - Confidential 45

 The STEP certificate generation tool does not overwrite existing certificates/private keys.
For example, if key/certificate with provided alias already exists in keystore, STEP tool will
not generate new element. This makes it easy to work in cluster environment where the
NOTE
master node generates all certificates in shared directory, and all slaves then reuse that
data. To overwrite an existing certificate, you must manually remove it from keystore or
from local file system.

Certificate-generation related properties

Property Default value Description

SAML.CertificatesAndKeys.Generate false When set to true, certificates and keys used

for SAML assertion signing and encryption
are automatically generated.

SAML.CertificatesAndKeys.Storage FILE Specifies how private keys and certificates

used for signing and message encryption are
stored. Possible values are FILE and
KEYSTORE.

SAML.ServiceProvider.Step. stepSAMLSigningCert Alias for certificate used for signing SAML

Signing.Certificate.Alias assertions if stored in KEYSTORE. Must be
provided when using KEYSTORE as a storage
type. Certificate must be in the PEM X509
format.

SAML.ServiceProvider.Step. ${SHARED_DIR}/signing/ File containing certificate used for signing

Signing.Certificate.File stepSAMLSigning.cert SAML assertions. ${SHARED_DIR} is a variable
that, in a clustered setup, points to a
directory accessible from all app servers
(value of System.SystemShare.Root).
${SHARED_DIR} must be used as the prefix
for property value followed by relative path
to the certificate file. Must be provided when
using FILE as a storage type.

SAML.ServiceProvider.Step. stepSAMLEncryptionCert Alias of certificate used for SAML assertion

Encryption.Certificate.Alias encryption if stored in KEYSTORE. Must be
provided when using KEYSTORE as a storage
type. Certificate must be in the PEM X509
format.

SAML.ServiceProvider.Step. ${SHARED_DIR}/encryption/ File containing certificate used for SAML

Encryption.Certificate.File stepSAMLEncryption.cert assertion encryption. ${SHARED_DIR} is a
variable that, in a clustered setup, points to a
directory accessible from all app servers
(value of System.SystemShare.Root).
${SHARED_DIR} must be used as the prefix
for property value followed by relative path
to the certificate file. Must be provided when
using FILE as a storage type. Certificate must
be in the PEM X509 format.

SAML.ServiceProvider.Step. stepSAMLSigning Alias of private key for signing SAML

Signing.PrivateKey.Alias assertions if stored in KEYSTORE. Must be
provided when using KEYSTORE as a storage
type. Key should be in PEM X509 format and
secured with password.

46 © Stibo Systems - Confidential

SAML.ServiceProvider.Step. ${SHARED_DIR}/signing/ File containing private key for signing SAML
Signing.PrivateKey.File stepSAMLSigning.pkcs8 assertion. ${SHARED_DIR} is a variable that,
in a clustered setup, points to a directory
accessible from all app servers (value of
System.SystemShare.Root). ${SHARED_DIR}
must be used as the prefix for property value
followed by relative path to the key file. Must
be provided when using FILE as a storage
type. Key should be in PEM X509 format and
secured with a password.

SAML.ServiceProvider.Step. changeit Password for signing private key (if none is

Signing.PrivateKey.Password provided, it is assumed that the private key
file is not encrypted) or password for key
saved in KEYSTORE. Must be used for both
FILE/KEYSTORE storage types if only
password is encrypted.

SAML.ServiceProvider.Step. stepSAMLEncryption Alias of private key for signing SAML

Encryption.PrivateKey.Alias assertions if stored in KEYSTORE. Must be
provided when using KEYSTORE as a storage
type. Key should be in PEM X509 format and
secured with a password.

SAML.ServiceProvider.Step. ${SHARED_DIR}/encryption/ File containing private key for encrypting

Encryption.PrivateKey.File stepSAMLEncryption.pkcs8 SAML assertions. ${SHARED_DIR} is a variable
that, in a clustered setup, points to a
directory accessible from all app servers
(value of System.SystemShare.Root).
${SHARED_DIR} must be used as the prefix
for property value followed by relative path
to the key file. Must be provided when using
FILE as a storage type. Key should be in PEM
X509 format and secured with a password.

SAML.ServiceProvider.Step. changeit Password for encrypting private key (if none

Encryption.PrivateKey.Password is provided, it is assumed that the private key
file is not encrypted) or password for key
saved in keystore. Must be used for both
FILE/KEYSTORE storage types if only
password is encrypted.

SAML.ServiceProvider.Step.KeyStore.File ${SHARED_DIR}/keystore.store File containing KeyStore for SAML purpose.

${SHARED_DIR} is a variable that, in a
clustered setup, points to a directory
accessible from all app servers (value of
System.SystemShare.Root). ${SHARED_DIR}
must be used as the prefix for property value
followed by relative path to the KeyStore file.
Must be provided when using KEYSTORE as a
storage type.

SAML.ServiceProvider.Step. changeit Password to provided KeyStore. Must be

KeyStore.Password provided when using KEYSTORE as a storage
type.

SAML.ServiceProvider.Step. Country name used for generating signing

Signing.Certificate.CountryName certificate (C field in X509 certificate
definition).

SAML.ServiceProvider.Step. State or province name used for generating

Signing.Certificate.StateOrProvinceName signing certificate (ST field in X509 certificate
definition).

SAML.ServiceProvider.Step. City name used for generating signing

Signing.Certificate.City certificate (L field in X509 certificate
definition).

© Stibo Systems - Confidential 47

SAML.ServiceProvider.Step. Organization name used for generating
Signing.Certificate.OrganizationName signing certificate (O field in X509 certificate
definition).

SAML.ServiceProvider.Step. Organization unit name used for generating

Signing.Certificate.OrganizationUnitName signing certificate (OU field in X509 certificate
definition).

SAML.ServiceProvider.Step. Common name used for generating signing

Signing.Certificate.CommonName certificate (CN field in X509 certificate
definition).

SAML.ServiceProvider.Step. Email address used for generating signing

Signing.Certificate.EmailAddress certificate (EMAILADDRESS field in X509
certificate definition).

SAML.ServiceProvider.Step. 365 Number of days until generated signing

Signing.Certificate.ValidDays certificate is valid. Default is 365 days. After
that period generated certificate has to be
renewed.

SAML.ServiceProvider.Step. Country name used for generating

Encryption.Certificate.CountryName encryption certificate (C field in X509
certificate definition).

SAML.ServiceProvider.Step. State or province name used for generating

Encryption.Certificate.StateOrProvinceName encryption certificate (ST field in X509
certificate definition).

SAML.ServiceProvider.Step. City name used for generating encryption

Encryption.Certificate.City certificate (L field in X509 certificate
definition).

SAML.ServiceProvider.Step. Organization name used for generating

Encryption.Certificate.OrganizationName encryption certificate (O field in X509
certificate definition).

SAML.ServiceProvider.Step. Organization unit name used for generating

Encryption.Certificate.OrganizationUnitName encryption certificate (OU field in X509
certificate definition).

SAML.ServiceProvider.Step. Common name used for generating

Encryption.Certificate.CommonName encryption certificate (CN field in X509
certificate definition).

SAML.ServiceProvider.Step. Email address used for generating encryption

Encryption.Certificate.EmailAddress certificate (EMAILADDRESS field in X509
certificate definition).

SAML.ServiceProvider.Step. 365 Number of days until generated encryption

Encryption.Certificate.ValidDays certificate is valid. Default is 365 days. After
that period generated certificate has to be
renewed.

Required configuration for basic usage contains properties:

SAML.Enabled,
SAML.ServiceProvider.Step.EntityID,
SAML.ServiceProvider.Step.AssertionConsumerService.Location,
SAML.ServiceProvider.Step.SingleLogoutService.Location,
SAML.IdentityProviders.Names,
SAML.IdentityProvider.n.Metadata.Endpoint,
SAML.IdentityProvider.n.EntityId
properties connected with certificates/private keys.

48 © Stibo Systems - Confidential

Additional properties are available for customizing STEP as a Service Provider.

Example settings

Below example is based on configuration for open-source "shibboleth" Identity Provider server.

SAML.Enabled = true

SAML.IdentityProviders.Names=Test
SAML.IdentityProvider.Test.EntityId=https://idptest/idp/shibboleth
SAML.IdentityProvider.Test.Metadata.Endpoint=https://idptest/idp/shibboleth
SAML.IdentityProvider.Test.Metadata.OfflineCache.Path=workarea/STEP-LOCALHOST.xml

SAML.ServiceProvider.Step.EntityID=https://stepwebstart
SAML.ServiceProvider.Step.AssertionConsumerService.Location=https://stepwebstart/saml/StepAssertion
SAML.ServiceProvider.Step.SingleLogoutService.Location=https://stepwebstart/saml/StepLogout
SAML.ServiceProvider.Step.Signing.Certificate.File=${SHARED_DIR}/test/signing/stepTestSigning.cert
SAML.ServiceProvider.Step.Signing.PrivateKey.File=${SHARED_DIR}/test/signing/stepTestSigning.pkcs8
SAML.ServiceProvider.Step.Signing.PrivateKey.Password=s3cr3t
SAML.ServiceProvider.Step.Encryption.Certificate.File=${SHARED_DIR}/test/encryption/stepTestEncryption.cert
SAML.ServiceProvider.Step.Encryption.PrivateKey.File=${SHARED_DIR}/test/encryption/stepTestEncryption.pkcs8
SAML.ServiceProvider.Step.Encryption.PrivateKey.Password=s3cr3t

HttpAuthentication.Resource.CoreSAML.Type=CoreSAML
HttpAuthentication.ResourceNames=CoreSAML

Example for generating certificates:

© Stibo Systems - Confidential 49

 # General configuration
SAML.CertificatesAndKeys.Generate=true
SAML.CertificatesAndKeys.Storage=KEYSTORE

# Keystore information
SAML.ServiceProvider.Step.KeyStore.Password=changeit
SAML.ServiceProvider.Step.KeyStore.File=${SHARED_DIR}/keystore.store

# Signing key and certificate

SAML.ServiceProvider.Step.Signing.PrivateKey.Password=changeit
SAML.ServiceProvider.Step.Signing.PrivateKey.Alias=stepSAMLSigning
SAML.ServiceProvider.Step.Signing.Certificate.Alias=stepSAMLSigningCert

SAML.ServiceProvider.Step.Signing.Certificate.CountryName=DK
SAML.ServiceProvider.Step.Signing.Certificate.StateOrProvinceName=North Denmark
SAML.ServiceProvider.Step.Signing.Certificate.City=Aarhus
SAML.ServiceProvider.Step.Signing.Certificate.OrganizationName=StiboSystems
SAML.ServiceProvider.Step.Signing.Certificate.OrganizationUnitName=RD
SAML.ServiceProvider.Step.Signing.Certificate.CommonName=StiboSystems
SAML.ServiceProvider.Step.Signing.Certificate.EmailAddress=test@stibosystems.com
SAML.ServiceProvider.Step.Signing.Certificate.ValidDays=3650

# Encryption key and certificate

SAML.ServiceProvider.Step.Encryption.PrivateKey.Password=changeit
SAML.ServiceProvider.Step.Encryption.Certificate.Alias=stepSAMLEncryptionCert
SAML.ServiceProvider.Step.Encryption.PrivateKey.Alias=stepSAMLEncryption

SAML.ServiceProvider.Step.Encryption.Certificate.CountryName=DK
SAML.ServiceProvider.Step.Encryption.Certificate.StateOrProvinceName=North Denmark
SAML.ServiceProvider.Step.Encryption.Certificate.City=Aarhus
SAML.ServiceProvider.Step.Encryption.Certificate.OrganizationName=StiboSystems
SAML.ServiceProvider.Step.Encryption.Certificate.OrganizationUnitName=RD
SAML.ServiceProvider.Step.Encryption.Certificate.CommonName=StiboSystems
SAML.ServiceProvider.Step.Encryption.Certificate.EmailAddress=test@stibosystems.com
SAML.ServiceProvider.Step.Encryption.Certificate.ValidDays=3650

Workbench SSO
Single Sign On functionality, already configured for the Web UI, can also be enabled for the workbench. In
order to enable SSO for the workbench, the SSO for the WebUI must already be enabled, via the following
configuration:

Workbench.Authentication.UseSSO=true

<the rest of the HttpAuthentication.* configuration>

When SSO is enabled for the workbench, the user will be authenticated on the webstart page, before
downloading the workbench.

Although this will disable the manual workbench login prompt, it is still possible to perform manual

50 © Stibo Systems - Confidential

workbench login by going to the following url:

http://step.server.hostname/workbenchlauncher/manualwblogin

Smartsheet SSO
In order to enable SSO for smartsheets, set the SSO on configuration property:

SmartSheet.Authentication.Method=SSO

When SSO is enabled for the smartsheet, users will be authenticated via the configured SSO provider
when performing an action requiring access to STEP data.

Please be aware that this will disable basic authentication in smartsheets. Also remember that SSO won’t
be working for older smartsheet files downloaded before the configuration property has been set to use
SSO mode.

STEP Logout behavior

The logout behavior of STEP depends on whether the user has logged in manually or using an SSO
solution, as well as on whether there are any customizations to it.

When manual authentication is used, by default STEP presents the user with the Login page. However, if
the user logged in using an SSO solution, the following login screen is displayed:

From here, the user can choose to login automatically again, using the SSO solutions, or login manually as
another user.

Once the user logs in manually, the state of the session will change and he/she cannot
NOTE
login using SSO unless the browser is restarted.

If the default behavior is not wanted, this can be changed with customizations to the post logout action.

© Stibo Systems - Confidential 51

Workbench 3rd Party Proxy
Using the workbench with a 3rd party proxy requires the JRE installation to be configured on the client
machine.

• Open the Java Control Panel on the client machine.

• Java 8 and earlier:

Select "Network Settings…" on the General tab.

• Java 10:
Select the "Network" tab on the Web Settings tab.

Use browser settings

This is the default option, which means that any java appllications will run with the same proxy
configuration as the client machines default browser.

Use proxy server

This option will run the java applications with the configured proxy for all http based communication.

If https(secure) communication is needed, then this can be enabled by selecting the "Advanced Network
Settings (Java8)" or "Refine (Java10)" option, and configuring the additional parameters.

OAuth2-Based Authentication for SaaS

customers
From STEP 10.0 it is possible for Stibo Systems to enable OAuth2-based authentication for SaaS
customers. A STEP system for which OAuth2-based authentication has been enabled will functionality-
wise work like any other STEP system. The login process will however differ and further, 3rd party
applications integrating with STEP via the HTTP-based STEP APIs (GraphQL, REST, SOAP) must obtain a
token to be passed with the service requests.

User Interfaces
With OAuth2-based authentication enabled, authentication for all STEP user interfaces (Web UIs,
Workbench, STEP Homepage, STEP System Administration etc.) will be handled centrally. In practice, when
a user accesses a Web UI or the STEP Homepage without being authenticated, he/she will be redirected to
the central login page and will upon successful authentication be able to access all STEP user interfaces
without having to re-enter credentials.

52 © Stibo Systems - Confidential

HTTP-Based APIs
With OAuth2-based authentication enabled, all HTTP-based STEP APIs (GraphQL, REST, SOAP) require
Bearer Authentication using which an access token is passed with each API request. The sections below
describe how 3rd party applications can obtain a token. Notice that for existing customers who already
have 3rd party applications integrating with STEP via the REST or SOAP APIs, it is possible for Stibo
Systems to enable the option to still use Basic Authentication (REST) / passing credentials in message
body (SOAP) even with OAuth2-based authentication enabled. This will however not work for users
maintained and authenticated by external identity providers.

Integrations from 3rd Party User Interfaces

When integrating with STEP from an application with a user interface, an access token should be obtained
using Open ID Connect (OIDC). With OIDC configured, 3rd party application users must be redirected to
the central STEP authentication page when trying to access STEP resources. Upon successful
authentication, users will be redirected back to the 3rd party application with an access token that can be
used for communication with the STEP APIs. The OIDC configuration endpoint for STEP is
[server]/auth/.well-known/openid-configuration (still valid pre-STEP 10.1 endpoint is [server]/auth/openid-
configuration). Clients should be configured to use the authorization code flow (grant_type:
authorization_code), preferably with Proof-Key for Code Exchange (PKCE). In addition to the information
available via the OIDC endpoint, an OIDC client ID is required for configuring the client application and
further client application URLs should be configured on the STEP side to avoid CORS issues. Please contact
Stibo Systems to have client URLs registered and to obtain the client ID to use.

Machine to Machine Integrations

For machine to machine integrations where no human user is involved, OIDC cannot be used. Instead
STEP exposes an endpoint [server]/auth/token using which client applications can trade user credentials
for an access token by sending a POST request with a JSON requets body like:

{
  "username": "myusername",
  "password": "mypassword"
}

Notice that the [server]/auth/token functionality only works with credentials for users maintained and
authenticated in STEP or a user federation database.

User Federation and Identity Brokering

The OAuth2-based authentication mechanism can work with users maintained and authenticated in STEP
but further supports identity brokering and can be configured to work with 3rd party SAML 2.0 or OAuth2
compliant identity providers. Also, it is possible to integrate with an external user database like Active
Directories via LDAP or Kerberos. For all integrations, it is possible to configure synchronization of users

© Stibo Systems - Confidential 53

and user metadata (group membership, attributes) to STEP. Please contact Stibo Systems for more
information about the integration capabilities.

Http Authentication Test Tool

Introduction
STEP comes with a built-in tool called “Http Authentication Test Tool”, which makes it possible to test new
or alternative SSO and LDAP configurations without affecting the running STEP server and its
configurations.

Tool access
The “Http Authentication Test Tool” is hosted on the following URL: http://step.server.hostname/webui/
webui/authenticationtest

It can accessed directly or through the link on the Admin Web UI’s “Tools” page (right-click on the link and
select “open in new tab” to stay in Admin Web UI).

Test configurations
To avoid interferences with the configuration of the running STEP server, the test tool will load its own
separate configurations from a predefined file.

The test configuration file is defined by the following config property:

Property Description

Http.Authentication.Test.Config.Property.File The path to file (can be absolute or relative). Defaults to

“STEPRootDir”/admin/operations/authentiontest/config.properties”

This is not a hot property, so adding or changing it only takes effect when the STEP server
NOTE
is restarted.

The test configuration file is loaded as hot properties, and changes applied to that file will
NOTE take effect “immediately”. However as mentioned earlier you are not allowed to change
the file name property without restarting server.

For security reasons it is not possible to output test configuration errors during the test
NOTE itself. If the test is failing for unknown reasons it is therefore necessary to consult the STEP
log files.

54 © Stibo Systems - Confidential

Test Output
A variety of messages can be displayed while testing. The message text and descriptions are defined
below.

User not automatically authenticated

None of the configured authentication plugins were able to handle authentication of the user accessing
the servlet. This might be caused by a misconfiguration in the test configuration file on the client, or on
external resources. Consult the STEP logs for available info.

User automatically authenticated as “username”

One of the configured authentication plugins was able to handle authentication of the user “username”
accessing the servlet. Consult the STEP logs for available info.

“message” returned ‘Responded’

One of the configured authentication plugins was in the process of handling authentication of the user
accessing the servlet. The “Responded” status means that the plugin is awaiting a response from an
external source. This might be due to a misconfiguration of external services that are not redirecting
correctly to the servlet, or the nature of the authentication solution which might not be compatible with
this test solution. Consult the STEP logs for available info.

Fatal error occurred | No state | No session

HTTP ERROR 401

The test configurations could not be loaded or one of the configured plugins encountered an internal
error. Consult the STEP logs for available info.

Limitations
User Synchronization

User synchronization is currently not supported by the Http Authentication Test Tool.

Caveats
• Multiple authentication mechanisms are not supported previous to STEP 7.4.

• If none of the STEP groups have a "LDAP Synchronization ID" and there is no default group
configured, the user is rejected from login with "username does not exist".

• If a STEP user is not a member of any LDAP groups that match a STEP group’s

© Stibo Systems - Confidential 55

 "LdapSynchronizationID" and there is no default group configured, the user is rejected from login with
"invalid user or password".

• If a user is member of a group in LDAP, this membership is only subject to synchronization if the LDAP
group name is registered in the "LdapSynchronizationID" field on a STEP group.

• If a user is member of a STEP group with a valid "LdapSynchronizationID", he may be removed from
this group if he is not member of the corresponding group in LDAP.

• If a user is member of a STEP group with a valid "LdapSynchronizationID", he will not be removed
from this group if not known to the LDAP.

• If a user logs in through the STEP Workbench and leaves the client instance open for several days, the
user will not be affected by changes to the user’s group memberships in LDAP until the user logs off
and in again.

• It may be necessary to do some security modifications if the SSL communication with the LDAP server
does not work. Due to import control restrictions, the version of JCE policy files that are bundled in the
JDK™ environment allow "strong" but limited cryptography to be used. Therefore, it is necessary to
download and install the "Unlimited Strength Java Cryptography Extension Policy Files".

Appendix
Deprecated LDAP configuration properties
The section contains the deprecated configuration properties used for authentication. The global LDAP
properties (Global properties) can be used together with the deprecated configuration properties.

NOTE The deprecated configuration only supports synchronization of the email attribute!

Basic properties

Property Description

LDAP.AuthenticationMechanisms Default is "simple", which will typically be used with SSL.

Alternatively, use “GSSAPI” (Kerberos).

LDAP.ServerURL The URL of the company’s LDAP server, e.g.:

ldap://ad‑server.mycompany.com:389.

LDAP.UserDistinguishedName The distinguished name of user to be authenticated e.g: domain\%u,

%u@stibo.com or uid=%u,ou=Catalog,dc=stibo,dc=corp. The %u will be
replaced by the current user on runtime. NOTE: This is a required
configuration.

LDAP.BaseDN The distinguished name of the node to search for user in your
company’s LDAP, e.g.
"OU=Catalog,OU=Hoejbjerg,OU=DK,OU=Domain
Users,DC=stibo,DC=corp". NOTE: This field is mandatory if
LDAP.AuthenticateAndSynchronize=true. If this value is not specified,
lookup of user in LDAP will fail.

56 © Stibo Systems - Confidential

Property Description

LDAP.UserBaseDN The DN base used for searches specific for user attributes. Normally,
this is the same as LDAP.BaseDN, and is used instead of
LDAP.BaseDN in most cases. To specify multiple user baseDNs
separate them with the new line character "\n" : DC=test\nDC=other.
If configured, the number of user baseDN configurations must
match the number of LDAP.FindUserDNFilter. If not configured, the
LDAPBaseDN will be used.

LDAP.FindUserDNFilter The search filter used for looking up a user or user’s groups in LDAP.
This filter may contain the attribute to use for locating a userid. %u
(e.g. in the default value: "(sAMAccountName=%u)") will at runtime
be replaced by username from login. It may as well contain a search
filter to directly find the groups that the user is member of (Again,
use %u for replacement). For configuring multiple filters, separate
them by the new line character "\n" : (filter1)\n(filter2)

Basic properties (SSL)

Property Description

LDAP.SecurityProtocol The protocol to use for communicating with the LDAP server. Set this
to ssl if you wish to communicate via secure socket layer. Otherwise
leave blank (which is the default).

Basic properties (Kerberos)

Property Description

LDAP.JAASConfigurationEntryName Name of the entry in the JAAS configuration file to use. Typical value
is "STEP". Do not use “spnego-server” entry which is used for Web UI
standard SSO.

User Synchronization properties

Property Description

LDAP.AuthenticateAndSynchronize Authentication will be followed by a synchronization of group

memberships. For example, if the user is a member of an LDAP
group that is marked in STEP as LDAP managed, this membership
will be inherited in STEP. In fact, this allows an unknown STEP user to
be automatically created in STEP if he is authenticated against LDAP
and at least one LDAP group membership matches a STEP group, or
an LDAP default STEP group has been declared. Note that this is a
one-time authentication…

LDAP.MemberOfAttributeName (Only used with Microsoft AD) This is the name of the attribute in
LDAP that contains membership. If this property is blank or
nonexistent, it is assumed that group memberships are not to be
found in an attribute on the user entity.

LDAP.SynchronizeUserEMailFrom The ID of the attribute in LDAP containing the email address of the
user. This is typically “mail”. If the property is set, the email stored in
LDAP for the user will be synchronized to the user in STEP.

© Stibo Systems - Confidential 57

Additional features properties

Property Description

LDAP.NotifyDaysBeforeExpire Upon login, the user will be notified about his LDAP password expiry
the specified number of days before. Defaults to 10 days.

LDAP.ChangePassword When set to true, passwords can be changed in LDAP. Defaults to

false.

LDAP.Domains Defines the login domains as a comma-separated list. Default is

blank and indicates only one domain.

LDAP.BindAccount.DN The bind account used when searching after users. This is NOT used
for authentication but for synchronization and password expiration
warning mechanisms. And it is NOT used for Web UI SSO
mechanisms. The Web UI standard SSO has its own property
LDAP.Preauthentication.UserName which it uses for synchronization.
Mandatory property if trusted headers are configured with LDAP.

LDAP.BindAccount.Password The password of the bind account.

Single-Sign-On properties

Property Description

LDAP.Preauthentication.UserName Property used with the SPNEGO Kerberos single-sign Web UI solution
to specify the Principal used for pre-authentication. Not used at all
for ordinary LDAP operations.

LDAP.Preauthentication.Password Property used with the SPNEGO Kerberos single-sign Web UI solution
to specify the Password used for pre-authentication.

Additional seldom used properties

Normally these properties should just be left at their defaults.

Property Description

LDAP.JAASSendUppercaseUsername Convert usernames to uppercase when authenticating against LDAP.

Only used with JAAS authentication enabled (When
LDAP.AuthenticationMechanisms=GSSAPI). Defaults to false.

LDAP.JAASSendLowercaseUsername Convert usernames to lowercase when authenticating against LDAP

(is ignored if LDAP.JAASSendUppercaseUsername = true). Only used
with JAAS authentication enabled (When
LDAP.AuthenticationMechanisms=GSSAPI). Defaults to false.

Configuration examples for the deprecated configuration

Kerberos configuration - LegacySSO

The following example configures STEP to access LDAP via Kerberos. Members of groups are listed as
"uniqueMember" on the "groupOfUniqueNames" group entity.

58 © Stibo Systems - Confidential

 LDAP.Enabled=true
LDAP.AuthenticateAndSynchronize=true
LDAP.InitialContextfactory=com.sun.jndi.ldap.LdapCtxFactory
LDAP.Timeout=15

LDAP.SynchronizeUserEMailFrom=mail
LDAP.MemberOfAttributeName=memberOf
LDAP.FindUserDNFilter=(sAMAccountName=%u)
LDAP.BaseDN=dc=company,dc=com
LDAP.UserBaseDN=dc=company,dc=com
LDAP.UserDistinguishedName=%u
LDAP.Domains=company.com

LDAP-AuthenticationMechanisms=GSSAPI
LDAP.SecurityProtocol=simple
LDAP.ServerURL=ldap://ldap-server.company.com:389

LDAP.JAASConfigurationEntryName=STEP
LDAP.KerberosConfigurationFile=/home/stibosw/step/shared/jaas/krb5.conf
LDAP.JAASConfigurationFile=/home/stibosw/step/shared/jaas/step-jaas.conf

Example of the kerberos configuration krb5.conf file:

[libdefaults]
  default_realm = COMPANY.COM
  default_tkt_enctypes = aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha1-96 rc4-hmac
  default_tgs_enctypes = aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha1-96 rc4-hmac
  udp_preference_limit = 1
[realms]
  DOMAINTEST.CORP = {
  kdc = ldap-server.company.com:88
  default_domain = COMPANY.COM
  }
[domain_realm]
  . COMPANY.COM = COMPANY.COM
  kdc = FILE:krb5kdc.log
  default = FILE:krb5lib.log

Example of the kerberos configuration step-jaas.conf file:

© Stibo Systems - Confidential 59

 STEP {
  com.sun.security.auth.module.Krb5LoginModule required;
};

spnego-client {
  com.sun.security.auth.module.Krb5LoginModule required;
};

spnego-server {
  com.sun.security.auth.module.Krb5LoginModule required
  storeKey=true
  isInitiator=false;
};

OAuth configuration properties – LegacyGoogleAccountOAuth

Property Description

Portal.UseOAuth Boolean value for enabling OAuth in the Web UI.

OAuth.Redirect.Url URL that is used for the purpose of basic callback-redirection.

OAuth.Resource.Server.Key Server key used for authentication-step process.

OAuth.Resource.Server.Secret Server secret key.

OAuth.Authenticating.Endpoint Authenticating endpoint.

OAuth.Token.Endpoint Token request endpoint.

OAuth.Validation.Endpoint Token validation endpoint.

OAuth.Client.Id Client identifier.

OAuth.Client.Secret Client secret key.

OAuth.Authenticating.Scope Authentication scope.

OAuth.Authenticating.Hint Authentication user hint.

Auth configuration example

60 © Stibo Systems - Confidential

 #Enbale OAuth
Portal.UseOAuth=true

# Authentication endpoint url (OAuth 1st step - request token)

OAuth.Authenticating.Endpoint=https://accounts.google.com/o/oauth2/auth

# Token exchange endpoint url (OAuth 2nd step - token exchange)

OAuth.Token.Endpoint=https://accounts.google.com/o/oauth2/token

# Token validation endpoint url (OAuth 3d step - token validation)

OAuth.Validation.Endpoint=https://www.googleapis.com/oauth2/v1/tokeninfo

# Account access scope (it is used to allow the application some scope of user data)
OAuth.Authenticating.Scope=profile

# This is the hint displayed at the 1st step at provider side (Google will show "email" in the appropriate fields for typing the account
credentials)
OAuth.Authenticating.Hint=email

# This url is the point where the user is redirected in the end (even if the authentication failed on some reason)
OAuth.Redirect.Url=http://stibo-auth.com:9870/

# OAuth Provider client identifier

OAuth.Client.Id=449161492363-1bopd4q69vb43p6j660lndpdtvnjq8ea.apps.googleusercontent.com

# OAuth Provider client secret code

OAuth.Client.Secret=YSsl_Nl7nfnnu815UG-NUX6k

Setting up SSO, LDAP server, using the deprecated

configuration
The STEP server of a Web UI application must also be authorized to access the LDAP Server (AD) and must
have an account that is allowed to look up and authenticate other users. But the STEP server does not
necessarily have to be logged to the domain in order to perform authentication. It is necessary to setup a
Service Principal Name (SPN) for the Web UI service. An SPN is used for mapping the Web UI service to a
user so the AD knows that the Web UI server is allowed to authenticate users for the Web UI.

To see which servers are already configured for a specific preauthentication user: * setSPN -L
[preauthentication user]

To add an SPN for Web UI located at http://portalserver.stibo.com/webui, run the setSPN command on
the LDAP Server (instructions apply for Windows ADs only): * setSPN -a http/[server] [preauthentication
user] e.g.: setSPN -a http/portalserver.stibo.com preauthUser

The Web UI URL used in this command must be the fully qualified URL, even if the server can be reached
by its short name (e.g. http://portalserver). Note that it is NOT supposed to be http:// but just http/

If the Web UI is hosted on a port different from the default port 80, the port number must also be
specified in the setSPN command, e.g. http/portalserver.stibo.com:8080 (i.e. both with and without port

© Stibo Systems - Confidential 61

number)

Web UI SSO uses kerberos tokens for secure communication, which means that the LDAP Server must
support Kerberos. Kerberos has been the standard recommended by Microsoft since Windows 2000
server, and it has been the default on Windows servers ever since.

NOTE NTLM is NOT supported!

Setting up SSO, STEP application server, using the

deprecated configuration
Settings needed in the config.properties file for SSO to work:

LDAP.Enabled=true
LDAP.AuthenticateAndSynchronize=true
LDAP.InitialContextfactory=com.sun.jndi.ldap.LdapCtxFactory
LDAP.Timeout=15
Portal.UseSSO=true

LDAP.SynchronizeUserEMailFrom=mail
LDAP.MemberOfAttributeName=memberOf
LDAP.FindUserDNFilter=(sAMAccountName=%u)
LDAP.BaseDN=dc=company,dc=com
LDAP.UserBaseDN=dc=company,dc=com
LDAP.UserDistinguishedName=%u
LDAP.Domains=company.com
LDAP-AuthenticationMechanisms=GSSAPI
LDAP.SecurityProtocol=simple
LDAP.ServerURL=ldap://ldap-server.company.com:389

LDAP.JAASConfigurationEntryName=STEP
LDAP.KerberosConfigurationFile=[path]/krb5.conf
LDAP.JAASConfigurationFile=[path]/step-login.conf
LDAP.Preauthentication.UserName=[user name for the authentication account on the LDAP server]
LDAP.Preauthentication.Password=[password for the authentication account on the LDAP server]

If LDAP is enabled for the workbench, but SSO is not desired for the Web UI, use this setting: *
Portal.UseSSO=false

The LDAP.JAASConfigurationFile file must contain entries spnego-client and spnego-server,

NOTE
which is used by this standard SSO mechanism.

Trusted Headers – deprecated configuration and behavior

(LegacyTrustedHeaders)
Before STEP 7.4, if a request without headers would come into STEP, the user would be redirected to the

62 © Stibo Systems - Confidential

login url configured.

Configuration

Portal.TrustedHeaders=true
TrustedHeaders.Header.Username=[Name of the header which contains the user name]
TrustedHeaders.Header.SessionId=[Name of the header which contains the user Session ID from the authentication server]
TrustedHeaders.LoginUrl=[URL for redirect on fail]

Additional STEP Settings for Trusted Headers with LDAP

Portal.UseSSO=false
LDAP.Enabled=true

(See LDAP configuration for more properties related to LDAP integration and synchronization)

About Stibo Systems

Stibo Systems provides global organizations with a leading multi-domain Master Data Management
(MDM) solution. Stibo Systems enables its customers to better manage enterprise intelligence on a global
scale, improve sales, and quickly adjust to changes in business requirements. Stibo Systems' STEP
technology is a flexible MDM solution that provides a single trusted source of operational information for
the entire enterprise. Stibo Systems offers industry-specific solutions, engineered and supported to meet
the strategic information needs of global customers including: GE, Sears, Siemens, Target and Thule.
Stibo Systems is a subsidiary of the privately held Stibo A/S group, originally founded in 1794 with
corporate headquarters in Aarhus, Denmark.

For more information, please visit www.stibosystems.com.

© Stibo Systems - Confidential 63