1. Introduction

JOSSO 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-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 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.

2. JOSSO2 Rollout

JOSSO 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 :

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.

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.

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.

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.

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">
       <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 :

identity_provider

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.

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.

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 :

saml_service_provider

An External SAML2 IdP element is represented with this figure :

external_saml_identity_provider

An External SAML2 SP element is represented in the figure below :

external_saml_service_provider

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.

An External OpenID IdP element is represented with this figure :

external_openid_identity_provider

An External OpenID SP element is represented in the figure below :

external_openid_service_provider

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 :

external_wsfed_service_provider

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 :

oauth_service_provider

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.

Salesforce

Salesforce.com is a customer relationship management (CRM) software-as-a-service (SaaS) provider.

A Salesforce element is represented with this figure :

salesforce_service_provider

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 :

google_service_provider

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 :

google_identity_provider

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).

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 :

identity_vault

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 :

db_identity_vault

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 :

ldap_identity_source

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 :

database_identity_source

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 :

xml_identity_source

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 Activation .

The upcoming sections describe all the JOSSO-supported execution environments onto which service providers can build, for participation in a Federated SSO setting.

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.

An Apache Execution Environment element is represented with this figure :

apache_web_server_execution_environment

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 :

java_ee_execution_environment

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 :

jboss_as_execution_environment

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 :

apache_web_server_execution_environment

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 :

tomcat_execution_environment

Webserver Execution Environment

A Webserver Execution Environment represents a "vanilla" web server.

A Webserver Execution Environment element is represented with this figure :

web_server_execution_environment

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 :

weblogic_execution_environment

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 :

websphere_execution_environment

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 :

windows_execution_environment

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.

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 :

wikid_authentication_service

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 :

directory_authentication_service

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 :

windows_authentication_service

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 :

domino_authentication_service

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 :

clientcert_authentication_service

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 :

jbossepp_authentication_service

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.

A connection is capable of associating identity appliance elements of a specific type. In the next section we’ll cover the available connection elements.

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 :

connection

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.

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. 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 :

identity_lookup

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 :

activation

For more information on the procedure for provisioning Single Sign-On support onto execution environments please refer to [Brinding_SSO_readyness_to_Execution_Environments]

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, 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 :

identity_verification

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 :

service_connection

3.2.7. Resources

Resources are used to represents identity consumers, such as business applications as well as commercial off-the-shelf solutions.

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 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 :

josso1_resource

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 :

sharepoint_resource

Microstrategy Resource

MicroStrategy is an enterprise business intelligence (BI) software solution.

A Microstrategy Resource element is represented in the figure below :

microstrategy_resource

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 :

sas_resource

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 :

alfresco_resource

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.

A JBoss Portal Resource element is represented in the figure below :

jboss_portal_resource

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 :

liferay_resource

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 :

phpbb_resource

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 :

jbossepp_resource

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 :

selfservices_resource

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 :

domino_resource

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 :

blackboard_resource

4. Atricore Console and Model Driven Identity

This 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.

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.

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.

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 :

modeler_birds_eye

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 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.

lifecycle_birds_eye

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).

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 : accounts_birds_eye

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.

groups_birds_eye

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.

schemas_birds_eye

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.

system_settings_birds_eye

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.

help_birds_eye

5. Identity Appliance Creation

An 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.

new_appliance_scratch

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 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.

6. Identity Source Setup

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, 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 : identity_vault

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 identity_vault in the "Identity Sources" drawer and drag it to the preferred location within the Diagram Canvas.

new_identity_vault

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 : db_identity_vault

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 db_identity_vault in the "Identity Sources" drawer and drag it to the preferred location within the Diagram Canvas.

new_db_identity_vault

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 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_source

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.

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.

new_ldap_base

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.

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.

new_ldap_lookup

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.

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.

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 : database_identity_source

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.

new_db_connection

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.

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.

new_db_lookup

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.

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.

new_db_password

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.

7. Authentication Setup

Authentication 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 :

identity_verification

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 directory_service element to the preferred location within the Diagram Canvas.

new_directory_service_base

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.

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.

new_directory_service_lookup

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 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 win_integrated_authn in the "Authentication" drawer.

Click on and drag the "Windows Domain" element to the preferred location within the Diagram Canvas.

new_windows_domain

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.

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.

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 wikid in the "Authentication" drawer.

Click on and drag the "WikID Authentication element to the preferred location within the Diagram Canvas.

new_wikid

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 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 domino_authentication_service in the "Authentication" drawer.

Click on and drag the "Domino" element to the preferred location within the Diagram Canvas.

new_domino_authentication_service

In the "New Domino Definition" window, enter the Domino configuration used by the associated Identity Providers to offer LTPA authentication.

Field Descriptions

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 clientcert_authentication_service in the "Authentication" drawer.

Click on and drag the "Client-certificate Authentication" element to the preferred location within the Diagram Canvas.

new_clientcert_authentication_service

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 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 jbossepp_authentication_service in the "Authentication" drawer.

Click on and drag the "JBoss EPP Authentication" element to the preferred location within the Diagram Canvas.

new_jbossepp_authentication_service

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.

8. Identity Provider Setup

In 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.

new_idp_core

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.

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.

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.

new_idp_saml2

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 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.

new_idp_oauth2

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.

new_idp_openid2

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.

new_idp_certificate

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.

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.

new_idp_identity_confirmation

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.

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 external_saml_identity_provider 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).

new_external_saml2_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 external_openid_identity_provider 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).

new_external_openid_idp

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 google_identity_provider 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.

new_google_signin_core

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 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.

new_google_signin_openidconnect

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

new_google_signin_services

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 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 identity_lookup 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.

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 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 identity_lookup 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 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 identity_lookup 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 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 identity_lookup 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.

9. Service Provider Setup

Once 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 saml_service_provider 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.

new_internal_saml2_sp_core

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 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.

new_internal_saml2_sp_saml2

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.

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: ?

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.

new_internal_saml2_sp_certificate

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.

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 external_saml_service_provider 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).

new_external_saml2_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 oauth_service_provider in the "Providers" drawer.

Drag the "OAuth2 Service Provider" element to the preferred location within the Diagram Canvas.

In the "New OAuth2 Service Provider Definition" window, enter the name of the OAuth2 Service Provider (SP).

new_internal_oauth2_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 salesforce_service_provider in the "Cloud Providers" drawer.

Drag the "Salesforce Service Provider" element to the preferred location within the Diagram Canvas.

new_salesforce_sp

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.

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 google_service_provider in the "Cloud Providers" drawer.

Drag the "Google Service Provider" element to the preferred location within the Diagram Canvas.

new_googleapps_sp

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 sugarcrm_service_provider in the "Cloud Providers" drawer.

Drag the "SugarCRM Service Provider" element to the preferred location within the Diagram Canvas.

new_sugarcrm_sp

Field Descriptions

Field

Description

Name

The unique identifier of the Google Apps SP.

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 Setup of an Embedded Identity Vault and 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.

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 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 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.

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 :

service_connection

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 josso1_resource 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 :

new_josso1_resource

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.

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 sharepoint_resource in the "Resources" drawer, and drag it to the preferred location within the Diagram Canvas.

Within the setup dialog, enter the Sharepoint resource details :

new_sharepoint_resource

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 microstrategy_resource in the "Resources" drawer, and drag it to the preferred location within the Diagram Canvas.

Within the setup dialog, enter the Microstrategy resource details :

new_microstrategy_resource

Field Descriptions

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 alfresco_resource 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 :

new_alfresco_resource

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 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 jboss_portal_resource 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 :

new_jbossportal_resource

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 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 liferay_resource 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 :

new_liferay_resource

Field Descriptions

Field

Description

Name

The unique identifier for the resource.

Description

A descriptive text for the resource.

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.

From the Palette, click phpbb_resource in the "Resources" drawer, and drag it to the preferred location within the Diagram Canvas.

Within the setup dialog, enter the phpBB resource details :

new_phpbb_resource

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.

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 jbossepp_resource in the "Resources" drawer, and drag it to the preferred location within the Diagram Canvas.

Within the setup dialog, enter the JBossEPP resource details :

new_jbossepp_resource

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.

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 selfservices_resource 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 :

new_selfservices_resource

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 domino_resource 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 :

new_domino_resource

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.

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 apache_web_server_execution_environment in the "Execution Environments" drawer.

Within the setup dialog, enter the Apache Web Server execution environment details :

new_apache_ee

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.

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 java_ee_execution_environment 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 :

new_javaee_ee

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 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 web_server_execution_environment 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 :

new_webserver_ee

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 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 apache_web_server_execution_environment 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 :

new_php_ee

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 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.

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 weblogic_execution_environment 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 :

new_wls_ee

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 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.

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 websphere_execution_environment 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 :

new_wasce_ee

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 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 windows_execution_environment 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 :

new_iis_ee

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.

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 tomcat_execution_environment 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

new_tomcat_ee

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.

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.

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 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 jboss_as_execution_environment 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 :

new_jboss_ee

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.

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.

10. Circle of Trust Establishment

A 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.

new_federated_connection_idp

Field Descriptions

Field

Description

Name

The unique identifier of the Federated SSO connection.

Description

A descriptive text for the Federated SSO connection.

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.

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.

new_federated_connection_sp

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, 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.

11. Identity Appliance Lifecycle Management

The 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.

lifecycle_birds_eye

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 edit_identity_appliance button to open the identity appliance within the modeler view. To delete an identity appliance, click on the trash_identity_appliance 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.

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 edit_identity_appliance button to open the identity appliance within the modeler view. Then, click on the setup 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 start_identity_appliance 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 stop_identity_appliance 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 undeploy_identity_appliance 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.

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 dispose_identity_appliance 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 trash_identity_appliance 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 trash_identity_appliance 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.

12. Execution Environment Activation

As explained in 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.

new_activation_connection

Field Descriptions

Field

Description

Name

The unique identifier of the Activation connection.

Description

A descriptive text for the Activation connection.

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.

reactivate

Note
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 Build an Identity Appliance

13. Account and Entitlement Management

Generally 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.

accounts_birds_eye

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 manage_users button.

13.2.1. General User Information

User profile information is entered on the General User Information screen.

new_user_general

Field Descriptions

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 "jdoe@acme.com".

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.

new_user_preferences

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 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.

new_user_groups

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.

new_user_security

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 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.

new_user_password

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.

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 add_user 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 edit_user button. Modify the fields as needed and click Save.

13.2.8. Search Users

To search for a user entry, click on the search_user 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.

search_user_dialog

13.2.9. Deprovision a User Account

To deprovision a user, select the target user entry in the user list and click the remove_user button.

13.3. Groups

To reach the Group Management screen, go to Account and Entitlement Management on the Main screen and click the manage_groups button.

groups_birds_eye

13.3.1. Provision a Group

To provision a group, click on the add_group 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 search_group 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.

search_group_dialog

13.3.3. Update a Group

To edit an existing group, select the corresponding group entry in the group table and click the edit_group 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 remove_group button.

14. Profile Operations

Profile 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.

administrator_menu

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.

web_settings

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.

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.

remote_console_settings

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.

persistence_settings

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.

monitoring_and_management_settings

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.

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.

message_bus_settings

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.

logging_settings

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.

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.

branding_settings

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.

new_branding_extension

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.

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.

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.

live_services_birds_eye

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.

licensing_birds_eye

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.

  • 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.

ha_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.

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.

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.

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

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.

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.

Generating a server certificate with keytool

The following command will generate a key pair and certificate directly into a Java keystore:


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
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".

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.

Note
Note

Remove the trailing dot from the 8443 port value.

Note
Note

You must specify the full path to jetty keystore.

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.

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