josso 2 - atricoredocs.atricore.com/josso2/2.4.0/josso-reference-guide/docbook/... · iii 1....
TRANSCRIPT
JOSSO 2.4
JOSSO 2.4
iii
1. Introduction ................................................................................................................. 1
1.1. Enter Point-and-Click Internet Single Sign On (SSO) ............................................. 1
1.2. First or Second Generation ? .............................................................................. 1
2. JOSSO2 Rollout ........................................................................................................... 4
2.1. Install JOSSO ..................................................................................................... 4
2.2. The JOSSO2 Layout ........................................................................................... 5
3. The Building Blocks .................................................................................................... 7
3.1. Architecture ........................................................................................................ 7
3.1.1. OSGi background .................................................................................... 7
3.1.2. Identity Appliances ................................................................................... 7
3.2. JOSSO2 Building Blocks ................................................................................... 10
3.2.1. Providers ............................................................................................... 10
3.2.2. Cloud Providers ..................................................................................... 12
3.2.3. Identity Sources ..................................................................................... 13
3.2.4. Execution Environments ......................................................................... 15
3.2.5. Authentication Servers ............................................................................ 17
3.2.6. Connections ........................................................................................... 19
3.2.7. Resources ............................................................................................. 23
4. Atricore Console and Model Driven Identity .............................................................. 27
4.1. Model-Driven Identity ........................................................................................ 27
4.2. Modeling vs. Implementing ................................................................................ 28
4.3. What is Model-Driven Development? ................................................................. 28
4.4. The Identity Architect Role ................................................................................ 28
4.5. Identity Appliance Modeler Overview .................................................................. 29
4.6. Identity Appliance Life Cycle Management Overview ........................................... 31
4.7. Account and Entitlement Management Overview ................................................. 31
4.7.1. Accounts Overview ................................................................................. 32
4.7.2. Groups Overview ................................................................................... 32
4.7.3. Schema Overview .................................................................................. 32
4.8. System Settings Overview ................................................................................. 32
4.9. Help Overview .................................................................................................. 32
5. Identity Appliance Creation ....................................................................................... 33
5.1. Starting from Scratch ........................................................................................ 33
6. Identity Source Setup ................................................................................................ 35
6.1. Setup of an Embedded Identity Vault ................................................................. 35
6.2. Setup of a Database Identity Vault ..................................................................... 36
6.3. Setup of an LDAP Directory Identity Source ....................................................... 37
6.4. Set Up an RDBMS Identity Source .................................................................... 41
7. Authentication Setup ................................................................................................. 44
7.1. Set Up Directory-based Authentication ............................................................... 44
7.2. Set Up Integrated Windows Authentication ......................................................... 47
7.3. Set Up Two-Factor Authentication ...................................................................... 49
7.4. Set Up Domino Authentication ........................................................................... 50
7.5. Set Up Client-certificate Authentication ............................................................... 51
JOSSO 2.4
iv
7.6. Set Up JBoss EPP Authentication ...................................................................... 52
8. Identity Provider Setup .............................................................................................. 53
8.1. Add an Internal IdP to the Identity Appliance ...................................................... 53
8.2. Add an external SAML2 IdP to the Identity Appliance .......................................... 59
8.3. Add an external OpenID IdP to the Identity Appliance ......................................... 59
8.4. Add Google Sign-In to the Identity Appliance ...................................................... 60
8.5. Set Up the Identity Store of the Identity Provider ................................................. 61
8.5.1. Using an Embedded Identity Vault as the Authoritative Source for the
Identity Provider .............................................................................................. 61
8.5.2. Using a DB Identity Vault as the Authoritative source for the Identity
Provider .......................................................................................................... 62
8.5.3. Using an LDAP Directory as Authoritative Source for the Identity Provider ... 62
8.5.4. Using an RDBMS as Authoritative Source for the Identity Provider ............. 62
9. Service Provider Setup .............................................................................................. 63
9.1. Internal SAML2 Service Provider Setup .............................................................. 63
9.2. External SAML2 Service Provider Setup ............................................................. 67
9.3. Internal OAuth2 Service Provider Setup ............................................................. 67
9.4. Add Salesforce to the Identity Appliance ............................................................ 68
9.5. Add Google Apps to the Identity Appliance ......................................................... 69
9.6. Add SugarCRM to the Identity Appliance ............................................................ 69
9.7. Set Up the Identity Source of the Service Provider .............................................. 70
9.7.1. Using an Identity Vault as the Authoritative Source for the Service Provider .. 70
9.7.2. Using an LDAP Directory as the Authoritative Source for the Service
Provider .......................................................................................................... 70
9.7.3. Using an RDBMS as the Authoritative Source for the Service Provider ...... 71
9.8. Set Up the Resource of the Service Provider ...................................................... 71
9.8.1. Onboarding a JOSSO1 Resource ............................................................ 72
9.8.2. Onboarding a Sharepoint Resource ......................................................... 73
9.8.3. Onboarding a Microstrategy Resource ..................................................... 73
9.8.4. Onboarding an Alfresco Resource ........................................................... 74
9.8.5. Onboarding a JBoss Portal Resource ...................................................... 75
9.8.6. Onboarding a Liferay Portal Resource ..................................................... 76
9.8.7. Onboarding a PhpBB Resource .............................................................. 77
9.8.8. Onboarding a JBossEPP Resource ......................................................... 79
9.8.9. Onboarding a Self-Services Resource ..................................................... 80
9.8.10. Onboarding a Domino Resource ........................................................... 80
9.9. Set Up the Execution Environment of the Resource ............................................ 81
9.9.1. Using an Apache Web Server Execution Environment .............................. 81
9.9.2. Using a JavaEE Execution Environment .................................................. 82
9.9.3. Using a Webserver Execution Environment .............................................. 83
9.9.4. Using a PHP Execution Environment ....................................................... 84
9.9.5. Using an Oracle Weblogic Execution Environment .................................... 85
9.9.6. Using a Websphere Community Edition (WASCE) Execution Environment .. 87
9.9.7. Using a Windows IIS Execution Environment ........................................... 89
JOSSO 2.4
v
9.9.8. Using an Apache Tomcat Execution Environment ..................................... 91
9.9.9. Using a JBoss Execution Environment ..................................................... 93
10. Circle of Trust Establishment .................................................................................. 96
10.1. Connecting Identity Providers with Service Providers ......................................... 96
11. Identity Appliance Lifecycle Management .............................................................. 101
11.1. Build an Identity Appliance ............................................................................. 101
11.2. Deploy an Identity Appliance .......................................................................... 101
11.3. Managing Identity Appliance Execution ........................................................... 102
11.3.1. Start an Identity Appliance .................................................................. 102
11.3.2. Stop an Identity Appliance .................................................................. 102
11.4. Undeploy an Identity Appliance ...................................................................... 102
11.5. Dispose an Identity Appliance ........................................................................ 103
11.6. Remove an Identity Appliance ........................................................................ 103
12. Execution Environment Activation ......................................................................... 104
12.1. Bringing SSO-Readiness to Execution Environments ....................................... 104
13. Account and Entitlement Management .................................................................. 106
13.1. Identity Vault Selection .................................................................................. 106
13.2. User Accounts .............................................................................................. 106
13.2.1. General User Information .................................................................... 106
13.2.2. User Language Preferences ................................................................ 107
13.2.3. User Groups ...................................................................................... 108
13.2.4. User Account Security ........................................................................ 108
13.2.5. Account Password .............................................................................. 109
13.2.6. Provision a User Account .................................................................... 110
13.2.7. Update User Details ........................................................................... 110
13.2.8. Search Users ..................................................................................... 110
13.2.9. Deprovision a User Account ................................................................ 110
13.3. Groups ......................................................................................................... 110
13.3.1. Provision a Group .............................................................................. 110
13.3.2. Search Groups ................................................................................... 110
13.3.3. Update a Group ................................................................................. 111
13.3.4. Deprovision a Group ........................................................................... 111
14. Profile Operations .................................................................................................. 112
15. System Settings ..................................................................................................... 113
15.1. Platform Settings ........................................................................................... 113
15.1.1. Controlling Web Settings ..................................................................... 113
15.1.2. Controlling SSH Settings ..................................................................... 114
15.1.3. Controlling Persistence Settings .......................................................... 114
15.1.4. Controlling Monitoring and Management Settings .................................. 115
15.1.5. Controlling Message Bus Settings ....................................................... 116
15.1.6. Controlling Logging Settings ................................................................ 116
15.1.7. Controlling Branding Settings .............................................................. 117
15.2. Live Services ................................................................................................ 117
15.3. Licensing ...................................................................................................... 118
JOSSO 2.4
vi
16. High-availability and Scalability ............................................................................. 119
16.1. About High Availability ................................................................................... 119
16.1.1. System Failover .................................................................................. 119
16.1.2. Session Failover ................................................................................. 119
16.1.3. Exploring a Reference Architecture ...................................................... 119
16.1.4. Enabling Clustering ............................................................................. 120
16.1.5. Replicating the Configuration ............................................................... 121
17. Security Setup ....................................................................................................... 123
17.1. Configuring Secure Sockets Layer ................................................................. 123
17.1.1. What Is Secure Socket Layer Technology? .......................................... 123
17.1.2. Security Identity and Access Management Services .............................. 123
1
Chapter 1. IntroductionJOSSO is an open source Internet SSO solution for rapid and standards-based Internet-scale
Single Sign-On implementations, allowing secure Internet access to the Web-based applications
or services of customers, suppliers, and business partners.
With Single Sign-On (SSO), access to multiple applications and services that are related (yet
independent of one another) can be achieved without requiring multiple authentications by the
user. By logging in just once, the user gains access to all the applications - saving time and
avoiding the inconvenience of logging in to each separately.
JOSSO accomplishes this with ease. In most cases, deploying an SSO solution means investing
some pretty significant resources for SSO-enabling business applications and the set up of
authoritative sources of identity data. With JOSSO things are different. Through its agent
architecture, JOSSO enables these capabilities transparently, making integration so simple it’s
practically non-existent. In most cases, it won’t even require an application build.
Third-party applications – whose source code might not be available – can be SSO-enabled just
as if they were in-house applications.
1.1. Enter Point-and-Click Internet Single Sign On (SSO)
Identity and Access Management is widely considered to be a highly technical domain, with an
implementation that’s out of reach for most people. The process of setting up a system for identity
and access management has a well-earned reputation for technical difficulty, inconvenience, and
errors; all in pursuit of an end product that most users dislike and avoid.
Commercial identity and access management packages offer web-based facilities to set up their
products; but without an intimate knowledge of the product’s inner structure, the overall set up
and roll-out experience is tedious and error-prone.
JOSSO incorporates the Atricore Console Rich Internet Application (RIA) to enable ease of use,
which translates to productivity. Technically savvy people can get on board with your identity
solutions, significantly accelerating time-to-value for enabling federated identity settings.
Simply "draw" your Internet SSO setting, and bring it to life in a snap. Work at the architecture level.
1.2. First or Second Generation ?
JOSSO1 represents the first generation of the JOSSO product line. It’s a mature and stable SSO
solution for transparent SSO, targeted to introduce End-to-End SSO capabilities onto application
servers and web containers.
The transparency capability is mainly achieved via JOSSO’s compliance with security contract
standards such as the ones offered by the JavaEE platform. The main benefit of transparency is
that the applications which rely on the the underlying platform’s security contracts can be SSO-
Introduction
2
enabled without any integration effort at all, and without being forced to couple with the underlying
SSO stack.
JOSSO’s wide support for application vendors makes it a compelling option for bringing on board
applications built on heterogeneous platforms.
Moreover, the product is highly extensible, offering a simple component model for implementing
plug-ins intended to introduce business-specific variability within the access management layer.
One of the major limitations of JOSSO1 is that it doesn’t "play nice" with third-party SSO solutions,
potentially hosted in external security domains. For instance, there is no out of the box support for
passing on the security context to an SaaS provider. Whereas setting up an Internet-scale SSO
setting is possible with JOSSO1, it would force all the involved parties to use JOSSO1. This is
rarely the case.
In terms of usability, setting up the product requires the involvement of technically-savvy
personnel, capable of dealing with configuration descriptors and with a good working knowledge
of both the SSO pieces and the underlying infrastructure.
JOSSO1 is highly extensible in terms of the wide support provided for mainstream application
platforms, authentication mechanisms and identity stores, but the SSO protocol is hardwired onto
the product. Therefore, providing full compatibility with other protocols and their bindings - such
as the commonly known SAML or OpenID - is not possible.
Another limitation is that JOSSO1 is not oriented to work in a multi-tenant environment. Limited
support is provided for this feature through the definition of security domains.
Finally, JOSSO1 is targeted for SSO only, thus leaving account and entitlement management and
storage to third-party software components. As a result, more effort and investment are usually
involved in order to cope with the missing pieces.
JOSSO2 is the second generation of the JOSSO product line. This generation is an all-in-one
solution that enables end-to-end delivery of Internet/Federated Single Sign-On settings, building
on a purely model-driven approach to lower the entry barrier and shorten time-to-value. It’s also
bundled with account and entitlement management support, building on an RDBMS-based internal
identity store. Many other building blocks, which are provided by the Atricore Identity Bus kernel,
enable JOSSO2 to expand its coverage to other areas of identity and access management which
haven’t been addressed in the past.
If you have a rather standard and controlled setting, and you’re looking to implement it in an out-of-
the-box fashion with little involvement from IT, JOSSO2 might be the right choice for you. JOSSO2
can significantly help by delivering an Internet-scale SSO solution, thus involving external/cloud-
based partner sites (e.g. suppliers, remote branches, etc.) and potentially hosting their internal
identity back-end.
You might consider using JOSSO1 for solving simpler SSO scenarios scoped to a single
administrative unit, with few or no requirements in terms of interoperability with external entities
(e.g. partners, suppliers, branches, etc.) where the trust relationship among these is weak. Since
Introduction
3
no account and entitlement management is provided, a third-party solution would need to be
adopted, or a home-grown application would need to be built.
Alternatively, whoile a third-party generic tooling could be leveraged for this (like an LDAP
console), it would provide a view only at the specific storage technology abstraction level, thus
significantly affecting usability and information consistency, as well as increasing the entry barrier
for administrators.
In addition, you’ll find more free support from the large community of adopters that the project has
won since project inception in the year 2004.
4
Chapter 2. JOSSO2 RolloutJOSSO ships in two different editions: JOSSO Community Edition (CE) and JOSSO Enterprise
Edition (EE).
Frequently updated and bursting with the latest features, CE is the same JOSSO SSO (Single
Sign On) that has been available for years; offered for free under the business-friendly LGPL open
source license.
JOSSO EE is a supported version targeted for enterprise use. Hardened for security and designed
to be rock solid stable, EE is offered with a subscription and support package that allows
organizations to build their Internet SSO settings on a stable version of the product that is offered
over an extended period of time.
Because the release cycle for EE is longer than it is for CE, each enterprise release is supported
for 4 years. All the latest bug fixes are backported to your version of JOSSO for the duration of
your subscription. Knowing that their JOSSO-powered Identity and Access Management setting
is stable and will run bug-free for years to come gives organizations peace of mind, enabling them
to build their sites on a proven, stable platform. In addition, JOSSO’s professional services team
offers training and consulting on the Enterprise Edition to ensure long-term support and stability
for our clients.
The first step is to download the JOSSO distribution.
To download the latest JOSSO Community Edition release, go to: http://sourceforge.net/projects/
josso/files/
To request a trial version of the JOSSO Enterprise Edition, use this link : http://www.atricore.com/
software/trial
Follow the instructions to enable your JOSSO Enterprise Edition installation.
2.1. Install JOSSO
Expand the file into a directory of your choice. This directory will be the JOSSO2 home directory,
which we will refer to as JOSSO2_HOME.
Change to the "bin" directory within JOSSO2_HOME, and execute the "atricore" command. This
will bootstrap JOSSO2 and the built-in identity appliances, which offer the essential provisioning
interfaces upon which the Atricore Console depends. This process can take several minutes
depending on the processing capabilities of the host equipment.
All bundles need to be up and running before using the product, so make sure that they all show an
initialization state of "Active". Through the command line console, you can monitor the execution
status of all the modules that make up the product. The following command can be used to
determine that all JOSSO modules are up and running :
JOSSO2 Rollout
5
osgi:list | grep Atricore
Make sure that all listed bundles are in the "Active" state.
If startup fails, use the log file located within the JOSSO2_HOME/data/logs directory to diagnose
the reason for the failure.
From the Atricore Console, you can specify your digital identity architecture at a birds-eye view
level, while still retaining the ability to "drill down" on any single component. Atricore Console also
makes it possible for you to seamlessly mix and match the building blocks of your Internet SSO
setting, realizing both SAML-compliant Identity Provider and Service Provider roles. These can
then be connected to any number of identity sources, automatically provisioning SSO capabilities
onto the web container or application server of your choice.
Now you’re ready to run the Atricore Console. In order to launch it, hit the following URL:
http://josso2host:8081/atricore-console and sign in using the default credentials: admin as the
username and atricore as the password.
2.2. The JOSSO2 Layout
The directory structure of JOSSO2 is as follows :
-<JOSSO_HOME>/ - the path to your JOSSO installation.
|-- appliances
|-- bin
|-- data
| |-- cache
| |-- derby
| |-- generated-bundles
| |-- log
| |-- port
| |-- work
| # #-- repository
| # #-- config
|-- lib
|-- lock
|-- system
The appliances folder contains identity appliances currently managed by JOSSO. The layout of
its content follows the one used for Apache Maven repositories.
The bin folder contains start scripts.
The data folder contains files representing persistent application state information, such as the
OSGi bundle cache, database files, log files and temporary artifacts produced as a result of
transformation procedures.
JOSSO2 Rollout
6
The lib folder contains the core libraries for the OSGi Microkernel Implementation on top of which
JOSSO builds.
The lock folder is used as a support for fail-over settings when more than one JOSSO instance
is used.
The system folder contains the libraries that make up the JOSSO distribution. Its layout is based
on the Apache Maven repository.
7
Chapter 3. The Building Blocks
3.1. Architecture
JOSSO builds on the Atricore Identity Bus. It is distributed as stand-alone software within which
your specific Identity and Access Management solutions can be specified and implemented.
As opposed to an end-solution, JOSSO is an infrastructure on top of which solutions can be
implemented. In some sense, JOSSO acts as an application server specifically targeted for
realizing Internet Single Sign-On (SSO) scenarios.
3.1.1. OSGi background
OSGi (the Open Services Gateway Initiative) is many things to many people. A full discussion
of the history of, viewpoints on, and capabilities of OSGi is beyond the scope of this book and
would likely fill an entire volume on its own. We encourage readers who are interested in OSGi’s
origins and rationale to consult link:http://en.wikipedia.org/wiki/OSGi and http://www.osgi.org/
Main/HomePage. As of November 2010, JOSSO uses version 4.1 of the OSGi standard, also
known as JSR-291 within the Java Community Process.
3.1.2. Identity Appliances
Internet SSO solutions are known within JOSSO as "Identity Appliances". An Identity Appliance
is an artifact which encompasses the definitions necessary to instantiate Internet SSO services,
in order to realize a specific identity architecture.
For instance, upon deployment of an identity appliance, defined Internet SSO endpoints are
enabled. Each endpoint will expose a specific behavior, such as for a specific authentication
service, or identity data streams from an arbitrary identity store responding to a specific user
schema.
Identity Appliances can be specified either by using a visual notation (using the Atricore Console)
or directly, using a textual notation based on XML descriptors .
Identity Appliances are standard OSGi Bundles, as are all the artifacts that make up JOSSO. A
bundle is a single file containing all the information about a given component; this single file is in
"jar" format, nearly identical to the "jar archives" that Java developers use to distribute libraries of
code. The bundle is composed of a MANIFEST.MF file which specifies its identity and the bundles
upon which it depends, as well as what is visible for other bundles to use.
Descriptors are based on Spring Dynamic Modules for OSGi Service Platforms. The Spring
Dynamic Modules for OSGi(tm) Service Platforms projects make it easy to build Spring
applications that run in an OSGi framework. A Spring application written in this way provides
better separation of modules with the ability to dynamically add, remove, and update modules in
a running system, the ability to deploy multiple versions of a module simultaneously (and allow
clients to automatically bind to the appropriate one), and a dynamic service model. For more
detailed information consult http://www.springsource.org/osgi.
The Building Blocks
8
Apache Maven is the recommended build system for packaging an identity appliance, though any
build system can be used. Apache Maven is a software project management and comprehension
tool. Based on the concept of a project object model (POM), Maven can manage a project’s build,
reporting and documentation from a central piece of information.
In addition, identity appliances generated through the Atricore Console include a build descriptor -
namely pom.xml - for packaging the identity appliance in an out-of-the-box fashion through Apache
Maven 3. Additionally, the layout used internally by JOSSO to reference identity appliances is the
one used by Apache Maven.
A Maven repository is a collection of project artifacts stored in a directory structure that closely
matches a project’s Maven coordinates. You can see this structure by opening up a Web browser
and browsing the central Maven repository at http://repo1.maven.org/maven2/]. You will see that
an artifact with the coordinates org.apache.commons:commons-email:1.1 is available under the
directory /org/apache/commons/commons-email/1.1/ in a file named commons-email-1.1.jar. The
standard for a Maven repository is to store an artifact in the following directory relative to the root
of the repository:
/<groupId>/<artifactId>/<version>/<artifactId>-<version>.
<packaging>
</programlisting>
Maven downloads artifacts and plugins from a remote repository to your local machine and stores
these artifacts in your local Maven repository. Once Maven has downloaded an artifact from the
remote Maven repository, it never needs to download that artifact again. Maven will always look
for the artifact in the local repository before looking elsewhere.
JOSSO hosts two internal Maven Repositories which are accessed each time an OSGi bundle
needs to be installed.
The first repository, located under ${josso_home}/system, contains the executable artifacts that
make up the JOSSO distribution. Both JOSSO-specific artifacts and their dependencies can be
found here.
The second repository, located under ${josso_home}/appliances, contains identity appliances
which are OSGi bundles as well. Identity appliances represent the deployment-specific artifacts,
building on the JOSSO ones. Every time an identity appliance is generated and packaged using
the lifecycle management facilities provided with the Atricore Console, it is dropped into this
location.
Once dropped into the ${josso_home}/appliances repository, the appliance can be referenced
whenever a deployment action is requested for a specific identity appliance. Once deployed, its
lifecycle can be managed the same as any other OSGi bundle.
Feature descriptors are used in order to simplify the provisioning of capabilities within JOSSO.
These provide a simple yet flexible way to provision applications, or "features". Such a mechanism
is mainly provided by a set of commands available in the features shell. JOSSO features are
stored in the ${josso_home}/features folder which complies with the Maven repository layout.
The Building Blocks
9
For instance, the main features descriptor for the JOSSO2 distribution looks like this :
<?xml version="1.0" encoding="UTF-8"?>
<features name="atricore-josso-ce-2.4.0">
<!-- JOSSO CE -->
<feature name="josso-ce" version="2.4.0">
<feature version="1.1.0">common</feature>
<feature version="2.4.0">josso-ce-svcs</feature>
<feature version="1.1.0">atricore</feature>
<feature version="1.1.0">atricore-management</feature>
<feature version="2.4.0">josso-ce-console</feature>
</feature>
<!-- JOSSO CE Servies -->
<feature name="josso-ce-svcs" version="2.4.0">
<!-- License Manager service -->
<bundle start-level="35">mvn:com.atricore.idbus.console.licensing/
com.atricore.idbus.console.licensing.josso2-license-v1_0/1.0.0</bundle>
<bundle start-level="35">mvn:com.atricore.idbus.console.licensing/
com.atricore.idbus.console.licensing.main/1.0.0</bundle>
<bundle start-level="35">mvn:com.atricore.idbus.console.licensing/
com.atricore.idbus.console.licensing.command/1.0.0</bundle>
<bundle>mvn:org.atricore.josso/org.atricore.josso.services/2.4.0</bundle>
</feature>
<!-- JOSSO CE Console -->
<feature name="josso-ce-console" version="2.4.0">
<feature version="2.4.0">josso-ce-console-svcs</feature>
<feature version="2.4.0">josso-ce-console-web</feature>
</feature>
<!-- JOSSO CE Console Services -->
<feature name="josso-ce-console-svcs" version="2.4.0">
<bundle>mvn:com.atricore.idbus.console.appliance/
com.atricore.idbus.console.appliance.console-default-idau/1.0.0</bundle>
<bundle>mvn:com.atricore.idbus.console.appliance/
com.atricore.idbus.console.appliance.console-jaas/1.0.0</bundle>
<bundle>mvn:com.atricore.idbus.console.activation/
com.atricore.idbus.console.activation.protocol/1.0.0</bundle>
<bundle>mvn:com.atricore.idbus.console.activation/
com.atricore.idbus.console.activation.main/1.0.0</bundle>
<bundle>mvn:com.atricore.idbus.console.activation/
com.atricore.idbus.console.activation.command/1.0.0</bundle>
<bundle>mvn:com.atricore.idbus.console.lifecycle/
com.atricore.idbus.console.lifecycle.main/1.0.0</bundle>
<bundle>mvn:com.atricore.idbus.console.lifecycle/
com.atricore.idbus.console.lifecycle.command/1.0.0</bundle>
</feature>
<!-- JOSSO CE Console Web -->
<feature name="josso-ce-console-web" version="2.4.0">
The Building Blocks
10
<bundle>mvn:com.atricore.idbus.console/com.atricore.idbus.console.web/1.0.0/war/ce</
bundle>
<bundle>mvn:com.atricore.idbus.console/com.atricore.idbus.console.docs/1.0.0/war</bundle>
</feature>
</features>
As you might notice, a feature encompasses one or more bundles whose coordinates follow the
Maven repository model. On the other hand, features can depend on other features. For instance,
the upper descriptor shows that JOSSO depends on Atricore Identity Bus-specific features, which
encompass Atricore Identity Bus OSGi bundles.
3.2. JOSSO2 Building Blocks
This section covers the building blocks of JOSSO2. Federated SSO usage scenarios are
implemented by mixing and matching those building blocks in identity appliance models, using a
purely visual approach.
The following is a high-level overview which introduces element semantics without covering the
precise usage details of every element. Those usage details are covered in the Setup sections.
3.2.1. Providers
Providers can be categorized as either a Service Provider or and Identity Provider.
A Service Provider role is played by a system entity, when the system entity provides services to
principals or other system entities.
An Identity Provider is a type of Service Provider that creates, maintains, and manages identity
information for principals, and provides principal authentication to other Service Providers within
a federation.
Simply put, an Identity Provider supplies authentication for a user, while a Service Provider relies
on an Identity Provider to authorize it, and establishes a security context.
An Identity Provider (IdP) element is represented with this figure :
An IdP can be connected with a SP through a Federated Identity connection. This establishes
a trust relationship between the IdP and the SP, which implies that the latter is willing to rely
on the claims about a principal established by the former. The common trust system for SSO
exchanges is based on digital signature, which ensures message integrity, authentication and
non-repudiation.
An IdP can be associated with an Identity Source through an identity lookup connection. This
makes the IdP point to a specific identity store for consuming user and entitlement information.
Such information is then leveraged for backing authentication processes and obtaining claim
entries for populating security tokens.
The Building Blocks
11
A SP, as mentioned earlier, can be connected with one or more IdPs through a Federated Identity
Connection, meaning that the SP will rely upon the claims presented by the trusted IdP.
Providers can be internal or external; internal providers are locally hosted and built on JOSSO2 to
deliver IDAM services, while external ones are remotely hosted - in the Cloud, for instance - and
built on third-party solutions. Furthermore, given that internal providers are hosted within the user
organization, their setup and lifecycle can be fully managed. Whereas with external providers,
the user organization can leverage them by establishing Federated SSO connections, but has no
right to change their behaviour or have access to the details of the underlying identity and access
management back-end. This is because external entities are outside the boundaries of the user
organization or administrative unit.
By convention, the "Identity Provider" and "Service Provider" entities are internal, while external
entities are prefixed with the "External" keyword.
In addition to where providers hosted - either internally or externally - a provider must also include
information on which protocol will be used to service requests from consumers. By default, internal
identity and service providers are communicating with the external world by building on the SAML2
protocol. All external providers - either identity or service providers - include in their definition
which protocol they support.
3.2.1.1. SAML2 Providers
Security Assertion Markup Language 2.0 (SAML 2.0) is a version of the SAML standard for
exchanging authentication and authorization data between security domains. SAML 2.0 is an
XML-based protocol that uses security tokens containing assertions to pass information about
a principal (usually an end user) between a SAML authority, that is, an identity provider, and a
SAML consumer, that is, a service provider. SAML 2.0 enables web-based authentication and
authorization scenarios including cross-domain single sign-on (SSO), which helps reduce the
administrative overhead of distributing multiple authentication tokens to the user.
An Internal Service Provider (SP) element is represented in the figure below :
An External SAML2 IdP element is represented with this figure :
An External SAML2 SP element is represented in the figure below :
3.2.1.2. OpenID Providers
OpenID is an open standard that allows users to be authenticated by certain co-operating sites
(known as Relying Parties or RP) using a third party service, eliminating the need for webmasters
to provide their own ad hoc systems and allowing users to consolidate their digital identities. An
OpenID provider can handle versions 1.1 and 2 of the protocol.
The Building Blocks
12
An External OpenID IdP element is represented with this figure :
An External OpenID SP element is represented in the figure below :
3.2.1.3. WS-Federation Providers
WS-Federation describes the management and brokering of trust relationships and security token
exchange across web services and organizational boundaries. WS-Federation can be difficult
to understand but it is also a part of the larger WS-Security framework and an extension to the
functionality of WS-Trust. For example, WS-Federation builds on the Security Token Service
(STS) model defined in WS-Trust by providing mechanisms that facilitate interactions. Through
WS-Federation protocol extensions, WS-Trust enables integrating attribute, pseudonym, and
claims authorization services with Security Token Services.
JOSSO2 may act as WS-Federation Identity Provider providing authentication assertions to an
external WS-Federation service provider.
An External WS-Federation SP element is represented with this figure :
3.2.1.4. OAuth2 Providers
OAuth is an open standard for authorization. OAuth provides client applications a secure
delegated access to server resources on behalf of a resource owner. It specifies a process
for resource owners to authorize third-party access to their server resources without sharing
their credentials. Designed specifically to work with Hypertext Transfer Protocol (HTTP), OAuth
essentially allows access tokens to be issued to third-party clients by an authorization server, with
the approval of the resource owner, or end-user. The client then uses the access token to access
the protected resources hosted by the resource server.
JOSSO2 may act an OAuth2 Authorization Server providing access tokens to a Resource Servers.
An OAuth2 SP element - namely a resource server - is represented with this figure :
3.2.2. Cloud Providers
The "Cloud Providers" drawer holds items used to establish Federated Connections with pre-
integrated Software-as-a-Service (SaaS) applications.
3.2.2.1. Salesforce
Salesforce.com is a customer relationship management (CRM) software-as-a-service (SaaS)
provider.
The Building Blocks
13
A Salesforce element is represented with this figure :
3.2.2.2. Google Apps
Google Apps is a Web-based and collaborative Software as a Service (SaaS) solution that
customizes the proprietary Google platform and brand for businesses of all sizes, including large
enterprises. Google Apps facilitates the provisioning of Google applications and user/enterprise
management tools.
A Google Apps element is represented with this figure :
3.2.2.3. Google Sign-In
Google Sign-In - built on the OpenID Connect protocol - allows leveraging Google as an Identity
Provider.
A Google Sign-In element is represented with this figure :
3.2.3. Identity Sources
Identity Sources represent the data layer of providers. Identity and access management processes
require such a layer in order to back authentication and related processes such as SSO. For
instance, Identity Providers use the information provided by identity sources to retrieve the user
entry that will be used to carry out the authentication process, and extract the claims that will
populate a security token. SPs also rely on a data layer. Common usage scenarios for this process
include augmenting IdP-facing claims with additional claims, or supporting the local authentication
of principals.
Identity Sources have three main distinctive characteristics which determine their nature: storage
mechanism, user schema and access protocol.
The storage mechanism determines the technological support and information model - such as
the relational or hierarchical - which will be used to persist user information. A commonly used
storage mechanism is the directory, which relies on a hierarchical information model.
The user schema determines how user entries are structured: how user attributes are going to
be referenced, and how the semantics for these will be placed. This represents the data contract
with which consumers need to comply in order to be allowed to access user information.JOSSO
Identity Sources are schema-agnostic; they’re capable of adapting to the schema supplied.
The access protocol determines the set of messages for operating on user entries as well as the
means of delivering these over the network. The most common access protocol used to locate
user entries from a directory is LDAP (Lightweight Directory Access Protocol).
The Building Blocks
14
3.2.3.1. Identity Vault
An Identity Vault represents the default repository - built on a local Apache Derby relational
database system - for user and entitlement information.
An Identity Vault element is represented with this figure :
3.2.3.2. DB Identity Vault
An DB Identity Vault represents a type of Identity Vault which, instead of pointing to the local
Apache Derby’s database instance, it can rely an external database hosted within a JDBC-
compliant database.
A DB Identity Vault element is represented with this figure :
3.2.3.3. LDAP Identity Source
An LDAP Identity Source is a type of identity source which can be accessed through the LDAP
protocol and which exposes user entries in a hierarchical form, responding to an arbitrary user
schema.
A LDAP Identity Source element is represented with this figure :
3.2.3.4. DB Identity Source
An DB Identity Source is one which is accessible through the vendor’s JDBC (Java Database
Connectivity) driver. The JDBC driver hides the internal details of the protocol used to access
databases.
A DB Identity Source element is represented with this figure :
3.2.3.5. XML Identity Source
An XML identity source is one that is based on a hierarchical information model. The basic building
blocks of XML are elements and attributes. Elements describe data, whereas attributes are like
the properties of an element, in that they provide further definition of the element. The semantics
of XML documents are defined using XML schemas, through which it becomes possible to define
the individual elements and attributes, and to assign valid types to them.
An XML Identity Source element is represented with this figure :
The Building Blocks
15
3.2.4. Execution Environments
In order to offer their services to end-users and applications, SPs build on a third-party software
piece which acts as the supporting infrastructure for distributed communication, security and
connectivity, among others. In the specific case of supporting the execution of Web-based SPs -
or simply Web applications - Web containers are used.
Within this setting, Web access management concerns are handled by underlying security
mechanisms which handle user authentication and authorization. When these processes are
complete, the corresponding security context - namely valid claims concerning user identity - are
passed on to the underlying Web application. Within the scope of the application, the security
context can be leveraged further by performing finer-grained authorization or support application
services in a business-specific way.
While enterprise-grade SSO standards exist (i.e. SAML), there is no standard API for introducing
SSO support onto Web applications. Therefore, in order for the SP to become SSO-ready,the most
common approach in SSO products is to impact on the codebase. This is usually accomplished by
adapting an application’s logic through coupling with the SSO vendor’s application programming
interfaces (API) in order to harness any supplied SSO services.
JOSSO takes a different approach. It leverages standard, as well as container-specific, application
Security Service Provider interfaces (SPIs) in order to build the SSO capabilities onto the
container, as opposed to the specific application.
Therefore, as long as the SP consumes security services that are provided by the underlying
container, it will become SSO-enabled in a transparent fashion. There’s no need to depend on
the SSO vendor API; no need to have access to the application’s source code, and no rebuilding
of the application.
Within the JOSSO domain, an execution environment is where SPs run in order to offer services
to end users and applications.
Execution environments can range from Web containers to application servers, Web portals
to application platforms. Within the identity appliance model, defining the characteristics of an
execution environment and binding it to an SP is key to activating SSO support onto the specific
execution environment, and from there, onto the underlying applications.
An activation connection is employed as the means for binding an SP with an execution
environment. The semantics of the activation is covered in Section 3.2.6.3, “Activation” .
The upcoming sections describe all the JOSSO-supported execution environments onto which
service providers can build, for participation in a Federated SSO setting.
3.2.4.1. Apache Execution Environment
The Apache HTTP Server is a popular open source, standard, secure, efficient and extensible
HTTP server for modern operating systems, including UNIX and Windows NT.
The Building Blocks
16
An Apache Execution Environment element is represented with this figure :
3.2.4.2. JavaEE Execution Environment
Java Platform, Enterprise Edition or Java EE is a widely used platform for server programming
in the Java programming language. The Java platform (Enterprise Edition) differs from the Java
Standard Edition Platform (Java SE) in that it adds libraries which provide functionality to deploy
fault-tolerant, distributed, multi-tier Java software, based largely on modular components running
on an application server.
A JavaEE Execution Environment element is represented with this figure :
3.2.4.3. JBoss Execution Environment
JBoss is a Java EE certified platform for developing and deploying enterprise Java applications,
Web applications, and Portals. JBoss Application Server provides the full range of Java EE 5
features, as well as extended enterprise services including clustering, caching, and persistence.
JOSSO2 supports JBoss versions 4, 5, 6, 7 and Wildfly 8.
A JBoss Execution Environment element is represented with this figure :
3.2.4.4. PHP Execution Environment
PHP is a server-side scripting language designed for web development but also used as a general-
purpose programming language. A PHP Execution Environment represents a PHP runtime for
servicing web requests.
JOSSO2 is compatible with all versions of PHP.
A PHP Execution Environment element is represented with this figure :
3.2.4.5. Tomcat Execution Environment
Apache Tomcat (or Jakarta Tomcat or simply Tomcat) is an open source servlet container
developed by the Apache Software Foundation (ASF). Tomcat implements the Java Servlet and
the JavaServer Pages (JSP) specifications from Sun Microsystems, and provides a "pure Java"
HTTP web server environment for Java code to run.
JOSSO2 is compatible with Apache Tomcat 5, 6, 7 and 8.
A Tomcat Execution Environment element is represented with this figure :
The Building Blocks
17
3.2.4.6. Webserver Execution Environment
A Webserver Execution Environment represents a "vanilla" web server.
A Webserver Execution Environment element is represented with this figure :
3.2.4.7. Weblogic Execution Environment
A Weblogic Execution Environment represents the J2EE-compliant WebLogic Server produced
by Oracle. It implements the full range of J2EE technologies, and provides features such as
advanced management, clustering, and web services. It forms the core of the WebLogic platform,
and provides a framework for building scalable, highly available and secure applications.
A Weblogic Execution Environment element is represented with this figure :
3.2.4.8. Websphere Execution Environment
The Websphere Community Edition - also known as WASCE - is an open source application
server developed by the Apache Software Foundation and distributed under the Apache license.
It is the free edition of IBM WebSphere application server and is based on Geronimo.
A Websphere Execution Environment element is represented with this figure :
3.2.4.9. Windows IIS Execution Environment
Internet Information Services (IIS) – formerly called Internet Information Server – is a web server
application and set of feature extension modules, created by Microsoft, for use with Microsoft
Windows.
A Windows IIS Execution Environment element is represented with this figure :
3.2.5. Authentication Servers
Authentication servers are servers that provide authentication services to users or other systems
via networking. Remotely placed users and other servers authenticate to such a server, and
receive cryptographic tickets. These tickets are then exchanged with one another to verify identity.
Authentication Servers can be linked to IdPs to externalize the identity verification concern from
the latter to the former.
The Building Blocks
18
3.2.5.1. WiKID Authentication
Two Factor Authentication, also known as 2FA, two step verification or TFA (as an acronym), is
an extra layer of security that is known as "multi factor authentication" that requires not only a
password and username but also something that only, and only, that user has on them, i.e. a piece
of information only they should know or have immediately to hand - such as a physical token.
The WiKID Strong Authentication System is a patented dual-source, self-hosted, software-
based two-factor authentication system designed to be less expensive and more extensible than
hardware tokens.
JOSSO2 comes with Two Factor Authentication support powered by WiKID.
A WiKID Authentication Element is represented with this figure :
3.2.5.2. Directory Authentication Service
Directory-based authentication is built onto the bind operation of the LDAP protocol. Verifying
user credentials will be delegated to delegate this task to an external directory through an LDAP
Bind request. If the LDAP Bind operation is successful the user will be considered authenticated,
whereas in the opposite case the authentication will fail.
A Directory Authentication Service Element is represented with this figure :
3.2.5.3. Windows Domain Authentication Service
Integrated Windows Authentication uses the security features of Windows clients and servers.
Unlike Basic or Digest authentication, it does not initially prompt users for a user name and
password. The current Windows user information on the client computer is supplied by the browser
through a cryptographic exchange.
A Windows Domain Authentication Service Element is represented with this figure :
3.2.5.4. Domino Authentication Service
Lightweight Third Party Authentication (LTPA) is the most commonly used IBM proprietary
technology for single sign-on (SSO) in distributed, multiple application-server and machine
environments. LTPA supports security in a distributed environment through cryptography,
permitting it to encrypt, digitally sign, and securely transmit authentication-related data, and then
later decrypt and verify the signature.
A Domino Authentication Service Element is represented with this figure :
The Building Blocks
19
3.2.5.5. Client Certificate Authentication Service
Client-certificate authentication is a more secure method of authentication than either basic or
form-based authentication. It uses HTTP over SSL, in which the server and, optionally, the client
authenticate one another using public key certificates. Secure Socket Layer (SSL) provides data
encryption, server authentication, message integrity, and optional client authentication for a TCP/
IP connection. You can think of a public key certificate as the digital equivalent of a passport.
It is issued by a trusted organization, which is called a certificate authority (CA), and provides
identification for the bearer.
If you specify client-certificate authentication, the identity provider will authenticate the client using
the client’s X.509 certificate, a public key certificate that conforms to a standard that is defined
by X.509 Public Key Infrastructure (PKI).
A Client Certificate Authentication Service Element is represented with this figure :
3.2.5.6. JBoss EPP Authentication Service
The JBoss Enterprise Application Platform (or JBoss EAP) is a subscription-based/open-source
Java EE-based application server runtime platform used for building, deploying, and hosting
highly-transactional Java applications and services. The JBoss Enterprise Application Platform is
part of the JBoss Enterprise Middleware portfolio of software. Because it is Java-based, the JBoss
application server operates cross-platform: usable on any operating system that supports Java.
The JBoss Enterprise Application Platform was developed by JBoss, now a division of Red Hat.
The JBoss EPP Authentication service is used for having the identity provider delegate the
authentication to JBoss EPP.
A JBoss EPP Authentication Service Element is represented with this figure :
3.2.6. Connections
In the previous chapter, we introduced all the building blocks - identity appliance elements - that
can play a part in an Internet SSO setting.
In order to put together a meaningful identity appliance model, one that can be transformed to
something that can actually execute, all the different pieces need to be brought together.
Connections are used to join two identity appliance elements. In our model, connections are
edges, representing flows of control and data between identity appliance elements. Each
connection enables a flow of data and control from one identity appliance element to another,
creating a contract between the two elements.
The Building Blocks
20
A connection is capable of associating identity appliance elements of a specific type. In the next
section we’ll cover the available connection elements.
3.2.6.1. Federated Connection
Federated Identity Management describes a model which enables users to employ their digital
identities in collaborating organizations, regardless of organizational borders. The essential pre-
requisite to sharing user authentication across different security domains is the establishment of
trust between the collaborating partners. Usually, this is done by setting up complex contracts, that
describe common policies, obligations and procedures that must be followed by each collaboration
member.
Multiple providers can connect to form a trust network, known as a Circle of Trust. The trust
system is based on a contract between separate parties and authentication that is enforced using
cryptographic key certificates.
A federated connection allows the association of an IdP element with an SP element. The
federated connection defines a relationship of mutual trust between the service and the IdP,
indicating that one provider is willing to rely on the other to handle its principal identities.
Setting up a Circle of Trust among providers provides users with new value-added services and
enhanced operational efficiency, by delivering the SSO experience in a cross-domain fashion.
A Federated Connection element is represented in the figure below :
3.2.6.1.1. SAML Binding
Security Assertion Markup Language (SAML) is an XML-based standard for exchanging
authentication and authorization data between security domains. That is, between an IdP (a
producer of assertions) and an SP (a consumer of assertions). SAML is a product of the OASIS
Security Services Technical Committee.
SAML assumes that the principal (often a user) has enrolled with at least one IdP. This IdP is
expected to provide local authentication services to the principal. However, SAML does not specify
the implementation of these local services; indeed, SAML does not care how local authentication
services are implemented (although individual SPs most certainly will). So an SP is reliant upon
an IdP to identify the principal. At the principal’s request, the IdP passes a SAML assertion to the
SP. On the basis of this assertion, the SP makes an access control decision.
JOSSO is SAML 1.1 and 2 compliant. IdPs and SPs build on exchanges based on SAML so that
they can inter-operate in terms of identity management and realize usage scenarios like cross-
domain SSO.
From within the Identity Appliance Modeler, Identity and Service Provider entity elements are
SAML2-based by convention. Consequently, a Federation Connection is a SAML2 Federation
Connection, given that it specifically deals with binding two SAML2 entities together.
The Building Blocks
21
3.2.6.2. Identity Lookup
At some point, both IdPs and SPs need to rely on one or more authoritative sources to obtain user
and entitlement entries. IdPs can then use this information to back authentication and authorization
processes, as well as to populate security tokens with the claims thus derived.
On the other hand, SP’s usage scenarios are close to the ones of an IdP. SPs can consume
user information from alternative authoritative identity sources, in addition to relying on claims
submitted by one or more trusted IdPs. Within a typical federated identity setting, upon relaying an
authentication request from an IdP, SPs are able to leverage an internal identity source to carry
out the account linkage. User details are located within the local authoritative source, based on the
account identifier referenced by the IdP. Once a local account counterpart is obtained, the claims
conveyed by the IdP can be augmented with user details, obtained from the local authoritative
source.
An identity lookup connection defines the identity source as an entity - either IdP or SP - and is
willing to rely on that definition to support identity and access management processes such as
those involving authentication and authorization.
An identity lookup edge, connecting an IdP with an identity source, determines two things: which
authoritative identity source will be used, and what means will be employed in order to access the
source in order to obtain the user credentials required for performing authentication. Moreover,
it specifies the authoritative source from which user and entitlement details, that will populate
security tokens, will be obtained.
An identity lookup edge, connecting an SP with an identity source, determines which local
authoritative identity source is going to be used, as well as the means to access it.
In addition to relying on authentication requests from IdPs, SPs may authenticate users in order
to grant access to the protected resources that they host. In other words, the local authoritative
source may be used to obtain user credentials for supporting authentication.
In addition, the SP can be part of a Circle of Trust, relaying authentication requests conveyed
by trusted IdPs. In this case the SP can build on the local authoritative source to obtain the
local account record based on the name identifier conveyed in the authentication request. This
procedure is known as Account Linkage. Based on the claims conveyed by the IdP and the local
account information, a new set of claims can be created that will be passed on for application
consumption. For instance, a user having a set of roles at the IdP end, might have a different set
of roles when navigating to a partner site, which restrict the actions the user is entitled to perform
within the target partner site.
Alternatively, in cases where a local account is not available for the supplied name identifier,
the SP can provision (i.e., create) it. This is known as Federated Provisioning. This might be a
requirement where SPs need to rely on a local account in addition to the security context.
The semantics placed for an identity lookup edge connecting a SP with an identity source
determine only how the identity source will be harnessed to feed the account linkage operation.
The Building Blocks
22
What means will be employed by the SP to obtain user credentials in order to carry out local
authentication are still left undetermined.
An identity lookup element is represented in the figure below :
3.2.6.3. Activation
One distinctive feature of JOSSO is the ability to support transparent SSO. In a nutshell, this
translates to instant SSO-enablement of SPs, by removing the system integration effort for
leveraging the SSO solution which typically involved coupling with the SSO solution APIs.
This feature is mainly based on SSO-enabling applications by "JOSSifying" the execution
environments on top of which they run; and passing on a security context that is standard-
compliant (therefore accessible), to any application which relies on standard security contracts -
such as the JavaEE ones - for their access control operations.
An "activation" is a type of connection used to bind the SP to an execution environment,
applying SSO-enablement semantics to execution environments hosting SPs for a specific identity
appliance.
The execution environment element type determines the specific SSO agent that will be
provisioned for bringing the SSO capabilities on board for the associated SP.
Activation can be either local or remote. A local activation implies that the execution environment
instance is located within the same host as JOSSO, hence the corresponding configuration
descriptors and other artifacts are accessible by the activation procedures. A remote activation
implies that the execution environment is hosted in a different location than JOSSO, so the remote
execution environment end needs to be accessible by the JOSSO host through the network.
Activation is a two-phase process. The first phase involves introducing SSO-support onto the
target execution environment. This takes place at "design time"; during the modeling process of
an identity appliance.
The second phase happens when the identity appliance model is transformed to an executable
artifact. Within this phase, the execution environment is set up so that it recognizes the service
providers that will be hosting .
An activation element is represented in the figure below :
For more information on the procedure for provisioning Single Sign-On support onto execution
environments please refer to ???
3.2.6.4. Identity Verification
Providers - usually Identity Providers - regard asserting the identity of principals as one of their
main concerns, such as users and applications consuming applications services. For instance,
The Building Blocks
23
for a Single Sign-On system this is a prerequisite for emitting a token upon which applications will
rely in order to authenticate requests.
An IdP can realize the asserting authority role, or delegate this responsibility to a third-
party software or hardware component. A commonly used mechanism for provider-managed
authentication is simple authentication, where username and password credentials are matched
against a user record in an external identity source. An example of delegated authentication
is RADIUS-based authentication, where an authentication request is submitted to a RADIUS-
compliant server for asserting user identity. In this case, the means and details for carrying out
this process are completely hidden from the authentication consumer.
In order for an IdP to delegate the authentication to a third-party, an Authentication Server element
needs to be associated with the IdP by using an Identity Verification edge.
An identity verification element is represented in the figure below :
3.2.6.5. Service Connection
The main responsibility of an Identity Provider is to establish the identity of a user by means of
authentication. Once this process is completed, the outcome - in the form of an authentication
assertion - is passed on to the service provider. Technically, the service provider is servicing
requests from within the JOSSO2 server instance, being completely unaware of the target service
that will be leveraging such authentication information.
The responsibility of mapping an authentication assertion to a security context for consumption
by the target business application or service lies in the resource. Resources may receive such
authentication assertion using different means - such as a different authentication protocol - than
the one used originally between the identity and service provider. Such semantics is determined
in the prefix of the resource element type.
In order to specify how authentication assertions will be passed on to the business tier as well as
the target location, a service connection is used. A service connection links an internal service
provider with a resource.
A service connection element is represented in the figure below :
3.2.7. Resources
Resources are used to represents identity consumers, such as business applications as well as
commercial off-the-shelf solutions.
3.2.7.1. JOSSO1 Resource
A JOSSO1 Resource represents a web application building on the JOSSO1 protocol for delivering
the single sign-on experience to users. This type of resource may be used to allow onboarding
The Building Blocks
24
legacy - namely those relying on the JOSSO1 Gateway - web applications to a JOSSO2 setting
non-disruptively. Whereas JOSSO2 doesn’t rely on the JOSSO1 protocol internally, it will honour
it so that the aforementioned backward compatibility is guaranteed.
A JOSSO1 Resource element is represented in the figure below :
3.2.7.2. SharePoint Resource
SharePoint is an enterprise information portal, from Microsoft, that can be configured to run
Intranet, Extranet and Internet sites.
A SharePoint Resource element is represented in the figure below :
3.2.7.3. Microstrategy Resource
MicroStrategy is an enterprise business intelligence (BI) software solution.
A Microstrategy Resource element is represented in the figure below :
3.2.7.4. SAS Resource
SAS is a software suite developed by SAS Institute for advanced analytics, business intelligence,
data management, and predictive analytics. It is the largest market-share holder for advanced
analytics.
A SAS Resource element is represented in the figure below :
3.2.7.5. Alfresco Resource
Alfresco is a free/libre enterprise content management system for Microsoft Windows and Unix-
like operating systems.
An Alfresco Resource element is represented in the figure below :
3.2.7.6. JBoss Portal Resource
JBoss Portal provides an open source platform for hosting and serving a portal’s Web interface,
publishing and managing its content, and customizing its experience.
The Building Blocks
25
A JBoss Portal Resource element is represented in the figure below :
3.2.7.7. Liferay Portal Resource
Liferay Portal is a free and open source enterprise portal project written in Java and distributed
under the GNU Lesser General Public License and optional commercial license.
A Liferay Portal Resource element is represented in the figure below :
3.2.7.8. phpBB Resource
phpBB is a free flat-forum bulletin board software solution that can be used to stay in touch with
a group of people or can power your entire website.
A phpBB Resource element is represented in the figure below :
3.2.7.9. JBoss EPP Resource
The JBoss Enterprise Portal Platform (or JBoss EPP) is an enterprise portal with the core portal
features of presentation, master page objects, containers, and a repository, and also an optional
site publisher.
A JBoss EPP Resource element is represented in the figure below :
3.2.7.10. Self Services Resource
This is an application bundled with JOSSO2 which allows users to manage their account as well
as accessing configured service providers from a standard web browser.
A Self Service Resource element is represented in the figure below :
3.2.7.11. Domino Resource
IBM Domino (formerly IBM Lotus Domino) is an IBM server product that provides enterprise-grade
e-mail, collaboration capabilities, and a custom application platform.
A Domino Resource element is represented in the figure below :
The Building Blocks
26
3.2.7.12. Blackboard Resource
The Blackboard Learning System is a virtual learning environment and course management
system developed by Blackboard Inc. It is a Web-based server software which features course
management, customizable open architecture, and scalable design that allows integration with
student information systems and authentication protocols.
A Blackboard Resource is represented in the figure below :
27
Chapter 4. Atricore Console and
Model Driven IdentityThis is the first identity and access management product that employs a model-driven approach
to visually specify and execute identity architectures.
Even those of you who are not familiar with this approach - commonly referred to as MDD (Model
Driven Development) - may have actually been using tools based on this paradigm for more
than a decade. For instance, Database Administrators use this approach to specify and set up
database schemas; those of you involved in software engineering use diagramming tools to
specify application designs and, eventually, to scaffold the code. There are many examples of
MDD implementations out there, and almost every technical domain employs at least one of these
tools to shorten learning curves and improve productivity.
But we couldn’t find one that addressed the inherent (and ever-increasing) complexity of the
identity and access management space. At Atricore we felt that one was needed; so we built one.
Then we delivered it, for free, with JOSSO2.
Here’s where the Atricore Console comes in. You can use it to model an identity architecture
and transform it into something that executes, without necessarily being exposed to the myriad
technical details that surround the process.
Because of the strong JOSSO binding, in addition to enabling the services needed to realize an
identity architecture, target execution environments can be activated so that they’ll be provisioned
with the building blocks that are necessary to deal with the setting in an out-of-the-box fashion.
When we tested the first bits of the Atricore Console we were amazed at how much we were able
to achieve with so little. We delivered a simple Federated SSO deployment in just fifteen minutes!
4.1. Model-Driven Identity
Simply put, Model-Driven Identity (MDId) is the result of crossing model-driven development with
identity and access management domains. To understand what MDId really is, you need to know
one more thing: what, in this context, do we mean by a "model"?
If you’re familiar with Unified Modeling Language (UML), you might imagine a higher-level
description of an application from which we can generate some (or all) of the implementation. In
that case, you’d be right about what a "model" is, but not exactly about MDId’s spin on it.
Although the idea is the same, a model in MDId is less general and high-level than the
commonly accepted interpretation. MDId doesn’t require a completely different methodology, or
any sophisticated modeling tools. All you need to get started with MDId is the Atricore Console,
which is bundled in JOSSO2.
Atricore Console and
Model Driven Identity
28
As you’ll see in the following sections, MDId relates the modeling concepts portion of the identity
and access management domain directly to their implementations, thereby bringing to JOSSO -
and to Identity Architects in general - the benefits of modeling, with a low cost of entry.
4.2. Modeling vs. Implementing
In a nutshell, Atricore Console is an Integrated Development Environment (IDE) that is used to
describe a model of an identity architecture, and then to generate the artifacts which bring that
architecture to life.
With Atricore Console, both modeling and implementing IDAM (Identity and Access Management)
architecture can be considered as one and the same action. Instead of forcing a separation of the
high-level engineering and modeling work from the low-level implementation activities, Atricore
Console bridges the gap; bringing them together as two well- integrated parts of the same task.
Why is modeling interesting for an IDAM project in the first place? For starters, it gives you
the ability to describe what your identity and access management solution is supposed to
do (presumably) more easily than with dealing with technical artifacts such as configuration
descriptors and code. In turn, this gives you a solid, high-level way to both communicate the
identity architecture and to generate part, if not all, of the implementation artifacts.
4.3. What is Model-Driven Development?
MDD addresses full life cycle application development, data, and application integration standards
that work with multiple middleware languages and interchange formats. MDD unifies some of the
industry’s best practices in software architecture, modeling, metadata management and software
transformation technologies; practices that allow the user to develop a modeling specification
just once, then target multiple technology implementations by using precise transformations and
mappings.
Atricore Console supports the key MDD concept of using models as input for development and
integration tools. In Atricore Console, a model is used to drive the generation of identity and access
management solutions.
4.4. The Identity Architect Role
IDAM projects require different roles in order to increase the chances for success. The
fundamental roles are these: a Project Manager to keep track of the overall implementation; a
Solution Architect capable of putting together solution blueprints; a System Integrator to ensure
that all the identity architecture pieces of the solution play together nicely in both sandbox and
production settings and a System Developer to introduce the customization required to make the
underlying identity suite match finer-grained usage scenarios as required by the business.
It’s a sad fact that most IDAM projects fail. The blame for this high failure rate can be shared by
multiple areas, and happens for a myriad of reasons. Covering all of them lies beyond the scope
of this document, but we’re happy to take aim at one: the gap that exists between the roles of
Solution Architect and System Integrator.
Atricore Console and
Model Driven Identity
29
The Solution Architect builds on different pieces of information to come up with a solution. These
range from identity management use-case specifications to user stories, from quality attributes
required for the technical architecture to resource availability and the capabilities available in the
underlying product - and the list goes on.
The outcome of the solution-building process is usually a set of artifacts - mainly technical
documents - which contain the detailed descriptions and supporting diagrams of the identity
management architecture. Let’s say that these documents are 10,000', bird’s-eye views of the
solution. These are then passed on to the System Integrator in order to bring the proposed
solution to life. Now the System Integrator must work up at 10,000'. New aspects related to the
implementation tasks introduce significant changes, constraints and detail to the solution. But
these valuable pieces of information are not brought back to the original solution blueprints. As
the integration iterations flow, the artifacts covering the solution rapidly become stale, leaving
the actual implementation as the only source available for parsing the identity and access
management solution.
Herein lies the problem. Understanding the solution architecture via the actual implementation
requires detailed knowledge of the product and internals - which are scattered throughout the
entire implementation. Gathering all the pieces together into an updated high-level view is a classic
"mission impossible".
In the advanced stages of the implementation, the Solution Architect tends to play a passive role,
with little control over the project in terms of the identity architecture. The lack of control in this
area represents a risk for the overall project, since the end product might not match stakeholder
expectations, or scale as planned.
The role of Identity Architect is a relatively new one in the IDAM market. Responsible for putting
the identity architecture together, like a builder/designer for identity and access management
architecture, it’s a similar role to that of the Solution Architect - but with some notable differences.
We think of an Identity Architect as the combination of the Solution Architect and System Integrator
roles. The Identity Architect works with live architecture models, which act as the pieces that drive
the realization of an identity architecture.
With this approach identity architecture blueprints are always up-to-date, since they’re in sync with
the underlying implementation. A live view of the architecture can be accessed at any time, along
with the ability to extend or prototype it (among many other possibilities).
The Identity Appliance Modeler is the principle enabler of these processes, and serves a twofold
purpose. It can be used to diagram the identity architecture as well as to realize it onto the target
product suite.
4.5. Identity Appliance Modeler Overview
While JOSSO1 provides a command line console in order to provision SSO support onto the target
environment, users are still required to deal with low-level artifacts - such as XML descriptors -
in order to fine tune the implementation.
Atricore Console and
Model Driven Identity
30
This creates a high entry barrier for less technically-savvy users, due to the learning curve
involved with JOSSO and the constructs employed in order to set up the product to realize SSO
usage scenarios. In addition, the people responsible for the identity architecture do not have
visibility or control of the federated single sign-on setting, so they have to rely on more technically
proficient people - usually not SME experts - in order to bring their project to life. Chances for
miscommunication increase as a consequence, and that poses a significant risk to the identity
and access management project.
With the Identity Appliance Modeler, the Identity Architect gains complete control of the process
of mapping the high-level identity architecture to something that will actually execute. Definition of
the identity architecture can be accomplished in a purely visual fashion, thus eliminating the high
entry barrier that’s typically required to engage in the delivery of Internet SSO.
Here’s what the Identity Appliance Modeler looks like :
The action bar offers operations related to the identity appliance. These are mainly concerned with
managing the workspace within which an identity appliance model is bootstrapped and edited.
For instance, an identity appliance can be scaffolded by clicking on the "New" button, or we can
continue working on an existing appliance by selecting it and clicking on the "Open" button.
The Palette consists of seven drawers.
The "Providers" drawer holds the items used to specify the primary building blocks of the identity
architecture, namely the Identity Provider and Service Provider.
The "Cloud Providers" drawer holds items used to establish Federated Connections with pre-
integrated Software-as-a-Service (SaaS) applications.
The "Authentication" drawer holds items used to specify Authentication Servers on top of which
Identity Providers can delegate for identity verification.
The "Identity Sources" drawer holds items used to specify the specific storage mechanism which
will be leveraged to back authentication and authorization processes.
The "Resources" drawer holds items used to specify services acting as identity consumers,
namely business applications as well as commercial off-the-shelf offerings.
The "Execution Environments" drawer holds items used to specify the application platform upon
which resources can execute.
Finally, the "Connections" drawer holds the items used to connect the building blocks of the identity
architecture together.
The Diagram Canvas plays the role of placeholder for all of the elements constituting an identity
appliance model.
The Appliance Browser, on the left side of the Diagram Canvas, provides a tree view of the
identity appliance model. Any change that’s made to an identity appliance element is automatically
Atricore Console and
Model Driven Identity
31
reflected on the tree. Any time an element is selected on the tree, it is also selected on the Diagram
Canvas and its details are presented on the property sheet panel.
The property sheet section is at the bottom of the Identity Appliance Modeler screen. It’s the entry
point for accessing the details of identity appliance elements, and it’s where editing actions on
those details take place.
In order to add an element to an existing identity appliance model, simply click on one of the items
from the Palette and then drag and drop it onto the Diagram Canvas.
Connecting two elements is achieved by dragging onto the diagram an item of the required
connection type, then selecting the source and target elements you wish to associate together.
You can edit by clicking the element in question from the Diagram Canvas and selecting the field
you wish to update within the property sheet section.
Element removal is achieved by clicking on the red cross that appears when a rollover action is
performed on an element of the diagram.
4.6. Identity Appliance Life Cycle Management
Overview
The Identity Architect is also in control of transforming the identity architecture model into a fully
executing artifact. As with the Identity Appliance Modeler, it’s a simple point-and-click process.
The Identity Appliance Life Cycle Management screen offers a grid-based layout, within which
columns are used to represent the different states possible for the identity appliance artifact.
Switching the identity appliance from one state to another is achieved by dragging the identity
appliance item from the column representing the source state, and dropping it into the column
representing the target state.
For instance, in order to build an identity appliance: select and drag the corresponding item from
the "Saved" column and drop it into the "Staged" column. Additionally, an identity appliance in the
"Deployed" state can be started and stopped with the buttons located to the right of the item.
4.7. Account and Entitlement Management Overview
Being an all-in-one solution, JOSSO2 is bundled with an identity store - known as and identity vault
- onto which user accounts and entitlements can be provisioned. Identity vaults can be bound to
both Identity and Service Provider entities. The identity vault is built on an Apache Derby relational
database system.
Both accounts and groups can be provisioned. Accounts can also be associated to one or more
groups in order to serve as the input for Role-Based Access Control (RBAC).
Atricore Console and
Model Driven Identity
32
4.7.1. Accounts Overview
Clicking on the "Manage Users" button displays the screen through which the complete life cycle
of user accounts can be managed: provisioning, detail editing, entitlement association and de-
provisioning.
Here’s how the Account Management screen is structured :
4.7.2. Groups Overview
Clicking on the "Manage Groups" button displays a screen with which the full life cycle of group
records can be managed. Groups serve as the means to determine the entitlements users.
4.7.3. Schema Overview
Clicking on the "Manage Schema" button displays a screen with which custom attribute types can
be added to the built-in user entity. Custom attributes - based on defined attributes types - can be
managed as any of the already available attributes.
4.8. System Settings Overview
System settings are used to control and configure behaviour of the JOSSO2 product. If you need
to change an aspect of JOSSO2’s system-wide configuration, such as setting up monitoring or
increasing the logging verbosity, It will generally be achieved through modification of settings.
4.9. Help Overview
Clicking on the "Help" option displays the JOSSO2 documentation. Alternatively, the same
documentation may be accessed directly from a web browser.
33
Chapter 5. Identity Appliance
CreationAn identity appliance contains the definitions for the identity architecture. By leveraging the Identity
Appliance Modeler, you can define identity appliances for realizing standards-based Internet SSO
settings. Additional identity appliance flavors will be supported in future releases.
An identity appliance contains instances of the element types that conform to the identity appliance
meta-model.
These constructs can be dragged from the palette view and dropped into the identity appliance
diagram. The identity services that will be available upon identity appliance deployment will be
driven by the definitions that are part of this appliance. For instance, if we’ve specified a SAML2
Identity Provider (IdP), the endpoints for the chosen SAML profile and bindings combination will be
enabled. Moreover, if this IdP is connected to an LDAP (Lightweight Directory Access Protocol),
authentication will be based on user entries within the target directory.
Multiple identity appliances can run simultaneously, representing distinctive facets of a large
infrastructure, or - within a multi-tenant setting - the Federated Identity services for a specific
tenant. Identity Appliances will run isolated from one another, yet be managed centrally through
the Atricore Console.
An identity appliance can be created from scratch or scaffolded by building on reference identity
appliance templates. Let’s explore these options in more detail.
5.1. Starting from Scratch
Starting from scratch is usually the best option when your setting is very particular - there is a
template available that will match your setting. To create a new appliance, press on the "New"
button with the "Empty Identity Appliance" item set on the select box on the right. This will open
a dialog for specifying information to identify the target identity appliance.
The Name field contains the unique identifier for the identity appliance. Choose an identifier that
is within the parameters of the allowed character set, and that is not in use by another identity
appliance.
The Description field is an informative field used to describe the function of the identity appliance.
Characteristics like the owner’s organization name and the type of service that will be implemented
through the appliance can be defined here.
The Realm Name provides a unique namespace for the elements contained by the identity
appliance. For instance, artifacts produced by an identity appliance transformation process:
module identifiers, java classes, etc. will be qualified using the Realm Name. The Realm Name
Identity Appliance Creation
34
and the Identity Appliance Name are the building blocks of the fully qualified identity appliance
name, or FQIAN.
The Appliance Location specifies the host name, and the port where identity endpoints for the
identity appliance will be bound. We strongly suggest that you use a fully qualified host name, so
that the identity appliance services are decoupled from a specific physical host.
The Branding field contains the available branding extensions. Choose your preferred branding
extension or alternatively stick with the defaults by selecting the default one, namely "JOSSO 2.x
Default".
The IDP selection field allows you to specify the policy that will be used upon a service provider
selects an identity provider. By default, the explicitly requested identity provider will be used
for authentication before the preferred ones are selected. Once the fields are filled in, press
the "Accept" button. This will create an empty identity appliance, enabling the identity appliance
modeling process.
35
Chapter 6. Identity Source SetupIdentity Sources represent the data layer of providers. Identity and access management processes
require such a layer in order to back authentication and related processes such as SSO. For
instance, IdPs use the information provided by identity sources to retrieve the user entry that will
be employed to carry out the authentication process, and to extract the claims that will populate a
security token. SPs also rely on a data layer. Common usage scenarios for this process include
augmenting IdP-facing claims with additional claims, or supporting the local authentication of
principals.
Identity Sources have three main distinctive characteristics which determine their nature: storage
mechanism, user schema and access protocol.
The storage mechanism determines the technological support and information model - such as
the relational or hierarchical - which will be used to persist user information. A commonly used
storage mechanism is the directory, which relies on a hierarchical information model.
The user schema determines how user entries are structured: how user attributes are going to
be referenced, and how the semantics for these will be placed. This represents the data contract
with which consumers need to comply in order to be allowed to access user information.JOSSO
Identity Sources are schema-agnostic; they’re capable of adapting to the schema supplied.
The access protocol determines the set of messages for operating on user entries as well as the
means of delivering these over the network. The most common access protocol used to locate
user entries from a directory is LDAP (Lightweight Directory Access Protocol).
6.1. Setup of an Embedded Identity Vault
An Embedded Identity Vault is a type of Identity Source which is built into the product.
The account and entitlement management functionality can only act on Identity Vaults instances.
The Identity Vault is based on an Apache Derby relational database engine. An Embedded Identity
Vault, like any identity source, can be bound to both an IdP and a SP. In the former case, the
Identity Vault is used to back authentication processes. In the latter case, the Identity Vault is
used to support account linkage and identity mapping, for augmenting IdP-facing claims with those
provided by the local Identity Vault.
An Embedded Identity Vault is represented in the figure below :
Using an Embedded Identity Vault over a general purpose identity source allows you to leverage
the existing visual account and entitlement management facilities, as well as decrease the time
to deployment; since the activities involved in setting up an external identity store and linking it to
the identity infrastructure are not required.
From the Palette, click in the "Identity Sources" drawer and drag it to the preferred location
within the Diagram Canvas.
Identity Source Setup
36
On the "New Identity Vault" window, enter the name of the "Embedded Identity Vault" element.
Optionally, enter a description for the Identity Vault definition that is being created.
Finally, specify the Identity Vault backing the Embedded Identity Vault. The recommended option
is "Default Identity Vault".
6.2. Setup of a Database Identity Vault
An Database Identity Vault is a type of Identity Vault which relies on an external JDBC-compliant
database as it’s backing store.
Using a Database Identity Vault over an Embedded one allows you to build on the database of
the embedded Apache Derby-based one. Furthermore, the account and entitlement management
functionality can still act on this type of identity vault even if the database is no longer under it’s
control.
Lke any identity source, it can be bound to both an IdP and a SP. In the former case, the Database
Identity Vault is used to back authentication processes. In the latter case, it is used to support
account linkage and identity mapping, for augmenting IdP-facing claims with those provided by
the local Identity Vault.
An Database Identity Vault is represented in the figure below :
Using a Database Identity Vault over an embedded identity source allows you to leverage your in
place data layer yet reusing the existing visual account and entitlement management facilities.
From the Palette, click in the "Identity Sources" drawer and drag it to the preferred location
within the Diagram Canvas.
Field Descriptions
Field Description
Name The unique identifier of the Database Identity
Vault element.
Description A descriptive text for the Database Identity
Vault element.
Hash Algorithm Hash Algorithm used for storing passwords.
Available options are "MD5" for MD5 hashing,
"SHA-1" for SHA-1 hashing, "SHA-256"
for SHA-256 hashing and "Plain Text" for
Identity Source Setup
37
disabling hashing thus leaving passwords in
clear text.
Hash Encoding The string format for the hashed pass
and must be either "BASE64", "HEX" or
"RFC2617". The default is base64.
Salt Length A salt is a random sequence of bytes which
is added to the hash function, and it’s length
must be either 8, 16, 24 32 and 48. By default
no password salt is used.
Username The "Username" portion of the credentials
set, which will be passed along upon
establishment of a connection to the target
database.
Password The "Password" portion of the credentials
set, which will be passed along upon
establishment of a connection to the target
database.
Confirm Password The password entered in the above field.
Use External DB Server Whether an external database server will be
used as the backing store.
Driver The name of the JDBC driver class.
Connection URL The mean of connecting JOSSO2 to the
external database.
6.3. Setup of an LDAP Directory Identity Source
LDAP (Lightweight Directory Access Protocol) is a software protocol which enables anyone to
locate organizations, individuals and other resources - such as files and devices - in a network,
whether on the public Internet or on a corporate Intranet.
An LDAP Identity Source is a type of identity source which can be accessed through the LDAP
protocol and which exposes user entries in a hierarchical form, responding to an arbitrary user
schema.
An Ldap Identity Source is represented in the figure below :
LDAP Identity Sources can be bound to both Identity and Service Providers. Connecting an IdP to
an LDAP Identity Source implies that queries for retrieving user records to be fed to authentication
and related processes will be performed against a directory using the LDAP Procotol.
Connecting an SP to an Identity Source implies that queries meant to authenticate users locally,
or to augment IdP-facing claims, will be backed by an directory accessible through the LDAP
protocol.
Identity Source Setup
38
In order to play nice with arbitrary schemas - and realize schema-agnosticity - the identity source
can be customized in terms of the LDAP queries used to access user identity records.
From the Palette, click "LDAP Identity Source" in the "Identity Sources" drawer.
Click on and drag the "LDAP Identity Source" element to the preferred location within the Diagram
Canvas.
In the "Create LDAP Identity Source" window, enter the name of the LDAP Identity Source element
to be added to the Identity Appliance Diagram.
Field Descriptions
Field Description
Name The unique identifier of the LDAP Identity
Source element.
Description A descriptive text for the LDAP Identity
Source element.
Initial Context Factory The fully qualified class name of the
InitialContextFactory implementation.
This defaults to the Sun LDAP
provider implementation
com.sun.jndi.ldap.LdapCtxFactory.
Provider URL Enter the LDAP URL for the LDAP Directory
Server.
This defaults to "ldap://localhost:389", thus
expecting a directory server listening on the
standard port available in the same server
that JOSSO (and the identity appliance)
executes.
Security Principal Enter the security principal for authenticating
the caller to the service.
This defaults to "uid=admin,ou=system", the
default for OpenLDAP.
Security Credential Enter the credential for the security principal
that will be passed on to authenticate the
caller to the service.
The semantics of this field depend on the
chosen authentication mechanism, as
described below.
Identity Source Setup
39
Security Authentication Determines what authentication mechanism
will be used to authenticate the caller to the
service.
Available options are "None" for anonymous
binding, "Simple" for password-based
authentication and "Strong" for authenticating
using X.509 client certificates.
Search Scope Enter the search strategy used to query user
and role entries in the target LDAP directory.
The default is "Subtree".
Setting the search scope to "Base" queries
within the specified contexts.
Setting the search scope to "One" will cause
LDAP queries to search only the immediate
children of the LDAP object corresponding to
the DN for users and roles.
Setting it to "Subtree" will query the entire
LDAP directory subtree below the search
baseDN for users and roles.
Setting the search scope to "Children" will
cause LDAP queries to search one level
below, all direct children of the base entry.
On the "Lookup" screen, you can determine how user and role entries are to be retrieved. This
is required in order to access identity data responding to arbitrary schemas. The forced migration
of user data to a product-specific user schema is avoided, allowing you to re-use existing identity
silos independently of user data structure.
Field Description
User DN Enter the Distinguished Name (DN) that will
be used as the context for user searches.
This defaults to "ou=People,dc=my-
domain,dc=com".
Principal UID (User Identity) Attribute ID Enter the LDAP attribute name that holds the
distinctive identifier of the user. This defaults
to "uid".
Role Matching Mode Select the mechanism used to obtain the
roles for a user.
Identity Source Setup
40
Every mode builds on a specific user attribute
to obtain user roles.
If "Distinguished Name" is selected, roles will
be retrieved by using the DN of the user entry
as the key.
If "User ID" is selected, roles will be retrieved
by using the user identity.
If "User Principal" is selected ++
UID Attribute ID Enter the attribute identifier holding the UID.
This defaults to "uniquemember".
Role Attribute ID Enter the attribute identifier for the role name.
This defaults to "cn".
Updatable Credential Attr (Attribute) Enter the attribute identifier for holding
the token value used for Remember-Me
authentication.
Credential Query Enter the query used to obtain username and
password values from the user entry.
The left-hand part represents the LDAP
attribute name, while the right-hand
one identifies the variable name that
holds its value. In this case, "username"
identifies the placeholder for the username
portion; and "password" identifies the
placeholder for the password portion. Both
need to be defined in order for the IdP
to retrieve the user credentials that are
required for authentication. This defaults to
uid=username, userPassword=password.
User Properties Query Enter the query used to obtain user attributes
from the user entry.
The left-hand part represents the LDAP
attribute name, while the right-hand one
identifies the variable name holding its value.
In this case, the left-hand portion contains
the LDAP attribute name for the user attribute
to be extracted, while the right-hand portion
holds the property name that will be bound to
it. This defaults to mail=mail,cn=description.
Click on OK to confirm LDAP Identity Source element creation.
Identity Source Setup
41
Click on Cancel to abort LDAP Identity Source element creation.
6.4. Set Up an RDBMS Identity Source
RDBMS stands for Relational Database Management System. RDBMS data is structured in
database tables, fields and records. Each RDBMS table consists of database table rows. Each
database table row consists of one or more database table fields.
An RDBMS Identity Source is one which is accessible through the vendor’s JDBC (Java Database
Connectivity) driver. The JDBC driver hides the internal details of the protocol used to access
databases.
An RDBMS Identity Source is represented in the figure below :
Within an RDBMS, user details are stored in database rows grouped using tables. Each single
user attribute is stored in table fields. User information might span to more than one table. For
instance, user details can be spanned in two different tables: one for holding user attributes and
another for holding the related entitlement records.
RDBMS Identity Sources can be bound to both Identity and Service Providers. Connecting an
IdP to an RDBMS Identity Source implies that queries for retrieving user records (in order to back
authentication and related processes) will be performed against a database using the supplied
JDBC driver.
Connecting a SP to an Identity Source implies that queries meant to authenticate users locally, or
to augment IdP-facing claims, will be backed by a database made accessible through the supplied
JDBC driver.
In order to adapt to arbitrary schemas - and realize schema-agnosticity - the identity source can
be customized in terms of the SQL queries that are used to access user identity records.
From the Palette, click "DB Identity Source" in the "Identity Sources" drawer.
Click on and drag the "DB Identity Source" element to the preferred location within the Diagram
Canvas.
In the "Create DB Identity Source" window, enter the name of the DB Identity Source element to
be added to the identity appliance diagram.
Field Descriptions
Connection attributes can be specified within the "Connection" screen.
Field Description
Driver By default, the only available option for
connecting with a database system, that is
allowed from the identity appliance scaffolding
wizard, is through a JDBC-ODBC driver.
Identity Source Setup
42
This approach is tailored to a Windows-based
system (Open Database Connectivity, or
ODBC, is a Windows standard) but it can also
be made to work from a Linux host.
A native JDBC (Type 4) driver can be used,in
case the RDBMS vendor has not supplied an
ODBC driver, or if JOSSO is being hosted in
a system running the Unix operating system
(e.g. Linux).
In order to use a native JDBC (Type 4)
driver, copy the corresponding jar file into the
$JOSSO2_HOME/lib/jdbc folder and restart
JOSSO.
Connection URL The connection string employed to establish a
connection to the target database.
Username The "Username" portion of the credentials
set, which will be passed along upon
establishment of a connection to the target
database.
Password The "Password" portion of the credentials
set, which will be passed along upon
establishment of a connection to the target
database.
Within the "User Lookup" tab you can supply the SQL queries that will be used by an IdP to retrieve
user credentials and details, as well as roles. Supplying this information is required, since JOSSO
is schema-agnostic and therefore must be told how to adapt to an arbitrary schema.
Field Description
User Query SQL query for selecting the record from the
table that stores users.
This field will be automatically filled in with the
query corresponding to the default schema.
Roles Query SQL query for selecting the role records for
the selected user.
This field will be automatically filled in with the
query corresponding to the default schema.
Credentials Query SQL query for selecting the credential records
for the selected user.
Identity Source Setup
43
This field will be automatically filled in with the
query corresponding to the default schema.
Properties Query SQL query for selecting custom user
attributes that will be conveyed as claims in
authentication assertions.
This field will be automatically filled in with the
query corresponding to the default schema.
Within the "Password Update" screen you can supply the SQL queries employed for self-services,
such as password change.
Field Description
Credentials Update SQL update statement for changing user
credentials.
This field will be automatically filled in with the
query corresponding to the default schema.
Relay Credentials SQL update statement for updating
the credentials backing Remember Me
functionality.
This field will be automatically filled in with the
query corresponding to the default schema.
Click on OK to confirm DB Identity Source element creation.
Click on Cancel to abort DB Identity Source element creation.
44
Chapter 7. Authentication SetupAuthentication is the process of verification that an individual or an entity is who it claims to be.
Authentication is commonly performed by submitting a user name or ID and one or more items of
private information that only a given user should know.
Typically, the Identity Provider will be the entity responsible of authenticating users by building
on one or more authentication mechanisms. Within this type of settings, a Service Provider does
not handle authentication, instead it relies on authentication assertions made by a trusted Identity
Provider.
An IdP can realize the asserting authority role, or delegate this responsibility to a third-
party software or hardware component. A commonly used mechanism for provider-managed
authentication is simple authentication, where username and password credentials are matched
against a user record in an external identity source. An example of delegated authentication
is RADIUS-based authentication, where an authentication request is submitted to a RADIUS-
compliant server for asserting user identity. In this case, the means and details for carrying out
this process are completely hidden from the authentication consumer.
In order for an IdP to delegate the authentication to a third-party, an Authentication Server element
needs to be associated with the IdP by using an Identity Verification edge.
An identity verification element is represented in the figure below :
7.1. Set Up Directory-based Authentication
Directory-based authentication is built onto the bind operation of the LDAP protocol. It
authenticates the client to the server using this operation. The server will typically check the
password against the userPassword attribute in the named entry.
An Identity Provider setup for directory-based authentication will, instead of verifying the supplied
user credentials locally, delegate this task to an external directory through an LDAP Bind request.
If the LDAP Bind operation is successful the user will be considered authenticated, whereas in
the opposite case the authentication will fail.
Using Directory-based authentication allows you to leverage a corporate identity silo, such as
Microsoft’s Active Directory, for centralized user authentication. Therefore, the time to deployment
decreases, given that the burden of setting up an authoritative source for user and entitlement
information to be consumed by the Single Sign-On system is unnecessary.
Click on and drag the element to the preferred location within the Diagram Canvas.
Authentication Setup
45
In the "New Directory Service Definition" window, enter the name of the Directory Service element
to be added to the Identity Appliance Diagram.
Field Descriptions
Field Description
Name The unique identifier of the Directory-based
Authentication element.
Description A descriptive text for the Directory-based
Authentication element.
Initial Context Factory The fully qualified class name of the
InitialContextFactory implementation.
This defaults to the Sun LDAP
provider implementation
com.sun.jndi.ldap.LdapCtxFactory.
Provider URL Enter the LDAP URL for the LDAP Directory
Server.
This defaults to "ldap://localhost:389", thus
expecting a directory server listening on the
standard port available in the same server
that both JOSSO and the identity appliance
execute.
Perform DN search Determines whether the distinguished name
of the user entry will be used as the user
identifier. The user’s distinguished name will
then be used to retrieve the user’s roles. If
this option is not selected, the user identifier
will be set to the common name attribute of
the user entry.
LDAP Security Policy The LDAP Security Policy mechanism to use.
Select "RFC Draft" to enable LDAP Security
Policy support based on the specifications
contained in the draft RFC titled draft-
behera-ldap-password-policy-09. For more
information see : http://tools.ietf.org/html/draft-
behera-ldap-password-policy-09
Select "None" to disable LDAP Security
Policy support.
Security Principal Enter the security principal for authentication
of the caller to the service.
Authentication Setup
46
This defaults to "uid=admin,ou=system", the
default for OpenLDAP.
Security Credential Enter the credential for the security principal
that will be passed on to authenticate the
caller to the service.
The semantics of this field depend on the
chosen authentication mechanism, as
described below.
Retype Security Credential Re-enter the security credential supplied in
the upper field.
Security Authentication Determines what authentication mechanism
will be used to authenticate the caller to the
service.
Available options are "None" for anonymous
binding, "Simple" for password-based
authentication and "Strong" for authentication
using X.509 client certificates.
On the "Lookup" screen, you can determine how user and role entries are to be retrieved. This
is required in order to access identity data responding to arbitrary schemas. The forced migration
of user data to a product-specific user schema is avoided, allowing you to re-use existing identity
silos independently of user data structure.
Field Description
User DN Enter the Distinguished Name (DN) that will
be used as the context for user searches.
This defaults to "ou=People,dc=my-
domain,dc=com".
Principal UID (User Identity) Attribute ID Enter the LDAP attribute name that holds the
distinctive identifier of the user. This defaults
to "uid".
Search Scope Enter the search strategy used to query user
and role entries in the target LDAP directory.
The default is "Subtree".
Setting the search scope to "Base" queries
within the specified contexts.
Setting the search scope to "One" will cause
LDAP queries to search only the immediate
Authentication Setup
47
children of the LDAP object corresponding to
the DN for users and roles.
Setting it to "Subtree" will query the entire
LDAP directory subtree below the search
baseDN for users and roles.
Setting the search scope to "Children" will
cause LDAP queries to search one level
below all direct children of the base entry.
Click on OK to confirm Directory Service element creation.
Click on Cancel to abort Directory Service element creation.
7.2. Set Up Integrated Windows Authentication
Integrated Windows Authentication uses the security features of Windows clients and servers.
Unlike Basic or Digest authentication, it does not initially prompt users for a user name and
password. The current Windows user information on the client computer is supplied by the browser
through a cryptographic exchange.
By enabling Integrated Windows Authentication for an Identity Provider, a user with an existing
session against a trusted Windows Domain will be automatically logged in when accessing a
service provider’s resources.
From the Palette, click in the "Authentication" drawer.
Click on and drag the "Windows Domain" element to the preferred location within the Diagram
Canvas.
In the "New Windows Domain Definition" window, enter the name of the Windows Domain
Authentication element to be added to the Identity Appliance Diagram.
Field Descriptions
Field Description
Name The unique identifier of the Windows Domain
Authentication element.
Description A descriptive text for the Windows Domain
Authentication element.
Protocol Enter the GSSAPI (Generic Security Services
Application Program Interface) mechanism to
use for negotiating a security token with the
selected Windows domain controller.
Authentication Setup
48
The default is "Kerberos".
Setting the protocol to "Kerberos" enables the
use of the Kerberos protocol when negotiating
service tickets with a Windows domain
controller.
Setting the protocol to "NTLM v2", enables
the use of the NTLM v2 protocol when
negotiating service tickets with a Windows
domain controller.
Windows Domain The identifier of the trusted Windows domain
controller.
Service Class The service that is being accessed, such as
HTTP.
Set this to the protocol used by JOSSO for
servicing requests.
Host The computer name for the computer that
hosts the service.
Set this to the fully qualified hostname used
by JOSSO for servicing requests. By default
JOSSO is bound to localhost.
Port Port is optional and only used for nonstandard
port configurations.
Set this to the port used by JOSSO for
servicing requests. By default JOSSO listens
on port 8081.
Service Name The Service Name portion of the SPN.
Domain Controller The fully qualified hostname where the
trusted Windows domain controller is
servicing requests.
Configure Kerberos Select to choose an automatically generating
Kerberos configuration.
Keytab file Select to upload the keytab file from the
local file system. The supplied keytab file
will be used to authenticate the Identity
Provider against the trusted Windows domain
controller.
Click on OK to confirm Windows Domain element creation.
Click on Cancel to abort Windows Domain element creation.
Authentication Setup
49
7.3. Set Up Two-Factor Authentication
Two-factor authentication is a security process in which the user provides two means of
identification; one of which is typically a physical token, such as a card, and the other typically
something memorized, such as a security code. In this context, the two factors involved are
sometimes spoken of as "something you have" and "something you know".
JOSSO supports out-of-the-box two-factor authentication, creating a secure, easy-to-use solution
for organizations that require SSO. JOSSO supports a wide variety of services including: Tomcat,
JBoss, Apache Web Server, IIS, Liferay, Weblogic and Alfresco; as well as cloud services
like Google Apps, Salesforce and SugarCRM. WiKID, for its part, supports Radius, LDAP and
TACACS+ in addition to having an API. WiKID Software tokens run on Linux, Mac, Windows,
iPhone, Android, J2ME and others.
Fundamentally, WiKID Strong Authentication works like this: a user selects the domain they wish
to use and enters the PIN into their WiKID two-factor client. It is encrypted with the WiKID Server’s
public key - assuring that only that server can decrypt it with its private key. If the server can
decrypt the PIN, and it is correct and the account is active, it generates the one-time passcode
(OTP) and encrypts it with the client’s public key. The user then enters their username and the
OTP into whatever service they are using, (a VPN, for example) which forwards it to the WiKID
Server for validation.
From the Palette, click in the "Authentication" drawer.
Click on and drag the "WikID Authentication element to the preferred location within the Diagram
Canvas.
In the "New WiKID Definition" window, enter the WiKID client configuration used by the associated
Identity Providers to offer strong authentication.
Field Descriptions
Field Description
Name The unique identifier of the WiKID Two-Factor
Authentication element.
Description A descriptive text for the WiKID Two-Factor
Authentication element.
Server Host Fill with the IP address or host name for your
WiKID server.
Server Code Enter the Server Code of your WiKID domain.
Certificate Authority Store Select to upload the Certificate Authority
Keystore of the WiKID server from the local
file system. The supplied keystore file will be
Authentication Setup
50
used to authenticate and decrypt messages
coming from the WiKID server.
Certificate Authority Password The passphrase required to open the
Certificate Authority Store.
WiKID Client Store Select to upload the keystore of the JOSSO
network client server from the local file
system. The supplied keystore file will be
used to authenticate and encrypt requests to
the WiKID server.
WiKID Client Password The passphrase required to open the WiKID
Client keystore.
Click on OK to confirm WiKID Authentication element creation.
Click on Cancel to abort WiKID Authentication element creation.
7.4. Set Up Domino Authentication
Lightweight Third-Party Authentication (LTPA), is an authentication technology used in IBM
WebSphere and Lotus Domino products. When accessing web servers that use the LTPA
technology it is possible for a web user to re-use their login across physical servers.
A Lotus Domino server or an IBM WebSphere server that is configured to use the LTPA
authentication will challenge the web user for a name and password. When the user has been
authenticated, their browser will have received a session cookie - a cookie that is only available
for one browsing session. This cookie contains the LTPA token.
If the user – after having received the LTPA token – accesses a server that is a member of the
same authentication configuration as the first server, and if the browsing session has not been
terminated (the browser was not closed down), then the user is automatically authenticated and
will not be challenged for a name and password. Such an environment is also called a Single-
Sign-On (SSO) environment.
An Identity Provider using LTPA as it’s authentication mechanism will rely on a Domino server
for authenticating users as well as establishing a Domino-specific SSO session for on-boarding
LTPA-compliant applications.
From the Palette, click in the "Authentication" drawer.
Click on and drag the "Domino" element to the preferred location within the Diagram Canvas.
In the "New Domino Definition" window, enter the Domino configuration used by the associated
Identity Providers to offer LTPA authentication.
Field Descriptions
Authentication Setup
51
Field Description
Name The unique identifier of the Domino
Authentication element.
Description A descriptive text for the Domino
Authentication element.
Domino Service Endpoint of the Domino Service for issuing
LTPA tokens.
Click on OK to confirm Domino Authentication element creation.
Click on Cancel to abort Domino Authentication element creation.
7.5. Set Up Client-certificate Authentication
There are many ways to use authentication over networks. Certificates are one of those way.
Network interactions typically take place between a client, such as a web browser, and a server.
Client authentication refers to the identification of a client (the person assumed to be using the
software) by a server. Server authentication refers to the identification of a server (the organization
assumed to be running the server at the network address) by a client.
Client authentication based on certificates is part of the SSL protocol. The client digitally signs a
randomly generated piece of data and sends both the certificate and the signed data across the
network. The server validates the signature and confirms the validity of the certificate.
From the Palette, click in the "Authentication" drawer.
Click on and drag the "Client-certificate Authentication" element to the preferred location within
the Diagram Canvas.
In the "New Domino Definition" window, enter the Client-certificate authentication configuration
used by the associated Identity Providers to offer this type of strong authentication.
Field Descriptions
Field Description
Name The unique identifier of the Client-certificate
Authentication element.
Description A descriptive text for the Client-certificate
Authentication element.
CRL URL The URL for downloading the full Certificate
Revocation List. The CRL is a list of all
certificates that have been issued by your
PKI but have been revoked for one reason or
Authentication Setup
52
another. A CRL is a primary mechanism that
ensures the security and health of your PKI.
Click on OK to confirm Client-certificate authentication element creation.
Click on Cancel to abort Client-certificate authentication element creation.
7.6. Set Up JBoss EPP Authentication
The JBoss Enterprise Portal Platform (or JBoss EPP) is an enterprise portal with the core portal
features of presentation, master page objects, containers, and a repository, and also an optional
site publisher.
The JBoss EPP Authentication service is used for having the identity provider delegate the
authentication to JBoss EPP.
From the Palette, click in the "Authentication" drawer.
Click on and drag the "JBoss EPP Authentication" element to the preferred location within the
Diagram Canvas.
In the "New JBoss EPP Authentication" window, enter the JBoss EPP Authentication configuration
used by the associated Identity Providers to offer JBossEPP-based authentication.
Field Descriptions
Field Description
Name The unique identifier of the JBoss EPP
Authentication element.
Description A descriptive text for the JBoss EPP
Authentication element.
Host The host from where the target JBoss EPP
instance is servicing requests.
Port The port where the target JBoss EPP is
listening. By default JBoss EPP listens on
port 8080.
Context The web application context of the target
JBoss EPP instance. It’s recommended to
leave this field blank.
Click on OK to confirm JBoss EPP Authentication element creation.
Click on Cancel to abort JBoss EPP Authentication element creation.
53
Chapter 8. Identity Provider SetupIn order to enable an Internet SSO setting you’ll need at least one entity playing the role of Identity
Provider (IdP). An IdP manages your identity, and provides an authentication service for client
applications. IdPs authenticate users and issue security tokens - like Security Assertions Markup
Language (SAML). Security Tokens contain user IDs and other identity properties of the user
(claims). Examples of some IdPs are: Windows Live ID, Google Accounts and Facebook.
Security Tokens issued by the IdP - upon successful user authentication - are pushed to the
parties who rely upon them, commonly known as Service Providers. A Service Provider (SP)
is an application that relies on the claims issued by an IdP to authorize a user, and to release
appropriate access to that user.
We’re assuming that you are beginning with an empty Identity Appliance, with no defined IdP.
8.1. Add an Internal IdP to the Identity Appliance
From the Palette, click "Identity Provider" in the "Providers" drawer.
Drag the "Identity Provider" element to the preferred location within the Diagram Canvas.
In the "New Identity Provider Definition" window, enter the name of the IdP.
On the "Core" screen, specify how the endpoints of the IdP will be reachable by consumers. The
default location is built using attributes supplied at identity appliance-creation time. For the sake
of consistency, we strongly suggest that you leave these default attributes "as-is".
Field Descriptions
Field Description
Location The access protocol - whether http or https.
Host name, port and context path to which the
endpoints for the IdP will be bound. Clients
will refer to services provided by the IdP using
URIs (Uniform Resource Identifiers) that are
qualified using the location value. We strongly
suggest that you use a fully qualified host
name, so that the identity appliance services
are not tied to a specific physical host.
Override Branding The branding extension used by this Identity
Provider to be applied in order to customize
the Look & Feel upon interacting with the
user.
Identity Provider Setup
54
User Dashboard URL The location where the user’s dashboard and
self-services - such as password reset - live.
Since such self-services are provided by an
external service provider, the IdP needs to
know the specific URL for users to access
such services.
Session Timeout how long a user session can be idle before
being discarded.
Limit Simultaneous Logins Maximum concurrent user sessions allowed
for a user.
Terminate Previous Sessions Specified whether previous user sessions
will be discarded upon a new session is
established. TBD: Double check
User Identifier Determines which type of user attribute will
be conveyed in authentication assertions to
service providers in order to determine their
name identifier. Select Principal to use the
username as the name identifier. Alternatively
select Email Address for using user’s email
address as the name identifier.
Ignore Requested User ID Type Determined whether the IdP will honour the
name identifier type for the IdP to use for
authentication assertions pushed to the SP
requesting to authenticate on behalf of the
user.
Authentication Contract The message contract for submitting input
claims, such as user credentials, to the IdP.
The default (and the only available contract)
builds on JOSSO-specific parameters, which
are submitted whenever simple web-based
authentication is attempted.
Authentication Mechanism The means by which users are authenticated.
The only supported authentication
mechanism is Simple Authentication which
performs the identification of users based on
username and password.
Authentication Assertion Emission Policy Used to customize how assertions are
issued, upon successful authentication.
The authentication assertions issued are
conveyed via security tokens, which are
pushed to relying parties.
Identity Provider Setup
55
On the SAML 2.0 screen, specify the SAML Profiles and Bindings to be enabled, as well as the
level of security for the artifacts involved in message exchanges between SPs and the IdP.
Field Descriptions
Field Description
Enabled SAML Profiles The SAML Profile to activate for this IdP.
These mainly represent the usage scenarios
realized by the IdP. The most important
SAML profile is the "Web Browser Single
Sign-On Profile", which can be enabled by
selecting the SSO checkbox.
Select the SLO checkbox to enable Single
Logout Support.
Enabled SAML Bindings The SAML bindings to be enabled for the
chosen SAML profiles.
Specifies the mapping of a SAML protocol
message onto standard messaging formats
and/or communications protocols. Select
the Http Post checkbox to convey SAML
messages through HTTP Post.
Select the Http Redirect checkbox to convey
SAML messages through HTTP Get.
Select the Artifact checkbox to convey
SAML messages through the SAML Artifact
Binding, which builds on both HTTP Redirect
and SOAP bindings for exchanging SAML
messages.
Select the SOAP checkbox to convey SAML
messages through SOAP over HTTP(s).
Want Authentication Requests Signed Determines whether the IdP expects only
digitally signed Authentication Requests.
Want Requests Signed Determines whether the IdP expects digitally
signed SAML requests.
Sign Authentication Assertions Determines whether SAML Authentication
Assertions, to be pushed to the target service
provider, will be digitally signed. Digitally
signing SAML Authentication Assertions
Identity Provider Setup
56
provides proof-of-identity of the IdP to Service
Providers, as well as ensuring their integrity.
Message TTL The timeframe in seconds for a message of a
SAML exchange between the identity provider
and a service provider is considered valid.
External Message TTL Tolerance TBD: ?
On the OAuth 2.0 screen specify whether you wish the IdP to act as a Security Token Service
(STS).
JOSSO2 builds on the OAUTH2 standard to deliver security token issuance services.
JOSSO2 Token-based Authentication focuses on client developer simplicity while providing
specific authorization flows for web and desktop applications. The core concepts are simple: The
end user client application requests for a particular scope of access. With user approval (e.g. by
sending user credentials), the application will get a short-lived access token that can be used to
validate requests for protected resources or user’s data.
Field Descriptions
Field Description
Enabled Select to enable OAuth2 based authentication
Enabled Flows Select to enable username-password
authentication flow. This flow can be used to
authenticate when the consumer already has
the user’s credentials.
Enabled Bindings These options specify the way in which
messages can be transported. Select
the SOAP checkbox for using the SOAP
transport. Select the RESTful checkbox for
using the RESTful transport.
Server Key The secret (password) used internally by
the OAuth2 service. TBD: What is this for ?
encrypting client db ?
Clients Configuration Specify which clients are allowed to consume
the OAuth2 service. The format is the
following : [ { "id": "client’s unique identifier",
"secret": "client’s secret" }, … ]. For instance :
[ { "id": "scott", "secret": "tiger" }, { "id": "john",
"secret": "foo" } ]
On the OpenID 2.0 screen specify whether the IdP should play the role of an OpenID Identity
Provider.
Identity Provider Setup
57
Field Descriptions
Field Description
Enabled Select to enable OpenID 2.0 support.
On the Certificate screen select the keystores holding the private and public key pairs used to
secure SAML message exchanges between SPs and the IdP.
The second step involves setting up the building blocks of the trust system, which is based
on public key infrastructure (PKI). The trust system allows for provision of peer authentication,
integrity, confidentiality and non-repudiation in a transport-agnostic fashion. The SAML standard
- which JOSSO supports - builds on PKI to guarantee these security attributes for SSO message
exchanges.
The requested information is mainly used by providers, to access private and public key pairs.
Field Descriptions
Field Description
Use Default Keystore Use a built-in JKS-compliant keystore.
Choosing to use the default keystore is only
recommended for sandbox settings, where
security is not really an issue.
Within a production system, using a custom
keystore is strongly recommended.
Upload the keystore file Use custom keystore file.
Certificate Key Pair Select this if you’d like to upload a keystore
file from the local file system.
Format The format of the keystore file.
The only supported keystore format is Java
Keystore.
Keystore Password The password that the IdP will use to decrypt
the supplied keystore, in order to access the
key pair entries stored within.
Certificate Alias The identifier of the keystore entry for the
IdP’s public key.
Key Alias The identifier of the keystore entry for the
IdP’s private key.
Identity Provider Setup
58
Key Password The password required to obtain the keystore
entry which holds the Identity Provider’s
private key.
On the Identity Confirmation screen you can setup whether the Identity Provider - in addition to
authenticate a user - shall use contextual for additionally assurance on their identity.
Identity Confirmation uses contextual information to ascertain whether a user’s identity is authentic
or not. Based on risk profiles, organizations may limit access to specific systems or content items
based on a user’s criteria, including whether the user is authenticating from the local or remote
network, whether the user is accessing information from a corporate computer, or whether the
access time appears reasonable (i.e. office hours for that user’s country location based on their
computer IP address). Since much of the information used by context-based information is publicly
available and therefore easily accessible to hackers, it is recommended to use this method to
complement other stronger authentication methods or as a first level of authentication in a multi-
layered approach.
Field Descriptions
Field Description
Enabled Select to enable Identity Confirmation for this
IdP.
Identity Confirmation Policy Specify how will identity confirmation be
accomplished. By default, the IdP uses email-
based identity confirmation.
Externally Hosted Select for the IdP to rely on an external
OAuth2 server in order to issue access
tokens.
Client ID The client identifier for authenticating token
requests to the OAuth2 server.
Client Secret The client secret for authenticating token
requests to the OAuth2 server.
Authorization Server Location Specify the endpoint (URL) for the external
OAuth2 server.
Click on OK to confirm IdP element creation.
Click on Cancel to abort IdP element creation.
Identity Provider Setup
59
8.2. Add an external SAML2 IdP to the Identity
Appliance
Use this option for on-boarding an externally hosted SAML2 identity provider, such as a SAML2-
compliant SaaS provider.
From the Palette, click in the "Providers" drawer.
Drag the "External SAML2 Identity Provider" element to the preferred location within the Diagram
Canvas.
In the "New External Saml2 Identity Provider Definition" window, enter the name of the External
SAML2 Identity Provider (IdP).
Field Descriptions
Field Description
Name The unique identifier of the IdP.
Description A descriptive text for the IdP.
Metadata file The metadata descriptor for the external
SAML2 identity provider. Metadata lets you
efficiently exchange federation configurations
between a site that uses JOSSO2 and a
partner that uses a third party or JOSSO2
solution.
Click on OK to confirm IdP element creation.
Click on Cancel to abort IdP element creation.
8.3. Add an external OpenID IdP to the Identity
Appliance
Use this option for on-boarding an externally hosted OpenID identity provider.
From the Palette, click in the "Providers" drawer.
Drag the "External OpenID Identity Provider" element to the preferred location within the Diagram
Canvas.
In the "New External OpenID Identity Provider Definition" window, enter the name of the External
OpenID Identity Provider (IdP).
Identity Provider Setup
60
Field Descriptions
Field Description
Name The unique identifier of the IdP.
Description A descriptive text for the IdP.
Claim type Choose the representation of Claim Values
that will be used in authentication assertions
to service providers.
Discovery URL for obtaining endpoint information
of the external OpenID Identity Provider.
The Discovery is the process where the
Relying Party uses the Identifier to look up
("discover") the necessary information for
initiating requests.
Click on OK to confirm IdP element creation.
Click on Cancel to abort IdP element creation.
8.4. Add Google Sign-In to the Identity Appliance
Google Sign-In - built on the OpenID Connect protocol - allows leveraging Google as an Identity
Provider.
Use this option for on-boarding Google as an external identity provider.
From the Palette, click in the "Cloud Providers" drawer.
Drag the "Google Sign-In" element to the preferred location within the Diagram Canvas.
On the "Core" screen, specify how consumers will reach the endpoints of the Google Sign-In IdP.
The default location is built using attributes supplied at identity appliance-creation time. For the
sake of consistency, we strongly suggest leaving the attributes as-is.
Field Descriptions
Field Description
Name The unique identifier of the Google Apps SP.
Description A descriptive text for the Google Apps SP.
Location The access protocol - whether http or https
- host name, port and context path where
Identity Provider Setup
61
the endpoints for the Google Sign-In will be
bound.
On the "OpenID Connect" screen, specify the Google Sign-In endpoints as well as the credentials
to authenticate requests.
Field Descriptions
Field Description
Client ID The “Client ID” generated by Google.
Client Secret This is the “Client secret” generated by
Google.
Confirm Secret Re-enter the “Client secret”.
Authorize Endpoint Authorization URL as provided by the OpenID
Connect Authorization Server.
Token Endpoint Token URL as provided by the OpenID
Connect Authorization Server.
On the "Services" screen, specify which services you wish to access using a Google Sign-In token
as well as the associated Google Apps domain
Click on OK to confirm Google Sign-In IdP element creation.
Click on Cancel to abort Google Sign-In IdP element creation.
8.5. Set Up the Identity Store of the Identity Provider
8.5.1. Using an Embedded Identity Vault as the Authoritative
Source for the Identity Provider
In order to use an embedded identity vault as the identity store for an IdP, an embedded identity
vault element needs to be defined for the identity appliance. See Section 6.1, “Setup of an
Embedded Identity Vault” to learn more on how to set up an identity vault.
Once the IdP and embedded identity vault elements have been defined for the current Identity
Appliance, use the Identity Lookup connection to connect them.
From the Palette, click in the "Connections" drawer.
Click on the source IdP element and drag the edge to the target embedded identity vault element.
An edge should appear connecting the IdP and embedded identity vault elements.
Identity Provider Setup
62
8.5.2. Using a DB Identity Vault as the Authoritative source for
the Identity Provider
In order to use a DB Identity Vault as the identity store for an IdP, a DB Identity Vault element
needs to be defined for the identity appliance. See Section 6.2, “Setup of a Database Identity
Vault” to learn more on how to set up a DB Identity Vault.
Once an IdP and DB Identity Vault elements have been defined for the current Identity Appliance,
use the Identity Lookup connection to connect them both.
From the Palette, click in the "Connections" drawer.
Click on the source IdP element and drag the edge to the target DB Identity Vault element.
An edge should appear connecting the IdP and DB Identity Vault elements.
8.5.3. Using an LDAP Directory as Authoritative Source for the
Identity Provider
In order to use an LDAP Directory as the identity store for an IdP, an LDAP Identity Source element
needs to be defined for the identity appliance. See Section 6.3, “Setup of an LDAP Directory
Identity Source” to learn more on how to set up an LDAP Identity Source.
Once the IdP and LDAP Identity Source elements have been defined for the current Identity
Appliance, use the Identity Lookup connection to connect them.
From the Palette, click in the "Connections" drawer.
Click on the source IdP element and drag the edge to the target LDAP Identity Source element.
An edge should appear connecting the IdP and LDAP identity source elements.
8.5.4. Using an RDBMS as Authoritative Source for the Identity
Provider
In order to use a Relational Database as the identity store for an IdP, an RDBMS Identity Source
element needs to be defined for the identity appliance. See Section 6.4, “Set Up an RDBMS
Identity Source” to learn more on how to set up an RDBMS Identity Source.
Once the IdP and RDBMS Identity Source elements have been defined for the current Identity
Appliance, use the Identity Lookup connection to connect them.
From the Palette, click in the "Connections" drawer.
Click on the source IdP element and drag the edge to the target DB Identity Source element.
An edge should appear connecting the IdP and DB identity source elements.
63
Chapter 9. Service Provider SetupOnce an IdP has been defined as the identity source that will be used to back authentication
processes, the next step is to define the trusted partner sites that will consume the claims made
by the IdP on behalf of any given user.
Service Providers will build on this claim set to authorize service requests made by end users
and applications.
Service Providers may be classified based on their location - whether internally or externally
hosted - as well as the the protocols they support in terms of the interoperability with an Identity
Provider.
JOSSO2 allows on-boarding service providers supporting different single sign-on standards.
9.1. Internal SAML2 Service Provider Setup
From the Palette, click in the "Providers" drawer.
Drag the "Internal SAML2 Service Provider" element to the preferred location within the Diagram
Canvas.
In the "New Saml2 Service Provider Definition" window, enter the name of the Internal SAML2
Service Provider (SP).
On the "Core" screen, specify how consumers will reach the endpoints of the SP. The default
location is built using attributes supplied at identity appliance-creation time. For the sake of
consistency, we strongly suggest leaving the attributes as-is.
Field Descriptions
Field Description
Name The unique identifier of the SP.
Description A descriptive text for the SP.
Location The access protocol - whether http or https -
host name, port and context path where the
endpoints for the SP will be bound.
Clients will refer to services provided by the
SP using URIs which are qualified using this
location value.
We strongly suggest that you use a fully
qualified host name, so that the identity
Service Provider Setup
64
appliance services are decoupled from a
specific physical host.
Account Linkage Policy The means by which input claims, conveyed
in the security token, which are issued and
submitted by a trusted IdP, will be mapped to
output claims; which will in turn be consumed
by the relevant party in order to authorize
users and grant them appropriate access.
Select "Use Theirs" to link IdP and SP
accounts using the supplied name identifier,
and to map input to output claims in a one-to-
one fashion.
Select "Use Ours" to link IdP and SP
accounts using the supplied name identifier,
and to issue output claims based only on
the user details that are available within the
identity source connected with the SP.
Select "Aggregate" to link IdP and SP
accounts using the supplied name identifier,
and to issue output claims based on merging
both the user details conveyed in the security
token and those obtained from the identity
source connected to the SP.
On the Contract screen, specify the IdP-facing SAML Profiles and Bindings to enable.
You can also check on the level of security of the artifacts involved in message exchanges between
SPs and the IdP.
Field Descriptions
Field Description
Enabled SAML Profiles The SAML Profile to activate for this IdP.
These mainly represent the usage scenarios
realized by the SP.
The most important SAML profile is the "Web
Browser Single Sign-On Profile", which can
be enabled by selecting the SSO checkbox.
Select the SLO checkbox to enable Single
Logout Support.
Service Provider Setup
65
Enabled SAML Bindings The SAML bindings to be enabled for the
selected SAML profiles.
These specify the mapping of a SAML
protocol message onto standard messaging
formats and/or communications protocols.
Select the Http Post checkbox to convey
SAML messages through HTTP Post.
Select the Http Redirect checkbox to convey
SAML messages through HTTP Get.
Select the Artifact checkbox to convey
SAML messages through the SAML Artifact
Binding, which builds on both HTTP Redirect
and SOAP bindings to exchange SAML
messages.
Select the SOAP checkbox to convey SAML
messages through SOAP over HTTP(s).
Sign Authentication Requests Determines whether SAML2 Authentication
Requests pushed to the IdP will be
digitally signed. Digitally signing SAML2
Authentication Requests provides proof-of-
identity of the SP to Identity Providers, as well
as ensuring their integrity.
Want Assertion Signed Determines whether the SP expects digitally
signed SAML authentication assertions.
Want SLO Response Signed Determines whether the SP expects digitally
signed SAML single logout requests.
Want Requests Signed Determines whether the SP expects digitally
signed SAML requests.
Sign Requests Determines whether SAML2 requests pushed
to the IdP will be digitally signed. Digitally
signing SAML2 Authentication Requests
provides proof-of-identity of the SP to Identity
Providers, as well as ensuring their integrity.
Message TTL The timeframe in seconds for a message of a
SAML exchange between the identity provider
and a service provider is considered valid.
External Message TTL Tolerance TBD: ?
Service Provider Setup
66
On the Certificate screen, select the keystores which hold the private and public key pairs to
secure SAML message exchanges between SPs and the IdP.
This involves setting up the building blocks of the trust system, which is based on public key
infrastructure (PKI). The trust system provides peer authentication, integrity, confidentiality and
non-repudiation in a transport-agnostic fashion. The SAML standard - which JOSSO supports -
builds on PKI to guarantee these security attributes for SSO message exchanges. The requested
information is mainly used for providers to access private and public key pairs.
Field Descriptions
Field Description
Use Default Keystore Use the built-in keystore portion of the
distribution.
We recommend this for sandbox settings
only, where security is not really an issue.
Within a production system, using a custom
keystore is strongly recommended.
Upload the keystore file Select this option if you wish to use a custom
keystore.
Certificate/Key Pair Allows you to select the desired keystore file
from the local filesystem.
Format The Keystore Format for the uploaded
keystore file.
Choose "Java Keystore" which is currently the
only supported keystore format. It is expected
that the PKCS#12 will be supported in future
releases.
Keystore Password Password that providers will use to open the
keystore, to obtain the private and public
certificate pairs that are required to secure
SSO exchanges.
Certificate Alias Identifier of the keystore entry for the public
key. The public key is used, for instance, to
validate the digital signature conveyed in
SAML messages, to identify the requester
and the integrity of the messages.
Key Alias Name of the keystore entry used to obtain the
corresponding private key. The private key
is used, for instance, to digitally sign SAML
messages.
Service Provider Setup
67
Key Password The password required to obtain the private
key.
Click on OK to confirm SP element creation.
Click on Cancel to abort SP element creation.
9.2. External SAML2 Service Provider Setup
Use this option for on-boarding an externally hosted SAML2 service provider, such as a SAML2-
compliant SaaS provider.
From the Palette, click in the "Providers" drawer.
Drag the "External SAML2 Service Provider" element to the preferred location within the Diagram
Canvas.
In the "New External Saml2 Service Provider Definition" window, enter the name of the External
SAML2 Service Provider (SP).
Field Descriptions
Field Description
Name The unique identifier of the SP.
Description A descriptive text for the SP.
Metadata file The metadata descriptor for the external
SAML2 service provider. Metadata lets you
efficiently exchange federation configurations
between a site that uses JOSSO2 and a
partner that uses a third party or JOSSO2
solution.
Click on OK to confirm SP element creation.
Click on Cancel to abort SP element creation.
9.3. Internal OAuth2 Service Provider Setup
Use this option for defining a local OAuth2 Service Provider.
From the Palette, click in the "Providers" drawer.
Drag the "OAuth2 Service Provider" element to the preferred location within the Diagram Canvas.
Service Provider Setup
68
In the "New OAuth2 Service Provider Definition" window, enter the name of the OAuth2 Service
Provider (SP).
Field Descriptions
Field Description
Name The unique identifier of the SP.
Description A descriptive text for the SP.
Location The access protocol - whether http or https.
Host name, port and context path to which the
endpoints for the SP will be bound. Clients
will refer to services provided by the SP using
URIs (Uniform Resource Identifiers) that are
qualified using the location value.
Click on OK to confirm SP element creation.
Click on Cancel to abort SP element creation.
9.4. Add Salesforce to the Identity Appliance
Salesforce.com is a customer relationship management (CRM) software-as-a-service (SaaS)
provider.
Use this option for on-boarding Salesforce (SFDC) as an external service provider.
From the Palette, click in the "Cloud Providers" drawer.
Drag the "Salesforce Service Provider" element to the preferred location within the Diagram
Canvas.
Field Descriptions
Field Description
Name The unique identifier of the Salesforce SP.
Login URL The endpoint used by Salesforce for servicing
authentication requests.
Description A descriptive text for the Salesforce SP.
Click on OK to confirm Salesforce SP element creation.
Click on Cancel to abort Salesforce IdP element creation.
Service Provider Setup
69
9.5. Add Google Apps to the Identity Appliance
Google Apps is a Web-based and collaborative Software as a Service (SaaS) solution that
customizes the proprietary Google platform and brand for businesses of all sizes, including large
enterprises. Google Apps facilitates the provisioning of Google applications and user/enterprise
management tools.
Use this option for on-boarding Google Apps as an external service provider.
From the Palette, click in the "Cloud Providers" drawer.
Drag the "Google Service Provider" element to the preferred location within the Diagram Canvas.
Field Descriptions
Field Description
Name The unique identifier of the Google Apps SP.
Description A descriptive text for the Google Apps SP.
Domain The Google Apps domain honouring
assertions made by JOSSO2 identity
provider.
Click on OK to confirm Google Apps SP element creation.
Click on Cancel to abort Google Apps SP element creation.
9.6. Add SugarCRM to the Identity Appliance
SugarCRM is a customer relationship management system (CRM) that is available in both open
source and Commercial open source applications.
Use this option for on-boarding SugarCRM as an external service provider.
From the Palette, click in the "Cloud Providers" drawer.
Drag the "SugarCRM Service Provider" element to the preferred location within the Diagram
Canvas.
Field Descriptions
Field Description
Name The unique identifier of the Google Apps SP.
Service Provider Setup
70
Description A descriptive text for the Google Apps SP.
Instance Unique URL The URL where the target SugarCRM service
is hosted.
Click on OK to confirm SugarCRM SP element creation.
Click on Cancel to abort SugarCRM SP element creation.
9.7. Set Up the Identity Source of the Service Provider
An SP may build on an identity source in order to link the IdP account with a local counterpart,
and employ the user details available in the IdP account to augment output claims.
Associating an SP with an Identity Source is not mandatory. Only use this feature when
augmenting claims pushed by trusted IdPs with information available in an SP-local store.
To define a local identity source for an SP, drag one of the available identity sources and connect
it to the target SP, using the "identity lookup" edge.
9.7.1. Using an Identity Vault as the Authoritative Source for the
Service Provider
In order to build the SP on the information provided by the built-in identity store, define an Identity
Vault element and associate it with the IdP.
From the Palette, click either an "Embedded Identity Vault" or "DB Identity Vault" in the "Identity
Sources" drawer.
Click on and drag the "Identity Vault" element to the preferred location within the Diagram Canvas.
For more information regarding the setup of identity vaults, please refer to Section 6.1, “Setup of
an Embedded Identity Vault” and Section 6.2, “Setup of a Database Identity Vault”.
In order to use an identity vault as the identity store for an IdP, establish an "identity lookup"
connection between them both.
From the Palette, click "Identity Lookup" on the "Connections" drawer.
Click on the source SP element, and drag the edge to the target identity vault element.
An edge should appear, connecting the SP and identity vault elements.
9.7.2. Using an LDAP Directory as the Authoritative Source for
the Service Provider
In order to build the SP using the information provided by an LDAP directory, first define an LDAP
Identity Source element and then associate it with the IdP.
Service Provider Setup
71
From the Palette, click "Ldap Identity Source" in the "Identity Sources" drawer.
Click on and drag the "Ldap Identity Source" element to the preferred location within the Diagram
Canvas.
For more information regarding the setup of LDAP identity sources, please refer to Section 6.3,
“Setup of an LDAP Directory Identity Source”.
To employ an LDAP Directory as the identity store for an IdP, establish an identity lookup
connection between both.
From the Palette, click "Identity Lookup" on the "Connections" drawer.
Click on the source SP element and drag the edge to the target LDAP Identity Source element.
An edge should appear, connecting the SP and LDAP identity source elements.
9.7.3. Using an RDBMS as the Authoritative Source for the
Service Provider
In order to build the SP on the information provided by an RDBMS-based identity source, you
must define an RBMS Identity Source element and associate it with the SP.
From the Palette, click "RDBMS Identity Source" in the "Identity Sources" drawer.
Click on and drag the "RDBMS Identity Source" element to the preferred location within the
Diagram Canvas.
For more information regarding the setup of RDBMS identity sources please refer to Section 6.4,
“Set Up an RDBMS Identity Source”.
In order to use an RDBMS source as the identity store for an SP, you must establish an Identity
Lookup connection between them.
From the Palette, click "Identity Lookup" in the "Connections" drawer.
Click on the source SP element, and drag the edge to the target XML Identity Source element.
An edge should appear, connecting the SP and RDBMS identity source elements.
9.8. Set Up the Resource of the Service Provider
Resources are used to represents identity consumers, such as business applications as well as
commercial off-the-shelf solutions.
The main responsibility of an Identity Provider is to establish the identity of a user by means of
authentication. Once this process is completed, the outcome - in the form of an authentication
assertion - is passed on to the service provider. Technically, the service provider is servicing
requests from within the JOSSO2 server instance, being completely unaware of the target service
that will be leveraging such authentication information.
Service Provider Setup
72
The responsibility of mapping an authentication assertion to a security context for consumption
by the target business application or service lies in the resource. Resources may receive such
authentication assertion using different means - such as a different authentication protocol - than
the one used originally between the identity and service provider. Such semantics is determined
in the prefix of the resource element type.
In order to specify how authentication assertions will be passed on to the business tier as well as
the target location, a service connection is used. A service connection links an internal service
provider with a resource.
A service connection element is represented in the figure below :
9.8.1. Onboarding a JOSSO1 Resource
Alfresco offers true Open Source Enterprise Content Management (ECM): Document
Management, Collaboration, Records Management, Knowledge Management, Web Content
Management and Imaging.
In order to build the SP on a JOSSO1 resource, you must define the JOSSO1 resource element,
and associate it with the SP.
From the Palette, click in the "Resources" drawer, and drag it to the preferred location within
the Diagram Canvas.
Within the setup dialog, enter the Alfresco CMS resource details :
Field Descriptions
Field Description
Name The unique identifier for the execution
environment.
Description A descriptive text for the execution
environment.
Location Specify the protocol, host, port and URI
to which your partner application is bound
for servicing requests from end-users. In
order to enable the SSO capabilities in your
application, user requests should refer to the
web application using URLs that match the
values specified in this field. If your SP is the
example JOSSO application, make sure to
specify "partnerapp" in the URI field.
Service Provider Setup
73
9.8.2. Onboarding a Sharepoint Resource
SharePoint is an enterprise information portal, from Microsoft, that can be configured to run
Intranet, Extranet and Internet sites.
In order to build the SP on a Sharepoint resource, you must define the Sharepoint resource
element, and associate it with the SP.
From the Palette, click in the "Resources" drawer, and drag it to the preferred location within
the Diagram Canvas.
Within the setup dialog, enter the Sharepoint resource details :
Field Descriptions
Field Description
Name The unique identifier for the resource.
Description A descriptive text for the resource.
Site Collection Location Specify the protocol, host, port and URI of the
SharePoint site.
STS Location Specify the protocol, host, port and URI of the
Security Token Service (STS) .
Signing Certificate Specify the identifier of the entry pointing
to the X.509 certificate for digitally signing
messages.
Encryption Certificate Specify the identifier of the entry pointing to
the X.509 certificate for encrypting messages.
9.8.3. Onboarding a Microstrategy Resource
MicroStrategy is an enterprise business intelligence (BI) software solution.
In order to build the SP on a Microstrategy resource, you must define the Microstrategy resource
element, and associate it with the SP.
From the Palette, click in the "Resources" drawer, and drag it to the preferred location within
the Diagram Canvas.
Within the setup dialog, enter the Microstrategy resource details :
Field Descriptions
Service Provider Setup
74
Field Description
Name The unique identifier for the resource.
Description A descriptive text for the resource.
Shared Secret A shared secret for authenticating and
decrypting security issued by the Identity
Provider.
Location Specify the protocol, host, port and URI to
which the Microstrategy Web application is
bound for servicing requests from end-users.
9.8.4. Onboarding an Alfresco Resource
Alfresco offers true Open Source Enterprise Content Management (ECM): Document
Management, Collaboration, Records Management, Knowledge Management, Web Content
Management and Imaging.
In order to build the SP on an Alfresco resource, you must define the Alfresco resource element,
and associate it with the SP.
From the Palette, click in the "Resources" drawer, and drag it to the preferred location within
the Diagram Canvas.
Within the setup dialog, enter the Alfresco CMS resource details :
Field Description
Name The unique identifier for the resource.
Description A descriptive text for the resource.
Target Host The host where the Alfresco CMS instance is
located.
The available options are "Local" and
"Remote". If the "Local" option is selected, it is
assumed that the execution environment will
be found within the same host that is running
JOSSO2. Alternatively, if the "Remote" option
is selected, it is assumed that the execution
environment will be located within a different
host than the one that’s running JOSSO2.
Install Home The folder hosting the artifacts of the Alfresco
CMS server instance.
Remote JOSSO 2 URL The endpoint of the activation web service for
the remote JOSSO2 instance. In order for the
Service Provider Setup
75
remote activation to be successful, the target
execution environments need to be located
within the same host as the remote JOSSO2
instance. This field is only shown if the remote
target host option is selected.
Container Type The web container flavour on top of which the
Alfresco CMS server is deployed.
Container Home The folder hosting the web container on top of
which the Alfresco CMS server runs.
Overwrite Original Setup Select this option if the execution environment
has been previously activated, either from the
JOSSO1 command line console or through
the Atricore Console, and you wish to replace
the original settings with new ones.
9.8.5. Onboarding a JBoss Portal Resource
JBoss Portal provides an open source platform for hosting and serving a portal’s Web interface,
publishing and managing its content, and customizing its experience.
In order to build the SP on a JBoss Portal resource, you must define the JBoss Portal resource
element, and associate it with the SP.
From the Palette, click in the "Resources" drawer, and drag it to the preferred location within
the Diagram Canvas.
Within the setup dialog, enter the JBoss Portal resource details :
Field Descriptions
Field Description
Name The unique identifier for the resource.
Description A descriptive text for the resource.
Target Host The host where the JBoss Portal instance is
located.
The available options are "Local" and
"Remote". If the "Local" option is selected, it is
assumed that the execution environment will
be found within the same host that is running
JOSSO2. Alternatively, if the "Remote" option
is selected, it is assumed that the execution
Service Provider Setup
76
environment will be located within a different
host than the one that’s running JOSSO2.
Install Home The folder hosting the artifacts of the JBoss
Portal server instance.
Remote JOSSO2 URL The endpoint of the activation web service for
a remote JOSSO2 instance. In order for the
remote activation to be successful, the target
execution environments need to be located
within the same host as the remote JOSSO2
instance. This field is only shown if the remote
target host option is selected.
Overwrite Original Setup Check in cases where the execution
environment has been previously activated,
either from the JOSSO1 command line
console or through the Atricore Console,
and you wish to have the original settings
replaced with new ones.
Install Demo Applications Check, if deploying JOSSO example web
applications onto the target execution
environment. We strongly recommend that
you check this field in order to verify that the
Internet SSO setting works as expected,
before engaging in SSO-enabling candidate
business applications.
9.8.6. Onboarding a Liferay Portal Resource
Liferay Portal is a free and open source enterprise portal project written in Java and distributed
under the GNU Lesser General Public License and optional commercial license.
In order to build the SP on a Liferay Portal resource, you must define the Liferay Portal resource
element, and associate it with the SP.
From the Palette, click in the "Resources" drawer, and drag it to the preferred location within
the Diagram Canvas.
Within the setup dialog, enter the Liferay Portal resource details :
Field Descriptions
Field Description
Name The unique identifier for the resource.
Description A descriptive text for the resource.
Service Provider Setup
77
Target Host The host where the Liferay Portal instance is
located.
The available options are "Local" and
"Remote". If the "Local" option is selected, it is
assumed that the execution environment will
be found within the same host that is running
JOSSO2. Alternatively, if the "Remote" option
is selected, it is assumed that the execution
environment will be located within a different
host than the one that’s running JOSSO2.
Install Home The folder hosting the artifacts of the Liferay
Portal server instance.
Remote JOSSO2 URL The endpoint of the activation web service for
a remote JOSSO2 instance. In order for the
remote activation to be successful, the target
execution environments need to be located
within the same host as the remote JOSSO2
instance. This field is only shown if the remote
target host option is selected.
Container Type The web container flavour on top of which the
Liferay Portal server is deployed.
Container Path The folder hosting the web container on top of
which the Liferay Portal server runs.
Overwrite Original Setup Check, if the execution environment has been
previously activated, either from the JOSSO1
command line console or through the Atricore
Console, and you wish to have the original
settings replaced with new ones.
Install Demo Applications Check, to deploy JOSSO example web
applications onto the target execution
environment. We strongly recommend that
you check this field, in order to verify that
the Internet SSO setting works as expected,
before engaging in SSO-enabling candidate
business applications.
9.8.7. Onboarding a PhpBB Resource
phpBB is a free flat-forum bulletin board software solution that can be used to stay in touch with
a group of people or can power your entire website.
In order to build the SP on a phpBB resource, you must define the phpBB resource element, and
associate it with the SP.
Service Provider Setup
78
From the Palette, click in the "Resources" drawer, and drag it to the preferred location within
the Diagram Canvas.
Within the setup dialog, enter the phpBB resource details :
Field Descriptions
Field Description
Name The unique identifier for the resource.
Description A descriptive text for the resource.
Target Host The host where the PhpBB instance is
located. The available options are "Local" and
"Remote". If the "Local" option is selected, it is
assumed that the execution environment will
be found within the same host that is running
JOSSO2. Alternatively, if the "Remote" option
is selected, it is assumed that the execution
environment will be located within a different
host than the one that’s running JOSSO2.
Install Home The folder hosting the artifacts of the phpBB
forum application.
Remote JOSSO2 URL The endpoint of the activation web service for
a remote JOSSO2 instance. In order for the
remote activation to be successful, the target
execution environments need to be located
within the same host as the remote JOSSO2
instance.
This field is only shown if the remote target
host option is selected.
Overwrite Original Setup Check, if the execution environment has been
previously activated, either from the JOSSO1
command line console or through the Atricore
Console, and you wish to have the original
settings replaced with new ones.
Install Demo Applications Check, to deploy JOSSO example web
applications onto the target execution
environment. e strongly recommend that
you check this field in order to verify that the
Internet SSO setting works as expected,
before engaging in SSO-enabling candidate
business applications.
Service Provider Setup
79
9.8.8. Onboarding a JBossEPP Resource
The JBoss Enterprise Portal Platform (or JBoss EPP) is an enterprise portal with the core portal
features of presentation, master page objects, containers, and a repository, and also an optional
site publisher.
In order to build the SP on a JBossEPP resource, you must define the JBossEPP resource
element, and associate it with the SP.
From the Palette, click in the "Resources" drawer, and drag it to the preferred location within
the Diagram Canvas.
Within the setup dialog, enter the JBossEPP resource details :
Field Descriptions
Field Description
Name The unique identifier for the resource.
Description A descriptive text for the resource.
Target Host The host where the JBossEPP instance is
located. The available options are "Local" and
"Remote". If the "Local" option is selected, it is
assumed that the execution environment will
be found within the same host that is running
JOSSO2. Alternatively, if the "Remote" option
is selected, it is assumed that the execution
environment will be located within a different
host than the one that’s running JOSSO2.
Install Home The folder hosting the artifacts of the
JBossEPP server instance.
Remote JOSSO 2 URL The endpoint of the activation web service for
the remote JOSSO2 instance. In order for the
remote activation to be successful, the target
execution environments need to be located
within the same host as the remote JOSSO2
instance. This field is only shown if the remote
target host option is selected.
Instance The active JBossEPP instance.
Overwrite Original Setup Check, if the execution environment has been
previously activated, either from the JOSSO1
command line console or through the Atricore
Console, and you wish to have the original
settings replaced with new ones.
Service Provider Setup
80
9.8.9. Onboarding a Self-Services Resource
This is an application bundled with JOSSO2 which allows users to manage their account as well
as accessing configured service providers from a standard web browser.
In order to build the SP on a Self Services resource, you must define the Self Services resource
element, and associate it with the SP.
From the Palette, click in the "Resources" drawer, and drag it to the preferred location within
the Diagram Canvas.
Within the setup dialog, enter the Self Services resource details :
Field Descriptions
Field Description
Name The unique identifier for the resource.
Description A descriptive text for resource.
9.8.10. Onboarding a Domino Resource
IBM Domino (formerly IBM Lotus Domino) is an IBM server product that provides enterprise-grade
e-mail, collaboration capabilities, and a custom application platform.
In order to build the SP on Domino resource, you must define the Domino resource element, and
associate it with the SP.
From the Palette, click in the "Resources" drawer, and drag it to the preferred location within
the Diagram Canvas.
Within the setup dialog, enter the Domino Resource resource details :
Field Descriptions
Field Description
Name The unique identifier for the resource.
Description A descriptive text for the resource.
Location Specify the protocol, host, port and URI
to which your Domino server is bound
for servicing requests from end-users. In
order to enable the SSO capabilities in your
application, user requests should refer to the
web application using URLs that match the
values specified in this field.
Service Provider Setup
81
Domino Service Endpoint of the Domino Service for verifying
LTPA tokens.
9.9. Set Up the Execution Environment of the Resource
One or more Resources can be hosted within an execution environment.
9.9.1. Using an Apache Web Server Execution Environment
The Apache HTTP Server is a popular open source, standard, secure, efficient and extensible
HTTP server for modern operating systems, including UNIX and Windows NT.
An Apache HTTP Server can run virtually all types of web applications, such as those written in
PHP, Perl, Ruby and Python among many others.
Establishing an activation connection between a resource and an Apache Web Server Execution
Environment implies that the Resource is a web application, hosted by an Apache Web Server
instance.
There is no support for automatic activation upon an Apache Web Server execution environment
that is connected with a Resource.
Applications running under Apache Web Server can be SSO-enabled seamlessly, without having
to couple the application to the underlying SSO infrastructure, and deal with SSO internals.
Once a successful security context is established, the web application - playing the service
provider role - can consume it by relying on the REMOTE_USER environment variable set as the
JOSSO Agent for Apache Web Server.
This variable contains the user name of the authenticated user. The REMOTE_USER value can be
used to search for the user details as well as any other business-specific user profile information.
From the Palette, click in the "Execution Environments" drawer.
Within the setup dialog, enter the Apache Web Server execution environment details :
Field Descriptions
Field Description
Name The unique identifier for the execution
environment.
Description A descriptive text for the execution
environment.
Target Host The host where the Apache Web Server
instance is located.
Service Provider Setup
82
The available options are "Local" and
"Remote". If the "Local" option is selected, it is
assumed that the execution environment will
be found within the same host that is running
JOSSO2. Alternatively, if the "Remote" option
is selected, it is assumed that the execution
environment will be located within a different
host than the one that’s running JOSSO2.
Install Home The folder hosting the artifacts of the Apache
Web Server instance.
Remote JOSSO 2 URL The endpoint of the activation web service for
the remote JOSSO2 instance. In order for the
remote activation to be successful, the target
execution environments need to be located
within the same host as the remote JOSSO2
instance.
This field is only shown if the remote target
host option is selected.
9.9.2. Using a JavaEE Execution Environment
Java Platform, Enterprise Edition or Java EE is a widely used platform for server programming
in the Java programming language. The Java platform (Enterprise Edition) differs from the Java
Standard Edition Platform (Java SE) in that it adds libraries which provide functionality to deploy
fault-tolerant, distributed, multi-tier Java software, based largely on modular components running
on an application server.
In order to build the Resource on a JavaEE execution environment, define a JavaEE Execution
Environment element and associate it with the Resource.
From the Palette, click in the "Execution Environments" drawer, and drag it to the preferred
location within the Diagram Canvas.
Within the setup dialog, enter the JavaEE execution environment details :
Field Descriptions
Field Description
Name The unique identifier for the execution
environment.
Description A descriptive text for the execution
environment.
Service Provider Setup
83
Target Host The host where the JavaEE server instance is
located.
The available options are "Local" and
"Remote". If the "Local" option is selected, it is
assumed that the execution environment will
be found within the same host that is running
JOSSO2. Alternatively, if the "Remote" option
is selected, it is assumed that the execution
environment will be located within a different
host than the one that’s running JOSSO2.
Install Home The folder hosting the artifacts of the JavaEE
server instance.
Remote JOSSO2 URL The endpoint of the activation web service for
the remote JOSSO2 instance. In order for the
remote activation to be successful, the target
execution environments need to be located
within the same host as the remote JOSSO2
instance.
This field is only shown if the remote target
host option is selected.
9.9.3. Using a Webserver Execution Environment
A web server execution environment represents a generic web server (or container) hosting web
applications or resources. Activation is not supported for this environment.
In order to build the Resource on a Web server execution environment, you must define the Web
Server execution environment element, and associate it with the Resource.
From the Palette, click in the "Execution Environments" drawer, and drag it to the preferred
location within the Diagram Canvas.
Within the setup dialog, enter the Web Server execution environment details :
Field Descriptions
Field Description
Name The unique identifier for the execution
environment.
Description A descriptive text for the execution
environment.
Service Provider Setup
84
Target Host The host where the Web Server instance is
located.
The available options are "Local" and
"Remote". If the "Local" option is selected, it is
assumed that the execution environment will
be found within the same host that is running
JOSSO2. Alternatively, if the "Remote" option
is selected, it is assumed that the execution
environment will be located within a different
host than the one that’s running JOSSO2.
Install Home The folder hosting the artifacts of the JavaEE
container.
Remote JOSSO 2 URL The endpoint of the activation web service for
a remote JOSSO2 instance. In order for the
remote activation to be successful, the target
execution environments need to be located
within the same host as the remote JOSSO2
instance.
This field is only shown if the remote target
host option is selected.
9.9.4. Using a PHP Execution Environment
A PHP execution environment represents a generic web server (or container) capable of hosting
PHP-based web applications . Activation is not supported for this environment.
In order to build the Resource on a Web server execution environment, you must define the PHP
execution environment element, and associate it with the Resource.
From the Palette, click in the "Execution Environments" drawer, and drag it to the preferred
location within the Diagram Canvas.
Within the setup dialog, enter the Web Server execution environment details :
Field Descriptions
Field Description
Name The unique identifier for the execution
environment.
Description A descriptive text for the execution
environment.
Service Provider Setup
85
Target Host The host where the PHP-capable Web Server
instance is located.
The available options are "Local" and
"Remote". If the "Local" option is selected, it is
assumed that the execution environment will
be found within the same host that is running
JOSSO2. Alternatively, if the "Remote" option
is selected, it is assumed that the execution
environment will be located within a different
host than the one that’s running JOSSO2.
Install Home The folder hosting the artifacts of the PHP-
capable Web Server instance.
Remote JOSSO 2 URL The endpoint of the activation web service for
a remote JOSSO2 instance. In order for the
remote activation to be successful, the target
execution environments need to be located
within the same host as the remote JOSSO2
instance.
This field is only shown if the remote target
host option is selected.
9.9.5. Using an Oracle Weblogic Execution Environment
WebLogic Server is a J2EE-compliant application server, produced by Oracle. It implements the
full range of J2EE technologies, and provides features such as advanced management, clustering,
and web services. It forms the core of the WebLogic platform, and provides a framework for
building scalable, highly available and secure applications.
JOSSO supports SSO-enabling JavaEE applications running under Oracle WebLogic Server 9
and 10. Both web and business layers can be SSO-enabled. For instance, within a 3 or n-
tier setting, once the security context is established on the web tier, JOSSO will seamlessly
propagate it to the potentially distributed business tier. A business tier realized using Enterprise
Java Beans (EJB) - namely Session Beans - will then be able to leverage the security context
by applying the EJB-specific access control rules in both declarative - through Java annotations
- and programmatic form.
Establishing an activation connection between a Resource and a WebLogic Execution
Environment implies that the Resource is a standard JavaEE application hosted by a WebLogic
Server instance.
Launching the activation on a WebLogic Server execution environment triggers the provisioning
of the specific SSO Agent for the target WebLogic Server instance.
Once a successful security context is established, the web application - playing the Service
Provider role - can consume it by relying on the security methods of the standard Servlet APIs.
Service Provider Setup
86
The getUserPrincipal method can be used to return the javax.security.Principal object that
contains the SSO user principal. The outcome of this method can be casted to the JOSSOUser
class for the specific release of the Apache Tomcat Agent, allowing you to access SSO-specific
properties, such as all the asserted claims for the user.
The isUserInRole allows you to assert if the remote user is granted the specified security role.
Through this operation, it’s possible to perform Role-based Access Control based on the supplied
entitlement claims.
Within a business tier realized as Enterprise Java Beans, two approaches can be used for
authorizing the caller: Declarative and Programmatic Authorization. With the declarative approach,
access roles are defined in either the EJB descriptor or directly in the EJB class, using Java
annotations. With the programmatic approach , the EJBContext.isCallerInRole method can be
used to perform finer-grained access control. Both declarative and programmatic authorization
can be used, building on the security context established by JOSSO.
From the Palette, click in the "Execution Environments" drawer, and drag it to the preferred
location within the Diagram Canvas.
Within the setup dialog, enter the Web Server execution environment details :
Field Descriptions
Field Description
Name The unique identifier for the execution
environment.
Description A descriptive text for the execution
environment.
Version The Oracle Weblogic application server
family.
Select "9.2" to define an execution
environment element based on the Oracle
Weblogic 9.2 family.
Select "10" to define an execution
environment element based on the Oracle
Weblogic 10 family.
Target Host The host where the Oracle Weblogic instance
is located.
The available options are "Local" and
"Remote". If the "Local" option is selected, it is
assumed that the execution environment will
Service Provider Setup
87
be found within the same host that is running
JOSSO2. Alternatively, if the "Remote" option
is selected, it is assumed that the execution
environment will be located within a different
host than the one that’s running JOSSO2.
Install Home The folder which hosts the artifacts of the
Oracle Weblogic execution environment. The
value for this field should correspond to that
of the WL_HOME environment variable.
Remote JOSSO2 URL The endpoint of the activation web service for
a remote JOSSO2 instance. In order for the
remote activation to be successful, the target
execution environments need to be located
within the same host as the remote JOSSO2
instance.
This field is only shown if the remote target
host option is selected.
Overwrite Original Setup Check, if the execution environment has been
previously activated, either from the JOSSO1
command line console or through the Atricore
Console, and you wish to have the original
settings replaced with new ones.
Install Demo Applications Check, if you wish to deploy JOSSO example
web applications onto the target execution
environment. It is strongly recommended that
you check this field, in order to verify that
the Internet SSO setting works as expected,
before engaging in SSO-enabling candidate
business applications.
9.9.6. Using a Websphere Community Edition (WASCE)
Execution Environment
The Websphere Community Edition - also known as WASCE - is an open source application
server developed by the Apache Software Foundation and distributed under the Apache license.
It is the free edition of IBM WebSphere application server and is based on Geronimo.
JOSSO supports SSO-enabling JavaEE applications running under WASCE 2.1 . Both web and
business layers can be SSO-enabled. For instance, within a 3 or n-tier setting, once the security
context is established on the web tier, JOSSO will seamlessly propagate it to the potentially
distributed business tier. A business tier realized using Enterprise Java Beans (EJB) - namely
Session Beans - will then be able to leverage the security context by applying the EJB-specific
access control rules in both declarative - through Java annotations - and programmatic form.
Service Provider Setup
88
Establishing an activation connection between a Resource and a Websphere Community Edition
Execution Environment implies that the Resource is a standard JavaEE application, hosted by a
Websphere Community Edition Server instance.
Launching the activation on an Websphere Community Edition execution environment triggers
the provisioning of the specific SSO Agent for the target instance.
Once a successful security context is established, the web application - playing the Service
Provider role - can consume it by relying on the security methods of the standard Servlet APIs.
The getUserPrincipal method can be used to return a javax.security.Principal object, that contains
the SSO user principal. The outcome of this method can be casted to the JOSSOUser class for
the specific release of the Apache Tomcat Agent, allowing you to access SSO-specific properties,
such as all the asserted claims for the user.
The isUserInRole allows you to assert if the remote user is granted a specified security role.
Through this operation, it’s possible to perform Role-based Access Control based on the supplied
entitlement claims.
Within a business tier realized as Enterprise Java Beans, two approaches can be used for
authorizing the caller : Declarative and Programmatic Authorization. In the declarative approach,
access roles are defined in either the EJB descriptor or directly in the EJB class using Java
annotations. In the programmatic approach, the EJBContext.isCallerInRole method can be used
to perform finer-grained access control. Both declarative and programmatic authorization can be
used, building on the security context established by JOSSO.
From the Palette, click in the "Execution Environments" drawer, and drag it to the preferred
location within the Diagram Canvas.
Within the setup dialog, enter the Web Sphere execution environment details :
Field Descriptions
Field Description
Name The unique identifier for the execution
environment.
Description A descriptive text for the execution
environment.
Target Host The host where the Websphere Community
Edition server instance is located.
The available options are "Local" and
"Remote". If the "Local" option is selected, it is
assumed that the execution environment will
Service Provider Setup
89
be found within the same host that is running
JOSSO2. Alternatively, if the "Remote" option
is selected, it is assumed that the execution
environment will be located within a different
host than the one that’s running JOSSO2.
Install Home The folder hosting the artifacts of the
Websphere Community Edition execution
environment. The value for this field should
correspond to that of the WASCE_HOME
environment variable.
Remote JOSSO2 URL The endpoint of the activation web service for
a remote JOSSO2 instance. In order for the
remote activation to be successful, the target
execution environments need to be located
within the same host as the remote JOSSO2
instance.
This field is only shown if the remote target
host option is selected.
Overwrite Original Setup Check, if the execution environment has been
previously activated, either from the JOSSO1
command line console or through the Atricore
Console, and you wish to have the original
settings replaced with new ones.
Install Demo Applications Check, to deploy JOSSO example web
applications onto the target execution
environment. It is strongly recommended
to check this field, in order to verify that the
Internet SSO setting works as expected,
before engaging in SSO-enabling candidate
business applications.
9.9.7. Using a Windows IIS Execution Environment
Internet Information Services (IIS) – formerly called Internet Information Server – is a web server
application and set of feature extension modules, created by Microsoft, for use with Microsoft
Windows.
In order to build the Resource on a Windows IIS execution environment, you must define a
Windows IIS Execution Environment element, and associate it with the Resource.
From the Palette, click in the "Execution Environments" drawer, and drag it to the preferred
location within the Diagram Canvas.
Within the setup dialog, enter the Windows IIS execution environment details :
Service Provider Setup
90
Field Descriptions
Field Description
Name The unique identifier for the execution
environment.
Description A descriptive text for the execution
environment.
Target Host The host where the Windows IIS server
instance is located.
The available options are "Local" and
"Remote". If the "Local" option is selected, it is
assumed that the execution environment will
be found within the same host that is running
JOSSO2. Alternatively, if the "Remote" option
is selected, it is assumed that the execution
environment will be located within a different
host than the one that’s running JOSSO2.
Install Home The folder hosting the Windows IIS
installation.
Remote JOSSO 2 URL The endpoint of the activation web service for
a remote JOSSO2 instance. In order for the
remote activation to be successful, the target
execution environments need to be located
within the same host as the remote JOSSO2
instance.
This field is only shown if the remote target
host option is selected.
Overwrite Original Setup Check, in case the execution environment
has been previously activated, either from the
JOSSO1 command line console or through
the Atricore Console, and you wish to have
the original settings replaced with new ones.
Install Demo Applications Check to deploy JOSSO example web
applications onto the target execution
environment. It is strongly recommended
to check this field, in order to verify that the
Internet SSO setting works as expected,
before engaging in SSO-enabling candiate
business applications.
Service Provider Setup
91
9.9.8. Using an Apache Tomcat Execution Environment
Apache Tomcat (or Jakarta Tomcat or simply Tomcat) is an open source servlet container
developed by the Apache Software Foundation (ASF). Tomcat implements the Java Servlet and
the JavaServer Pages (JSP) specifications from Sun Microsystems, and provides a "pure Java"
HTTP web server environment for Java code to run.
JOSSO supports SSO-enabling JavaEE web applications running under Apache Tomcat 5.0, 5.5,
6, 7 and 8.
Establishing an activation connection between a Resource and a Tomcat execution environment
implies that the Resource is a standard Java Web Application, hosted by an Apache Tomcat
container.
Launching the activation on an Apache Tomcat Execution Environment triggers the provisioning
of the SSO Agent for this web container.
Once a successful security context is established, the web application - playing the Service
Provider role - can consume it by relying on the security methods of the standard Servlet APIs.
The getUserPrincipal method can be used to return a javax.security.Principal object that contains
the SSO user principal. The outcome of this method can be casted to the JOSSO User class
pertaining to the specific release of the Apache Tomcat Agent, allowing you to access SSO-
specific properties, such as all the asserted claims for the user.
The isUserInRole allows you to assert if the remote user is granted the specified security role.
Through this operation it’s possible to perform Role-based Access Control based on the supplied
entitlement claims.
From the Palette, click in the "Execution Environments" drawer, and drag it to the preferred
location within the Diagram Canvas.
Within the setup dialog, enter the Apache Tomcat execution environment details :
Field Descriptions
Field Description
Name The unique identifier for the execution
environment.
Description A descriptive text for the execution
environment.
Version The Apache Tomcat web container family.
Select "5.0.x" to define an execution
environment element based on the Apache
Tomcat 5 family.
Service Provider Setup
92
Select "5.5.x" to define an execution
environment element based on the Apache
Tomcat 5.5 family.
Select "6.0.x" to define an execution
environment element based on the Apache
Tomcat 6 family.
Select "7.0.x" to define an execution
environment element based on the Apache
Tomcat 7 family.
Select "8.0.x" to define an execution
environment element based on the Apache
Tomcat 8 family.
Target Host The host where the Apache Tomcat web
container instance is located.
The available options are "Local" and
"Remote". If the "Local" option is selected, it is
assumed that the execution environment will
be found within the same host that is running
JOSSO2. Alternatively, if the "Remote" option
is selected, it is assumed that the execution
environment will be located within a different
host than the one that’s running JOSSO2.
Install Home The folder hosting the artifacts of the Apache
Tomcat execution environment. The value
for this field should correspond to that of the
CATALINA_HOME environment variable.
Remote JOSSO2 URL The endpoint of the activation web service for
a remote JOSSO2 instance. In order for the
remote activation to be successful, the target
execution environments need to be located
within the same host as the remote JOSSO2
instance.
This field is only shown if the remote target
host option is selected.
Overwrite Original Setup Check in case the execution environment has
been previously activated, either from the
JOSSO1 command line console or through
the Atricore Console, and you wish to have
the original settings replaced with new ones.
Service Provider Setup
93
Install Demo Applications Check, to deploy JOSSO example web
applications onto the target execution
environment. It is strongly recommended
to check this field, in order to verify that the
Internet SSO setting works as expected,
before engaging in SSO-enabling candidate
business applications.
9.9.9. Using a JBoss Execution Environment
JBoss is a Java EE certified platform for developing and deploying enterprise Java applications,
Web applications, and Portals. JBoss Application Server provides the full range of Java EE 5
features, as well as extended enterprise services including clustering, caching, and persistence.
The Web Server component of the JBoss Application Server is the JBoss Web Server. The JBoss
Web Server is an enterprise-ready web server designed for medium and large applications, based
on Apache Tomcat, providing a single deployment platform for Java Server Pages (JSP) and Java
Servlet technologies, PHP, and CGI.
JOSSO supports SSO-enabling JavaEE applications running under JBoss 3.2, 4.0, 4.2, 5, 6 and
7. Both web and business layers can be SSO-enabled. For instance, within a 3 or n-tier setting,
once the security context is established on the web tier, JOSSO will seamlessly propagate it to the
potentially distributed business tier. A business tier realized using Enterprise Java Beans (EJB)
- namely Session Beans - will then be able to leverage the security context by applying the EJB-
specific access control rules in both declarative - through Java annotations - and programmatic
form.
Establishing an activation connection between a Resource and a JBoss Execution Environment
implies that the Resource is a standard JavaEE application hosted by a JBoss Application Server.
Launching the activation on an Apache Tomcat Execution Environment triggers the provisioning
of the specific SSO Agent for the target JBoss Application Server instance.
Once a successful security context is established, the web application - playing the Service
Provider role - can consume it by relying on the security methods of the standard Servlet APIs.
The getUserPrincipal method can be used to return the javax.security.Principal object that
contains the SSO user principal. The outcome of this method can be casted to the JOSSOUser
class for the specific release of the Apache Tomcat Agent, allowing you to access SSO-specific
properties, such as all the asserted claims for the user.
The isUserInRole allows you to assert if the remote user is granted the specified security role.
Therefore, through this operation it’s possible to perform Role-based Access Control based on
the supplied entitlement claims.
Within a business tier realized as Enteprise Java Beans, two approaches can be used for
authorizing the caller: Declarative and Programmatic Authorization. In the declarative approach
Service Provider Setup
94
access roles are defined in either the EJB descriptor or directly in the EJB class using Java
annotations. In the programmatic approach , the EJBContext.isCallerInRole method can be used
to perform finer-grained access control. Both declarative and programmatic authorization can be
used, building on the security context established by JOSSO.
From the Palette, click in the "Execution Environments" drawer, and drag it to the preferred
location within the Diagram Canvas.
Within the setup dialog, enter the JBoss execution environment details :
Field Descriptions
Field Description
Name The unique identifier for the execution
environment.
Description A descriptive text for the execution
environment.
Version The Redhat JBoss application server family.
Select "3.2.6" to define an execution
environment element based on the Redhat
JBoss 3.2.6 family.
Select "4.0.x" to define an execution
environment element based on the Redhat
JBoss 4.0 family.
Select "4.2.x" to define an execution
environment element based on the Redhat
JBoss 4.2 family.
Select "5.x" to define an execution
environment element based on the Redhat
JBoss 5 family.
Select "6.x" to define an execution
environment element based on the Redhat
JBoss 6 family.
Select "7.x" to define an execution
environment element based on the Redhat
JBoss 7 family.
Target Host The host where the Redhat JBoss application
server instance is located.
Service Provider Setup
95
The available options are "Local" and
"Remote". If the "Local" option is selected, it is
assumed that the execution environment will
be found within the same host that is running
JOSSO2. Alternatively, if the "Remote" option
is selected, it is assumed that the execution
environment will be located within a different
host than the one that’s running JOSSO2.
Install Home The folder hosting the artifacts of the Redhat
JBoss application server instance. The value
for this field should correspond to that of the
JBOSS_HOME environment variable.
Remote JOSSO 2 URL The endpoint of the activation web service for
a remote JOSSO2 instance. In order for the
remote activation to be successful, the target
execution environments need to be located
within the same host as the remote JOSSO2
instance.
This field is only shown if the remote target
host option is selected.
Overwrite Original Setup Check in case the execution environment has
been previously activated, either from the
JOSSO1 command line console or through
the Atricore Console, and you wish to have
the original settings replaced with new ones.
Install Demo Applications Check, to deploy JOSSO example web
applications onto the target execution
environment. It is strongly recommended that
you check this field, in order to verify that
the Internet SSO setting works as expected,
before engaging in SSO-enabling candidate
business applications.
96
Chapter 10. Circle of Trust
EstablishmentA Circle of Trust is a group of Service Providers that share linked identities and have pertinent
business agreements in place regarding how to do business and interact with identities.
The first and most obvious way in which trust is established is through existing relationships
with partners, vendors and customers. If your organization already has agreements in place with
another organization and you have a history of working together, they’re already part of your circle.
Having put together the building blocks of an Identity Appliance defining at least one Identity
Provider (IdP) and a set of Service Providers, the next step is to enable a seamless SSO
experience for users to leverage when consuming the business services provided by the Service
Provider (SP).
This is accomplished by creating a relationship of trust between IdPs and SPs, who agree to honor
one another’s authentication and authorization information.
10.1. Connecting Identity Providers with Service
Providers
To connect IdP and SP elements in order to create a relationship of trust, use the "Federated
Connection" edge available in the "Connections" palette drawer.
Click on the "Federation Connection" element. Select the SP and drag the edge onto the target
IdP.
The following dialog will appear for defining the characteristics of the federation connection
between the chosen entities.
On the Contract screen, specify the SAML Profiles and Bindings to be enabled, as well as the
level of security of the artifacts involved in message exchanges between SPs and the IdP.
Field Descriptions
Field Description
Name The unique identifier of the Federated SSO
connection.
Description A descriptive text for the Federated SSO
connection.
Circle of Trust Establishment
97
In the "Identity Provider Channel" section, define the SP’s contract, specific to the IdP end of the
Federated SSO connection. IdP Channel properties specified within this section will override the
default contract established by the SP toward trusted IdPs.
Field Descriptions
Field Description
Use Inherited Service Provider Settings Select this checkbox if you wish to override
the default contract established by the SP
toward the IdP.
Enabled SAML Profiles The SAML Profile to activate in the SP for
the IdPs. These mainly represent usage
scenarios which arerealized by the SP for
this specific IdP. The most important SAML
profile is the "Web Browser Single Sign-On
Profile", which can be enabled by selecting
the SSO checkbox. Select the SLO checkbox
to enable Single Logout Support.
Enabled SAML Bindings Enable SAML bindings for selected SAML
profiles. This action specifies the mapping
of a SAML protocol message onto standard
messaging formats and/or communications
protocols. Select the Http Post checkbox
to convey SAML messages through HTTP
Post. Select the Http Redirect checkbox
to convey SAML messages through HTTP
Get. Select the Artifact checkbox to convey
SAML messages through the SAML Artifact
Binding, which builds on both HTTP Redirect
and SOAP bindings to exchange SAML
messages. Select the SOAP checkbox to
convey SAML messages through SOAP over
HTTP(s).
Sign Authentication Requests Select this checkbox to authenticate - by
digitally signing SAML authentication request
messages - submitted to the IdP by the SP.
Want Assertions Signed Select this checkbox to request that the
IdP authenticate assertions conveyed in
responses pushed by the IdP to the SP.
Account Linkage Policy The means by which an IdP user account
is mapped with one on the SP end; it
determines which of the input claims is the
name identifier to use at the SP end.
Circle of Trust Establishment
98
Select "One To One" to link IdP and SP
accounts using the supplied name identifier.
Select "Email" to link IdP and SP accounts
using the supplied email.
Select "UID" to link IdP and SP accounts
using the username identifier.
Identity Mapping Policy The means by which input claims conveyed
in the security token, which are issued and
submitted by the IdP’s end of the Federated
SSO connection, are mapped to output
claims; which will in turn be consumed by the
relevant party in order to authorize users and
grant appropriate access.
Select "Use Theirs" to link IdP and SP
accounts using the supplied name identifier,
and mapping input to output claims in a one-
to-one fashion.
Select "Use Ours" to link IdP and SP
accounts using the supplied name identifier,
and to issue output claims based only on
the user details that are available within the
identity source that is connected to the SP.
Select "Aggregate" to link IdP and SP
accounts using the supplied name identifier,
and to issue output claims based on merging
both the user details conveyed in the security
token and those obtained from the identity
source connected to the SP.
Preferred IdP Channel Select this checkbox to select the IdP of
this connection as the SP’s default authority
for identification of a user when a protected
resource is requested. More specifically, this
is the IdP to which the user will be redirected
in an SP-initiated usage scenario.
In the "Service Provider Channel" section, define the IdP’s contract specific to the SP end of
the Federated SSO connection. Service Provider Channel properties specified within this section
override the default contract established by the IdP toward trusted SPs.
Circle of Trust Establishment
99
Field Descriptions
Field Description
Use Inherited Identity Provider Settings Select this checkbox if you wish to override
the default contract, established by the IdP
end, toward trusted SPs.
Enabled SAML Profiles The SAML Profile to activate in the IdP, for
SPs. These profiles mainly represent usage
scenarios which have been realized by the
IdP for a specific SP. The most important
SAML profile is the "Web Browser Single
Sign-On Profile", which can be enabled by
selecting the SSO checkbox. Select the SLO
checkbox to enable Single Logout Support.
Enabled SAML Bindings The SAML bindings to be enabled for your
chosen SAML profiles. This specifies the
mapping of a SAML protocol message
onto standard messaging formats and/or
communications protocols. Select the Http
Post checkbox to convey SAML messages
through HTTP Post. Select the Http Redirect
checkbox to convey SAML messages through
HTTP Get. Select the Artifact checkbox to
convey SAML messages through the SAML
Artifact Binding, which builds on both HTTP
Redirect and SOAP bindings for exchanging
SAML messages. Select the SOAP checkbox
to convey SAML messages through SOAP
over HTTP(s).
Want Authentication Requests Signed Determines whether SAML Authentication
Requests submitted by the SP end will need
to be authenticated using digital signature.
Digitally signing SAML Authentication
Requests provides proof-of-identity of the SP
to the Identity Provider, as well as ensuring
their integrity.
Authentication Contract The authentication contract is a fundamental
set of assumptions made by application-level
code about the security context of any given
request.
Authentication Mechanism The means for authenticating a user.
Authentication Mechanism Select "Two-Factor Authentication" checkbox
if you wish to use strong authentication,
Circle of Trust Establishment
100
instead of simple authentication, for
identifying users accessing from the SP end.
Authentication Assertion Emission Policy This enables you to customize how, upon
successful authentication, assertions are
emitted for the SP’s connection end. The
emitted authentication assertions are
conveyed in security tokens pushed to relying
parties.
101
Chapter 11. Identity Appliance
Lifecycle ManagementThe Identity Architect also controls the transformation of the identity architecture model into a fully
executing artifact. As in the identity appliance modeler, this process is carried out in a point-and-
click fashion.
The Identity Appliance Lifecycle Management screen offers a grid-based layout, within which
tables represent the different states the identity appliance artifact can be in. Transitioning the
identity appliance from one state to another state is achieved by dragging the identity appliance
item from one table of the grid - representing the source state - and dropping it onto the table
representing the target state.
11.1. Build an Identity Appliance
Enabling an Identity Appliance Model to deliver the specified identity and access management
services requires that you transform it to an executable artifact. Simply put, the executable artifact
onto which an identity appliance is mapped is a set of JOSSO2 descriptors that are packaged
as an OSGi bundle. JOSSO2 descriptors contribute identity and access management service
definitions - such as SAML endpoints - to the underlying core.
In order to build an identity appliance, select the corresponding row for the target identity appliance
within the "Saved" table of the lifecycle management grid.
The "Saved" table holds entries for the identity appliances that are candidates for compilation, and
which will ultimately be deployed and executed. Within this state, identity appliances can be edited
and removed. To continue with the design process, click on the button to open the identity
appliance within the modeler view. To delete an identity appliance, click on the button.
To build an identity appliance, select and drag the row for the target identity appliance item from
the "Saved" table and drop it onto the "Staged" table of the grid. If the operation is successful, the
target identity appliance will appear in the "Deployed" table of the lifecycle management grid.
11.2. Deploy an Identity Appliance
Once an identity appliance has been transformed to an executable artifact it is still not available
for execution, since the underlying execution environment is not aware of its existence. In order to
execute an identity appliance you must first deploy it by installing the corresponding artifact onto
the JOSSO2 execution environment.
The identity appliances candidates for deployment are shown in the "Staged" table of the lifecycle
management grid.
Identity Appliance
Lifecycle Management
102
The "Staged" table holds entries for the identity appliances that have been successfully compiled.
Within this state, identity appliances can be viewed and rebuilt. To continue the design process,
click on the button to open the identity appliance within the modeler view. Then, click on the
button to rebuild the identity appliance (required in order to achieve visibility of the latest changes
made in the editing session).
To deploy an identity appliance, select and drag the row for the target identity appliance item
from the "Staged" table and drop it onto the "Deployed" table. The target identity appliance should
appear in the "Deployed" table of the lifecycle management grid.
11.3. Managing Identity Appliance Execution
Once an identity appliance has been deployed - meaning that it is now hosted within the JOSSO2
execution environment - it is available for execution.
The "Deployed" table holds the entries for identity appliances which have been deployed and are
candidates for execution. Within the deployed state, identity appliances can be either running or
stopped. The "State" column shows the identity appliance’s current state. Possible states include:
"Deployed", "Started" or "Stopped". The deployed state, identified as "DEPLOYED" in the State
column, represents identity appliances which have been deployed, but have not been started.
The started state ("STARTED" in the State column) represents identity appliances which have
been deployed and started. These identity appliance definitions are being realized through identity
and access management services which are available to consumers. Finally, the stopped state
("STOPPED" in the State column) represents identity appliances that are no longer executing.
Services corresponding to these identity appliance definitions are no longer up and running. Within
the "Actions" columns three actions can be applied to the identity appliance: "Start","Stop" and
"Undeploy".
11.3.1. Start an Identity Appliance
Within the "Deployed" table of the lifecycle management grid, click on the button in the Actions
column. This starts the identity appliance, transitioning it to the "Started" state. The target identity
appliance should display as "started" in the State column.
11.3.2. Stop an Identity Appliance
Within the "Deployed" table of the lifecycle management grid, click on the button to stop an
identity appliance. It will be transitioned to the "Stopped" state. The target identity appliance should
display as "stopped" in the State column.
11.4. Undeploy an Identity Appliance
Identity Appliance undeployment can be carried out from the "Deployed" table of the lifecycle
management grid. Click on the button to undeploy an identity appliance, which will transition
it to the staged state. The target Identity Appliance will be undeployed and transitioned to the
"Staged" state, and should appear in the "Staged" table of the lifecycle management grid.
Identity Appliance
Lifecycle Management
103
11.5. Dispose an Identity Appliance
Identity Appliance disposal can be carried out from the "Staged" table of the lifecycle management
grid. This can be accomplished in two distinct ways: 1) Click on the button to dispose of an
identity appliance, transitioning it to the "Disposed" state. 2) Select and drag the row for the target
identity appliance item from the "Staged" table and drop it onto the "Disposed" table. The target
identity appliance will be disposed and transitioned to the "Disposed" state, and should appear in
the "Disposed" table of the lifecycle management grid.
11.6. Remove an Identity Appliance
An identity appliance that is no longer in use may be discarded and completely erased from the
system. Once an identity appliance is removed, it cannot be recovered.
Disposal can be realized for appliances in either the "Saved" and "Disposed" states. The
"Disposed" table holds the entries for the identity appliances that have been discarded, and are
no longer available to be edited or executed. Identity Appliances within this states are candidates
for definitive removal.
In order to dispose of an identity appliance in the "Disposed" table, select the row for the identity
appliance and click on the button within the state column. The disposed-of identity appliance
should no longer show up within the state-specific tables of the lifecycle management grid.
In order to dispose of an identity appliance in the "Saved" table, select the row for the identity
appliance and click on the button within the state column. The disposed-of identity appliance
should no longer show up within the state-specific tables of the lifecycle management grid.
104
Chapter 12. Execution Environment
ActivationAs explained in Section 3.2.6.3, “Activation”, the activation feature allows you to provision Single
Sign-On (SSO) support onto the execution environment (such as an application server or web
container) where the application is hosted.
The activation procedure involves the installation of JOSSO-specific artifacts, such as the
corresponding JOSSO agent and configuration descriptors; as well as the wiring that makes
it possible for the execution environment to interoperate with JOSSO2 in a seamless and
transparent manner.
Once an execution environment is activated, the applications executing within it will be able to
harness the SSO capabilities that are provided by the target identity appliance.
12.1. Bringing SSO-Readiness to Execution
Environments
In order to specify an activation procedure, there must be at least one Service Provider and
one execution environment element, since specifying an activation relationship involves the
connection of such elements.
To connect SP and execution environment elements and create an activation relationship, use
the "Activation" edge available in the "Connections" palette drawer.
Click on the "Activation" element. Select the SP and drag the edge onto the target execution
environment.
The following dialog will appear for defining the characteristics of the activation connection
between the chosen entities.
On the Create JOSSO Activation screen, specify the endpoints used by the application to service
requests from the target execution environment.
Field Descriptions
Field Description
Name The unique identifier of the Activation
connection.
Description A descriptive text for the Activation
connection.
Execution
Environment Activation
105
Application Identifier The Service Provider-facing unique identifier
of the partner application.
By default, the name of the source SP
element is used.
Location Specify the protocol, host, port and URI to
which your partner application is bound for
servicing requests from end-users.
In order to enable the SSO capabilities in your
application, user requests should refer to the
web application using URLs that match the
values specified in this field.
If your SP is the example JOSSO application,
make sure to specify "partnerapp" in the URI
field.
Once the activation properties have been specified, the actual activation process may be run.
Select the SP element, and within the property sheet section, choose the "Activation" tab and
mark the "Reactivate" check.
If activating an execution environment which was previously activated within the context of a
different SP or identity appliance, mark the "Overwrite Original Setup" check.
To run the pre-integrated example applications included in the JOSSO distribution, mark the
"Install Demo Applications" check.
Once the activation connection setup is complete, roll out from the property sheet in order for the
activation procedure to take place.
Note
In order for the activation to be completed successfully, the identity appliance
encompassing these definitions needs to be built and started. For more information
on this, please refer to Section 11.1, “Build an Identity Appliance”
106
Chapter 13. Account and
Entitlement ManagementGenerally speaking, when you add users and groups using the administration console, you’re
adding that data to the database on top of which the identity vault is founded. By default, even
if you use an external identity source such as an LDAP (Lightweight Directory Access Protocol)
directory, the users you add through the console will be added to JOSSO’s identity vault and not
to the external identity source.
A user account represents a person using the application’s members of a circle of trust. Each
user account has associated attributes which make up the person’s profile. The console can be
used to change any user’s name and password, and to view and/or edit their profile information.
It’s also possible to disable a user (if, for example, that user is no longer involved) but it’s best
to preserve their profile information.
A group collects user accounts, typically in order to make it easier to grant all of the collected
users certain entitlements. For example, you might create a group of human resources workers
so that you can give them (and only them) permission to view potentially sensitive information
about employees in a "Benefits" space. As an Administrator, you can add users and groups, and
assign users to groups in order to determine their permissions.
13.1. Identity Vault Selection
Clicking on the "Identity Vault" button displays the enabled Identity Vault instances.
An Identity Vault, is an isolated user repository environment running within JOSSO2. An Identity
Vault instance can contain multiple objects - such as user and entitlements - and can be accessed
by providers.
By default there is one Identity Vault only, whereas any number of Identity Vaults may be enabled.
13.2. User Accounts
To reach the Account Management screen, go to the Main screen and click on Account and
Entitlement Management and click the button.
13.2.1. General User Information
User profile information is entered on the General User Information screen.
Field Descriptions
Account and Entitlement
Management
107
Field Description
Username The unique identifier for the person used for
authentication. An example of a username is
"jdoe".
First Name A given name is that part of a person’s name
which signifies the person’s primary individual
identity. Sometimes also called a "given
name" or (in some countries) a "Christian
name". An example of a first name is "John".
Last Name A last name is that part of a person’s name
which signifies the person’s primary family
association. Sometimes also called a "family
name" or "surname". An example of a last
name is "Doe".
Full Name A full name name is a version of a person’s
name intended for display in a user interface.
Sometimes also called a "display name" or a
"formatted name". An example of a full name
is "John Doe".
E-mail Address An e-mail address is the value of a mailto:
the URL at which a person or other entity can
be contacted using standard electronic mail
protocols. An example of an e-Mail address is
"[email protected] [mailto:[email protected]]".
Telephone number A landline telephone number is a number for
a traditional "PSTN" or "POTS" telephone.
An example of a telephone number is
212-302-4434.
Fax number A fax number is a number for a machine that
handles facsimile transmissions. An example
of a fax number is 212-302-4450.
13.2.2. User Language Preferences
A user’s language preference is entered on the Preferences screen. This should be set to the
default language that will be used in the application screens.
Field Description
Language Everyone knows at least one language well
(they are able to speak or write the language
with a fair degree of fluency). Determination
Account and Entitlement
Management
108
of whether someone knows a language "well"
or "fluently" is left to the user. The value
of this field MUST be an abbreviation for
a language as specified in RFC 4646. An
example of "Language" is "en".
13.2.3. User Groups
A user is assigned to one or more groups on the Groups screen. A user’s entitlements are
determined by their Group association.
To associate a user to one of the available groups, drag the group entry from the "Available
Groups" column, and drop it into the "Member Of" column. If the association is successful, the
target group will appear in the "Member Of" column.
To disassociate a user from a group, drag the group entry from the "Member Of" column and
drop it into the "Available Groups" column. If the disassociation is successful, the target group will
appear in the "Available Groups".
13.2.4. User Account Security
On the Security screen, preferences concerning securing the account may be specified in order
to reduce the chances of unauthorized access.
Field Description
Disabled Determines whether the user account is
active. Select this checkbox to disable
the account. This will block the user from
authenticating against Identity Providers
bound to an identity vault instance.
Account Expires Determines whether the user account will
expire. Select this checkbox to restrict the
life span of the user account. The specific
life span of the account is determined by the
"Account expires date" field below.
Account Expiration Date Determines the date upon which the account
will expire. Enter a date in the …. format.
Maximum Logins Maximum logins allowed from this user
account.
Terminate Previous Session Determines whether, when the user
establishes a new session, the previous
Account and Entitlement
Management
109
session has to be terminated. Select this
checkbox to terminate the previous session
when a new session using this account is
established.
Prevent New Sessions Determines whether the user is entitled
to establish a session against an Identity
Provider bound to an identity vault instance.
13.2.5. Account Password
On the Password screen a user’s credentials - namely a password - are provided in order to
identify the person owning the account. In addition, preferences that will maintain the security of
user credentials by enforcing password freshness and strength may be defined here.
Field Description
Allow user to change password Determines whether the user will be able to
update the password. Select this checkbox to
allow the user to change their password.
Force periodic password change Determines whether the user is informed that
the password will expire. Select this heckbox
to inform the user that their password will
expire.
Days between changes If the "Force periodic password change"
option is selected, this field sets the maximum
number of days before the user is required to
change their password.
Password expiration date The date the password for the user account
will expire.
Notify password expiration Select this checkbox to enable e-mail
notifications to the user regarding the
approach of the password expiration date.
Days before expiration Sets the desired number of days in advance
of password expiration for the system to notify
the user.
Password The password for the user account.
Retype password Verification of the password for the user
account.
Automatically generate password Select this checkbox to automatically
generate a strong password.
Account and Entitlement
Management
110
E-mail new password Select this checkbox to have a new password
e-mail sent to the e-mail address for this
account.
13.2.6. Provision a User Account
To provision a user account, click on the button. Fill in the desired information and click "Save".
Username, First Name, Last Name and Password are required.
13.2.7. Update User Details
To edit an existing user account, select the corresponding user entry in the user list and click the
button. Modify the fields as needed and click Save.
13.2.8. Search Users
To search for a user entry, click on the button. A search can be conducted based on Username,
First Name, Last Name and Full name criteria. Complete the field with the chosen search criteria
and click "Search". If the search is successful, entries for users matching the search criteria will
be listed in the user accounts table.
13.2.9. Deprovision a User Account
To deprovision a user, select the target user entry in the user list and click the button.
13.3. Groups
To reach the Group Management screen, go to Account and Entitlement Management on the
Main screen and click the button.
13.3.1. Provision a Group
To provision a group, click on the button. Fill in the information needed and click "Save". The
group name is required.
13.3.2. Search Groups
To search for a group, click on the button. A search can be conducted based on the group name
and description. Fill in the field corresponding to the chosen search criteria and click "Search". If
successful, the entries for groups matching the search criteria will be listed in the groups table.
Account and Entitlement
Management
111
13.3.3. Update a Group
To edit an existing group, select the corresponding group entry in the group table and click the
button. Modify the fields as needed and click "Save".
13.3.4. Deprovision a Group
To deprovision a group, select the target group entry in the groups table and click the button.
112
Chapter 14. Profile OperationsProfile operations enable the Administrator to update an account’s credentials, as well as to
manage the console session.
To display the profile operations, click the "Administrator" button in the uppermost right corner.
113
Chapter 15. System Settings
15.1. Platform Settings
15.1.1. Controlling Web Settings
On this screen you can customize the embedded web server behaviour. The web server
component acts as the entry point for consumers, being responsible for servicing requests from
both users - typically using a web browser - and client applications.
Field Descriptions
Field Description
Server Id A unique identifier for this server instance.
This is mainly used to establish the identity
of the server within a cluster of nodes on
top of which to deliver high-availability and
scalability capabilities.
Port The port number the JOSSO2 web server will
bind to. By default, JOSSO2 will bind to port
8081.
Bind addresses The hostnames the JOSSO2 web server will
bind to. If no host name is specified, then
JOSSO2 will bind to all available interfaces.
Session Timeout Determines the maximum idle time in
interaction between user and JOSSO2. It’s
set by default to 120 milliseconds.
Max header buffer size The size in bytes of the memory buffer to hold
the HTTP header for processing. When a
request exceeds the specified HTTP header
size limit, JOSSO2 aborts the connection. By
default is set to 6144 bytes.
Disable Session URL By checking this option, URL-based session
tracking is disabled. URL-based session
tracking is intended for web clients that do
not support session cookies. Every browser
worth mentioning supports these cookies, and
almost nobody surfs with them disabled. Most
web sites either state explicitly or assume that
a user’s browser supports session cookies.
System Settings
114
Enable SSL Ensures confidentiality and data integrity by
running sensitive network traffic on HTTPS.
SSL Port The port number the JOSSO2 HTTPS service
will bind to.
Keystore path The absolute path of the server certificate
keystore.
Keystore password The password for opening the server
certificate keystore.
Key password The password for the server certificate.
Optimize Redirects Indicates whether to boost JOSSO2 web
server performance by significantly reducing
the number of hops the browser needs to go
through for servicing a web single sign-on
request.
Redirects Include/Exclude URLs Specifies which URL patterns are handled
and those who are not. These is only used if
redirect optimization is turned on.
15.1.2. Controlling SSH Settings
JOSSO2 is bundled with a remote console feature which allows to connect to a running instance
from a remote computer and perform all the operations that are usually accessible from the local
console.
Field Descriptions
Field Description
Port The port number the JOSSO2 HTTPS service
will bind to. By default, JOSSO2 will bind to
port 8101.
Bind Address The hostname the JOSSO2 SSH server will
bind to. If no host name is specified, then
JOSSO2 will bind to all available interfaces.
15.1.3. Controlling Persistence Settings
By default JOSSO2 relies on an embedded relational database management system as the
persistence mechanism for storing user details as well as application state information. In this
screen you will be able to configure the JOSSO2 database service as well as configure the system
for relying on an external database of your choice.
System Settings
115
Field Descriptions
Field Description
Port The port number the JOSSO2 database
service will bind to. By default, JOSSO2 will
bind to port 1527.
Username The username that should be used when
creating connections to the JOSSO2
database service.
Password The password that should be used when
creating connections to the JOSSO2
database service.
Confirm Password The password entered in the above field.
Use External DB Determines whether an external database
instance is used instead of the JOSSO2
embedded database service.
Driver The name of the JDBC driver class.
Connection URL The mean of connecting JOSSO2 to the
external database.
Username The username that should be used when
creating connections to the external database
service.
Password The password that should be used when
creating connections to the external database
service.
Confirm Password The password entered in the above field.
15.1.4. Controlling Monitoring and Management Settings
JOSSO2 provides a large set of MBeans that allow you to fully monitor and administrate JOSSO2
using any JMX client (like jconsole for instance). You can find more or less the same actions that
you can do using the shell commands on the JMX layer.
Field Descriptions
Field Description
RMI Registry Port The port number the JOSSO2 RMI Registry
service will bind to. By default, JOSSO2 will
bind to port 1099.
System Settings
116
RMI Server Port The port number the JOSSO2 RMI Server will
bind to. By default, JOSSO2 will bind to port
44444.
Service URL The service URL the JOSSO2 JMX Service
will bind to.
15.1.5. Controlling Message Bus Settings
JOSSO2 relies on a shared messaging layer for connecting identity and access management
services. Such layer it built on top an asynchronous messaging backbone. This screen allows you
to fine tune the behaviour of this component.
Field Descriptions
Field Description
Broker name The unique identifier of the message broker.
Broker host The hostname the broker will use. If no host
name is specified, then JOSSO2 will bind to
localhost.
Broker bind address The hostname the broker will bind. If no host
name is specified, then JOSSO2 will bind to
all interfaces.
Broker port The port the broker will use. If no port is
specified, then JOSSO2 will bind to port
number 61217.
15.1.6. Controlling Logging Settings
This screen allows to configure the reporting and auditing preferences.
Field Descriptions
Field Description
Service Mode Select Production if you want to reduce
the logging verbosity. Alternatively, select
Development if you want to increase the
logging verbosity. For instance, this may be
useful for troubleshooting.
System Settings
117
15.1.7. Controlling Branding Settings
JOSSO2 provides a web-based graphical user interface (GUI) for all built-in and custom identity
and access management bundles installed in a deployment. This interface provides a dynamic and
customizable means for presenting the web-based pages to a user consuming JOSSO2 services.
You can customize this user interface per identity appliance.
From this screen you can manage the branding extensions available to be harnessed from identity
appliances for delivering an alternate look and feel to end users.
By default there is only one branding extension identified as josso2-default-branding. This
represents the built-in look & feel that comes out-of-the-box with JOSSO2.
15.1.7.1. Create a Branding Extension
To create a branding extension, click on the "New Branding Extension" button. The branding
extension creation screen will show. Fill in the desired information and click "Save" to confirm the
submission.
Field Descriptions
Field Description
Name The unique identifier of the branding
extension.
Description A descriptive text of the branding extension.
Bundle URI Maven-specific artifact coordinates for the
branding extension bundle.
Bundle file The path within the filesystem of branding
extension in the form of an OSGi bundle.
15.1.7.2. Activate Branding Changes
In order for branding extensions to become visible, these need to be activated. In order to do so
click on the "Activate Branding Changes" button. Once this process is successfully completed,
any branding functionality realized by branding extensions will be visible to end-users.
15.2. Live Services
The Automatic Update feature allows for the quick and easy installation of updates in your
JOSSO2 instance, ensuring that the software is up-to-date.
System Settings
118
Whenever a new version of the software is available from the Atricore website, JOSSO2 will
allow downloading the setup file automatically if a direct internet connection is available. The
administrator will then be able to initiate the update installation.
For customers using a JOSSO Community Edition, automatic software updates are not available.
Customers using a Commercial Edition need to have an active maintenance contract so updates
are available.
In order to check and update the software - in case any updates or upgrades are available - click
on the "Check for Updates" button. In case any update or upgrade setup file is found, it will show
up in the grid. In order to install a specific upgrade or update setup file, select the corresponding
row and click the "Install update" button.
JOSSO2 also supports notifying the administrator when updates are available through e-mail. In
order to setup and customize this feature click on the "Notification Schemes" button.
15.3. Licensing
From this screen you can view the licensing details of your JOSSO2 server. Additionally, you can
install a JOSSO Enterprise Edition license.
For viewing the license information of a specific feature, click on the corresponding row in the grid
and click the "View License" button. A windows will popup showing up this.
For updating the license click on the "Update License" button.
119
Chapter 16. High-availability and
Scalability
16.1. About High Availability
Two key high-availability elements in a JOSSO EE implementation are system failover and session
failover. These two features help to ensure that no single point of failure exists in the deployment,
and that JOSSO EE service is always available to end-users.
16.1.1. System Failover
In this chapter, system failure refers to a hardware or process failure at the JOSSO EE server or at
a load balancer. Hardware fails due to a mechanical problem or power outage. Whenever possible,
you should install redundant JOSSO EE servers, and load balancers to serve as backups, or to
fail over to, in the event of a system failure. This helps to ensure that no single point of failure
exists in your deployment. Load balancers distribute the workload among JOSSO EE servers. If
server hardware fails, requests are routed to other server hardware. Without system failover, a
single hardware failure or process failure can cause JOSSO EE downtime.
16.1.2. Session Failover
Session failover ensures that session data remains accessible to JOSSO EE servers. Service
requests are routed to a failover server, the user’s session continues uninterrupted, and no
user data is lost. The JOSSO EE Service maintains authenticated session states and continues
processing new client requests subsequent to the failure. In most cases, without session failover,
after system failure and subsequent service recovery, the user would have to re-authenticate.
Session failover is critical when end-users' transactions involve financial data or other sensitive
information that is difficult to recover when a system failure occurs. With session failover, when a
system failover occurs, the user’s transaction can proceed uninterrupted. Session failover is less
important if end-users are, for example, reading but not writing data.
16.1.3. Exploring a Reference Architecture
The figure below illustrates the building blocks you need for basic system failover and session
failover in a JOSSO EE deployment. Key components in this high availability deployment are: *
Multiple JOSSO Single Sign-On Agents serve as backups when system failure occurs.
• A single load balancer distributes the workload among multiple JOSSO EE Agents. This
increases transaction throughput, and ensures failover when a system failure occurs.
• Multiple JOSSO EE servers with respective embedded state cache act as backups when system
failure occurs. Embedded distributed cache ensures that replicated state is always available
even during system failure.
High-availability and Scalability
120
• Multiple load balancers distribute the workload among multiple JOSSO EE servers. This
increases transaction throughput, and ensures failover when system failure occurs.
• When JOSSO EE is configured for session failover, session and configuration data is replicated
among the servers. When a system failure occurs, the replicated session data is made available
to JOSSO Agent so that the end-user does not loose data and does not have to re-authenticate
after system recovery.
• Multiple Apache Derby Databases are used to store configuration data, such as Identity
Appliances. These are configured for configuration failover. If one Apache Derby Database fails,
the working Apache Derby Database can provide configuration data to the JOSSO EE servers.
In this example, load balancers represent the only access points to JOSSO EE servers. An access
point can be any hardware or software that acts as a load balancer, and is associated with a site,
that is installed in front of JOSSO EE servers. JOSSO Single Sign-On Agents interact with JOSSO
EE servers through these access points.
The following figure illustrates the components required for basic system failover and session
failover deployment.
16.1.4. Enabling Clustering
In order to enable the OSGi bundles on top of which clustering support for JOSSO
EE is built, replace the "featureBoot" property value in the $JOSSO2_HOME/etc/
org.apache.karaf.features.cfg with the following
featuresBoot=atricore-branding,config,ssh,management,spring,spring-dm,josso-
ee-ha
The main difference is that the josso-ee-ha feature is activated instead of the josso-ee one.
Then in the $JOSSO2_HOME/etc/ehcache-ha.xml descriptor add the following :
<cacheManagerPeerProviderFactory
class="net.sf.ehcache.distribution.RMICacheManagerPeerProviderFactory"
properties="hostName=node1.acme.com,peerDiscovery=automatic,
multicastGroupAddress=230.0.0.1,
multicastGroupPort=4446, timeToLive=32"
propertySeparator=","
/>
The "hostName" property value needs to be set with a valid hostname that can be resolved by
all the members of the cluster.
High-availability and Scalability
121
16.1.5. Replicating the Configuration
By enabling clustering support as described in the previous section, you are enabling application
state replication. Whereas, this does not encompass replicating configuration data, such as
identity appliances. Replicating identity appliances is cornerstone, since they represent the
blueprint of the identity services that will be exposed to users.
There are three fundamental approaches you can use to synchronize configuration data : manual,
managed automatic and non-managed automatic.
16.1.5.1. Manual Configuration Replication
Given that the configuration data is realized by identity appliances, you may leverage the Identity
Appliance Export and Import functionality for keeping those in sync.
Special care must be taken to manually update identity appliances replicas when one these is
updated.
16.1.5.2. Managed Automatic Configuration Replication
This approach is built on top of Apache Derby’s failover capabilities. * One master, one slave: A
replicated database resides in two locations and is managed by two different Derby instances.
One of these Derby instances has the master role for this database, and the other has the slave
role. Typically, the master and slave run on different nodes, but this is not a requirement. Together,
the master and its associated slave represent a replication pair.
• Roll-forward shipped log: Replication is based on shipping the Derby transaction log from the
master to the slave, and then rolling forward the operations described in the log to the slave
database.
• Asymmetry: Only the master processes transactions. The slave processes no transactions, not
even read operations.
• Asynchronicity: Transactions are committed on the master without waiting for the slave. The
shipping of the transaction log to the slave is performed regularly, and is completely decoupled
from the transaction execution at the master. This may lead to a few lost transactions if the
master crashes.
• Shared nothing: Apart from the network line, no hardware is assumed to be shared.
• Replication granularity: The granularity for replication is exactly one database. However, one
Derby instance may have different roles for different databases.
In order to enable data failover using Apache Derby replication for a JOSSO EE server refer to
the descriptor located at $JOSSO2_HOME/etc/com.atricore.idbus.console.db.cfg.
For more information on setting Apache Derby database replication see : Replicating databases
[http://db.apache.org/derby/docs/10.4/adminguide/cadminreplication.html]
High-availability and Scalability
122
16.1.5.3. Non-Managed Automatic Configuration Replication
The final solution is to use a highly available database to store configuration data. Therefore, the
high availability features are moved from the JOSSO EE server to the external repository.
In order to connect a JOSSO EE server to an external highly available database, update
the $JOSSO2_HOME/etc/com.atricore.idbus.console.db.cfg descriptor with the details of the
corresponding JDBC driver and connection coordinates.
123
Chapter 17. Security Setup
17.1. Configuring Secure Sockets Layer
17.1.1. What Is Secure Socket Layer Technology?
Secure Socket Layer (SSL) technology allows web browsers and web servers to communicate
over a secure connection. In this secure connection, the data that is being sent is encrypted before
being sent and then is decrypted upon receipt and before processing. Both the browser and the
server encrypt all traffic before sending any data. SSL addresses the following important security
considerations. * Authentication: During your initial attempt to communicate with a web server
over a secure connection, that server will present your web browser with a set of credentials in
the form of a server certificate. The purpose of the certificate is to verify that the site is who and
what it claims to be. In some cases, the server may request a certificate that the client is who and
what it claims to be (which is known as client authentication).
• Confidentiality: When data is being passed between the client and the server on a network, third
parties can view and intercept this data. SSL responses are encrypted so that the data cannot
be deciphered by the third party and the data remains confidential.
• Integrity: When data is being passed between the client and the server on a network, third
parties can view and intercept this data. SSL helps guarantee that the data will not be modified
in transit by that third party.
17.1.2. Security Identity and Access Management Services
There are two types of communication channels on top of which an identity appliance - holding
identity and access management definitions - can expose network services, namely browser-
facing and application-facing communication channels.
Browser-facing communication channels are intended for exchanging messages with end-users
behind a web browser. For instance, an example of this is a user submitting their credentials to
an identity provider, or the initiation of SAML2 based-authentication on the service provider.
In turn, application-facing communication channels are concerned with exchanging messages
with application-based clients, hence realizing Application-to-Application (A2A) flows. JOSSO
Agents represent the de-facto external consumer for services leveraging application-facing
channels. For instance, user details are passed on to JOSSO agents through a SOAP service
invocation to a server-side service servicing requests on an application-facing communication
channel.
The following steps are required to enable SSL support for JOSSO2.
17.1.2.1. Generating a server certificate with keytool
The following command will generate a key pair and certificate directly into a Java keystore:
Security Setup
124
keytool -keystore jetty.keystore -alias jetty -genkey -keyalg RSA
Enter keystore password: secret
What is your first and last name?
[Unknown]: sso.acme.com
What is the name of your organizational unit?
[Unknown]: it
What is the name of your organization?
[Unknown]: acme
What is the name of your City or Locality?
[Unknown]:
What is the name of your State or Province?
[Unknown]:
What is the two-letter country code for this unit?
[Unknown]:
Is CN=sso.acme.com, OU=it, O=acme,
L=Unknown, ST=Unknown, C=Unknown correct?
[no]: yes
Enter key password for <jetty>
(RETURN if same as keystore password): secret1
Finally, copy the generated keystore file jetty.keystore into $JOSSO2_HOME/etc
Note
In order for JOSSO2’s web server to be able to pick up the server certificate, the
key alias for the keystore holding the server certificate must be "jetty".
17.1.2.2. Enable SSL support in JOSSO Web Server
Edit the file $JOSSO2_HOME/etc/org.ops.pax.web.cfg and uncomment the following lines at the
bottom:
org.ops4j.pax.web.ssl.keystore=/opt/atricore/josso-ee-2.3.0/etc/
jetty.keystore
org.ops4j.pax.web.ssl.password=secret
org.ops4j.pax.web.ssl.keypassword=secret1
org.osgi.service.http.port.secure=8443
org.ops4j.pax.web.ssl.clientauthwanted=false
org.ops4j.pax.web.ssl.clientauthneeded=false
Make sure to reference the generated keystore file as well as the credentials for the web server
to open it.
Security Setup
125
Note
Remove the trailing dot from the 8443 port value.
Note
You must specify the full path to jetty keystore.
17.1.2.3. Export JOSSO Web Server SSL Certificate
The following commands will extract JOSSO Web module server certificate. The result is a DER
(binary) formatted file.
keytool -exportcert -alias jetty -keystore jetty.keystore -file josso-
der.crt
Then we’ll convert it to another format - PEM - which is more widely used in applications such as
apache and by openssl to do the PKCS12 conversion.
openssl x509 -out josso-pem.crt -outform pem -in josso-der.crt -inform der
The resulting certificate will be used by agents, to access JOSSO2 web services over HTTPS.
17.1.2.4. Connect Agents to JOSSO2 Web Services over SSL
Agents interoperate with JOSSO using web services. If you intend to use HTTPs protocol in your
identity appliance, you need to configure the JOSSO Web server certificate as trusted, unless
you’re going through a reverse proxy, in that case the proxy certificate may be configured as
trusted.
Upon building your identity appliance, and depending on your platform, you may need to edit the
generated agent configuration file to include SSL information. The following example applies to
Apache 2, Windows IIS and PHP Agents. As far as Java Agents is concerned you need to add
the server certificate to the trusted certificates keystore.
# Set to 'On' to enable secure SOAP clients with HTTPS/SSL
GatewayEndpointSSLEnable : On
# Path to server certificate file that stores trusted certificates (needed
to verify
server)
SSLServerCertFile : /opt/atricore/josso-ee-2.3.0/etc/josso-pem.crt