JOSSO 2.4. Ws-Federation Integration Tutorial

(1)

JOSSO 2.4

(2)

(3)

iii

1. Introduction ... 1

2. Prerequisites ... 2

3. Defining Identity Appliance Elements ... 3

3.1. SAML 2 Service Provider Element ... 3

3.2. Ws-Federation Resource Element ... 3

4. Security Token Service ... 5

4.1. Deployment ... 5

4.2. Web Application Configuration ... 5

4.2.1. jossoSTS Configuration Element ... 5

4.2.2. jossoAgent Configuration Element ... 6

4.2.3. appSettingssection id ... 7

4.3. STS Federation Metadata Configuration ... 8

(4)

Chapter 1. Introduction

Ws-Federation is an Identity Federation protocol supported by Windows Identity Foundation infrastructure, similar to SAML. It externalizes user access services, allowing applications integration with external authentication providers.

JOSSO EE provides a Ws-Federation bridge that can be used to connect Relaying Parties (the equivalent to a SAML Service Provider in WS-Federation) with JOSSO SAML Identity Providers by adapting messages from one protocol to the other. The bridge acts as a WS Security Token Service and relies on Windows Identity Foundation to provide the necessary services. Implemented as a .Net application, the bridge is deployed as an IIS application.

In this example we will go through the STS Bridge install and configuration process, and we will learn how to model the corresponding elements on the Identity Appliance. Although the relaying party application is outside the scope of this tutorial, we will provide an example as reference.

(5)

2

Chapter 2. Prerequisites

Before starting, make sure that the following prerequisites are meet. • JOSSO 2.4.x instance: JOSSO 2 Server hosting a SAML 2 IdP. • JOSSO 2.4.x STS Application distribution

• Working SSO environment: an already working Identity Appliance, including an Identity Provider.

• Windows Server 2003+: With Internet Information Server, .Net framework 3 or above and Windows Identity Foundation

(6)

Chapter 3. Defining Identity

Appliance Elements

The first step is to modify our SSO configuration, adding the required elements to enable the necessary identity services. Remember that the STS bridge will translate WS-Federation messages into SAML 2 messages, so you can connect it to any SAML IdP. For this to work, we need to define a SAML SP backed by a Ws-Federation resource (application). The two elements we need to include are:

• SAML Service Provider (Providers drawer) • Ws-Federation Resource (Resources drawer)

The SP will be connected using a Federated Connection to one or more IdPs, in our case we’re using a single IdP. The Ws-Fed resource will be connected using a Service Connection to the new SAML SP.

3.1. SAML 2 Service Provider Element

The SAML SP definition does not require any particular option, just configure it based on your SAML federation requirements. (i.e. bindings, profiles, certificates etc.)

3.2. Ws-Federation Resource Element

The Ws-Federation resource represents the STS bridge component. SSO services running on the JOSSO side will be created to handle incoming messages from the STS side of the bridge deployed on the IIS server. We must specify the STS base URL and the Relaying Party resource URLs. Let’s take a look at the element properties:

Property Description

Name The resource name, something representative of the application involved.

Description A brief description of the resource.

Security Token Service This is the URL that points to the STS component on the IIS server, normally https://<server>/STS

Relaying Party This is the URL that points to the Relaying Party application, in this example https://<server>/TestRP

(7)

Defining Identity Appliance Elements

4

Property Description

Signing Certificate Not used at the moment. Reserved for future user. The STS signing certificate Subject name (i.e. CN=My-Cert,OU=Secyrity,DC=mycompany,DC=com),

Encryption Certificate Not used at the moment. Reserved for future user. The STS encryption certificate Subject name (i.e. CN=My-Cert,OU=Secyrity,DC=mycompany,DC=com),

(8)

Chapter 4. Security Token Service

Now that we have updated our Identity Appliance, it is time to install the IIS application that works as STS bridge. The process consists of two activities:

• STS IIS site and application deployment: you can create a specific site for the STS application, or you can use an existing one.

• STS Application configuration: This step consist setting up the components that are part of the STS application.

4.1. Deployment

The Ws-Federation bridge distribution file contains the STS Web Application. Create a josso folder where you want the application to be deployed, and extract the contents of the file in that location. In our example, we’re using the following path: C:\inetpub\wwwroot\josso . The relaying party test application is also provided within the distribution , you can define a web application for it as well.

STS Web Application Folder

Now we’re going to define a new application on our existing IIS site (www.mycompany.com). We’re using the following base URL for: https://www.mycompany.com/STS. Make sure to configure the proper options when defining your own web application, specially the alias. In our case we will set it to STS and configure the physical path to C:\inetpub\wwwroot\josso\apps\STS .

STS Web Application Definition

4.2. Web Application Configuration

Now that we have the application in place, we need to configure the STS web application properties based on our current SSO deployment. First need to edit the application’s configuration file: C:\inetpub\wwwroot\josso\apps\STS\Web.config and look for the following elements

jossoSTS, and jossoAgent:

4.2.1. jossoSTS Configuration Element

The jossoSTS configuration element represents the component that exchanges messages with the relaying party. The following sub-elements must be configured:

Element Attribute Description

identityProvider partnerApplicationIdThe SAML SP name associated to this Ws-Federation resource

jossoSpBindingBaseUriThe SSO binding endpoint for the SP. The URL can be build using the following pattern: http[s]://

(9)

Security Token Service

6

<josso.server>[:<josso-port]/IDBUS/<id-appliance>/ <ws-resource-name>-EE

identifierClaim type The Ws-Federation claim that will be used as user identifier roleClaim type The Ws-Federation claim that will be used as role identifier claimMapping

(*)

from The reported SAML 2 claim

to The Ws-Federation claim used to identify the value associted with the from SAML claim

basedClaimsAwareWebApp (*)

validate Set to true If you want the STS to validate the origin for Ws-Federation requests agaist this URI. Only registered URISs will be served

uri A valid relying party URI, to be used when verifying incoming Ws-Federation messages

(*) You can have multiple entries of these elements.

Let’s take a look at the configuration for our current example:

4.2.2. jossoAgent Configuration Element

The jossoSTS configuration element represents the component that exchanges messages with the SSO server.

identityProvider partnerApplicationIdThe SAML SP name associated to this Ws-Federation resource

(10)

endpoint The SSO binding SOAP endpoint for the SP. The URL can be build using the following pattern: http[s]://

<josso.server>[:<josso-port]/IDBUS/<id-appliance>/ <ws-resource-name>-EE/JOSSO/SSO/REDIR

sloEndpoint The SSO single logout endpoint for the SP. The URL can be build using the following pattern: http[s]://

<josso.server>[:<josso-port]/IDBUS/<id-appliance>/ <ws-resource-name>-EE/JOSSO/SLO/REDIR

jossoSpBindingBaseUriThe SSO binding endpoint for the SP. The URL can be build using the following pattern: http[s]://

<josso.server>[:<josso-port]/IDBUS/<id-appliance>/ <ws-resource-name>-EE

defaultResourceUriThe default relaying party URL. Useful when using IdP initiated processes.

(*) You can have multiple entries of these elements.

Let’s take a look at the configuration for our current example:

4.2.3. appSettingssection id

In the application settings element, we need to configure the certificates that the STS will use to sign and encrypt Ws-Federation messages. Normally encryption is not used because all messages are exchanged using a secure channel (HTTPS/SSL). Make sure that the referred certificate and key are available in the local computer’s Personal certificates store, and that the identity running the application pool for the STS application has the proper permissions over the private key (IIS Service accounts).

(11)

8

Certificate Subject value

Private Key permissions for IIS service user

4.3. STS Federation Metadata Configuration

The final step requires the configuration of the STS metadata file. Similar to SAML, WS-Federation services also rely on metadata descriptors to exchange information among parties. To create the Metadata file, you can use an MD generator, or you can edit the file provided within the distrubution and modify the necessary elements. The file is located at josso\apps\STS\FederationMetadata \2007-06, in our case the full path is C:\inetpub\wwwroot\josso\apps\STS\FederationMetadata

\2007-06

When updating the provided file, you can go through the elements and update the different values according to your environment and organization details. They key elements to consider are: • X509Certificate: make sure to replace the default value with the certificate you’re using on your

deployment.

• ClaimTypesOffered: list of claims you want to expose to the relaying party.

• SecurityTokenServiceEndpoint: in particular the Address sub-element. It must point to the STS location, in our example https://www.mycompany.com/STS

(12)

Chapter 5. Test Relaying Party

The relaying party test application (TestRP) is provided for debugging/testing purposes. You will have to go through the application’s configuration files: Web.config and

FederationMetadata.xml and the modify the different values based on the STS configuration.