Java Platform

AUTHORIZED DOCUMENTATION
Java Platform Connector 1.0 Integration Guide
Novell
Cloud Security Service

April 29, 2011
www.novell.com
Legal Notices
Novell, Inc., makes no representations or warranties with respect to the contents or use of this documentation, and specifically disclaims any express or implied warranties of merchantability or fitness for any particular purpose. Further, Novell, Inc., reserves the right to revise this publication and to make changes to its content, at any time, without obligation to notify any person or entity of such revisions or changes. Further, Novell, Inc., makes no representations or warranties with respect to any software, and specifically disclaims any express or implied warranties of merchantability or fitness for any particular purpose. Further, Novell, Inc., reserves the right to make changes to any and all parts of Novell software, at any time, without any obligation to notify any person or entity of such changes. Any products or technical information provided under this Agreement may be subject to U.S. export controls and the trade laws of other countries. You agree to comply with all export control regulations and to obtain any required licenses or classification to export, re-export or import deliverables. You agree not to export or re-export to entities on the current U.S. export exclusion lists or to any embargoed or terrorist countries as specified in the U.S. export laws. You agree to not use deliverables for prohibited nuclear, missile, or chemical biological weaponry end uses. See the Novell International Trade Services Web page (http://www.novell.com/info/exports/) for more information on exporting Novell software. Novell assumes no responsibility for your failure to obtain any necessary export approvals. Copyright 2011 Novell, Inc. All rights reserved. No part of this publication may be reproduced, photocopied, stored on a retrieval system, or transmitted without the express written consent of the publisher. Novell, Inc. 404 Wyman Street, Suite 500 Waltham, MA 02451 U.S.A. www.novell.com Online Documentation: To access the latest online documentation for this and other Novell products, see the Novell Documentation Web page (http://www.novell.com/documentation).
Novell Trademarks
For Novell trademarks, see the Novell Trademark and Service Mark list (http://www.novell.com/company/legal/ trademarks/tmlist.html).
Third-Party Materials
All third-party trademarks are the property of their respective owners.
Cloud Security Service Java Platform Connector 1.0 Integration Guide
Contents
About This Guide 1 Getting Started
1.1
7 9
1.2
Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 1.1.1 Application Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 1.1.2 Development Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 1.1.3 Programming Skills . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 Overview of the Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
2 Creating a Java Connector

2.1 2.2 Setting Up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Customizing the XML Configuration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.2.1 Modifying the Application Context Security XML File . . . . . . . . . . . . . . . . . . . . . . . . 2.2.2 Modifying the Application Context Connector XML File. . . . . . . . . . . . . . . . . . . . . . . 2.2.3 Modifying the Web XML File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Customizing the Property Configuration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.3.1 Modifying the Connector Properties File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.3.2 Modifying the Event Properties File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating the SAML Assertion Specification File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.4.1 Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.4.2 SAMLProperties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.4.3 AssertionNodeGroup and AssertionNode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.4.4 AttributeSpec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.4.5 Sample SAML Assertion Specification File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding the Required JAR Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
13
13 13 14 15 16 17 17 19 19 20 21 22 23 25 26
2.3
2.4
2.5
3 Setting Up the Connector for Testing

3.1 Installing the Connector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.1.1 Exporting the Applications Trusted Root. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.1.2 Configuring Tomcat for SSL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.1.3 Importing the Directors Trusted Root . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.1.4 Modifying the Connectors Properties File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding the Connector to the Director . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring the Connector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Logging in to the Connector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Reinstalling the Connector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
27
27 27 28 28 29 29 30 30 30
3.2 3.3 3.4 3.5
4 Testing the Connector

4.1 Debugging the Connector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.1.1 Configuring Logging. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.1.2 Discovering Why a Connector Wont Import . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.1.3 Discovering Why Federation Fails . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.1.4 Useful Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Basic Test Cases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
33
33 33 33 34 34 34
4.2
Contents
A Sample Pet Clinic Connector Guide

A.1 Installing the Pet Clinic Demo Connector. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A.1.1 Verifying Machine Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A.1.2 Installing Certificates and the Pet Clinic Software . . . . . . . . . . . . . . . . . . . . . . . . . . . A.1.3 Adding the Pet Clinic Demo Connector into the Director . . . . . . . . . . . . . . . . . . . . . . Configuring the Pet Clinic Connector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Logging In to the Pet Clinic Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Changing the Director Certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Upgrading the Pet Clinic Connector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
35
35 35 35 38 39 40 40 41
A.2 A.3 A.4 A.5
About This Guide

This guide describes how to create a deep connector for a Java application. A deep connector automates the process of configuring the application for a trusted, federated SAML 2.0 relationship with Novell Cloud Security Service. It also enables auditing of events. Audience This guide is intended for software developers who are responsible for creating deep connectors for Java applications. Feedback We want to hear your comments and suggestions about this manual and the other documentation included with this product. Please use the User Comments feature at the bottom of each page of the online documentation, or go to www.novell.com/documentation/feedback.html and enter your comments there. Documentation Updates For the most recent version of this guide, visit the Cloud Security Service Web site (http:// www.novell.com/documentation/novellcloudsecurityservice). Additional Documentation
Cloud Security Service Surface Connector 1.0 Integration Guide Cloud Security Service 1.0 SP2 Installation Guide Cloud Security Service 1.0 SP2 Provider Administration Guide Cloud Security Service 1.0 SP2 Customer Administration Guide
About This Guide
Getting Started
This guide describes how to create a deep connector for a Java application. A deep connector automates the process of configuring the application for a trusted, federated SAML 2.0 relationship with Novell Cloud Security Service. It also enables auditing of events.
Section 1.1, Requirements, on page 9 Section 1.2, Overview of the Process, on page 10
1.1 Requirements
Section 1.1.1, Application Requirements, on page 9 Section 1.1.2, Development Environment, on page 9 Section 1.1.3, Programming Skills, on page 10
1.1.1 Application Requirements

This guide assumes that you are the developer of the Java application as well as the developer for the connector and that you can make the required modifications directly to the application. It also assumes that the application is deployed as a WAR file. You need to be thoroughly acquainted with how the application has implemented user security:
What does it require for authentication? Cloud Security Service currently supports only name
and password for authentication.

Does the application use roles to authorize access to specific resources?
The application must support SSL and have configuration options for mutual SSL and for signing and encryption certificates. The instructions in this guide assume that your application does not already use Spring Security. If your application is already using Spring Security, you need to integrate the supplied application context configuration. The details of how to do this are outside the scope of this document.
1.1.2 Development Environment

You need to have a Java developer environment set up for the application. You need to download the ncss-java-platform-integration-kit-1.0.zip file. To obtain the file, see Connector Downloads (http://www.novell.com/products/cloud-security-service/servicesand-support/#connectors). Chapter 2, Creating a Java Connector, on page 13 explains which files you need to copy to your application project and which files you need to customize for your application. You also need a basic installation of Novell Cloud Security Service, so you can import your connector and test its functionality.
Getting Started
1.1.3 Programming Skills

In addition to Java programming skills, you need to be familiar with the following technologies: XML: You must have basic XML skills, including a reading knowledge of the compact syntax of the RELAX-NG schema language for XML.(RELAX is an acronym for regular expression language for XML.) If you are unfamiliar with this form of XML schema, see the following links:
RELAX NG home page (http://relaxng.org) RELAX NG Compact Syntax Tutorial (http://relaxng.org/compact-tutorial-20030326.html)
SAML: You also need to have a basic understanding of SAML 2.0 and how it supports federation and single sign-on. Spring Security: The Java connector is built on top of Spring Security. You need to have a basic understanding of this framework, especially for configuration authentication and authorization. See Spring Security (http://static.springsource.org/spring-security/site/docs/2.0.x/reference/ springsecurity.html).
1.2 Overview of the Process

The Java Connector is a servlet filter that is installed into a Web application. It is configured to filter every URL within the application, which lets it have complete control over a user's access to any of the resources in the application. The filter is typically configured to require that the user authenticate (through an Identity Broker) for any significant access to any place in the application. When such authentication is required, the filter handles redirecting the user's browser to the Identity Broker, handles the resulting SAML assertion (security token), and redirects the user back to an appropriate entry point in the application itself. The Java Connector can also provide authorization. Based on the attributes and roles declared in the assertion, the filter can be configured to conditionally grant or deny access to various locations and facilities of the application. The Java Connector is implemented as a set of Spring components, based on the Spring Security Extensions SAML module. This module in turn is based on the OpenSAML library, the standard Spring Security framework, and the Spring framework. We supply a sample Web application (Pet Clinic), which has been configured to use the Java Connector for authentication. This application contains all the necessary JAR files to create a connector for a Java application. This guide explains which files to copy from the sample application to your application and how to modify them to work with your application. Spring is configured by one or more application context files. The application context security file configures the authentication of users via SAML2 single sign-on. Given this authentication, and the attributes and roles you have specified that the customer should provide about a user, you can use any of the Spring Security authorization mechanisms to secure various parts of your application. For more details, see Section 2.2.1, Modifying the Application Context Security XML File, on page 14. The connector reserves a configurable part of the URL namespace for its own use. The URLs are the locations that the Director calls to add or remove customers and perform other dynamic configuration. This part of the namespace is secured. It uses standard Spring Security mechanisms, so that it can only be accessed by the Director. The connector and the Director use SSL mutual
10
authentication for communication. This part of the connector is also configured in the application context files. For more details, see Section 2.2.2, Modifying the Application Context Connector XML File, on page 15. In addition to copying these two XML files to your application and customizing them to work with your application, you need to complete the following tasks:
Copy two .properties files and customize them. For more information about this task, see
Section 2.3, Customizing the Property Configuration Files, on page 17.

Create a SAML assertion specification, which defines what needs to be sent to the application
in order for the application to authenticate the user and to authorize the users access to resources. or more information about this task, see Section 2.4, Creating the SAML Assertion Specification File, on page 19.
Copy the required Spring JAR files to your application. For more information, see Section 2.5,
Adding the Required JAR Files, on page 26.
Getting Started
11
12
Creating a Java Connector
A Java connector is implemented as a servlet filter. You need to configure the filter so that all access goes through the filter. The filter then enforces the authentication and authorization requirements. You also need to configure the filter so it can communicate with the Director.
Section 2.1, Setting Up, on page 13 Section 2.2, Customizing the XML Configuration Files, on page 13 Section 2.3, Customizing the Property Configuration Files, on page 17 Section 2.4, Creating the SAML Assertion Specification File, on page 19 Section 2.5, Adding the Required JAR Files, on page 26
2.1 Setting Up
1 Download the ncss-java-connector-1.0.zip file from Connector Downloads (http:// www.novell.com/products/cloud-security-service/services-and-support/#connectors). 2 Unzip the file. 3 Extract the petclinic-css.war file. 4 Examine the files in the WEB-INF directory, the WEB-INF/lib directory, and the WEB-INF/ classes directory. The following sections explain which files you need to copy to your application development environment and which files need to be modified.
2.2 Customizing the XML Configuration Files

The WEB-INF directory of the extracted petclinic-css.war file contains the following XML files:
File Description
applicationContext-connector.xml Defines and configures beans used by the connector to

hold the configuration and to report events. Copy this file to your application. See Section 2.2.1, Modifying the Application Context Security XML File, on page 14.
applicationContext-jdbc.xml
Contains database configuration options specific to the PetClinic application. Do not copy this file to your application. Configures the Spring Security beans to use SAML authentication and to protect the connector's configuration endpoints. Copy this file to your application. See Section 2.2.2, Modifying the Application Context Connector XML File, on page 15. Defines configuration settings specific to the Pet Clinic application. Do not copy this file to your application.
applicationContext-security.xml
petclinic-servlet.xml
13
File
Description
web.xml
Installs the connector into the application as a filter. Copy this file to your application. See Section 2.2.3, Modifying the Web XML File, on page 16.
2.2.1 Modifying the Application Context Security XML File

The applicationContext-security.xml file configures the Spring framework to use the Java Connector to provide authentication and authorization services. Copy this file to the project for the application. When you build your WAR file, this file needs to be deployed in the WEB-INF directory. The Java Connector is built on Spring Security. It is helpful to have a basic understanding of this framework, in particular for configuration authentication and authorization. See Spring Security (http://static.springsource.org/spring-security/site/docs/2.0.x/reference/springsecurity.html). Modify the following sections of this file to match your application.
Setting Up Authentication Requirements on page 14 Configuring Authorization Requirements on page 14
Setting Up Authentication Requirements The following section in the applicationContext-security.xml file sets up the authentication requirements:
<security:http entry-point-ref="samlEntryPoint"> <security:intercept-url pattern="/index.jsp" filters="none"/> <security:intercept-url pattern="/*.do" access="IS_AUTHENTICATED_FULLY"/> <security:intercept-url pattern="/**" access="IS_AUTHENTICATED_ANONYMOUSLY"/> <security:logout logout-url="/saml/logout" logout-success-url="/index.jsp" /> </security:http>
Any URL matching the pattern /*.do requires authentication. If an unauthenticated user navigates to a URL matching that pattern, the user is redirected to the login page. This code snippet also overrides Spring Security's logout URL with the one provided by the SAML implementation. The logout link for the Pet Clinic application is displayed to the user with the WEBINF/jsp/footer.jsp file. This file contains the following line:
<a href="<c:url value="/saml/logout"/>">Logout</a>
You need to add a similar line to the JSP file that displays the logout link for your application. Configuring Authorization Requirements The application can hide features from users who dont have the a role assigned to them. For example, the WEB-INF/jsp/owner.jsp file of the Pet Clinic application restricts the ADD VISIT button to users who have been assigned the ROLE_PETCLINIC_ADMIN role. (To view this button, log in to the Pet Clinic application as an administrator, click Find owner, click Find Owners, then click the name of an owner. The ADD VISIT button appears in the Pets and Visits section.)
14
Examine the following lines in the applicationContext-security.xml file:

<security:authorize ifAllGranted="ROLE_PETCLINIC_ADMIN"> <form method="GET" action="<c:url value="/addVisit.do"/>" name="formVisitPet${pet.id}"> <input type="hidden" name="petId" value="${pet.id}"/> <p class="submit"><input type="submit" value="Add Visit"/></p> </form> </security:authorize>
These lines allow the ADD VISIT button to appear when the user is a Pet Clinic administrator, but prevent it from appearing to unauthorized users. If your application has links that only authorized users should see, you need to modify these lines to match the roles that your application uses and the links that these roles grant to the user. These authorization lines do not prevent unauthorized users from accessing the page, if they know the URL. To limit access to that URL to only users with the ROLE_PETCLINIC_ADMIN authority, the following lines were added to the applicationContext-security.xml file:
<security:global-method-security secured-annotations="enabled"> <security:protect-pointcut expression="execution(* org.springframework.samples.petclinic.Clinic.storeVisit(..))" access="ROLE_PETCLINIC_ADMIN"/> </security:global-method-security>
Note the secured-annotations="enabled" attribute. This attribute enables Spring Security annotations so that you can secure your application at the method level by annotating them. Spring Security also supports JSR250 annotations. To enable them, add the jsr250annotations="enabled" attribute.
The Pet Clinic application does not use method-level security. The following code snippet illustrates how to use this type of security:
// Spring Security annotation @Secured( {"ROLE_SECRET_AGENT"} ) public String getSecuredData() { return "Top-Secret Data"; } // JSR250 annotation @RolesAllowed( {"ROLE_SECRET_AGENT"} ) public String getSecuredData() { return "Top-Secret Data"; }
2.2.2 Modifying the Application Context Connector XML File

The connector requires a subspace of the applications URL namespace to provide communication with the Cloud Security Service components. You specify this namespace by setting the baseURL property on the connectorListener bean in the connector's applicationContext-connector.xml file. The following lines in the file set the baseURL property to a variable, which allows it to be set in the connector.properties file.
15
<bean id="connectorListener" class="com.novell.css.connector.endpoints.ConnectorListener"> <constructor-arg ref="connectorStore" /> <property name="baseURL" value="${connector.config}" /> <property name="directorAuthority" value="${connector.director.role}" /> <security:custom-filter after="X509_FILTER" /> </bean>
Novell recommends the following:

You should copy an unchanged version of the applicationContext-connector.xml file to
your application project.

You should use the connector.config property in the connector.properties file to set up
a namespace for your connector. For more information, see Section 2.3.1, Modifying the Connector Properties File, on page 17.
2.2.3 Modifying the Web XML File

The connector is installed into a Web application by the configuration specified in the applications WEB-INF/web.xml file. In the Pet Clinic application, there are two sections in the web.xml file that control the installation of the connector. These sections need to be added to your applications web.xml file. 1 Find the following lines in the web.xml file of the Pet Clinic application:
 <context-param> <param-name>contextConfigLocation</param-name> <param-value> /WEB-INF/applicationContext-jdbc.xml /WEB-INF/applicationContext-security.xml /WEB-INF/applicationContext-connector.xml </param-value> </context-param> <filter> <filter-name>springSecurityFilterChain</filter-name> <filter-class>org.springframework.web.filter.DelegatingFilterProxy </filter-class> </filter> <filter-mapping> <filter-name>springSecurityFilterChain</filter-name> <url-pattern>/*</url-pattern> </filter-mapping>
These lines set a context parameter, specify the application context files to use, and configure the filter to apply to the whole application (see the <url-pattern> element above). 2 Remove the /WEB-INF/applicationContext-jdbc.xml line, because this configuration file is specific to the Pet Clinic application. 3 Copy these modified lines into your applications web.xml file. 4 Find the following lines in the web.xml file of the Pet Clinic application:
16
 <listener> <listener-class> org.springframework.web.context.ContextLoaderListener </listener-class> </listener>
This <listener> element ensures that Spring has an opportunity to initialize itself before the application starts. It is the ContextLoaderListener that uses the contextConfigLocation parameter to find the application context files. 5 Copy the <listener> element into your applications web.xml file. 6 Ignore the rest of the configuration parameters in the web.xml file. They are specific to the Pet Clinic application.
2.3 Customizing the Property Configuration Files

The .properties files are in the WEB-INF/classes directory of the extracted Pet Clinic WAR file.
Section 2.3.1, Modifying the Connector Properties File, on page 17 Section 2.3.2, Modifying the Event Properties File, on page 19
2.3.1 Modifying the Connector Properties File

The connector.properties file defines the value of the various placeholder properties in the applicationContext-connector.xml file and the applicationContext-connector.xml file. For most implementations, it is probably best to use the connector.properties file to set the values that are specific to your application. Some of the values are used in more than one place. Copy the connector.properties file into the WEB-INF/classes directory of your application and customize the values for the following properties: 1 Specify the DNS name of the Director. The value of the connector.director.cn property must be set to the DNS name of the Director, which is the cn of the Directors SSL certificate. This is specific to the installation. You can either include manual instructions on how to edit this property or modify your installation program to prompt the user for this value when the application is installed.
17
2 Specify the context path for the baseURL. The connector.config property specifies the path within the application for URLs that are reserved for the connector. Cloud Security Service reserves all URLs that begin with this context path. This sets the value for the ${connector.config} variable for the baseURL property in the applicationContext-connector.xml file. The default value is
connector.config = /config
Modify this value if your application is already using this context path. The absolute form of this base URL must be supplied in the Provider Console when the connector is imported into the Director. For example, suppose you are connecting to a Web application with the following characteristics:
The application is deployed at //example.com/webapp.
The DNS name of the machine is example.com, and webapp is the directory where the application is installed.
The value of the connector.config property is config.
The connector URL for this Web application is https://example.com/webapp/config/. Cloud Security Service components can access this URL, or URLs with this prefix. To ensure security, such URLs are accessed over TLS/SSL with mutual authentication. 3 Specify the context paths for the SAML endpoints. The Spring Security SAML module uses these endpoints to process various SAML protocol messages. These properties do not need to be customized.
connector.saml = /saml connector.saml.login = ${connector.saml}/login connector.saml.sso = ${connector.saml}/SSO connector.saml.metadata = ${connector.saml}/metadata
4 Specify the URL that users are directed to after a successful authentication. The default value for the connector.saml.login.default-target property is
connector.saml.login.default-target = /
This directs the user to the root of your application after authentication. Modify this value if users should be directed to a different URL. 5 Specify the URL the user should be directed to on logout. The Spring Security SAML module performs a SAML single logout. The user is redirected to this target when the logout succeeds. This connector.saml.logout.target property must be customized. 6 Specify the location of the SAML assertion specification. If you have copied the SAML assertion specification into the /WEB-INF/classes directory of your application, you do not need to modify the connector.assertion-spec property. 7 Specify a Spring Director role. This role name must be distinct from any other role used in the application. The default value is
connector.director.role = ROLE_NCSS_DIRECTOR
Modify this value only if your application is already using this role name. 8 Configure the keystore properties. You might need to modify the keystore properties so that they contain the path to your applications keystore, the password to the keystore, and the alias of the signing certificate.
18
connector.keystore.path: Specifies the path to the keystore. connector.keystore.password: Specifies the password to the keystore. connector.keystore.signing-key.alias: Specifies the alias of the signing certificate. 9 Configure the query parameter. The query value is used to identify the Identity Broker when single sign-on is initiated by the application. This is the name of the query parameter that holds the customer code associated with a particular Identity Broker. It is used by the (optional) idpDispatcher (RequestParamIdPDispatcher) bean. The default value is
connector.dispatcher.param-name = customerCode
This is one way to incorporate the customer code in a user-provided URL. You can choose to provide a different implementation of IdPDispatching that looks elsewhere in the URL. 10 Configure the limit for asynchrony between the Identity Broker and the connector clocks. If the clocks between the two machines are greater than this value, the users are denied access. The default value is 120 seconds, or two minutes. Novell strongly encourages you to use Network Time Protocol (NTP) on all servers that are part of a Cloud Security Service installation, to minimize asynchrony problems.
2.3.2 Modifying the Event Properties File

The evclient.properties file specifies the configuration for the audit event client in the connector. It specifies the path to a directory where the connector can log events. The file also specifies the epBuilder.keystorePath and epBuilder.keystorePassword. These must be set to the path and password of the keystore that holds the X.509 certificate and private key for the event system. These are currently not being used because mutual authentication has not been enabled for the event system. Copy the evclient.properties file into the WEB-INF/classes directory of your application and customize the log property: 1 Open the file. 2 Find the following line:
epBuilder.logDirPath=/tmp/ncss
3 Modify the path (/tmp/ncss) to specify the directory you want the connector to use for temporary storage of log events. 4 Save the file.
2.4 Creating the SAML Assertion Specification File

The SAML assertion specification file defines the applications requirements for the SAML assertion that authenticates the user. When the Identity Broker creates the SAML assertion, the SAML assertion must contain everything that the application requires for single sign-on. The assertion-spec.xml file is in the WEB-INF/classes directory of the extracted Pet Clinic WAR file. You need to copy this file to your application and customize it.
19
When the connector is installed, the connector proxy receives this document from the connector, and converts it into a message object for transmission to the Director. The information in the message is placed in the database for use by the Identity Brokers when generating SAML assertions. On the customer configuration panel for a connector, the SAML assertion specification defines the required mappings and the role assignments:
The Required Mappings tab specifies the attributes that the application requires for user
authentication. The SAML assertion specification file for Pet Clinic defines three attributes. When you configure this connector from the Provider Console or the Customer Console, the specification causes the following information to display:
The Role Assignments tab specifies the roles that the application supports and the requirements
the user must meet to be assigned the role. How the application uses the role is controlled entirely by the application. For example, the Pet Clinic Connector uses the administrator role to determine whether the user can see the Add Visit link. When you configure this connector from the Provider Console or the Customer Console, the specification causes the following information to display:
2.4.1 Schema
The assertion-spec.xml file uses the following schema (in Relax NG Compact Syntax):
start = element connector-saml-assertion-spec { SAMLProperties ?, (AssertionNodeGroup | AssertionNode) *, AttributesSpec }
20
The ? next to the SAMLProperties rule indicates that this element is optional. The * next to the AssertionNodeGroup and AssertionNode rule indicates that zero or more of these elements are required. The | between the two rules indicates that these are alternatives. The following sections describe the requirements of these elements and supply examples:
SAMLProperties on page 21 AssertionNodeGroup and AssertionNode on page 22 AttributeSpec on page 23 Sample SAML Assertion Specification File on page 25
2.4.2 SAMLProperties
The <saml-properties> element, which is not required, uses the following schema:
SAMLProperties = element saml-properties ( Entry * ) Entry = element entry { attribute key {text}, string }
The entry keys use the following syntax:

<entry key="key_name">value</entry>
Replace key_name with the name of the key. This string must be enclosed with double quotes. Replace value with a supported string. For example, to set the default-name-id-format key:
<saml-properties> <entry key="default-name-id-format"> urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</entry> </saml-properties>
The <entry> element supports the following key names:

Key Name Description
default-name-idformat
Specifies the name ID format that is used by default. The services SAML metadata can specify more than one name ID format. The following values are supported:
urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified destination-url

Specifies the default URL to which the user should be redirected after authentication succeeds. If this value is not present, the Identity Broker does not include the corresponding field in the assertion.
21
2.4.3 AssertionNodeGroup and AssertionNode

The AssertionNodeGroup and AssertionNode use the following schema:
AssertionNode = element assertion-node { attribute xpath {text}, attribute scope { "global" | "customer" | "user" }, element value {text} ?, # required if scope="global" element name {text}, # display name element description {text} } AssertionNodeGroup = element assertion-node-group { AssertionNode + }
The <assertion-node-group> element allows you to associate multiple <assertion-node> elements. Currently it is used to associate a name ID with a format. The <assertion-node> element supports the following attributes:
Attribute Description
xpath
Indicates the XML node (element or attribute) within the assertion that is being required or restricted. The following values are supported:
Conditions/AudienceRestriction/Audience: Restricts the assertion to a

specified domain, for example:
https://saml.salesforce.com google.com http://www.webex.com https://accounts.zoho.com/samlresponse

Check your SAML documentation for the appropriate value.
Subject/NameID: Specifies the location of the subject or name value.

This xpath is usually set to a scope of user, indicating that the value is specific to an individual user. This xpath should always be in an <assertion-node-group> with an <assertion-node> element for the Subject/NameID/@Format path and an <assertion-node> element for the Subject/Name ID path.
Subject/NameID/@Format: Specifies the format for the name identifier

as an urn:oasis value. Cloud Security Service supports the following:
urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
22
Attribute
Description
scope
Specifies the scope of the definition: global: Indicates that the node specification applies to all customers and that the node specification includes a constant value. customer: Indicates that the node specification defines a value that is specific to a customer. The <description> element should provide information about the value the customer needs to provide. user: Indicates that the node specification defines a value that is specific to a user. The <description> element should provide information about the value that needs to come from the users LDAP entry in the Identity Store.
The <assertion-node> element includes the following elements:

Element Description
<value>
Specifies the value for the <assertion-node> element. This element is required when the scope attribute is set to global. When the scope is customer or user, this element is not present. Specifies a display name for this element. This name should be no more than 20 characters. Describes the type of information that is required, either from the customer or the user.
<name> <description>
2.4.4 AttributeSpec
The AttributeSpec uses the following schema:
AttributesSpec = element connector-saml-attributes { element \attribute { attribute id {text}, attribute type { "role" | "attribute" } ?, # defaults to "attribute" element name {text}, element description {text}, element required {xsd:boolean} ?, # defaults to false element multi-valued {xsd:boolean} ?, # defaults to false element values { element value { element name {text}, element description {text} } + # one or more value specs } ? } * # zero or more attribute specs }
A SAML assertion specification can contain zero or more <connector-saml-attributes> elements. This element supports the following XML attributes:
Attribute Description
id
Specifies an identifier for this definition.
23
Attribute
Description
type
Determines the type of definition:
attribute: Indicates that the definition is an LDAP attribute definition. role: Indicates that the definition is an LDAP role definition.
If this XML attribute is not specified, the definition defaults to an LDAP attribute definition.
The <connector-saml-attributes> element includes the following elements:

Element Description
<name> <description> <required> <multi-valued>
Specifies the display name for the attribute or role. This name should be no more than 20 characters. Describes the type of information that is required for the value. Determines whether a value is required or whether the user can authenticate without having a value for this attribute or role. Specifies whether the attribute or role can have more than one value:
true: Indicates that the setting can have multiple values, separated by
commas.
false: Indicates that the setting can have only one value.
If this element is not included, the definition defaults to false.
<values>
Used only if the definition is for a role. It specifies the conditions the user must match to be assigned to the role. A role definition must have one or more <value> elements in the <values> element. The <value> element includes the following elements:
<name> <description>
Specifies the name for the role. This name appears in console as a configuration option for the connector. Specifies purpose of the role.
The Pet Clinic application uses the following lines to define two roles:
<connector-saml-assertion-spec> <connector-saml-attributes> <attribute id="roles" type="role"> <name>Roles</name> <description> The security roles for the PetClinic webapp. </description> <required>true</required> <multi-valued>true</multi-valued> <values> <value> <name>PETCLINIC_USER</name> <description> An ordinary user: authorized to use the petclinic application. </description> </value>
24
<value> <name>PETCLINIC_ADMIN</name> <description> An administrator. PETCLINIC_USER privileges, plus the ability to manage petclinic resources. </description> </value> </values> </attribute> </connector-saml-attributes> </connector-saml-assertion-spec>
2.4.5 Sample SAML Assertion Specification File

The following sample SAML assertion specification is from the Pet Clinic Connector: It sets up two roles and three attributes. Only the Email attribute is a required attribute.
<connector-saml-assertion-spec> <connector-saml-attributes> <attribute id="roles" type="role"> <name>Roles</name> <description> The security roles for the PetClinic webapp. </description> <required>true</required> <multi-valued>true</multi-valued> <values> <value> <name>PETCLINIC_USER</name> <description> An ordinary user: authorized to use the petclinic application. </description> </value> <value> <name>PETCLINIC_ADMIN</name> <description> An administrator. PETCLINIC_USER privileges, plus the ability to manage petclinic resources. </description> </value> </values> </attribute>  <attribute id="email"> <name>Email</name> <description>Email Address</description> <required>true</required> <multi-valued>false</multi-valued> </attribute> <attribute id="firstName"> <name>FirstName</name> <description>First Name</description>
25
<required>false</required> <multi-valued>false</multi-valued> </attribute> <attribute id="lastName"> <name>LastName</name> <description>Last Name</description> <required>false</required> <multi-valued>false</multi-valued> </attribute> </connector-saml-attributes> </connector-saml-assertion-spec>
2.5 Adding the Required JAR Files

Copy the following JAR files from the WEB-INF/lib directory of the extracted Pet Clinic WAR file to the lib directory of your application.
aopalliance-1.0.jar bcprov-jdk15-1.43.jar commons-codec-1.3.jar commons-collections-3.2.jar commons-httpclient-3.1.jar commons-lang-2.1.jar commons-logging-1.1.1.jar cssevclient-1.0-SNAPSHOT.jar cssevent-1.0-SNAPSHOT.jar dom4j-1.6.1.jar joda-time-1.6.jar log4j-1.2.14.jar not-yet-commons-ssl-0.3.9.jar opensaml-2.3.0.jar openws-1.3.0.jar resolver-2.9.1.jar serializer-2.9.1.jar slf4j-api-1.5.8.jar slf4j-log4j12-1.5.8.jar spring-2.5.6.jar spring-aop-2.5.6.SEC01.jar spring-beans-2.5.6.SEC01.jar spring-context-2.5.6.SEC01.jar spring-core-2.5.6.SEC01.jar spring-css-connector-1.1-SNAPSHOT.jar spring-dao-2.0.8.jar spring-security-core-2.0.5.RELEASE.jar spring-security-saml2-css-1.2-SNAPSHOT.jar spring-support-2.0.8.jar velocity-1.5.jar xalan-2.7.1.jar xercesImpl-2.9.1.jar xml-apis-2.9.1.jar xmlsec-1.4.3.jar xmltooling-1.2.1.jar
26
Setting Up the Connector for Testing

3
The section explains the required processes for using the connector:
Section 3.1, Installing the Connector, on page 27 Section 3.2, Adding the Connector to the Director, on page 29 Section 3.3, Configuring the Connector, on page 30 Section 3.4, Logging in to the Connector, on page 30 Section 3.5, Reinstalling the Connector, on page 30
3.1 Installing the Connector

After you build your application with the required connector files, use its installation program to install the application and the connector on a machine. The connector then requires some additional configuration. To set up mutual SSL between the connector and the Director, the connector and the Director need to exchange trusted root certificates so they can set up a trusted relationship. You can have your installation program prompt for the required information, then install the certificates. Or you can include manual configuration steps in your installation guide. In addition to certificate configuration, the applications server.xml file needs to be modified. The following procedures explain how to manually perform these configuration steps. You can use the information to modify your installation program to perform the steps. The instructions assume that your application is running behind Tomcat. If your application is running behind a Web server such as Apache or IIS, you need to adapt these instructions to fit your deployment. Stop the application, then perform the following configuration steps:
Section 3.1.1, Exporting the Applications Trusted Root, on page 27 Section 3.1.2, Configuring Tomcat for SSL, on page 28 Section 3.1.3, Importing the Directors Trusted Root, on page 28 Section 3.1.4, Modifying the Connectors Properties File, on page 29
3.1.1 Exporting the Applications Trusted Root

In order to import a deep connector into the Director, you need to make the trusted root certificate of the application available to the provider administrator. The following instructions assume that you have not configured Tomcat for SSL. If your application configures Tomcat for SSL, you need to complete only Step 5 and Step 6. 1 Log in to the connector machine as the root user. 2 Enter the following command to create a certificate for the Tomcat server:
27
keytool -genkey -keystore .keystore -storepass changeit -keyalg RSA keysize 1024 -dname "CN=<CONNECTOR_DNS_NAME>"
Replace <CONNECTOR_DNS_NAME> with the DNS name of the machine. IMPORTANT: For the key algorithm (-keyalg), you must use RSA. Do not use DSA. This command does not specify an expiration date. By default, keytool generates certificates that are valid for 90 days. 3 Move the .keystore file to the /usr/share/tomcat6 directory. 4 Change to the /usr/share/tomcat6 directory. 5 Export the public SSL certificate from the .keystore file by entering the following command:
keytool -export -alias mykey -keystore .keystore -storepass changeit -file connector_cert.der
6 Make the connector_cert.der file available so that provider administrators can copy the file to the machines they are going to use for accessing the Provider Console and for importing the connector.
3.1.2 Configuring Tomcat for SSL

To set up mutual SSL, you need to modify the Tomcat server.xml file: 1 Open the /usr/share/tomcat6/conf/server.xml file for editing. 2 Find the following lines:
<!-<Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true" maxThreads="150" scheme="https" secure="true" clientAuth="false" sslProtocol="TLS" /> -->
3 Remove the comment symbols () from the <Connector port=8443> element. 4 Modify the clientAuth="false" parameter to clientAuth="want". Your lines should look similar to the following:
<Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true" maxThreads="150" scheme="https" secure="true" clientAuth="want" sslProtocol="TLS" />
This modification sets up Tomcat for mutual SSL. 5 Save the file.
3.1.3 Importing the Directors Trusted Root

Place the Directors trusted root CA certificate in the Tomcat cacerts file: 1 Obtain the Directors certificate. To obtain the certificate, you can open a browser, specify the URL of the Director, then use the browsers certificate management tools to export the certificate in DER format. 2 On the connector machine, change to the jre/lib/security directory that contains the cacerts file.
28
3 Copy the Directors certificate to this directory. 4 Copy the certificate into the keystore by entering the following command:
keytool -import -noprompt -storepass changeit -keystore cacerts -file <director_cert> -trustcacerts -alias <DIRECTOR_DNS_NAME>
Replace <director_cert> with the name of the trusted root CA certificate of the director. Replace <DIRECTOR_DNS_NAME> with the DNS name of your Director.
3.1.4 Modifying the Connectors Properties File

You need to modify the connector.properties file to contain the Directors CN name. 1 Change to the /srv/tomcat6/webapps/<application>/WEB-INF/classes/ directory. 2 Open the connector.properties file for editing. 3 Find the following line in the file:
connector.director.cn = DIRECTOR-CN-GOES-HERE
Update it with the CN name of the Director. For example, if the CN of your Director is director-88.amlab.net, the line should be the following:
connector.director.cn = director-88.amlab.net
4 Save the file.
3.2 Adding the Connector to the Director

1 Log in to the Provider Console. 2 In the Connectors panel, click New Connector. 3 Fill in the New Connector form. Name: Specify a connector name that is unique to your configuration. Connector Type: Specify Automatic for your connector. URL: Specify the URL of the connector. For your connector, specify the following:
https://<CONNECTOR_DNS_NAME><:port>/<application_specific>/
The URL scheme must be https, and the URL must have a trailing slash. Replace <:port> with the port of your application if it is using a port other than 443. If it is using port 443, you do not need to specify a port. Replace <CONNECTOR_DNS_NAME> with the DNS name of the connector. Replace <application_specific> with the value you specified in Step 2 of Modifying the Connector Properties File on page 17. If you used default values, this is the deployment directory of the application with /config for example, myapp/config. SSL Certificate: Browse to and select the public certificate you exported from Tomcat on the connector machine. See Step 5 of Exporting the Applications Trusted Root on page 27. 4 Click OK, then wait until the new connector appears in the Connectors panel.
29
5 Click the Connectors tab, and wait for the status of the connector to turn green. It turns red, sending an error alert similar to the following:
Error Adding Connector, reason: ProxyException starting new Automatic connector 9c31b250-0ea6-4f88-98ac-9ab22f0df391; cause: com.sun.jersey.api.client.ClientHandlerException: javax.net.ssl.SSLHandshakeException: com.ibm.jsse2.util.g: PKIX path building failed: java.security.cert.CertPathBuilderException: unable to find valid certification path to requested target.
6 Wait two minutes while this issue is resolved and the connector turns green.
3.3 Configuring the Connector

You need to assign the connector to a customer, then configure any required mappings, and roles that you have set up for the connector. These are the settings that you configured with the SAML assertion specification.
For information on how to configure the SAML assertion specification file for your connector,
see Section 2.4, Creating the SAML Assertion Specification File, on page 19.
For sample documentation on how a provider administrator needs to configure these types of
settings for a customer, see Section A.2, Configuring the Pet Clinic Connector, on page 39.
3.4 Logging in to the Connector

1 Close all sessions of your browser. 2 Open the browser, then specify the following URL:
https://<CONNECTOR_DNS_NAME><port>/ <application>?customerCode=<Customer_ID>
Replace <CONNECTOR_DNS_NAME> with the DNS name of your connector. Replace <port> with : and the port number if the application is using a port other than 443. If the application uses port 443, the port does not need to be specified in the URL. Replace <application> with the directory where the application is deployed. Replace <Customer_ID> with the code that is assigned to each customer. (In the Provider Console, click the Customers tab, select the customer, click the Customer tab, then click the Details tab. Note the value of the Connector URL Extension. This is the value to use for the <Customer_ID>. You are redirected to the home page of the Identity Broker. You see the https:// <Identity_Broker_DNS_NAME>/nidp/ URL followed by other information. 3 Log in to the Identity Broker page with a user that has an Identity Store account. You are logged in and redirected back to the your applications home page.
3.5 Reinstalling the Connector

To reinstall an updated version of the connector, you need to remove all assigned customers, delete the connector, then add the new version. When a deep connector is removed from the Director, the database is cleaned up, which allows you to add the same version or a newer version of the connector. This procedure is useful in a testing environment. In a production environment, you
30
should develop an upgrade process that does not require the administrator to remove all assigned customers. For ideas about an upgrade process, see Section A.5, Upgrading the Pet Clinic Connector, on page 41. 1 Log in to the Provider Console. 2 Click the Connectors tab, select the connector, then click Edit. 3 In the Customer List panel, move all assigned customers to the Available Customers list. 4 Click Save Changes. 5 In the Connector List panel, select the connector, click the Delete icon, then answer Yes to the prompt. 6 Push the configuration change to each of customers: 6a Click the Customers tab, select the customer, then click the Security Services tab. 6b Click Send Configuration. 6c (Conditional) If you removed multiple customers, repeat Step 6a and Step 6b for each customer. 7 Add the new version of the connector to the Director. For instructions, see Section 3.2, Adding the Connector to the Director, on page 29.
31
32
Testing the Connector

Section 4.1, Debugging the Connector, on page 33 Section 4.2, Basic Test Cases, on page 34
4.1 Debugging the Connector

Section 4.1.1, Configuring Logging, on page 33 Section 4.1.2, Discovering Why a Connector Wont Import, on page 33 Section 4.1.3, Discovering Why Federation Fails, on page 34 Section 4.1.4, Useful Tools, on page 34
4.1.1 Configuring Logging

You should set the logging level on both the Director and the Identity Broker to Debug or higher. 1 Configure Director logging: 1a Log in to the Provider Console as a Super Admin user 1b Click the Reporting tab, then click Logging. 1c In the Settings panel, click Edit. 1d For each category, set the log level to Debug. 1e Click Save Changes. 2 Configure Identity Broker logging: 2a Click the Customers tab. 2b In the Customer Settings panel, click the Reporting tab, then click Logging. 2c In the Settings panel, click Edit. 2d For each category, set the log level to All. 2e Click Save Changes. 3 Push the changes to the Identity Broker of the customer: 3a Click the Customers tab. 3b Click the Security Services tab in the Customer Settings panel. 3c In the Identity Brokers tab, click Send Configuration.
4.1.2 Discovering Why a Connector Wont Import

1 Log in to the Director machine as the root user. 2 Change to the /var/log/ncss directory. 3 Open the Provider-<guid>.log file. 4 Search for failure messages from the connector-proxy and the connector-manager modules.
Testing the Connector
33
4.1.3 Discovering Why Federation Fails

When federation fails, you need to verify the metadata. The information is in the SAMLRequest, which needs to be decoded to view. If you have set logging to Debug on the Identity Broker, the SAMLRequest is in the /var/log/ncss/Customer-<guid>.log file. If you have enabled live HTTP headers in the browser that you are using to log in, the SAMLRequest is in the output.
4.1.4 Useful Tools

Live HTTP header plug-in for your browser. This tool allows you to view the SAML response information that is sent from the connector to the browser when a user requests authentication. A free version of this tool is available on the Internet for most browsers. SAML 2.0 decoder. This tool allows you to insert the encoded SAML response, and the tool decodes it so you can examine what was sent in the POST. A number free decoders are available on the Internet. You might want to try the SAML 2.0 Debugger (https://rnd.feide.no/simplesaml/ module.php/saml2debug/debug.php). After decoding the SAML response, verify that the assertion contains a valid certificate and that it contains the required LDAP attributes.
4.2 Basic Test Cases

As you test your connector, you need to ensure that the following functionality works:
The connector imports into the Director. The connector can be added to a customer. The connector can be removed from a customer. The connector can be deleted from the Director. The required settings and required mappings appear in the Provider Console and in the
Customer Console, and the settings are configurable.

Users can log in, and the users are redirected to the appropriate page on the service. If the service supports single logout, the user is logged out from both the service and the
Identity Broker.
The connector logs messages to the log files. The connector accurately reports on the number of unique sessions created each day in the
reports on the Accounting tab.

The connector can be added to multiple customers without any loss of functionality.
34
Sample Pet Clinic Connector Guide

Section A.1, Installing the Pet Clinic Demo Connector, on page 35 Section A.2, Configuring the Pet Clinic Connector, on page 39 Section A.3, Logging In to the Pet Clinic Application, on page 40 Section A.4, Changing the Director Certificate, on page 40 Section A.5, Upgrading the Pet Clinic Connector, on page 41
A.1 Installing the Pet Clinic Demo Connector

The Pet Clinic Connector sets up authentication with an open-source Pet Clinic application. The application doesnt have a lot functionality, but it does allow you to configure roles for an administrator. When the application receives a SAML assertion that contains the authorization for the administration role, that information is displayed on the home page. It also grants access to the Add Visit option on the Owner Information page.
Section A.1.1, Verifying Machine Requirements, on page 35 Section A.1.2, Installing Certificates and the Pet Clinic Software, on page 35 Section A.1.3, Adding the Pet Clinic Demo Connector into the Director, on page 38
A.1.1 Verifying Machine Requirements

You need a machine with the following software:
SLES 11 SP1, 32-bit or 64-bit Sun 1.6 JDK/JVM
The IBM JDK seems to have problems with SSL connections. For this release, we recommend that you use the JDK from Sun.
Tomcat 6.0 DNS name for the machine
A.1.2 Installing Certificates and the Pet Clinic Software

To set up a trusted relationship between the Pet Clinic Connector and the Director, you need to install the Directors public certificate on the Pet Clinic machine. For instructions on how to obtain this certificate from the Director, see Obtaining the Director Certificate in the Cloud Security Service 1.0 SP2 Installation Guide. 1 Log in to the machine as the root user. 2 Configure Tomcat for SSL: 2a To create a certificate for your Tomcat server, enter the following command:
35
keytool -genkey -keystore .keystore -storepass changeit -keyalg RSA keysize 1024 -dname "CN=<CONNECTOR_DNS_NAME>"
Replace <CONNECTOR_DNS_NAME> with the DNS name of the machine. 2b Move the .keystore file to the /usr/share/tomcat6 directory. 2c Change to the /usr/share/tomcat6 directory. 2d Export the public SSL certificate from the .keystore file by entering the following command:
keytool -export -alias mykey -keystore .keystore -storepass changeit file connector_cert.der
2e Copy the connector_cert.der file to the machine you are going to use for accessing the Provider Console and for importing the connector. 3 Modify the Tomcat server.xml file: 3a Open the /usr/share/tomcat6/conf/server.xml file for editing. 3b Find the following lines:
<!-<Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true" maxThreads="150" scheme="https" secure="true" clientAuth="false" sslProtocol="TLS" /> -->
3c Remove the comment symbols () from the <Connector port=8443> element. 3d Modify the clientAuth="false" parameter to clientAuth="want". Your lines should look similar to the following:
<Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true" maxThreads="150" scheme="https" secure="true" clientAuth="want" sslProtocol="TLS" />
This modification sets up the connector for mutual SSL. 3e Save the file. 4 Place the Directors trusted root CA certificate in the cacerts file that Tomcat uses: 4a On the connector machine, search for the JDK security directory that contains the cacerts file. 4b Change to the jre/lib/security directory. 4c Copy the certificate to this directory. For instructions on how to obtain this certificate from the Director, see Obtaining the Director Certificate in the Cloud Security Service 1.0 SP2 Installation Guide. 4d Copy the certificate into the keystore by entering the following command:
keytool -import -noprompt -storepass changeit -keystore cacerts -file <director_cert> -trustcacerts -alias <DIRECTOR_DNS_NAME>
Replace <director_cert> with the name of the trusted root CA certificate of the director. Replace <DIRECTOR_DNS_NAME> with the DNS name of your Director. 5 Download the Pet Clinic Connector file to the connector machine: 5a Create a directory for the file and change to that directory.
36
5b Download the file to the directory you created. For the filename and download location, download the Novell Cloud Security Service Apache Platform Connector Integration Kit from Connector Downloads (http:// www.novell.com/products/cloud-security-service/services-and-support/#connectors). 5c Enter the following command to unzip the file:
unzip <filename>
Replace <filename> with the name of the zip file. 5d Change to the linux/connectors/spring directory. 5e To copy the petclinic.war to the Tomcat webapps directory, enter the following command:
cp petclinic-css.war /srv/tomcat6/webapps/
5f Start Tomcat (if it is not already running) and allow it to deploy the petclinic-css.war. 6 Modify the connector.properties file to contain the Directors CN name and to change the SAML keystore: 6a Change to the /srv/tomcat6/webapps/petclinic-css/WEB-INF/classes/ directory. 6b Open the connector.properties file for editing. 6c Find the following line in the file:
Update it with the CN name of the Director. If the CN of your Director is director88.amlab.net, the line should be the following: connector.director.cn = director-88.amlab.net
6d Find the following lines:

connector.keystore.path = classpath:samlKeystore.jks connector.keystore.password = novell connector.keystore.signing-key.alias = petclinic-certificate
6e Change them to the following values:

connector.keystore.path =/usr/share/tomcat6/.keystore connector.keystore.password = changeit connector.keystore.signing-key.alias = mykey
6f Save the file. 7 (Conditional) If you are going to run any kind of stress test against this demo application, you need to modify the tomcat6 configuration file. The following modifications enable the application so that it has enough memory and can perform garbage collection. 7a Log in to the connector machine as the root user. 7b Change to the /etc/sysconfig directory. 7c Open the tomcat6 file for editing. 7d Add the following lines:
37
JAVA_OPTS="-server -Xmx1300m -Xss128k -XX:+UseConcMarkSweepGC" CATALINA_OPTS="-Dsun.net.client.defaultConnectTimeout=29000 -Dsun.net.client.defaultReadTimeout=28000 -Djavax.net.ssl.sessionCacheSize=10000 -Daxis.EngineConfigFactory=com.novell.nidp.liberty.wsf.axis. NIDPAxisEngineConfigFactory -Dnids.freemem.threshold=10 -DDisableRootCARevocation=true"
If you copy and paste these lines, make sure to remove any extra white space. In this example, the line has been wrapped for presentation, but this text should be entered all on one line within the tomcat6 file. 7e Save the file. 8 (Conditional) If you have a firewall between the connector and the Director, ports 8080 and 8443 need to be open. 9 Restart Tomcat with the following command:
rctomcat6 restart
Your connector is now installed and running. 10 Continue with Section A.1.3, Adding the Pet Clinic Demo Connector into the Director, on page 38.
A.1.3 Adding the Pet Clinic Demo Connector into the Director
1 Log in to the Provider Console. 2 In the Connectors panel, click New Connector. 3 Fill in the New Connector form. Name: Specify a connector name that is unique to your configuration. Connector Type: Specify Automatic for the Pet Clinic Connector. URL: Specify the URL of the connector. For the Pet Clinic Connector, specify the following:
https://<CONNECTOR_DNS_NAME>:8443/petclinic-css/config/
The URL scheme must be https, and the URL must have a trailing slash. Replace <CONNECTOR_DNS_NAME> with the DNS name of the connector. SSL Certificate: Browse to and select the public certificate you exported from Tomcat on the connector machine. See Step 5 and Step 6 on page 28. 4 Click OK, then wait until the new connector appears in the Connectors panel. 5 Click the Connectors tab, and wait for the status of the connector to turn green. It turns red, sending an error alert similar to the following:
Error Adding Connector, reason: ProxyException starting new Automatic connector 9c31b250-0ea6-4f88-98ac-9ab22f0df391; cause: com.sun.jersey.api.client.ClientHandlerException: javax.net.ssl.SSLHandshakeException: com.ibm.jsse2.util.g: PKIX path building failed: java.security.cert.CertPathBuilderException: unable to find valid certification path to requested target.
6 Wait two minutes while this issue is resolved and the connector turns green. 7 Continue with Section A.2, Configuring the Pet Clinic Connector, on page 39.
38
A.2 Configuring the Pet Clinic Connector

The following instructions explain how to set up the mappings required by the Pet Clinic application. 1 Log in to the Provider Console. 2 Click the Customers tab. 3 In the Customer Settings panel, click the Connectors tab. 4 Select the Pet Clinic connector in the Connector List. 5 In the Connector Settings panel, click Edit. 6 Click the Required Mappings tab, then map the attributes so that they match what is in your LDAP server. If you are using an eDirectory server for the Identity Store, add the following mappings: Email: Map it to the mail attribute, select LDAP_USER_ATTRIBUTE for the type, then click Save. FirstName: Map it to the givenName attribute, select LDAP_USER_ATTRIBUTE for the type, then click Save. LastName: Map it to the sn attribute, select LDAP_USER_ATTRIBUTE for the type, then click Save. If your Identity Store uses different names for these standard LDAP attributes, modify these mappings to match the attribute names in the Identity Store. If you select STRING for the type, the Identity Broker does not obtain a value from the Identity Store; it assigns the specified mapping value to all users. 7 (Optional) Click the Role Assignments tab to restrict who can manage the Pet Clinic application: 7a For the PETCLINIC_ADMIN role, click New in the Role:PETCLINIC_ADMIN panel. 7b In the drop-down menu, select one of the following:
LDAP_ATTRIBUTE_CONTAINS_STRING: Allows you to select an LDAP
attribute that contains the value the user must have in order to obtain the PETCLINIC_ADMIN role. In the Attribute Name field, specify the name of the attribute, and in the Value field, specify the string you want the user to match. The Identity Broker performs a substring compare, so if you specify man for the value, the string matches manager as well as woman. To save your changes, click Save.
USER_IS_MEMBER_OF_GROUP: Allows you to select an LDAP group from
your Identity Store. All users who are members of this group gain the
PETCLINIC_ADMIN role. For a Group Name field, specify the typed DN of the group, such as cn=managers,cn=users,dc=bcf2,dc=provo,dc=novell,dc=com, then
click Save. If you add more that one condition, the conditions are ANDed together, and the user must match all the conditions in order to be assigned the role. 7c For the PETCLINIC_USER role, click New in the Role: PETCLINIC_ADMIN panel. 7d In the drop-down menu, select one of the following:
LDAP_ATTRIBUTE_CONTAINS_STRING: Allows you to select an LDAP
attribute that contains the value the user must have in order to obtain the PETCLINIC_USER role. In the Attribute Name field, specify the name of the attribute,
39
and in the Value field, specify the string you want the user to match. The Identity Broker performs a substring compare, so if you specify man for the value, the string matches mankind as well as woman. To save your changes, click Save.
USER_IS_MEMBER_OF_GROUP: Allows you to select an LDAP group from
your Identity Store. All users who are members of this group gain the
PETCLINIC_USER role. For a Group Name field, specify the typed DN of the group, such as cn=managers,cn=users,dc=bcf2,dc=provo,dc=novell,dc=com, then
click Save. If you add more that one condition, the conditions are ANDed together, and the user must match all the conditions in order to be assigned the role. 8 (Optional) Click the Authorization Policy tab to control access to the application by specifying conditions in addition to requiring authentication credentials. For configuration information, see Configuring an Authorization Policy in the Cloud Security Service 1.0 SP2 Provider Administration Guide. 9 Click Save Changes in the Connector Settings panel. These settings are now saved to the Secure Bridge. 10 Push the configuration to the Identity Broker: 10a Click the Security Services tab. 10b In the Identity Brokers tab, click Send Configuration. 11 When the health turns green, continue with Section A.3, Logging In to the Pet Clinic Application, on page 40.
A.3 Logging In to the Pet Clinic Application

1 Close all sessions of your browser. 2 Open the browser, then specify the following URL:
https://<CONNECTOR_DNS_NAME>:8443/petclinic-css/ welcome.do?customerCode=<Customer_ID>
Replace <CONNECTOR_DNS_NAME> with the DNS name of your connector. Replace <Customer_ID> with the Connector URL Extension. (Click the Customers tab, select the customer, then click the Customer tab > Details.) You are redirected to the home page of the Identity Broker. You see the https:// <Security_Broker_DNS_NAME>/nidp/ URL followed by other information. 3 Log in to the Identity Broker page with a user that exists in the Identity Store. You are authenticated and redirected back to the home page of the Pet Clinic application.
A.4 Changing the Director Certificate

If you have changed the Director keypair, you need re-establish the trust relationship with the connector by updating the connector trust store.
If you replaced the Director keypair with a keypair signed by a CA, you need to have the public
certificate of the CA that signed the Director keypair available.

If you replaced the Director keypair with a self-signed keypair, you need to have the leaf
certificate of the Director available.
40
To update the connector trust store: 1 Log in to the connector machine as the root user. 2 Search for the JDK security directory that contains the cacerts file. 3 Change to the jre/lib/security directory. 4 Copy the certificate file to the connector machine. 5 Copy the certificate into the keystore by entering the following command:
keytool -import -noprompt -storepass changeit -keystore cacerts -file <director>.der -trustcacerts -alias <DIRECTOR_DNS_NAME>
Replace <director> with the filename of the certificate. Replace <DIRECTOR_DNS_NAME> with the DNS name of your Director. 6 Restart Tomcat.
rctomcat6 restart
A.5 Upgrading the Pet Clinic Connector

Upgrading preserves the customer assignments and configurations. This section explains the process for upgrading the Pet Clinic Connector. 1 Log in to the Pet Clinic machine as the root user. 2 Shut down Tomcat with the following command:
rctomcat6 stop
3 Delete the Pet Clinic .war files by entering the following commands:
rm -r /srv/tomcat6/webapps/petclinic-css rm /srv/tomcat6/webapps/petclinic-css.war
4 Delete the related connector files by entering the following commands:

rm -r /var/cache/tomcat6/work/catalina/localhost/petclinic-css rm /var/cache/tomcat6/work/catalina/localhost/petclinic-css.xml
5 Download a new version of the connector. 6 Unzip the file. 7 Copy the new .war file to the /srv/tomcat6/webapps directory. 8 Start Tomcat so that the .war file can be deployed:
rctomcat6 start
9 After the .war file has unpacked, modify the connector.properties file: 9a Change to the /srv/tomcat6/webapps/petclinic-css/WEB-INF/classes directory. 9b Open the connector.properties file for editing. 9c Find the following line in the file:
Update it with the CN name of the Director. For example, if the CN of your Director is director-88.amlab.net, the line should be the following:
connector.director.cn = director-88.amlab.net
9d Find the following lines:
41
connector.keystore.path = classpath:samlKeystore.jks connector.keystore.password = novell connector.keystore.signing-key.alias = petclinic-certificate
9e Change them to the following values:

connector.keystore.path =/usr/share/tomcat6/.keystore connector.keystore.password = changeit connector.keystore.signing-key.alias = mykey
9f Save the file. 10 Restart Tomcat with the following command:

rctomcat6 restart
42

Java Platform

Transféré par

Informations du document

Description originale:

Copyright

Formats disponibles

Partager ce document

Partager ou intégrer le document

Options de partage

Avez-vous trouvé ce document utile ?

Ce contenu est-il inapproprié ?

Droits d'auteur :

Formats disponibles

Java Platform

Transféré par

Droits d'auteur :

Formats disponibles

AUTHORIZED DOCUMENTATION

Java Platform Connector 1.0 Integration Guide

Cloud Security Service

Cloud Security Service Java Platform Connector 1.0 Integration Guide

2 Creating a Java Connector

3 Setting Up the Connector for Testing

3.2 3.3 3.4 3.5

4 Testing the Connector

A Sample Pet Clinic Connector Guide

A.2 A.3 A.4 A.5

Cloud Security Service Java Platform Connector 1.0 Integration Guide

About This Guide

About This Guide

Cloud Security Service Java Platform Connector 1.0 Integration Guide

1.1.1 Application Requirements

and password for authentication.

1.1.2 Development Environment

1.1.3 Programming Skills

1.2 Overview of the Process

Cloud Security Service Java Platform Connector 1.0 Integration Guide

Section 2.3, Customizing the Property Configuration Files, on page 17.

Adding the Required JAR Files, on page 26.

Cloud Security Service Java Platform Connector 1.0 Integration Guide

Creating a Java Connector

2.2 Customizing the XML Configuration Files

applicationContext-connector.xml Defines and configures beans used by the connector to

Creating a Java Connector

2.2.1 Modifying the Application Context Security XML File

Cloud Security Service Java Platform Connector 1.0 Integration Guide

Examine the following lines in the applicationContext-security.xml file:

2.2.2 Modifying the Application Context Connector XML File

Creating a Java Connector

Novell recommends the following:

your application project.

2.2.3 Modifying the Web XML File

Cloud Security Service Java Platform Connector 1.0 Integration Guide

2.3 Customizing the Property Configuration Files

2.3.1 Modifying the Connector Properties File

Creating a Java Connector

Cloud Security Service Java Platform Connector 1.0 Integration Guide

2.3.2 Modifying the Event Properties File

2.4 Creating the SAML Assertion Specification File

Creating a Java Connector

Cloud Security Service Java Platform Connector 1.0 Integration Guide

The entry keys use the following syntax:

The <entry> element supports the following key names:

urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified destination-url

Creating a Java Connector

2.4.3 AssertionNodeGroup and AssertionNode

Conditions/AudienceRestriction/Audience: Restricts the assertion to a

https://saml.salesforce.com google.com http://www.webex.com https://accounts.zoho.com/samlresponse

Subject/NameID: Specifies the location of the subject or name value.

Subject/NameID/@Format: Specifies the format for the name identifier

Cloud Security Service Java Platform Connector 1.0 Integration Guide

The <assertion-node> element includes the following elements:

Specifies an identifier for this definition.

Creating a Java Connector

Determines the type of definition:

The <connector-saml-attributes> element includes the following elements:

<name> <description> <required> <multi-valued>

Cloud Security Service Java Platform Connector 1.0 Integration Guide

2.4.5 Sample SAML Assertion Specification File

Creating a Java Connector