JOSSO 2.4. Ws-Federation Integration Tutorial

Transcription

1 JOSSO 2.4 Ws-Federation Integration Tutorial

2 JOSSO 2.4 : Ws-Federation Integration Tutorial

3 1. Introduction Prerequisites Defining Identity Appliance Elements SAML 2 Service Provider Element Ws-Federation Resource Element Security Token Service Deployment Web Application Configuration jossosts Configuration Element jossoagent Configuration Element appsettingssection id STS Federation Metadata Configuration Test Relaying Party... 9 iii

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

5 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 Certificate/Key pair to be used by the Ws-Federation services to sign messages. 2

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 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 Name Description Security Token Service Relaying Party Description The resource name, something representative of the application involved. A brief description of the resource. This is the URL that points to the STS component on the IIS server, normally This is the URL that points to the Relaying Party application, in this example 3

7 Defining Identity Appliance Elements Property Signing Certificate Encryption Certificate Description 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), 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), 4

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 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 ( We re using the following base URL for: 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: 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 partnerapplicationid The SAML SP name associated to this Ws-Federation resource jossospbindingbaseuri The SSO binding endpoint for the SP. The URL can be build using the following pattern: http[s]:// 5

9 Security Token Service Element Attribute Description <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 to The reported SAML 2 claim The Ws-Federation claim used to identify the value associted with the from SAML claim basedclaimsawarewebapp validate (*) uri (*) You can have multiple entries of these elements. Let s take a look at the configuration for our current example: 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 A valid relying party URI, to be used when verifying incoming Ws-Federation messages <jossosts> <identityprovider partnerapplicationid="wsfed-app-sp" jossospbindingbaseuri=" STS-BRIDGE-EE"/> <identifierclaim type=" address"/> <roleclaim type=" <claimmapping from=" " to=" <basedclaimsawarewebapp validate="true" uri=" </jossosts> jossoagent Configuration Element The jossosts configuration element represents the component that exchanges messages with the SSO server. Element Attribute Description identityprovider partnerapplicationid The SAML SP name associated to this Ws-Federation resource 6

10 Security Token Service Element Attribute Description endpoint sloendpoint 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 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 jossospbindingbaseuri The 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 defaultresourceuri The 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: <jossoagent> <identityprovider partnerapplicationid="testrp-sp" endpoint=" JOSSO/SSO/REDIR" sloendpoint=" EE/JOSSO/SLO/REDIR" jossospbindingbaseuri=" STS-BRIDGE-EE" defaultresourceuri=" </jossoagent> 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). <appsettings> <add key="issuername" value="jossosts"/> <add key="signingcertificatename" value="cn= OU=IT, O=Atricore, L=San Francisco, S=California, C=US"/> 7

11 Security Token Service <add key="encryptingcertificatename" value=""/> </appsettings> 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 \ , in our case the full path is C:\inetpub\wwwroot\josso\apps\STS\FederationMetadata \ 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 PassiveRequestorEndpoint: same as SecurityTokenServiceEndpoint 8

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. The steps are similar to those used during the STS bridge setup. 9