Introduction

Single Sign-On is a method of access control that requires users to authenticate only once to gain access to the resources of multiple software systems.

This guide describes the procedure for installing JOSSO 2. Moreover, we'll show how to implement a simple standard-based (read: SAML2) Internet SSO setting in a purely visual fashion.

Preconditions

In the remainder of this chapter some assumptions will be made regarding the the resources available.
In the following sections, the name acme.com / ACME.COM is used as an example only. Replace this name with the appropriate domain name.

• The server from which the console is running is expected to be named: admin.acme.com
• The server hosting the identity provider is expected to be named: sso.acme.com.
• The server hosting the service provider one ("sp1") is expected to be named: sp1.acme.com.
• The server hosting the service provider two ("sp2") is expected to be named: sp2.acme.com.
• The identity provider and service providers hosts are known in the local DNS.
• The TCP/IP port 8081 on the identity provider ("AcmeIDP") host is accessible.
• The TCP/IP port 8090 on the service provider one ("SP1") host is accessible.
• The TCP/IP port 8091 on the service provider two ("SP2") host is accessible.

Installation

First of all download the JOSSO2 distribution from this location : http://sourceforge.net/projects/josso/files/JOSSO%202/

Expand it in a directory of your choice. This directory will be the JOSSO2 home directory referred to as JOSSO2_HOME.

Running JOSSO 2.0

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 essential provisioning interfaces the Atricore Console depends on. This process can take between one or two minutes depending on the processing capabilities of the host equipment.

All bundles need to be up and running before using the product, consequently all bundles initialization state should be "Active".

Through the command line console you can monitor the execution status of all the modules that make up the product. You can use the following command 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.

In case startup fails, you may use the log file located within the JOSSO2_HOME/data/logs directory to diagnose the reason of the failure.

Run the Atricore Console

From the Atricore Console, you can specify your digital identity architecture at a birds-eye view level, yet allowing to drill down on the single component.
Through the Atricore Console you can seamlessly mix and match the building blocks of your Internet SSO setting.
Realizing both SAML-compliant Identity Provider and Service Provider roles. Connecting these to the any number of identity sources and
automatically provisioning SSO capabilities onto the web container or application server of choice.

In order to launch the Atricore Console hit the following url : http://admin.acme.com:8081/atricore-console . Sign-in using the default credentials, therefore use 'admin' as the username and 'admin' as the password.

Create your first Identity Appliance

We're going to deliver an Internet SSO setting using a fully visual approach. In JOSSO2 you do not have to deal with XML descriptors as in JOSSO 1 for realizing single sign-on usage scenarios.

Our setting encompasses an Identity Provider (IdP) and two Services Providers (SP). All three are bound to their own and private identity store. Both Service Providers trust the Identity Provider, thus honoring authentication requests made by users having established a valid session against the Identity Provider.

The Service Providers role is played by example JavaEE web applications hosted by two dedicated Apache Tomcat container instances.

Login to the Atricore Console using the default credentials : "admin" user with "admin" as the password.
Create a new empty identity appliance by selecting the "Empty Identity Appliance" item and clicking on the "New" button;

Identity Provider setup

Drag the identity provider item from the entities drawer in the palette into the diagram canvas. Dragging is achieved by clicking on the element from the palette, moving the mouse pointer to the diagram and clicking again on the area where you wish to position the element.
Specify the name you are going to give to your identity provider, "AcmeIDP" in this case.
From the identity sources drawer, drag the Identity Vault item into the diagram which we'll name "IDPUsers".
Finally, connect the identity provider entity with the identity source created in previous steps. Simply select the Identity Lookup item from the "Connections" drawer, select "AcmeIDP" as the source element and the "IDPUsers" element as the target of the connection. The Identity Provider is now enabled for consuming user and entitlement information for authenticating an authorizing users.

Rolling out Service Providers

Drag the Service Provider element from the Entities drawer into the diagram canvas, naming it "SP1".
Drag an Identity Vault element into the diagram and bind it to Service Provider SP1, naming it "SP1Users".
Connect "SP1" with "SP1Users" as we did with the Identity Provider.

Now let's supply the details on where the service provider is hosted in, so that single sign-on support is provisioned onto it.
Drag the Tomcat element from the execution environment drawer into the diagram canvas.

Layout a second service provider, identified as "SP2" using the same procedure. Make sure to use unique identifiers for this, by substituting "SP2" with "SP1".

Establishing the circle of trust

Establish the circle of trust by dragging from the "Connections" drawer, the Federated Connection, and selecting "AcmeIDP" Identity Provider as the source element and Service Provider "SP1" as the target one. Repeat the same procedure for Service Provider "SP2". Finally, save the diagram.

This is how our identity appliance model should look like :

Build and Deploy the Identity Appliance

Now we're ready to bring all this to life through the deployment of our identity appliance onto JOSSO.
This is done from the lifecycle management control panel using a fully visual approach.
Just drag and drop your identity appliance you've defined in the modeler throughout the different columns of the grid, representing the different stages that our identity architecture can be in.
We build the identity appliance, converting our Internet SSO setting to something that can actually execute. Then host it within JOSSO
and finally start it, so that the identity services - such as SSO - we've specified are now up and running for user consumption.

Provisioning SSO support onto target container

Now, switch back to your identity appliance diagram. Connect the service provider with the execution environment by dragging from the "Connections" drawer, the Activation Connection, and selecting "SP1" Service Provider as the source element and Service Provider "SP1" as the target one.
This is how the Activation dialog should look like for the built-in examples :

Make sure to change the URI part of the Partner Application location field to the URI where your web application is servicing requests.

Once the activation properties have been specified, it's now time to run the actual activation process. Select the "SP1" Service Provider element, and within the property sheet section, choose the "Activation" tab and mark the "Reactivate" check. Then roll out from the property sheet in order for the activation procedure to take place. Repeat the same activation procedure for Service Provider "SP2".

Provision demo account

Last but not least from the Atricore Console you can provision and manage the lifecycle of your user accounts, as well as control their entitlements.
Your Identity Provider and Service Providers will use this information for authentication and authorization purposes.

In order to assert the single sign-on experience, we'll need at least a user account located in our IdP-specific identity store (i.e. "IDPUsers"). Therefore, switch to the "Account and Entitlement Management" view. Then click on the "Create User" button. Enter “user1” as the username, using “user1pwd” as the password. This account will be used to authenticate users against the Identity Provider, enabling seamless access to the service provider we've defined without forcing the user to authenticate a second time.

Testing

Now it's time to test our Internet SSO setting. First access a resource only visible to users having established a valid session against the identity provider. In this case the resource is http://sp1.acme.com:8090/partnerapp/protected . This will redirect you to the Identity Provider for authentication. Use the account "user1" we've provisioned in the previous step, ("user1" username and "user1password" as the password). You should now be able to see Service Provider SP1's protected resource.
Now, in order to test drive the SSO experience, browse to the protected resource hosted within Service Provider SP2 using http://sp2.acme.com:8091/partnerapp/protected. You you should be presented with the protected resource without having to authenticate a second time.