• Products Overview
• Virtual Directory Server
• LDAP Proxy
• Federated Identity Suite
• Schedule a product DEMO

Federated Identity Suite :: Quick Start Guide

1 Introduction

This Quick Start Guide describes how to install Symlabs Federated Identity Suite, and how to run and test the demos included with it. This guide does not explain the protocols used for Single Sign-On (SSO), please refer to the documentation provided by OASIS (www.oasis-open.org) and the Liberty Alliance (www.projectliberty.org) for further information in this regard. For a more detailed coverage of the demonstration kit and the protocols used for ID-WSF, please refer to the Symlabs Federated Identity Suite Administration Manual.

2 Installation

Symlabs Federated Identity Suite (SFIS) runs on both Windows and UNIX platforms. The installation process is simple but differs according to the underlying operating system. For the instructions below, replace n.n.n with the version number of the release that is being installed.

2.1 Windows Installation

Run the installer symfisN.N.N.exe. You are given the option to change the default installation location, however we recommend that you install the application in its default location at: "C:/Program Files/Symlabs/SFIS/Rn.n.n".

2.2 UNIX Installation

Install the UNIX package (*.pkg or *.rpm):

 rpm -i SFIS-ev-X.X.X-i386.rpm # Linux pkgadd -d SFIS-ev-X.X.X-sol-sparc.pkg # Solaris SPARC pkgadd -d SFIS-ev-X.X.X-sol-intel.pkg # Solaris Intel

SFIS will be installed in directory /opt/SFIS/Rn.n.n.

2.3 Remarks

Using the convention that includes the release number n.n.n in the installation location allows for different versions to be installed side by side.

Note - SFIS_HOME will be used to denote the directory where SFIS is installed.

3 Running The Demo

Note - If you are using an evaluation copy of Symlabs Federated Identity Suite, then you will need to obtain an evaluation license before you can run it. To request an evaluation license, please send an email to evalkey@symlabs.comincluding "Key Request" as subject and your name, company, and address in the body. You will receive a file named "evaluation.key" by return email. Copy this file into theSFIS_HOME/etc/directory to enable your evaluation copy.

Symlabs Federated Identity Suite comes with pre-built instances of IdP (Identity Provider), SP (Service Provider), and PP (Personal Profile) servers. Each of these servers can be started manually or by using a web based administration interface (WebAdmin). The WebAdmin interface can also be used to create and manage new instances of IdP, SP, or PP servers.

Fig-1: Start the WebAdmin server

To start the WebAdmin server, begin at a UNIX console or a Windows command prompt, then change directory to SFIS_HOME and run "start-symadm start" (UNIX) or "start-symadm.bat start" (Windows). When the server is running you will see a message telling you to point your browser to https://admin.symdemo.com:8000/ (Figure 1).

Fig-2: Administration Login

The WebAdmin interface (Figure 2) has various sections that you can hide or show by clicking on the corresponding link. By default, the SFIS evaluation version comes with three pre-defined server instances: symdemo-idpa (IdP A), symdemo-sp1 (SP 1), and symdemo-pp (PP) that are used for the demo.

Login using dsmanager/salainen as username/password ("salainen" means "password" in Finnish).

Fig-3: Administration Panel

Once you are logged in, you will that links are provided to start, stop, restart and manage each instance. There is also a "First Page" and a Metadata link for each instance (Figure 3).

Note - Default host names used in the demo are universally resolved to 127.0.0.1. This makes it possible to run the demo in a single machine environment, without needing to modify hosts file. Should you wish to use a different IP (i.e., for accessing the demo from a different machine, or any other reason) you will need to add the domain names of each server instance either to your DNS server or to your operating system hosts file before you run the demo. For UNIX environments, this can be achieved by editing the file located at /etc/hosts; while for Windows environments, this file is usually located at C:/Windows/system32/drivers/etc/hosts. In either case, you need to edit the IP line in the file so that it includes these domain names. When you are done, a standard line will look like this (in the example, we used 10.2.4.162 as the externally accessible IP address that we wish these domain names to resolve to):

10.2.4.162 idp.symdemo.com sp.symdemo.com pp.symdemo.com dap.symdemo.com admin.symdemo.com

To run the demo, first start the IdP, SP, PP and ID-DAP servers by clicking the corresponding "up" link under "Manage" for each one.

Next open the link indicated under SP "First Page" in a new browser window or tab.

Fig-4: SP Login Page

This is the entry page of the "Employee Portal" (Figure 4). This page provides a button to let a user log in using the different protocols that Symlabs Federated Identity Suite supports. These are specified in the dropdown menus at the bottom. For the demo, choose the first options (SAML2.0, browser POST) in the pulldown menus, and then click the "Corporate IdP" button.

Fig-5: IdP Login Page

This will redirect you to the "Corporate IdP" login page. Enter "dad/dad" as your username/password and click the login button (Fig. 5).

Fig-6: Accept IdP Federation

The next screen (Fig. 6) will ask you if you want to federate. Indicate "yes" by clicking the Accept Federation button.

Fig-7: User Authenticated To SP

You will then be redirected to the SP entry page (Figure 7) as an authenticated user. You can update your timesheet by using the "Update Time sheet (PP:WSF1.1)" link to make use of the PP service, or alternatively, you can try out the ID-DAP service by clicking on the "Update Time sheet (ID-DAP:WSF2.0)" link. Since you are already authenticated at the IdP, you will be able to make use of all of these services without any further login.

Fig-8: Personal Profile, asking for confirmation

After clicking the link you will be presented with a form where you can enter personal information. Instead of entering the requested information, click on the "Fill from Personal Profile" button. This will cause your personal information to be retrieved from the PP/ID-DAP server instance, but before being retrieved, the server will ask for user confirmation to release the personal data. This intermediate step can be configured to be automatic, but the demo includes the interaction for completion purposes. (Figure 8).

Fig-9: Personal Profile automatically loaded

Once consent has been given, the information is retrieved from the PP server instance (Figure 9).

For authtication purposes, the previous examples make use a flat file (SFIS_HOME/conf/symdemo-idpa/users.ldif) as the repository to store user authentication data. You can add new users to this file by clicking the "Manage" link in the WebAdmin interface, then on the "Edit Users" link. After entering and saving new user information, you can check to see that it has been added to the file. You can then re-run these demos as a different user. Note that if you add users to the ldif file via the WebAdmin interface, you will need to restart the IdP Server in order for it to load the changes into memory.

It is also important to understand that once a new user has been added to the IdP, no details will have been registered with the PP server or the ID-DAP server. In order for these facilities to work, the user will need to authenticate and then access the registration pages for each of these services. Information on how to do this is covered in more detail within the Symlabs Federated Identity Suite Manual.

4 An IdP With an LDAP Back-end

In this next section we are going to create a new SP and a new IdP, and we will also demonstrate use of an LDAP back-end as the repository to provide the user information. You will need an LDAP server that the demo can connect to either locally or over a network, so you will need to know its address and port. You will also need administrative access to the server plus at least one user account on it. If you don't have an LDAP server to use for the demo, you can still create new SP and IdP servers, and simply skip the LDAP configuration and login exercise.

Fig-10: Create New SP

To create a new SP enter "mysp" in the "New Server Instance" section of the WebAdmin interface (Figure 9), then choose SP from the drop down menu and click Create.

Fig-11: Configure SP settings

This will take you to the SP administration page (Figure 10), where you can specify the SP hostname (Enter "mysp.com") and the Common Domain hostname (Enter "mysp.common.com"), along with their respective ports (Use "8443" and "8081"). Accept the other default settings and remember to click the "Save Changes" button.

Note - Since you will be running these instances locally, you must also remember to edit your hosts file and add their domains to the "localhost" line. The Common Domain cookie functionality will not be tested in this exercise, so at this point you do not need to addmysp.common.com, but you do need to includemysp.com. Now the localhost line in your hosts file should resemble this:

10.2.4.162 idp.symdemo.com sp.symdemo.com pp.symdemo.com dap.symdemo.com mysp.com

Fig-12: Create new IdP

Similarly, create a new IdP named "myidp" (Figure 11) and choose IdP from the drop down menu.

Fig-13: Configure IdP Settings

In the administration page specify the IdP hostname ("myidp.com"), the Common Domain hostname ("myidp.common.com") and their respective ports ("8444" and "8082") (Figure 12). Once again remember to add the new hostnames to proper line in the hosts file (only "myidp.com" is needed right now).

Next we will configure the IdP to use an LDAP server as its data repository. Click the "DIT and Backends" link in the menu bar at top of the screen.

Fig-14: Configure IdP back-end

On the screen this takes you to (Figure 13), go to the first section, "User Authentication". If you have an LDAP server to use, this is where you will configure Symlabs Federated Identity Suite to access it. If not, you can simply read the following for familiarity with the process.

Select "External LDAP directory servers" from the pull down menu.

The naming attribute and suffix should match the "user" nodes of the LDAP tree that will be used for authentication. In the example shown here the "user" node (or LDAP attribute dn, the Distinguished Name) is "uid=jdoe,ou=user,dc=myidp,dc=com". So, the naming attribute entered is "uid" and the suffix entered is "ou=user,dc=myidp,dc=com". You should enter the actual values that correspond to your LDAP tree.

Select "Bind credentials" from the Authentication Mode pull down menu. The bind credentials are the account (usually "Directory Manager") and password of the administrator. You should enter the actual values that correspond to your LDAP server. Also enter the actual IP address or hostname, as well as the port used for your LDAP server, then click on "Add New Host". If you use hostname, make sure it can be resolved by a DNS server or by an entry in your hosts file.

Fig-15: SP Login Page

To test the new SP and IdP you just created, first make sure that they are running. Click their corresponding "up" links in the WebAdmin interface, then open the link under "First Page" for "mysp" in a new browser window or tab (Figure 14).

In this case we do not have an IdP associated with the new SP yet. One way to create this association would be to click on the "IdPs in Circle of Trust" link from the menu bar of the administration page for that SP instance (see Figure 10), and then add "myidp" (the name of our new IdP) to the list.

Instead, we will use the "IdP URL" to log in. First, check that the default selection of "SAML 2.0" is shown in the Preferred Protocol pull down menu. Then copy the Metadata link

 https://myidp.com:8444/idp.xml

from the WebAdmin interface and paste it into the "IdP URL" field of the SP Login Page, and click the "Login using other IdP (POST)" button.

Fig-16: IdP Login Page

In the new IdP page (Figure 15) enter the username/password of a user that exists in the LDAP server that you configured and click on "Cookie login".

Fig-17: Accept IdP Federation

Once again, accept Federation (Figure 16).

Fig-18: User Authenticated to SP

You are now logged to the Service Provider "mysp" (Figure 17) using an IdP with a LDAP backend.

Finally, you can logout from here by selecting "SAML 2.0" as the protocol and "Redir" as the binding from the pull down menus, then click on the "Logout All" button.

Fig-19: User logged out

Once you have logged out, you are returned to the SP login page (Figure 18).

4.1 Using Active Directory

Active Directory (AD) can also be used as your LDAP back-end, but this requires some minor configuration changes. By default, the user entries in AD have the following format:

 CN=John Smith,CN=Users,DC=myidp,DC=com

With this format, the CN used (equivalent to the "uid" from our LDAP tree) is the user's actual name, not the user's account login name. This creates a potential problem - in principle we could have users log in to the IdP with their "real" name instead of a username created specifically for account access, but in practice that is not a desirable method of operation.

The suggested approach, particularly in situations where there is already a large AD user repository, is to use a tool like ADModify (a .NET utility provided by Microsoft) to change the CN parameter so that it uses the sAMAccountName (an AD attribute) instead of "First Last" name.

Note that the equivalent of "cn=Directory Manager" for Active Directory is

 CN=Administrator,CN=Users,DC=myidp,DC=com

again using our example IdP at "myidp.com". It is suggested that before attempting to use AD as the IdP back-end you first try to view it with an LDAP browser (like the free "Softerra LDAP Browser") to make sure that there are no problems connecting to it.

5 STS & Managed Card Provider

The IdP can issue Infocards that can be imported by Cardspace-capable browsers and used to login at Infocard-enabled sites. During this process the IdP is contacted and returns security tokens with identity information.

Note that some InfoCard clients (AKA Identity selectors) have dificulties with Certificate Authorities that are not first level CA. The certificates included in the package are signed by a 2nd Level CA. In situations where the Infocard generated by the STS cannot be used, we suggest that you import the CA into the Certificate Storage so that it can be recognized by the system as a trusted authority. The CA certificate that needs to be imported is stored at SFIS_HOME/conf/symdemo-idpa/pem/ca.crt in your installation of SFIS.

5.1 Configuration

Fig-20: STS management screen

By default, the configuration provided for the Identity Provider includes the parameters required in order for STS to work. As such, STS is enabled by default and can be used out of the box. You can leave the default options for cardname and lifetime as they are and the system will function as expected.

To view or edit the STS configuration parameters, click on the "STS Control" tab of the menu on the Identity Provider management screen. This will take you to a screen where you can configure the main features of the STS and card provider.

"STS Enabled" is checked by default. For testing purposes we recommend that you do not check the card (keep the "Require InfoCard Provisioning" unchecked), unless you specifically want to test that feature.

You can also add or remove claims to be sent by the STS during login process.

Fig-21: STS management advanced options

Additional optional settings can be edited by clicking on the "Show" link next to each of the section headings: "Security Settings"; "SAML11 Tokens"; and "STS Authentication Methods". We recommend that while initially testing the product, you keep the default settings. You can return to this page at a later stage to edit these settings and to check the effect that they have on the login process and on Card validation.

5.2 Issue a new card

Fig-22: Access to STS capabilities at the IdP

A user can be issued with a new Infocard by logging into the Identity Provider and clicking on the "Infocard" link to access the Infocard Generation page. At this page, the user just needs to set the name for the card and click the "Issue New InfoCard" button. As the user issues new cards, they will be listed on this page and the option to Delete and infocard will appear.

Fig-23: InfoCard issued

Multiple InfoCards can be issued for the same user at the Identity Provider. Users can download them as often as needed and also delete them or issue new ones. To store or use the InfoCard, the user needs an identity selector, such as a built-in Cardspace client on Windows Vista, one of the plugins available for Windows XP, or the digitalme (http://www.bandit-project.org/index.php/Digital_Me) plugin available for Mac, Windows and tested successfully in Linux as well.

5.3 Using an InfoCard

The Identity Provider has InfoCard as one of the supported Authentication Mechanism when the user is trying to authenticate to access a Service Provider and is typically included in the list of authentication mechanisms enabled at the Identity Provider.

Fig-24: Authenticaton Methods order

To test the Cardspace login facility, there are a couple of options:

1. By default, the Identity Provider comes with both normal Login/Password and Cardspace login enabled. The order of authentication mechanisms displayed on the IdP configuration screen, determines the order in which the different mechanisms are presented. The default order is that the Login/Password facility is presented before Cardspace Login. This means that, by default, if the user goes to SP main page, clicks on "Log in Corporate IdP", and is redirected to the IdP login screen; the user will need to cancel the login/password login option in order to make use of the Cardspace Login facility.

2. Alternatively, the order of authentication mechanisms can be rearranged, so that Cardspace Login is presented before Login/Password. Once again, this can be done by accessing the IdP configuration screen, and altering the order of the authentication mechanisms listed in the section titled IdP Authentication Mechanisms. Once the order has been changed and the IdP service restarted, users redirected to the IdP login screen will be presented with the Cardspace Login option first. In order to login with a username and password, the user would have to cancel the Cardspace Login option first.

Note: keep "Session" as the first authentication mechanism if you want that in the case the user has a session at the IdP, it is used. Otherwise, the session will not be used unless the other authentication mechanisms are cancelled.

In following paragraphs, it is explained how to check that Cardspace Login is enabled and how to alter the order of Authentication Methods available at the IdP. It is easy to test the first option proposed above, as it works out of the box (of course the user needs an InfoCard and an Identity Selector software)

To add the Cardspace Login option to the supported Authentication Methods for an IdP, you will need to access the IdP Configuration screen in the WebAdmin GUI. Expand the "IdP Authentication Methods" section, and check to see whether Cardspace Login is supported. Here, you will also be able to change the order of the variously supported methods. Make sure that the "Cardspace Login" option is near the top of the list, just after "Session", and remember to save options before leaving the management screen, by clicking on the "Save Changes" button.

You will need to restart the Identity Provider in order for the changes to be saved and loaded into memory.

Fig-25: Cardspace Login at SP

Now access the Start Page of the Service Provider at https://sp.symdemo.com:8002/E and click on "Corporate IdP" as the Identity Provider to log with. You'll be redirected to the Identity Provider login page, but you will also notice that an InfoCard logo is present. To open the Identity Selector software and login using an Infocard, simply click on the InfoCard logo.

Fig-26: Identity Selector digitalme, running on Linux

For this example, we have used digitalme Identity Selector running on linux, but it will be pretty similar with any other InfoCard client. The Identity Selector offers all InfoCards loaded on it and the user must select the one that should be used for login scenario. The InfoCards issued in previous stages are present in the selector, so in the client we used one of the InfoCards that we had already allocated. Once selected, it asks for the identity of the user who issued the card, as that is the mechanism chosen.

Fig-27: Establish federation

The final step, after authentication but prior to entering the website, is the federation step. This step usually only needs to be completed the first time that the user logs in, to establish the federation relationship. Subsequent login attempts will not require that the user establishes federation, unless the user decides to defederate.

6 Support

Please direct any questions you may have or refer any problems you experience by email to support@symlabs.com.