PingFederate Administrator`s Manual

Add to my manuals
402 Pages

advertisement

PingFederate Administrator`s Manual | Manualzz
Preface
About This Manual
This manual provides information about using Ping Identity’s PingFederate to
deploy a secure Internet single sign-on (SSO) solution based on the latest
security and e-business standards.
Overview
The manual consists of:
Administrator’s Manual
•
Chapter 1, “Key Concepts” — A discussion of central concepts needed to
understand Internet SSO, the WS-Trust Security Token Service (STS), and
PingFederate deployment and administration.
•
Chapter 2, “System Administration” — Information about maintaining the
PingFederate server and deployment, using log files, managing users, and
handling other administrative functions.
•
Chapter 3, “System Settings” — How to configure your local PingFederate
server settings.
•
Chapter 4, “Security Management” — Information about importing,
exporting, and maintaining certificates and keys in PingFederate.
•
Chapter 5, “Identity Provider SSO Configuration” — How to configure
PingFederate to act as an Identity Provider (IdP) and establish connections
to Service Providers.
•
Chapter 6, “Service Provider SSO Configuration” — How to configure
PingFederate to act as a Service Provider (SP) and establish connections to
Identity Providers.
•
Chapter 7, “WS-Trust STS Configuration” — How to configure
PingFederate to act as a Security Token Service for Web Service Clients and
Providers in either an IdP or SP environment.
1
Preface
•
Appendix A, “OpenToken Adapter Configuration” — How to configure
PingFederate to use the packaged OpenToken Adapter for interfacing with
your Web applications.
•
Appendix B, “LDAP Adapter Configuration” — How to configure
PingFederate to use the packaged LDAP Authentication Adapter.
•
Appendix C, “Application Endpoints” — Detailed information about using
PingFederate connection endpoints for Web single sign-on and single
logout.
•
Appendix D, “Web Service Interfaces” — Information developers can use to
automate connection-configuration management and runtime SSO partner
discovery.
•
Appendix E, “Using Attribute Mapping Expressions” — How to enable and
use expressions in conjunction with mapping attributes.
•
Appendix F, “Troubleshooting” — Solutions for difficulties that may be
encountered.
•
Glossary — Definitions of terms used in the manual and in identity
federation parlance.
•
List of Acronyms
Intended Audience
This manual is intended for security and network administrators and other IT
professionals responsible for identity management among business entities, both
internal and external.
Note: The information in this manual is presented from the viewpoint of
an administrative user with full permissions (see “Account
Management” on page 36).
Text Conventions
This document uses the text conventions identified below.
Table 1: Text Conventions
2
Convention
Description
Fixed Width
Indicates text that must be typed exactly as shown in
the instructions. Also used to represent program code,
file names, and directory paths.
Blue text
Indicates hypertext links.
Italic
Used for emphasis and document titles.
X [text]
Used for procedures where only one step is required.
PingFederate 6
Other Documentation
Table 1: Text Conventions (Continued)
Convention
Description
Sans serif
Identifies descriptive text on a user-interface screen.
Example: “Print Document dialog”
Sans serif bold
Identifies menu items, navigational links, or buttons.
For example: Click Save.
Other Documentation
Unless otherwise noted, the documents listed below are located in your
PingFederate installation’s pingfederate/docs directory.
Tip: PingFederate provides context-sensitive online Help. Click Help in
the upper-right portion of the administrative console for immediate,
relevant guidance and links to related information.
Getting Started – Provides an introduction to secure Internet SSO and
PingFederate, including background information about federated identity
management and standards, product installation instructions, and a primer on
using the PingFederate administrative console.
Quick-Start Guide – Provides instructions for deploying a preconfigured
PingFederate server to run with example Web applications. Ping Identity
recommends that you follow this Guide as a first step to establishing a simple
identity federation between two Web applications and to familiarize yourself
with PingFederate. The Guide is located in the quickstart/docs directory.
Integration Overview – A high-level description of options available for
integrating identity-management systems and applications with PingFederate.
Server Clustering Guide – Describes how to deploy PingFederate in a cluster
to increase throughput and availability.
SDK Developer’s Guide – Provides technical guidance for using the Java
Software Developer Kit for PingFederate version 4 and higher. This Guide is
located in the pingfederate/sdk directory.
Web Resources – Ping Identity continually updates its Web site with general
and technical information in the form of White Papers, FAQs, Tech Notes, and
other resources—www.pingidentity.com.
PingFederate documents may include hypertext links to Web sites that provide
installation instructions, file downloads, and reference documentation. These
links were tested prior to publication, but they may not remain current
throughout the life of these documents. Please contact Ping Identity Support
([email protected]) if you encounter a problem.
Administrator’s Manual
3
Preface
4
PingFederate 6
PingFederate 6
®
Administrator’s Manual
© 2009 Ping Identity® Corporation. All rights reserved.
Part Number 3007-130
Version 6.0
April, 2009
Ping Identity Corporation
1099 18th Street, Suite 2950
Denver, CO 80202
U.S.A.
Phone: 877.898.2905 (+1 303.468.2882 outside North America)
Fax: 303.468.2909
Web Site: http://www.pingidentity.com
Trademarks
PingFederate, Ping Identity, the Ping Identity logo, and Auto-Connect are trademarks or registered trademarks of
Ping Identity Corporation.
All other trademarks or registered trademarks are the property of their respective owners.
Disclaimer
This document is provided for informational purposes only, and the information herein is subject to change without
notice. Ping Identity Corporation does not provide any warranties and specifically disclaims any liability in
connection with this document.
Contents
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Chapter 1
About This Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Intended Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Text Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Other Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Key Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Connection Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
About WS-Trust STS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Connection-Based Policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
IdP Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
SP Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Token Processors and Generators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Bundled Token Plug-ins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Commercial Token Plug-ins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Client SDKs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
SSO Integration Kits and Adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Bundled Adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Commercial Adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Software Development Kit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Identity Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Account Linking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Linking Permission and “Defederation” . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
SP Affiliations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Account Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
About Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Attribute Contracts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Adapter Contracts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Administrator’s Manual
iii
Contents
Chapter 2
Extended Adapter Contract . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
STS Token Contracts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Extended Token Generator Contract . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Data Stores . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Attribute Masking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Certificates, SSL, and XML Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Digital Signatures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Message Signing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Signature Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Certificate Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Digital Signing Policy Coordination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Secure Sockets Layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
SAML SSL/TLS Scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Verifying Trusted Certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
XML Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Using Auto-Connect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Providing Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Runtime Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Auto-Connect Security Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
User Provisioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
SaaS Provisioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Express Provisioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Federation Planning Checklist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Configuration Data Exchange . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
IdP to SP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
SP to IdP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Mutual Settings Between Parties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
System Administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Starting and Stopping PingFederate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Log File Generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Administrator Audit Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Runtime Transaction Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Transaction Logging Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Exporting Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Defining Metadata Attribute Contracts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Choosing a Metadata Signing Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
XML Encryption Certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Completing the Export . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Signing XML Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Using the Configuration Archive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Account Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Setting or Resetting Passwords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Changing Passwords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Managing Email Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
iv
PingFederate 6
Chapter 3
Using Virtual Host Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Changing Configuration Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Installing a New License Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Automating Configuration Migration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Using the Migration Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
SaaS Provisioning CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Customizing User-Facing Screens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
System Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Chapter 4
Managing Server Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Setting Administration Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Entering System Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Configuring Runtime Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Configuring Runtime Reporting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Using SNMP Monitoring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Runtime Monitoring Using JMX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Managing Accounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Choosing Roles and Protocols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Specifying Federation Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Configuring SaaS Provisioning Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Configuring Auto-Connect Metadata Signing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Configuring Auto-Connect Metadata Lifetime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Saving and Editing Server Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Managing Data Stores . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Configuring a JDBC Database Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Setting Advanced Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Configuring an LDAP Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Defining an LDAP Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Setting Pooling Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Configuring a Custom Data Store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Configuring a Custom Data Store Instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Invoking Adapter Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Editing and Saving a Data Store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Configuring IdP Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Standard IdP Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Choosing Domain Cookie Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Configuring a Common Domain Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Configuring a Local Common Domain Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Editing and Saving the Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
IdP Discovery Using a Persistent Cookie . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Security Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Trusted CAs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
SSL Server Certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
SSL Client Keys & Certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Digital Signing and Decryption Keys & Certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
Administrator’s Manual
v
Contents
Chapter 5
Application Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Certificate Revocation Checking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Identity Provider SSO Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
Application Integration Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
Configuring IdP Adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
Selecting an IdP Adapter Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Configuring an IdP Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
Invoking Adapter Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Extending an Adapter Contract . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Setting Pseudonym Values and Masking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Selecting an Authentication Context . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
Editing and Saving Adapter Instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
Configuring a Default URL and Error Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
Viewing Application Endpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Viewing Protocol Endpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Managing SP Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
Accessing Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Using the Main Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Using the Manage Connections Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
Choosing a Connection Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Choosing Connection Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Importing Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Importing a Verification Certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Viewing the Metadata Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
General Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Configuring Browser-Based SSO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
Configuration Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
Choosing Profiles (SAML 2.0) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
Setting an Assertion Lifetime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
Assertion Creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
Configuring Protocol Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
Editing and Saving Browser SSO Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
Configuring the Attribute Query Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
Defining Retrievable Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
Choosing a Data Store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
Configuring Data Store Lookup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
Attribute Mapping Fulfillment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
Specifying Security Policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
Editing and Saving Attribute Query Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
Configuring Credentials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
Configuring Back-Channel Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
Configuring Digital Signature Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
Selecting Signature Verification Certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
Selecting an Encryption Certificate (SAML) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
Selecting a Decryption Key (SAML) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
Editing and Saving Credential Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
vi
PingFederate 6
Chapter 6
Configuring SaaS Provisioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
Defining a Provisioning Target . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
Managing SaaS Channels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
Specifying Channel Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
Identifying the Source Data Store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
Modifying Source Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
Specifying a Source Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
Mapping Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
Channel Activation and Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
Connection Activation and Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
Defining SP Affiliations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
Using the Manage Affiliations Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
Importing Affiliation Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
Entering Affiliation Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
Managing Affiliation Membership . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
Configuring SP Auto-Connect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
Initial Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
Setting an Assertion Lifetime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
Choosing a Signing Certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
Configuring Assertion Creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
Auto-Connect Activation and Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
Specifying Allowed SP Domains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
Service Provider SSO Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
Application Integration Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
Configuring SP Adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
Creating an Adapter Instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
Configuring an Adapter Instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
Invoking Adapter Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
Extending an Adapter Contract . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
Editing and Saving SP Adapter Instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
Mapping URLs to Adapter Instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
Configuring Default URLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
Viewing Application Endpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
Federation Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
Attribute Requester Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
Viewing Protocol Endpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
Managing IdP Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
Accessing Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
Using the Main Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
Using the Manage Connections Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
Choosing a Connection Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
Choosing Connection Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
Importing Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
Importing a Verification Certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
Viewing the Metadata Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
General Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
Administrator’s Manual
vii
Contents
Chapter 7
Configuring Browser-Based SSO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
Configuration Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
Choosing SAML Profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
User-Session Creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
Configuring Protocol Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
Editing and Saving Browser SSO Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
User Provisioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
Choosing an Event Trigger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
Selecting Attribute Sources (SAML 2.0) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
Identifying the User Repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
Specifying User-Record Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
Specifying a Unique Identifier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
Identifying Provisioning Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
Mapping Attributes to User Accounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
Using the Provisioning Summary Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
Configuring the Attribute Query Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
Setting the Attribute Authority Service URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
Mapping Attribute Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
Specifying Security Policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
Editing and Saving Attribute Query Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
Configuring Credentials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
Configuring Back-Channel Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
Configuring Digital Signature Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267
Selecting Signature Verification Certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
Selecting an Encryption Certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
Selecting a Decryption Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
Editing and Saving Credential Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
Connection Activation and Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
Configuring IdP Auto-Connect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272
Configuring the Initial Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
Choosing a Signing Certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
Configuring User-Session Creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
Connection Activation and Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274
Specifying Allowed IdP Domains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
WS-Trust STS Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
Server Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
Enabling the WS-Trust STS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
Configuring STS Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
Selecting Authentication Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
Configuring Basic Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
Configuring Mutual SSL Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
Using the WS-Trust STS Settings Summary Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
IdP Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
Configuring Token Processors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
viii
PingFederate 6
Appendix A
Selecting a Token Processor Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
Configuring a SAML Token Processor Instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
Extending a Processor Contract . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
Setting Attribute Masking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
Editing and Saving Processor Instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289
Configuring SP Connections for STS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289
Configuring Protocol Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290
Setting a Token Lifetime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291
Configuring Token Creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291
SP Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308
Configuring Token Generators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308
Selecting a Token Generator Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
Configuring a Token Generator Instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
Extending a Generator Contract . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
Editing and Saving Generator Instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311
Configuring IdP Connections for STS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311
Configuring Protocol Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
Configuring Token Generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
OpenToken Adapter Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
Appendix B
Configuring the IdP OpenToken Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331
Configuring the SP OpenToken Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334
LDAP Adapter Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337
Appendix C
Configuring the IdP LDAP Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339
Configuring the SP LDAP Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342
Application Endpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347
Appendix D
IdP Endpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348
SP Endpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351
Maintenance Endpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356
Web Service Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
Appendix E
Connection Management Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
Exporting a Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358
Exporting Manually . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358
Using the Connection Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358
Importing Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359
Code Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359
Deleting Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360
Code Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360
Cluster Configuration Replication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360
Code Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361
Validation Disclaimer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361
SSO Directory Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361
Code Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362
SOAP Request and Response Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364
Using Attribute Mapping Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367
About OGNL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367
Administrator’s Manual
ix
Contents
Appendix F
Enabling/Disabling Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368
Using the OGNL Edit Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370
Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371
Data Stores . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371
Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372
Protocols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372
Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373
Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375
List of Acronyms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381
x
PingFederate 6
Chapter
1
Key Concepts
This chapter provides background information and preparation to help you
understand and use PingFederate:
•
“Connection Types” below
•
“About WS-Trust STS” on page 2
•
“SSO Integration Kits and Adapters” on page 4
•
“Identity Mapping” on page 5
•
“About Attributes” on page 7
•
“Certificates, SSL, and XML Encryption” on page 10
•
“Using Auto-Connect” on page 15
•
“User Provisioning” on page 18
•
“Federation Planning Checklist” on page 20
Tip: For an introduction to secure Internet single sign-on (SSO),
federated identity management, and PingFederate product features,
see the Getting Started manual in the pingfederate/docs directory.
Connection Types
PingFederate features an integrated administrative console for configuring two
kinds of connections to identity-federation partners:
•
Administrator’s Manual
Browser-based SSO – Also called Browser SSO in the administrative
console, this term is often used to refer to standards-based secure Internet
SSO, which generally depends on a user’s browser to transport identity
assertions and other messaging between partner endpoints (see the
“Supported Standards” chapter in Getting Started).
1
Chapter 1
Key Concepts
•
WS-Trust STS – This type of connection employs the PingFederate Security
Token Service (STS), which enables Web Service Client and Provider
applications to extend SSO to identity-enabled Web Services at provider
sites, using another set of standards (see the next section, “About WS-Trust
STS”). These standards, including WS-Trust, do not rely on the user’s
browser for message transport.
The two types of connections can be configured together for the same partner or
independently (see “WS-Trust STS Configuration” on page 277).
About WS-Trust STS
The PingFederate WS-Trust STS allows organizations to extend SSO identity
management to Web Services. (For information about WS-Trust and the role of
an STS, see “Web Services Standards” in the “Supported Standards” chapter of
Getting Started.)
The WS-Trust STS can be configured for partner connections independently or
in conjunction with browser-based SSO for either an IdP or an SP deployment.
The STS is bundled with separate plug-ins for standard SAML (Security
Assertion Markup Language) token processing and generation (see “Token
Processors and Generators” on page 3).
Connection-Based Policy
For both the IdP and SP roles, PingFederate employs a partner-connection
configuration, which enables the association of Web Services authentication
policies with federation partners. For STS processing, these policies define
configurations for handling WS-Trust requests and transferring identity
information between security domains (see “Web Services Standards” in the
“Supported Standards” chapter of Getting Started).
IdP Configuration
In an IdP role, you use the administrative console to configure WS-Trust requestprocessing policy for your SP partner including:
•
The type of SAML token to create—suitable for consumption by the
intended Web Service Provider (at the SP site)—in response to an “Issue”
request from a Web Service Client application
•
The mapping of attributes to include within the issued SAML token
•
The key used to create a digital signature for the issued SAML token
SP Configuration
In an SP role, you use the administrative console to configure WS-Trust requestprocessing policy for your IdP partner including:
•
2
Whether to validate the incoming SAML token only, or to validate the
incoming token and also issue a local token
PingFederate 6
About WS-Trust STS
•
The mapping of attributes to include in the locally issued token (when
applicable)
•
The certificate used to verify the digital signature for the incoming SAML
token
•
The key used to decrypt the incoming SAML token (when needed)
Token Processors and Generators
PingFederate provides support for a variety of security-token formats, through
token processors and generators that plug into the PingFederate server. These
plug-ins deploy similarly to browser-based SSO adapters (see “SSO Integration
Kits and Adapters” on page 4).
For an IdP, token processors provide a mechanism through which PingFederate
can validate an incoming token and map attributes to be included in the issued
SAML token.
For an SP, token generators provide a mechanism through which PingFederate
can generate a local token based upon the incoming SAML token and map
attributes to be included in that token.
Only SAML 1.1 or 2.0 tokens are generated by PingFederate configured as an
IdP for sending across trust boundaries to a federated SP partner. Likewise, only
SAML tokens are accepted by PingFederate configured as an SP. Token plug-ins
allow a modular approach for validating and producing the various token types
used by different applications or systems within a conceptual trust domain.
PingFederate provides bundled and separately available token plug-ins.
Token processors (for an IdP) and generators (for an SP) are configured globally
in the administrative console; and at runtime, only a single instance of each
token type can be active at one time.
Bundled Token Plug-ins
PingFederate is installed with token processors for an IdP configuration that
accept and validate SAML 1.1 and 2.0 tokens (SAML tokens are issued on the
IdP side via built-in browser-based SSO capabilities).
For an SP configuration, token generators are provided for issuing local SAML
1.1 or 2.0 tokens (incoming SAML tokens are validated, once again, by using
built-in capabilities).
Commercial Token Plug-ins
Separately available token plug-ins include:
Administrator’s Manual
•
Username – Accepts and validates Web Services Security (WSSE)
Username tokens against a password or an LDAP v3-compliant directory
•
X.509 – Accepts and validates WSSE X.509 tokens against the PingFederate
trust store
•
Kerberos – Accepts and validates Kerberos binary tokens
•
CA SiteMinder – Accepts and validates SMSESSION binary tokens
3
Chapter 1
Key Concepts
•
Oracle Access Manager (formerly *-) – Accepts and validates OBSSO
binary tokens
•
OpenToken – Accepts and validates an OpenToken at an IdP PingFederate
and issues an OpenToken at the PingFederate SP
Ping Identity regularly develops token plug-ins to work with various
authentication systems and leading identity management systems. Also known as
Token Translators, available plug-ins are posted on our Web site (see the
PingFederate Overview page).
Client SDKs
Ping Identity provides a set of Java and .NET WSE3 client Software
Development Kits (SDKs) for enabling Web Service applications (client or
provider) to interact with the PingFederate STS.
The SDKs provide interfaces that create the WS-Trust Request Security Token
(RST) and Request Security Token Response (RSTR) messaging to interact with
the PingFederate STS endpoints. Using the SDK libraries, applications are not
responsible for forming these WS-Trust messages, and instead interact only with
the tokens themselves.
SSO Integration Kits and Adapters
As a stand-alone server, PingFederate must be programmatically integrated with
end-user applications and identity management (IdM) systems to complete the
“first- and last-mile” implementation of a federated identity network for browserbased SSO.
Note: For more information, see the PingFederate Integration Overview
in the pingfederate/docs directory.
For an IdP (the first mile), this integration process involves providing a
mechanism through which PingFederate can look up a user’s current
authenticated session data (for example, a cookie) or authenticate a user without
such a session. For an SP, the last mile involves enabling PingFederate to supply
information needed by the target application to set a valid session cookie or
other application-specific security context for the user.
To enable both sides of this integration, PingFederate provides bundled and
commercial integration kits, which include adapters that plug into the
PingFederate server and agent toolkits that interface with local IdM systems or
applications.
PingFederate includes a robust software development kit (SDK), which software
developers can use to write their own adapters for specific systems. Adapters can
be written to retrieve attributes from custom data stores, connect to applicationor IdM-specific user authentication systems, or provide complex attribute
transformations or processing.
4
PingFederate 6
Identity Mapping
Bundled Adapters
PingFederate packages two adapters:
•
An OpenToken Adapter, which provides a generic interface for integrating
with various applications, including Java- and .NET-based applications (see
“OpenToken Adapter Configuration” on page 329)
•
An LDAP Authentication Service, which interfaces with LDAP v3compliant directories (see “LDAP Adapter Configuration” on page 337)
Commercial Adapters
Ping Identity regularly develops integration kits, including adapters, to work with
applications and leading identity management systems. Available kits are posted
on our Web site at www.pingidentity.com.
Software Development Kit
The PingFederate SDK provides a flexible means of creating custom integration
kits to integrate federated identity management into your system environment.
See the PingFederate SDK Developer’s Guide in the /sdk directory for more
information.
Identity Mapping
Identity mapping is at the core of identity federation. One of the primary goals of
SAML is to provide a way for an identity provider (IdP) to send a secure token
(the assertion) containing user-identity information that a service provider (SP)
can translate, or map, to local user stores. (For more information about SAML,
see the “Supported Standards” chapter in Getting Started.)
For browser-based SSO, PingFederate enables two modes of identity mapping
between domains:
•
Account Linking
•
Account Mapping
For WS-Trust STS, account mapping is used.
Account Linking
Under the standards, account linking can be used for browser-based SSO in cases
where each domain maintains separate accounts for the same user. Account
linking uses the SAML assertion to create a persistent association between these
distinct user accounts. The account link, or name identifier, may be either a
unique attribute, such as an email address, or a pseudonym generated by the IdP
to uniquely identify individual users. Pseudonyms can be used when privacy is a
concern; they cannot easily be traced back to a user's identity at the partner site.
During the user’s first SSO request, the SP prompts for local credentials, which
enables the SP to link the name identifier contained within the assertion—
either an open attribute or a pseudonym—with the user’s local account.
Administrator’s Manual
5
Chapter 1
Key Concepts
Subsequent SSO events will not prompt the user to authenticate with the SP,
since the SP federation server keeps a table associating remote users’ name
identifiers with local user accounts. The SP associates the link to the user’s
corresponding local account and provides access to the account without separate
authentication.
Optionally, additional attributes may be sent with the name identifier. When a
pseudonym is used as the account link, however, care must be taken to send only
general attributes (a user’s organizational role or department, for example) that
will not compromise privacy.
Linking Permission and “Defederation”
The SAML specification also allows the SP application to build in user
verification and approval of account linking and provides a means for the user to
permanently cancel the linking, known as defederation (see “/sp/defederate.ping”
on page 354). A user who has defederated may later elect to reassociate with a
local user account.
SP Affiliations
Under the SAML 2.0 specifications, an IdP can configure PingFederate to enable
a group of SPs—an SP affiliation—to share the same persistent name identifier
(see “Defining SP Affiliations” on page 190). This capability facilitates the use
case in which a number of business partners have an existing relationship and
sharing a single name identifier among all parties reduces the federation
integration effort.
Account Mapping
Account mapping (also called “attribute mapping”) enables an SP to use
PingFederate to perform a user lookup and map a user’s identity dynamically
based on one or more attributes received in the assertion. The attributes used to
look up the user are always “exposed”; that is, they are known to both the IdP
and SP. An email address, for example, is a commonly used identifying attribute.
Account mapping can be used to achieve one-to-one mapping (individual user
accounts exist on both sides of federated connection) or many-to-few (IdP users
without accounts at destination sites may be mapped to guest accounts or to a
role-based general account).
For browser-based SSO, transient identifiers provide an additional level of
privacy—virtual anonymity—by generating a different opaque ID each time the
user initiates SSO. Transient IDs are often used in conjunction with federation
role mapping, whereby the user is mapped to a guest account or to a role-based
account based on the user’s association with the IdP organization rather than
personal attributes.
As with pseudonyms, additional attributes may be sent with the transient
identifier. Again, care should be taken to preserve privacy.
Account mapping is commonly implemented in B-to-B or B-to-E use cases where
it might be appropriate for the administrator to create a user lookup on behalf of
the user.
6
PingFederate 6
About Attributes
About Attributes
Federation transactions require, at a minimum, the transmission of a unique
piece of information (such as an email address) that identifies the user for
identity mapping between security domains.
In addition to attributes used for identity mapping, the IdP can pass other user
attributes in an assertion (including SAML tokens for Web Services). This
supplemental information can be used by the SP for several purposes. For
example, attributes may be used to map and authorize the user into a specific
role, with associated site permissions. In other cases, attributes may be used to
customize the end application display for a more robust user experience.
The SP also has the option of incorporating additional attributes prior to
creating a session for the target application. This is commonly done where the
SP also maintains an account for the user and wants to pass additional
information for profiling or access-policy purposes.
Attributes must be carefully managed between IdPs and SPs. PingFederate
facilitates the process by providing configuration steps that enable administrators
to:
•
Define and enforce attribute contracts for each partner connection.
•
Define and retrieve attributes from the adapter or STS token processor to
populate an attribute contract directly or use these attributes to look up
additional attributes in IdP data stores.
•
Define and enforce a set of required attributes needed by SP adapters or STS
token generators to interface local systems or applications (see “Adapter
Contracts” on page 8).
•
Set up connections to local data stores (see “Data Stores” on page 9).
•
Configure specific attribute sources and lookups—based on the data stores—
and map attributes into IdP assertions or into SP adapters or token
generators used to interface target applications (see “SSO Integration Kits
and Adapters” on page 4 or “Token Processors and Generators” on page 3).
•
Selectively mask attribute values recorded in transaction logs (see “Attribute
Masking” on page 10).
Attribute Contracts
An attribute contract represents an agreement between an SP and an IdP about
user attributes sent in a SAML assertion, either for browser-based SSO or WSTrust STS. The contract is a list of case-sensitive attribute names. IdPs and SPs
must configure attribute contracts to match.
Tip: When privacy is required for sensitive attributes, you can configure
PingFederate to mask their values in log files (see “Attribute Masking”
on page 10).
For an IdP, the attribute contract defines which attributes PingFederate sends in
an assertion. While this contract is fixed for all users authenticating to the SP
Administrator’s Manual
7
Chapter 1
Key Concepts
partner, the values used to fulfill the contract may differ from one user to the
next. The attribute contract may be fulfilled by relying on a combination of
different sources of data:
•
The IdP adapter or STS token processor
•
An IdP attribute source, which identifies the location of individual
attributes in a data store
•
Static text values for some attributes, or text values combined with variables
•
Expressions (see “Using Attribute Mapping Expressions” on page 367)
For an SP, the attribute contract defines the attributes PingFederate expects in a
SAML assertion. PingFederate can be configured to pass these attributes to the
SP adapter or, for Web Services, to the SP token generator (see “Configuring SP
Adapters” on page 200 or “Configuring Token Generators” on page 308). You
can also use attributes to look up additional attributes in local data stores, which
may be needed to start a user session or create a local security token for Web
Services (see “Adapter Contracts” below or “STS Token Contracts” on page 9).
The attribute contract must contain the attribute SAML_SUBJECT, the primary
information used to identify the user, unless you are using account linking for
browser-based SSO. This attribute is automatically included when creating a new
contract.
Note: You create attribute contracts on a per-connection basis. For
example, if an SP has deployed two session creation adapters for two
separate applications, a single attribute contract can be created for the
IdP connection partner. This single contract would be constructed to
supply all the attributes needed by both SP adapters.
Adapter Contracts
An adapter contract represents an agreement between the PingFederate server
and an external application. In concert with the attribute contract between
partners, adapter contracts specify the transfer of attributes. Adapter contracts
consist of a list of case-sensitive attribute names.
On the IdP side of a federation, adapter attributes are supplied to PingFederate by
an IdP adapter (see “SSO Integration Kits and Adapters” on page 4 and
“Configuring IdP Adapters” on page 106).
On the SP side, adapter contract attributes are those required by an adapter to
start a session with an application. At least one adapter type is needed for each
security domain. Then an adapter instance must be configured for each target
application. (See “Configuring SP Adapters” on page 200.)
Adapter contracts on the SP side are fulfilled using attributes from the attribute
contract, possibly enhanced through other attributes looked up from local data
stores. For example, if several target applications are controlled by the same
security context (for example, SiteMinder) and can receive the same set of
attributes to start a session for the user, you would deploy an adapter type and
configure an adapter instance for each protected application (see “Configuring
Adapter Mapping and User Lookup” on page 230).
8
PingFederate 6
About Attributes
Extended Adapter Contract
Adapter contracts are created when an adapter type is deployed with
PingFederate. When developed, these adapters are “hard-wired” to look up or set
a specific set of attributes. After deployment, your attribute requirements may
change. To streamline adjustment of adapter contracts, PingFederate allows an
administrator to add additional attributes to the adapter instance through the
administrative console. These adjustments are called extended attribute contracts.
STS Token Contracts
Similar to an adapter contract for browser-based SSO, an STS token-processor or
token-generator contract represents an agreement between the PingFederate
server and an external application in the context of a Web Services transaction.
In concert with the attribute contract between partners, token contracts specify
the transfer of attributes, consisting of a list of case-sensitive attribute names.
On the IdP side of a federation, token-processor attributes are supplied to
PingFederate (see “Token Processors and Generators” on page 3 and
“Configuring Token Processors” on page 284).
On the SP side, token-generator contract attributes are those required by a token
generator to pass identity information from the token to the Web Service client
application. At least one token generator type is needed for each security
domain. Then a token generator instance must be configured for each target
application (see “Configuring Token Generators” on page 308. If several target
applications are controlled by the same security context (for example,
SiteMinder) and can receive the same set of attributes for the user, you would
deploy a token generator type and configure a token generator instance for each
target application (see “Mapping Token Generators” on page 314).
Extended Token Generator Contract
Token-generator contracts are created when a token-generator type is deployed
with PingFederate. When developed, these token generators are “hard-wired” to
look up or set a specific set of attributes. After deployment, your attribute
requirements may change. To streamline adjustment of token-generator
contracts, PingFederate allows an administrator to add additional attributes to
the token-generator instance through the administrative console. These
adjustments are called extended token-generator contracts.
Data Stores
PingFederate can be configured to use local data stores to supply attributes for
either the IdP’s attribute contract, the SP’s adapter contract, or STS token
contracts (see sections above). Standard data stores may include any JDBCaccessible database or an LDAP v3-compliant directory server (see “Managing
Data Stores” on page 72).
Alternatively, you can use the PingFederate Custom Source SDK to create your
own driver for non-JDBC/LDAP data stores—including, for example, flat files or
SOAP-connected databases (see the PingFederate SDK Developer’s Guide in the
pingfederate/sdk directory).
Administrator’s Manual
9
Chapter 1
Key Concepts
Data stores can be used across multiple connections.
Attribute Masking
At runtime PingFederate logs user attributes (see “Log File Generation” on
page 27). To preserve user privacy, you may wish to mask the values of logged
attributes.
PingFederate provides this masking capability at all points where the server logs
attributes. These points include:
•
Data-store lookup at either the IdP or SP site (see “Managing Data Stores”
on page 72).
•
Retrieval of attributes from an IdP adapter or token processor (see “Setting
Pseudonym Values and Masking” on page 110 and “Setting Attribute
Masking” on page 288).
•
SP-server processing of incoming attributes based on the SSO Attribute
Contract, (see “Creating an Attribute Contract” on page 228).
Note that the SAML Subject ID is not masked: the SAML specifications
provide for either pseudonymous account linking or transient identification
to support privacy for the Subject ID (see “Account Linking” on page 5).
•
SP-server processing of incoming attributes in response to an Attribute
Request under XASP (see “Specifying Security Policy” on page 262).
For information about XASP, see “Attribute Query and XASP” in the
“Supported Standards” chapter of Getting Started.
Important: Many adapter implementations, as well as other product
extensions, may independently write unmasked attribute values to the
PingFederate server log. These implementations are beyond the
control of PingFederate. If sensitive attribute values are a concern
when using such a component, a system administrator can adjust the
component’s logging threshold in log4j.xml to prevent the
recording of attributes (see “Log File Generation” on page 27).
Certificates, SSL, and XML Encryption
This section describes the PingFederate security infrastructure that supports
encrypted messaging, certificates, and digital signing. These functions are
integrated into PingFederate’s configuration screens to provide complete control
over certificate generation and authentication verification (see “Security
Management” on page 89).
Digital Signatures
A digital signature is a way to verify the identity of a person or entity who
originates an electronic document and ensure that the message has not been
10
PingFederate 6
Certificates, SSL, and XML Encryption
altered. Digital signatures are used in both SAML (including STS tokens) and
WS-Federation electronic documents.
Handling a digital signature involves message signing, signature and certificate
validation, and signing-policy coordination between connection partners.
Message Signing
Certificates contain information about the owner of the certificate along with a
public key. Applying a digital signature creates and encrypts a hash from the
message you are signing, using your private key.
To ensure the integrity of SAML messages or STS tokens, we recommend digital
signing practices, using public/private keypairs in conjunction with X.509
certificates.
Note: Digital signatures do not encrypt the contents of a message;
SSL/TLS and/or XML encryption is used for this purpose.
The certificate should be signed by a Certificate Authority (recommended), but
it can be self-signed or signed by an untrusted third party. After generating a
keypair and a self-signed certificate, you can use PingFederate to create a
Certificate Signing Request (CSR) and send it to a CA for signing. After the CA
has generated a Certificate Signing Response, you can import it into
PingFederate’s certificate management system. (The CA’s certificate must be in
PingFederate’s trusted store.)
PingFederate enables signing and validation of responses, requests, and/or the
assertion message. In addition, PingFederate provides for certificate generation,
import and export functionality, CSR generation, and application of digital
signatures. You can create reusable global signing certificates across your
federated connection base and import signature verification certificates for each
partner (see “Digital Signing and Decryption Keys & Certificates” on page 96).
Note: Ping Identity recommends generating unique certificates for
each connection, which limits your exposure if your private key
becomes compromised.
Signature Validation
After receiving a signed message, PingFederate verifies the signature using the
public key that corresponds with the private key used to sign the message or
token. Verification involves creating a hash of the received message, using the
signing partner’s public key to decrypt the hash sent with the original message,
and verifying that both hash values are equal.
Certificate Validation
PingFederate always checks certificates to see if they have expired, both when
they are initially imported and at runtime when they are used to encrypt,
decrypt, and digitally sign or verify assertions.
Administrator’s Manual
11
Chapter 1
Key Concepts
PingFederate can also check to see whether a certificate has been revoked, using
either Certificate Revocation Lists (CRLs) or the Online Certificate Status
Protocol (OSCP). Depending on the content of the certificate in question and
your requirements, the server will perform either of these checks during SSO or
SLO processing for the following cases:
•
Signature verification
•
Validation of a client certificate used for authentication to PingFederate
when the server is handling direct client requests
•
Validation of the server SSL certificate when PingFederate is acting as the
client making an HTTPS request to a separate server
If a certificate is expired or revoked, the associated SSO or SLO transaction fails
at runtime and an error is written to the transaction log. In the administrative
console, an expired or revoked certificate is identified as such in the Status
column of its respective Certificate Management list.
CRL Revocation Checking This process involves querying a CRL distributionpoint URL and ensuring that a certificate is not on the returned revocation list
maintained at the site. The URL is specified in the certificate.
No setup is needed in the administrative console to enable CRL checking.
PingFederate automatically checks CRLs if all of the following conditions are
met:
•
The certificate contains the URL where the CA maintains its CRL.
•
The URL is accessible.
•
The returned CRL is signed and the signature verified.
•
CRL validation is not explicitly disabled as a failover option in the OCSP
setup (see “Certificate Revocation Checking” on page 100).
OCSP Revocation Checking OCSP was developed as an alternative to CRL
validation and provides a more centralized and potentially more reliable means
of checking certificate status. In this scenario, an OCSP Responder URL is
normally embedded in the incoming certificate (a configured default URL may
be used, alternatively). The URL, maintained by the issuing CA, is used to query
the certificate status.
The primary difference between OCSP and CRL checking is how the
verification occurs. CRL checking requires the requesting client to determine if
the certificate has been revoked (or if any of the certificates in the chain of issuer
certificates has been revoked), based on the returned CRL. With OCSP, the
client sends the certificate itself, and revocation checking is handled by the
Responder server, which returns the certificate status.
A PingFederate administrator can enable and configure OCSP processing in the
administrative console (see “Certificate Revocation Checking” on page 100).
The protocol may be used exclusively or in conjunction with CRL checking as a
backup.
For more information about OCSP, see www.ietf.org/rfc/rfc2560.txt.
12
PingFederate 6
Certificates, SSL, and XML Encryption
Digital Signing Policy Coordination
To coordinate digital signature policy, partners must first agree about whether
they will sign SAML messages or tokens. In some cases, the protocol
specifications require signatures—for example, all SAML STS tokens and all
SSO assertions sent across the POST binding must be signed, (These
requirements are enforced by the PingFederate administrative console and the
runtime protocol engine.) Other uses of the digital signatures are optional
between partners. Numerous scenarios are possible, including:
•
SP verifies incoming response signatures
•
SP verifies incoming assertion signatures
•
SP signs outgoing requests
•
IdP signs outgoing responses
•
IdP signs outgoing assertions (for any binding)
•
IdP signs outgoing requests for single logout
•
IdP verifies incoming request signatures
The signing partner must send certificates (containing only the public keys) outof-band to the validating partner, who must import the certificates into
PingFederate before they can be used for validation of signed messages (see
“Digital Signing and Decryption Keys & Certificates” on page 96).
Example Configuration Scenario: IdP Signs Outgoing Response
1. The IdP generates a private and public keypair and submits a certificate for
CA signing (optional: self-signing by the IdP).
2. The IdP imports the CA’s signing response into the PingFederate keystore.
3. The IdP configures the connection to the SP to sign SAML responses.
4. The IdP exports the public key of the certificate, which is sent to the SP outof-band.
5. The SP administrator imports the certificate into the PingFederate digital
signature verification keystore for the IdP federated connection.
6. The SP administrator configures the connection to use the certificate to
verify the digital signatures on incoming IdP responses.
Secure Sockets Layer
SSL certificates signed by a CA can be used to identify one or both ends of the
federation. SSL/TLS provides an encrypted connection between the two parties
in which the content of a message is not exposed, thus ensuring confidentiality
and message integrity.
SAML SSL/TLS Scenarios
SSL/TLS should be used in association with the SOAP responder URL and
Single Sign-on Service located at an IdP site. On the SP side, the Artifact
Resolution Service should also use SSL/TLS. Optionally, SSL/TLS may also be
Administrator’s Manual
13
Chapter 1
Key Concepts
used to secure communication between internal user data stores and
PingFederate and between the PingFederate STS and Web Service client or
provider applications.
Authentication
Three methods of authentication, described below, are available for use with
PingFederate for browser-based SSO to authenticate connection partners making
SOAP requests. For SOAP authentication by STS clients, a separate option
using either or both of the first two methods, may be configured (the third
method, digital signing, is automatically required). The selection of one or more
method(s) must be agreed upon between partners and synchronized within IdP
and SP federation implementations:
•
HTTP Basic Authentication: partners identify themselves by passing
username and password credentials.
•
SSL Client Certificate Authentication: partners use SSL Client Certificates
presented during SOAP request transactions. Each partner needs to import
the other’s certificate out-of-band (see “SSL Client Keys & Certificates” on
page 94).
Important: The SSL/TLS server-client handshake involves
negotiating cipher suites to be used for encryption/decryption on
each side of a secured Internet transaction. PingFederate supports
only stronger cipher suites; to enhance security, weaker cipher
suites are commented out of two configuration files located in
<pf_install>/server/default/data/config-store:
com.pingidentity.crypto.SunJCEManager.xml
com.pingidentity.crypto.LunaJCEManager.xml
To ensure the most secure transactions, we recommend that
administrators retain this cipher-suite configuration.
Due to import control restrictions, the standard Java Runtime
Environment (JRE) distribution supports strong but not unlimited
encryption. For this reason, the strongest cipher suites in the same
configuration files are also commented out. To use the strongest
encryption, when permissible, remove the comments from the
AES 256 cipher suites and download and install the appropriate
version of “Java Cryptography Extension (JCE) Unlimited Strength
Jurisdiction Policy Files” from the Sun download Web site (http://
java.sun.com/javase/downloads).
•
14
Digital Signatures: partners sign the XML message transmitted via the SSL/
TLS connection. Signatures are verified by the receiver based upon the
certificate(s) configured for that connection. Each partner should import the
other’s certificate(s) out-of-band (see “Digital Signing and Decryption Keys
& Certificates” on page 96).
PingFederate 6
Using Auto-Connect
Verifying Trusted Certificates
PingFederate validates the trust of all certificates. A certificate is trusted if the
certificate of its issuer is in PingFederate’s trusted certificate store. The root
certificate of the CA, by which a certificate is issued, must be imported into
PingFederate’s trusted certificate store.
XML Encryption
PingFederate supports the optional SAML 2.0 specification allowing for
encryption of assertions (including STS SAML tokens), which further enhances
confidentiality when required.
For SAML 2.0 browser-based SSO connections you can choose to encrypt entire
assertions, the user’s name identifier, and/or other user attributes. You can use
signature verification and signing keys to encrypt and decrypt messages,
respectively.
Using Auto-Connect
PingFederate allows organizations to provide secure Internet SSO on the fly—
that is, without the need for configuring partner-specific, browser-based SSO
connection parameters. This feature—Auto-Connect™—extends SAML 2.0 SPinitiated SSO or SLO and metadata specifications to enable deployments to
retrieve partner connection information securely on an as-needed basis. (For
information about SAML 2.0, see the “Supported Standards” chapter in Getting
Started.)
The feature is especially useful to an SP who wants to provide SSO capability to
more than one partner. A Software-as-a-Service (SaaS) provider, for example,
can provide SSO to innumerable clients without specifying redundant
connection information for each one. Auto-Connect can also help an enterprise,
acting as an IdP, provide easily scalable SSO for multiple outsourced services.
For either an IdP or SP PingFederate server, you can implement Auto-Connect
for any number of partners by configuring a common initial setup and a list of
domain names. For an IdP, the domain-name list contains SP partners from
whom your site will accept Auto-Connect authentication requests. For an SP,
the list contains IdP-partner domains to which your site can send authentication
requests and receive SSO assertions.
For information about configuring Auto-Connect for your federation partners,
see “Configuring SP Auto-Connect” on page 194 or “Configuring IdP AutoConnect” on page 272.
Providing Metadata
You enable Auto-Connect as part of Server Settings from the Main Menu (see
“Choosing Roles and Protocols” on page 64). Once Auto-Connect is enabled
and your initial setup is fully configured and activated, partners can retrieve your
connection metadata via HTTP. At runtime, Auto-Connect deployments at
Administrator’s Manual
15
Chapter 1
Key Concepts
partner sites use the endpoints provided in the metadata to interact with your
server and complete SSO or SLO processing.
The metadata, which follows SAML 2.0 specifications, must be signed, and the
validity of the data is time-limited (see “Auto-Connect Security Model” on
page 17) and “Configuring Auto-Connect Metadata Lifetime” on page 71).
Runtime Processing
Auto-Connect runtime processing starts when a user tries to reach a protected
SP resource. The process depends on SP Web-application functionality that
determines the user’s IdP domain (for example, from a submitted email address)
and passes it to the SP PingFederate server in the SSO request.
Figure 1 and the accompanying “Processing Steps” describe the complete SSO
processing flow:
6HUYLFH3URYLGHU
,GHQWLW\3URYLGHU
3LQJ)HGHUDWH
3LQJ)HGHUDWH
q
0HWDGDWD
$SS
$GDSWHU
5XQWLPH
(QJLQH
p
0HWDGDWD
! #3
$SS
s
33/
,G3'RPDLQ/LVW
o
$GDSWHU
5XQWLPH
(QJLQH
t
63'RPDLQ/LVW
r
n
u
$VVHUWLRQ
$XWKQ5HTXHVW
v
%URZVHU
Figure 1: Auto-Connect Processing Flow
Processing Steps
1. Internet user sends a logon request with an email address to an SP
application. For example:
[email protected]
2. The application parses the email address and sends a request to
PingFederate. For example:
https://sp_host.com:9031/sp/
startSSO.ping/?Domain=mycompany.com
3. The SP PingFederate server looks up the domain in a list of domain names
allowed to use Auto-Connect.
16
PingFederate 6
Using Auto-Connect
4. If the domain is in the list, the SP retrieves connection metadata from the
IdP’s public endpoint.
By default, PingFederate looks for the metadata by prepending
http://saml to the domain. For example:
http://saml.mycompany.com
This default location can be changed, if necessary, in the Allowed Domains
lists configured in the PingFederate administrative console.
5. After validating the metadata (see “Auto-Connect Security Model” on
page 17), the SP sends an authentication request to the IdP’s SSO service.
6. If the request <Issuer> is not among the IdP’s static-connection partners,
the IdP PingFederate server looks for the issuer’s domain name in the list of
domains allowed to use Auto-Connect.
7. The IdP retrieves the SP’s metadata via its public endpoint and verifies the
metadata signature.
The process is the same as that used by the SP in Step 4.
8. The IdP requests user authentication via the configured adapter instance.
9. Once the user is authenticated, the IdP returns a signed SAML assertion to
the SP’s Assertion Consumer Service (ACS) endpoint.
10. (Not shown) The SP logs the user on to the requested resource via the
configured SP adapter.
Auto-Connect Security Model
Auto-Connect processing requires digital signatures to ensure the authenticity of
the published metadata as well as all subsequent SSO or SLO requests and
responses. The certificate used to sign the metadata is included in the metadata,
and all certificates must be signed by a trusted Certificate Authority; thus,
partners need not exchange certificates out of band.
In addition to validating certificates, the PingFederate runtime server compares
the partner certificate with the entity ID (the “Issuer”) found in the SAML
message. Then the server matches the entity ID against the configured list of
allowed Auto-Connect domains.
Figure 2 illustrates the security validation process:
Administrator’s Manual
17
Chapter 1
Key Concepts
6$0/
0HVVDJH
$VVHUWLRQ
6LJQLQJ
6LJQLQJ
&HUW
&HUWLILFDWH
7UXVWHG
7UXVWHG
&$
&$
&HUW&1
&HUWLILFDWHLVLQFOXGHG
LQWKH6$0/PHWDGDWD
0HWDGDWD
;0/
&1PDWFKHVWKH,VVXHU
HQWLW\,GRIWKH6$0/
DVVHUWLRQRURWKHUPHVVDJH
6LJQLQJFHUWLILFDWH&1
LVYHULILLHGDJDLQVW
H[SHFWHG'RPDLQ
&HUW&1
,VVXHU
'RPDLQ/LVW
,VVXHUPXVWPDWFK
DQ$OORZHG'RPDLQ
'RPDLQ
Figure 2: Auto-Connect Security Model
Note that the diagram assumes that the same certificate is used for signing both
the metadata and the runtime SAML messages. This is convenient, but not
required.
User Provisioning
PingFederate provides two different kinds of user provisioning for browser-based
SSO, one designed for an IdP and one for an SP:
•
At an IdP site, you can provision and maintain user accounts (including
“deprovisioning”) at selected hosted-software providers (see the next
section, “SaaS Provisioning”).
•
At an SP site, you can provision accounts for your own organization
automatically, using information from SAML assertions received during SSO
events (see “Express Provisioning” on page 19).
SaaS Provisioning
For IdP sites, PingFederate offers automated provisioning and deprovisioning to
facilitate SSO to either (or both) of two SaaS providers: Google Apps and
salesforce.com.
Tip: SaaS Provisioning, including quick-connection templates for
partner SSO, is available separately from Ping Identity. Contact
[email protected] for more information.
When SaaS Provisioning is enabled, the PingFederate runtime engine polls the
IdP organization’s user store periodically. The server uses a separate database
internally to monitor the state of the user store and keep user data synchronized
between the organization and the hosted SaaS application (see Figure 3).
18
PingFederate 6
User Provisioning
PingFederate (IdP)
LDAP
User
Store
Runtime SaaS Provisioner
SaaS
Vendor
Internal
Data Store
Figure 3: SaaS Provisioning Processing
PingFederate provides built-in support for Microsoft’s Active Directory and the
Sun Directory Server (formerly Sun ONE) as user-data sources; templates are
used to preconfigure many provisioning settings. Although these are the only
data stores formally tested and supported, other LDAP data stores will likely
work as well (see “Identifying the Source Data Store” on page 180). For
convenience, PingFederate provides a sample template that can be used for other
types of LDAP servers to simplify the provisioning configuration (see
“Configuring an LDAP Connection” on page 78).
Tested internal data stores include Hypersonic, MySQL, and Oracle databases (a
demonstration-only, embedded Hypersonic database is installed by default).
Again, any relational database may be used—scripts are provided to aid setup
(see “Configuring SaaS Provisioning Settings” on page 69).
Tip: Administrators have access to a command-line utility that can be
used to monitor and make adjustments to the internal database as
needed (see “SaaS Provisioning CLI” on page 47).
Express Provisioning
At an SP site, PingFederate can create and update local user accounts in an
external LDAP directory as part of SSO processing—Express Provisioning. This
feature allows SPs to maintain accounts for users that authenticate from IdP
partners without having to provision accounts manually prior to a user’s first
SSO.
When configured, the PingFederate SP server writes user information to the
local user store using attributes from the incoming SAML assertion. For SAML
2.0 partner connections, assertion attributes can be supplemented with user
attributes returned from an Attribute Query (see “Attribute Query and XASP”
in the “Supported Standards” chapter of Getting Started).
PingFederate can also update existing user accounts. When this option is
enabled, PingFederate can add or overwrite attributes for a local user account
each time SSO for a user is processed. Note that once user attributes are
provisioned, they cannot be removed using Express Provisioning.
For information about enabling Express Provisioning, see “Choosing Connection
Options” on page 217. For configuration information, see “User Provisioning” on
page 254).
Administrator’s Manual
19
Chapter 1
Key Concepts
Federation Planning Checklist
An essential first step in establishing an identity federation involves discussions
and agreements between you and your connection partners. Below is a checklist
of items that should be coordinated before you deploy PingFederate:
Signing and Validation
Decide which SAML messages—assertions, responses, requests—will be digitally
signed and how the messages will be verified by your federation partner. If
messages are signed, decide how certificates will be exchanged (for example,
secure email). (See “Certificates, SSL, and XML Encryption” on page 10.)
Back-Channel Security
Determine what type of SOAP channel authentication will be used: Basic or
SSL/TLS. If SSL/TLS is used, determine whether server-only or both server and
client certificates will be needed and how they will be managed. Also decide
what level of security will be required for connections to back-end data stores or
identity management systems.
Trusted Certificate Management
Determine whether both partners are using SSL/TLS and/or signing certificates
that have been signed by a major CA. (If self-signed certificates or nonstandard
CAs are used, the signed certificates must be exchanged and imported into
Trusted Certificate stores.)
Deployment
Decide how PingFederate fits into your existing network. Also, determine
whether high-availability and/or failover options are required (see the
PingFederate Server Clustering Guide).
Federation Server Identification
Determine how you and your partner(s) will identify your respective federation
deployments. Under federation standards, both the sender (IdP) and the receiver
(SP) of an assertion must be uniquely identified within the identity federation
(see “Configuration Data Exchange” on page 22).
With PingFederate, you define a unique ID for each supported protocol (see
“Specifying Federation Information” on page 67). Optionally, you can also use
Virtual Server IDs on a connection-by-connection basis. This option provides
more configuration flexibility in cases where you need more than one
connection to the same partner for different purposes. For example, you would
want to use virtual IDs if you are an IdP and you have an SP partner who requires
a different set of attributes to launch different applications. Assigning virtual IDs
allows you to configure multiple connections to such a partner, each set up to
manage attributes differently. (Note that the partner must also have a federation
deployment that supports multiple federation IDs.)
20
PingFederate 6
Federation Planning Checklist
You can assign virtual server IDs either as an IdP during configuration of an SP
connection (see “General Information” on page 121) or as an SP configuring an
IdP connection (see “General Information” on page 218).
Tip: PingFederate also provides for virtual host names, which differ
from virtual IDs (but are not mutually exclusive); they are intended to be
used when your network configuration is such that you receive
federation messages under more than one domain name (see “Using
Virtual Host Names” on page 42).
Server Clock Synchronization
Ensure that both the SP and IdP server clocks are synchronized. SAML messages
and STS tokens provide a time window that allows for small synchronization
differentials. However, wide disparities will result in assertion or request timeouts.
User Data Stores
Identify the type of data store that contains user data when needed: LDAP,
JDBC, or Custom (see “Data Stores” on page 9).
Web Application and Session Integration
Decide how PingFederate as an IdP receives subject identity information, either
from an STS token or a user session.
For an SP, decide how PingFederate will forward user identity information to the
destination Web application or system to start a session.
(See “SSO Integration Kits and Adapters” on page 4 and “Token Processors and
Generators” on page 3.)
Transaction Logging
PingFederate provides basic transaction logging and monitoring. Decide whether
transaction logging should be integrated with a systems management application
and whether you have regulatory compliance requirements that affect your
logging processes. (For more information, see “Log File Generation” on page 27.)
Identity Mapping
For browser-based SSO, decide whether you will use PingFederate to link
accounts on your respective systems using a persistent name identifier, or
whether you will use account mapping (see “Identity Mapping” on page 5).
Attribute Contract Agreement
If your federation partnership will not use account linking, or will not use it
exclusively, then you and your partner must agree on a set of attributes that the
IdP will send in an assertion for either SSO or Web Service access. (For more
information, see “Attribute Contracts” on page 7.)
Administrator’s Manual
21
Chapter 1
Key Concepts
Metadata Exchange
If you are using SAML, decide whether you will use the metadata standard to
exchange XML files containing configuration information. PingFederate makes
it easy to use this protocol, which provides a significant shortcut to setting up
your partner connections. (If you partner is also using PingFederate or supports
standards permitting runtime metadata exchange, the process can be even
simpler—see “Using Auto-Connect” on page 15.)
Configuration Data Exchange
If your partner’s deployment does not produce or consume a metadata file that
conforms to SAML metadata specifications, you may need to exchange
connection information manually. The following sections list some common
configuration details that must be exchanged if metadata files are not used.
(These lists are not exhaustive.)
IdP to SP
If you are the IdP, your SP partner will need some or all of the following
connection information (depending upon which profiles and bindings you are
configuring):
•
Unique ID—Identifies the IdP that issues an assertion or other SAML
message. For SAML 2.0, the ID is the IdP's Entity ID; for SAML 1.x, it is the
IdP's Issuer; for WS-Federation, it is the IdP's Realm.
PingFederate also supports the optional use of virtual IDs (see “Federation
Server Identification” on page 20).
•
SOAP Artifact Resolution URL—The endpoint your site uses to receive
an SP’s SOAP requests when the artifact binding is used.
•
Single Logout Service URL—The destination of SLO request messages.
•
Single Sign-On Service URL—The endpoint where you receive and
process assertions.
SP to IdP
If you are the SP, your IdP partner will need some or all of the following
connection information (depending upon which profiles and bindings you are
configuring).
•
Unique ID—Identifies the SP. For SAML 2.0, the ID is the Entity ID; for
SAML 1.x, it is the SP’s Audience; for WS-Federation, it is the SP’s Realm.
PingFederate also supports the optional use of virtual IDs (see “Federation
Server Identification” on page 20).
22
•
SOAP Artifact Resolution Service URL—The endpoint to use for SOAP
requests when the artifact binding is used.
•
Single Logout Service URL (SAML 2.0)—The destination of SLO request
messages.
PingFederate 6
Federation Planning Checklist
•
Assertion Consumer Service URL—The location where the SP receives
assertions.
•
Target URLs—The URLs for the protected resources that a user is trying to
access.
Mutual Settings Between Parties
Many settings must be mutually set by the parties. This information might
include such items as:
Administrator’s Manual
•
Attributes—User information that will be sent in an assertion, if any (see
“About Attributes” on page 7).
•
Signing certificates—The SAML and WS-Federation protocols specify a
number of conditions under which digital signatures are either required or
optional (these conditions are built into the PingFederate connection-setup
screens).
•
SOAP connection type and authentication style—For SAML connections
using the back channel (using the artifact binding, for example), HTTP
Basic authentication, SSL client certificate authentication, digital
signatures, or some combination of the three is required. You and your
partner must exchange the necessary credentials, certificates, and/or signing
keys.
23
Chapter 1
Key Concepts
24
PingFederate 6
Chapter
2
System Administration
This chapter describes general administrative functions for PingFederate,
including:
•
“Starting and Stopping PingFederate” on page 26
•
“Log File Generation” on page 27
•
“Exporting Metadata” on page 30
•
“Signing XML Files” on page 34
•
“Using the Configuration Archive” on page 35
•
“Account Management” on page 36
•
“Managing Email Configuration” on page 40
•
“Using Virtual Host Names” on page 42
•
“Changing Configuration Parameters” on page 42
•
“Installing a New License Key” on page 45
•
“Automating Configuration Migration” on page 45
•
“SaaS Provisioning CLI” on page 47
•
“Customizing User-Facing Screens” on page 50
Note: The information in this chapter is presented from the viewpoint
of an administrative user with “Admin” permissions (see “Account
Management” on page 36).
Administrator’s Manual
25
Chapter 2
System Administration
Starting and Stopping PingFederate
(Windows)
To start PingFederate:
X From Start > Run dialog or a command prompt, run the batch file:
<pf_install>\pingfederate\bin\run.bat
Or:
Open the \bin folder in Windows and double-click the file.
Wait a moment for the script to execute. The server is started when you see
the message “Started in [xx]s:[yy]ms” in the command window, near the end
of the startup sequence.
To shut down PingFederate:
1. Enter Ctrl+C in the command-prompt window.
2. Enter y to terminate when prompted.
(Linux)
To start PingFederate:
1. From a command prompt, change directories to <pf_install>/
pingfederate/bin.
2. Add executable permission to the startup script:
chmod 755 ./run.sh
3. Execute the run.sh file.
Wait a moment for the script to execute. The server is started when you see
the message “Started in [xx]s:[yy]ms” in the command window, near the end
of the startup sequence.
To shut down PingFederate:
X Enter Ctrl+C in the terminal window.
(All Platforms)
To access the PingFederate administrative console:
X Launch a Web browser and go this location:
https://<DNS_NAME>:<port>/pingfederate/app
where <DNS_NAME> is the fully qualified name of the machine running the
PingFederate server and <port> is the port where the administrative
console listens. The default port is 9999.
26
PingFederate 6
Log File Generation
Log File Generation
PingFederate generates log files that document the system’s activities. The logs are
stored in the <pf_install>pingfederate/log directory and include:
•
admin.log — Records all actions performed by administrative console users
(see “Administrator Audit Logging” on page 28)
•
transaction.log — Records individual identity-federation runtime
transactions at specified levels of detail
The level of detail is configurable globally or on a connection-by-connection
basis (see “Runtime Transaction Logging” on page 29).
•
server.log — Records all PingFederate runtime and administrative server
activity
•
provisioner.log — Records only SaaS Provisioning activity (see “SaaS
Provisioning” on page 18)
Tip: PingFederate logs user attributes, when they are present, in the
server log, the transaction log, or both. When privacy is required for
sensitive user attributes, you can configure PingFederate to obfuscate
(mask) their values in the server and transaction logs (see “Attribute
Masking” on page 10).
Other logs contained in the pingfederate/log directory are generated by the
PingFederate Web container. These logs, <date>.request.log, record all
HTTP requests for the given date.
Note: Properties controlling request logging are contained in the Webcontainer configuration file jboss-service.xml located in the
PingFederate-installation directory:
pingfederate/server/default/deploy/jetty.sar/META-INF
In addition, a JBoss-generated startup log, boot.log, is located in the directory:
pingfederate/server/default/log
The PingFederate-generated logs can be controlled through the log4j.xml file
located in pingfederate/server/default/conf/. See comments in the
file for more information. Refer to the log4j open-source project for more
information about logging levels and other configuration parameters (http://
logging.apache.org/log4j/docs).
By default, PingFederate installs with a highly verbose level of logging. However,
verbose logging may have a performance impact and clutter the log files. You may
Administrator’s Manual
27
Chapter 2
System Administration
choose to lower the level, but we recommend that you not set it below WARN. For
the transaction.log, note that any setting below INFO turns logging off.
Important: The transaction.log, the admin.log, and the
provisioner.log files roll over at midnight each day. The system
keeps all of the resulting historical log files. The transaction.log
can become quite large, depending on your production load and
settings (see “Runtime Transaction Logging” on page 29); you might
wish to back up or remove older files on a routine basis.
Other PingFederate log files roll over when they reach 10MB. The
system keeps five old log files of each type before overwriting the
oldest. (This number can be changed in the /conf/log4j.xml file.)
The following sections provide more detail about the admin and transaction
logs.
Administrator Audit Logging
PingFederate records actions performed by server administrators. This
information is recorded in the admin.log file. While the events themselves are
not configurable, log4j.xml configuration settings may be adjusted to deliver
the desired level of detail surrounding each event.
Each entry in the admin.log file is on a separate line and represents a single
administrator action. The general format of each entry is the same, though
specific events are recorded with information relevant to each type. Events are
recorded when the corresponding Save button in the administrative console is
clicked.
A log entry is generated for each of the events listed below:
28
•
Password change
•
Password reset
•
Account activation
•
Account deactivation
•
Role change
•
Login attempt
•
Explicit user logouts (no time-outs)
•
Data store created
•
Data store modified
•
Data store deleted
•
Certificate management
•
SP connection created, modified, or deleted
•
IdP connection created, modified, or deleted
PingFederate 6
Log File Generation
•
URL-to-adapter mapping management
•
SP Adapter created, modified, or deleted
•
IdP Adapter created, modified, or deleted
•
Server settings management
•
Metadata export
•
Configuration archive
•
IdP Discovery management
•
SP Affiliation created, modified, or deleted
•
Attribute requester mapping
•
IdP default URL modified
•
SP default URLs modified
•
XML file signatures applied
Each log entry contains information relating to the event, including:
•
The time the event occurred on the PingFederate server.
•
The username of the administrator performing the action.
•
The role(s) assigned to the administrator at the time the event occurred.
•
The type of event that occurred.
•
Details about the event.
Each of the above fields is separated by a vertical pipe (|) for easier parsing.
Runtime Transaction Logging
PingFederate provides for flexible, scalable logging of all federated-identity
transactions (inbound and outbound XML messaging). Transaction logging can
be configured to any of four modes on a connection-by-connection basis (see
“General Information” in either of the “Managing Connections: . . .” chapters).
You also have the option of overriding transaction logging for all connections (to
find this feature, click the relevant Manage All . . . under IdP/SP Connections
on the Main Menu). You might wish to use this override for troubleshooting or
as a one-step means of raising or lowering all connection logging modes to the
same level.
Transaction Logging Modes
The table below describes the four transaction logging modes:
Table 1: Transaction Logging Modes
Administrator’s Manual
Mode
Description
None
No transaction logging.
29
Chapter 2
System Administration
Table 1: Transaction Logging Modes (Continued)
Mode
Description
Standard
(Default) Logs summary information
for each transaction message,
including:
• Time stamp
• Hostname:Port
• LogMode
• ConnectionID
• SAML Status Code> (for SAML
responses only)
• Context
• MessageType
• SAML ID (for SAML messages only)
• Endpoint (for outbound messages
only)
• Target URL (if SSO transaction)
Enhanced
Includes everything logged at the
Standard level plus:
• SAML_SUBJECT*
• Binding
• RelayState (if available)
• SignaturePolicy
• SignatureStatus
• HTTP Request Parameters (outbound
messages only)
* Only when available in a SAML
assertion, a single-logout request, a
Request Security Token Response
(RSTR), or an authentication request
(AuthnRequest)
Full
Includes everything logged at the
Enhanced level plus the complete
XML message for every transaction.
Each of the above fields is separated by a vertical pipe (|) for easier parsing.
Exporting Metadata
For SAML deployments PingFederate supports the export and import of
metadata files, which federation partners can use to expedite their deployments.
You export metadata via the Main Menu. You can import your partner’s
metadata file, when available, at the beginning of the connection-configuration
process (see “Managing IdP Connections” on page 212 or “Managing SP
Connections” on page 114).
30
PingFederate 6
Exporting Metadata
To reach the Metadata Export task:
X Click SAML Metadata Export under Administrative Functions on the
Main Menu.
To export connection metadata:
1. If your PingFederate server is configured to act as both an IdP and an SP,
indicate which type of configuration you will export and click Next.
2. On the Metadata Mode screen, choose the option to “Use a
connection . . .” and click Next.
3. On the Connection Metadata screen, select the connection from the dropdown menu and click Next.
4. (Optional) On the Metadata Signing screen, select a certificate to use for
signing the metadata XML file and click Next.
Note: If you want to include the public-key information in the
signed XML file, select the Key Info option.
For more information, see “Signing XML Files” on page 34.
5. On the Export & Summary screen click the Export button, save the file,
and then click Done.
To export selected metadata:
1. If your PingFederate server is configured to act as both an IdP and an SP,
indicate which type of configuration you will export and click Next.
2. On the Metadata Mode screen, select the option to “Select information .
. .” and click Next.
3. If you support more than one federation protocol, select the desired protocol
on the Protocol screen and click Next.
4. Configure any or all of the remaining steps in the task (click Next to skip
steps). For information see:
Administrator’s Manual
•
“Defining Metadata Attribute Contracts” on page 32.
•
“Choosing a Metadata Signing Key” on page 33.
31
Chapter 2
System Administration
•
“XML Encryption Certificates” on page 33.
5. (Optional) On the Metadata Signing screen, select a certificate to use for
signing the metadata XML file and click Next.
Note: If you want to include the public-key information in the
signed XML file, select the Key Info option.
For more information, see “Signing XML Files” on page 34.
6. On the Export & Summary screen click the Export button, save the file,
and then click Done.
Defining Metadata Attribute Contracts
The Attribute Contract screen allows you to define the attribute contract you
want to export in the metadata. For more information, see “Attribute Contracts”
on page 7.
To reach this screen:
1. Click SAML Metadata Export under Administrative Functions on the
Main Menu.
2. On the Metadata Mode screen, click the button for selecting the
information manually and click Next.
To add an attribute:
1. Enter an attribute on the Attribute Contract screen and click Add.
2. Continue to add attributes as needed and click Next.
To edit an attribute name:
1. Click Edit and make your change.
2. Click Update.
To delete an attribute:
X Click Delete.
32
PingFederate 6
Exporting Metadata
Choosing a Metadata Signing Key
In your metadata file you can manually include the public key for partners to use
to verify the digital signature you will use to sign SAML messages. For more
information, see “Digital Signing and Decryption Keys & Certificates” on
page 96.
To export your public signature verification key:
X Select the key from the drop-down list and click Next.
XML Encryption Certificates
In your metadata file you can manually include the XML encryption key and
certificate your partners can use to encrypt SAML messages.
To export an XML encryption key:
X Select the key from the drop-down list and click Next.
If the certificate is not shown, click Manage Certificates to import it.
Administrator’s Manual
33
Chapter 2
System Administration
Completing the Export
On the Export & Summary screen, you can complete the XML-file download or
change any information by clicking any of the headings in the Summary.
Important: To finish the download, you must click the Export
button at the bottom left of the Export Metadata screen.
Signing XML Files
PingFederate supports digital signing of SAML metadata files or any other XML
files that you and your partner might want to exchange. A signature applied to
an XML file ensures that the file is from the original source and that its contents
have not been modified by a third party.
When you configure a partner connection, you can also verify and import signed
metadata files. For information:
•
As an SP configuring an IdP connection, see “Importing Metadata” on
page 217.
•
As an IdP configuring an SP connection, see “Importing Metadata” on
page 121.
X XML file signing is available from the Main Menu under Administrative
Functions.
To sign an XML file:
1. On the Select XML File screen, locate and open the file.
2. On the Digital Signature Settings screen, choose the certificate containing
your signing key from the drop-down list.
Note: By default, certificate and public-key information is included
in the signed XML file. If you do not wish to include this
information, clear the Key Info checkbox.
34
PingFederate 6
Using the Configuration Archive
3. On the Export & Summary screen, click the Export button to save the
signed file.
Important: Be sure to click Export in the lower-left portion of the
Export & Summary screen; clicking Done does not complete the
operation.
Using the Configuration Archive
PingFederate’s archive utility allows you to download your configuration to a ZIP
file. You can use this file to restore server configurations. A configuration archive
is created automatically every time you log on to the administrative console. The
archives are stored in pingfederate/server/default/data/archive.
Configuration archives can also be used to transfer data from one server to
another or into a new release of PingFederate.
Important: Configuration archives should not contain any draft
connections if the archive it intended to be used as a backup or to
transfer data—draft connections in archives are not imported.
Either complete or remove any unfinished partner connections
before creating a backup or migration archive.
Note: The configuration archive does not include error-page or other
end-user HTML templates (see “Customizing User-Facing Screens” on
page 50). If any changes have been made to these pages, you must
copy them over to new installations of PingFederate.
To reach this screen:
X Click Configuration Archive on the Main Menu.
To save an archive:
X On the Configuration Utilities screen, click Export and save the download
to your file system, then click Done.
Administrator’s Manual
35
Chapter 2
System Administration
To deploy an archive:
1. Copy the file into the directory:
<pf_install>/pingfederate/server/default/data/
drop-in-deployer
2. Rename the copied file to data.zip.
When the PingFederate server is running, the file is renamed with a time
stamp after a moment and the data automatically deploys.
Caution: A deployed archive overwrites all existing configuration
data.
Account Management
PingFederate provides a choice of single- or multi-user system administration
(see “Setting Administration Options” on page 56).
Note: This choice is not presented if you are using your network’s LDAP
user-data store for PingFederate authentication to the administrative
console (see “Using LDAP Authentication” in the “Installation” chapter
of Getting Started).
If you choose native multi-user administration or if you are using network LDAP
authentication, PingFederate provides role-based access control, as shown in
Table 2. For native multi-user administration, you can choose to use email for
password setting and resetting notifications.
Table 2: PingFederate User Access Control
36
Role Assignment
Access Privileges
User Admin
Manage users, select administration style (single- or
multi-user), define email notification policies, and
configure an SMTP server connection. (This role is
not provided if you are using LDAP authentication
for administrative logon, since user management is
handled outside of PingFederate.)
Admin
Configure partner connections and most system
settings (except user management and local key/
certificate handling).
Crypto Admin
Manage local keys and certificates.
Auditor
View-only permissions for all administrative
functions.
PingFederate 6
Account Management
When Auditor is assigned, no other roles may be set. Admin users may have
multiple roles set.
Tip: The same user may log on from more than one browser or
location. Also, by default, more than one user can log on to
PingFederate at a time. You can change this default to restrict the
administrative console to one administrative user at a time (see
“Changing Configuration Parameters” on page 42).
Any number of auditors may log on at any time, regardless of the
property setting.
To reach the Account Management screen:
X Click Account Management under Administrative Functions on the Main
Menu.
Note: If you are using your network’s LDAP user-data store for
PingFederate authentication, the Account Management
configuration is not available. Set PingFederate-specific
permissions for existing network users in the LDAP runtime
configuration file in <pf_install>/pingfederate/bin (see
“Using LDAP Authentication” in the “Installation” chapter of
Getting Started).
Users with User Admin permissions can add other users, assign them any role, or
reset their passwords, as well as change their own passwords. Other types of users
can change only their own passwords from this screen (see “Changing Passwords”
on page 40).
To add a user:
1. Click Create User.
Administrator’s Manual
37
Chapter 2
System Administration
2. On the User Information screen, enter the required fields (indicated by
asterisks).
Note: Only Username is required, unless you elected on the
Account Management screen to have PingFederate send
passwords via email, in which case you must supply an email
address.
3. (Optional) Enter additional information.
4. Click Next to set up a password (see “Setting or Resetting Passwords” on
page 39).
Important: After you set the password and return to the Account
Management screen, you must select permissions for the new
user and click Save to complete the process.
To define a user’s permissions:
X Select or clear the checkboxes under the permission categories you want to
assign or remove (see Table 2 on page 36).
Clicking the Auditor button deactivates other permission selections.
Note: For traceability and accountability purposes, users cannot be
deleted; their records are retained and they can be reactivated if
needed.
To enable password notification:
1. Click the password-notification checkbox.
2. If you have not yet configured PingFederate to use your email server, click
Email Server Settings and complete the configuration (see “Managing
Email Configuration” on page 40).
3. Click Save (or Next if you are installing PingFederate).
Note: If you are setting up email notifications for the first time, you
must click Email Server Settings and configure the settings. If you are
not sure of the correct settings, enter placeholders on the Email
Notification screen; you can return later and update the information.
38
PingFederate 6
Account Management
Setting or Resetting Passwords
A user administrator can generate or assign temporary passwords for other users,
either during user setup or at a later time (for example, if a user forgets his or her
password).
Note: If you are using an LDAP user-data store for PingFederate
authentication, password management is handled at the network level.
Initial or reset passwords may be used only once; the administrative console
requires the user to change the password immediately after logging on.
To reach this screen:
1. Click Account Management on the Main Menu.
2. Click Reset Password under Action for a user.
To set or reset a user’s password:
1. Either:
•
Click Generate one-time password.
Or:
•
Enter a password in the text box (no restrictions apply for a temporary
password).
2. Click Done.
Important: The password and any other changes, including new
user records, are not stored until you click Save on the Account
Management screen.
After you click Save on the Account Management screen, the new password is
emailed to the user automatically, if you have enabled email notifications (see
“Account Management” on page 36).
Administrator’s Manual
39
Chapter 2
System Administration
Changing Passwords
Any user can change his or her own password. For information about resetting
another user’s password (if you are a user administrator), see the previous section.
Note: If you logged on to PingFederate using your network ID and
password, you can change your password only at the network level. The
new password will apply to PingFederate automatically the next time
you log on.
To change your password:
1. Click Account Management on the Main Menu.
2. On the Account Management screen, click Change Password under the
Action column.
3. Enter your Current Password and New Password (twice) and click Save.
Passwords must be at least six characters long and contain at least one uppercase character, one lower-case character, and one number.
Important: If you are the sole user administrator, take steps to ensure
that you do not forget your new password.
Managing Email Configuration
If you are using email notification for password resets, licensing events, or
certificate-expiration warnings, you must set up and maintain a connection to
the email server that PingFederate will use to send messages (see “Account
Management” on page 36 and “Configuring Runtime Notifications” on page 58).
40
PingFederate 6
Managing Email Configuration
Field Descriptions
Field
Description
“From” Address
The email address that appears in the “From” header
line in email messages generated by PingFederate.
The address must be in valid format but need not be
set up on your system.
Email Server
The IP address or hostname of your email server.
SMTP Port
The SMTP port on your email server (default: 25).
Username
Authorized email username.
Password
User password.
Confirm Password
Re-entered password.
Test Address
(Optional) An email address where you want to send a
test message.
To reach this screen:
X Click Email Configuration on the Main Menu under Administrative
Functions.
If this link is not displayed, then no email notifications are configured (see
“Configuring Runtime Notifications” on page 58 or “Account Management”
on page 36).
Administrator’s Manual
41
Chapter 2
System Administration
To configure access to your email server:
1. Enter information into all fields. (Username and Password are not
required.)
2. (Optional) Enter an email address (or addresses) in the Test Address field
and click Test Email Connectivity.
A message next to the button indicates a successful test. Verify that the test
email address received a message from the server.
Test reports are also written to the server.log file in the /log directory.
Using Virtual Host Names
In certain contexts, the SAML specifications require that XML messages include
a URL identifying the host name to which the sender directed the message. (The
name of the XML element containing the URL varies among protocols.) In
addition, the recipient must verify that the value matches the location where the
message is received.
Depending on your networking requirements, this specification can present
problems—for example, in the case of proxy forwarding, where the final
destination host name might be unknown to your federation partner. To provide
more flexibility in such cases, you can set up a list of alternative host names for
PingFederate to use as part of its message-security validation.
Note that virtual host names are used for a different purpose than virtual server
IDs, which provide separate unique identifiers for a federation deployment,
normally in the same domain (see “Federation Server Identification” on
page 20). Depending on your needs, however, you can configure virtual server
IDs and virtual hosts in the same installation of PingFederate.
Changing Configuration Parameters
PingFederate’s default administrative-console and runtime behavior is controlled
in part by configuration properties contained in the file run.properties,
located in: <pf_install>/pingfederate/bin. Table 3 describes the
properties; refer to the file itself for default settings not specified here.
42
PingFederate 6
Changing Configuration Parameters
You can change these settings as needed. Restart the PingFederate server for
changes to take effect.
Note: Properties related to server clustering are described in the
PingFederate Server Clustering Guide.
Important: If your site uses clustering, changes to default settings
for runtime-server properties must be applied to other server
nodes manually. The settings in run.properties are not
replicated using automated synchronization methods.
Table 3: PingFederate Configuration Properties
Administrator’s Manual
Property
Description
pf.admin.https.port
Defines the port on which the PingFederate
administrative console runs. Default is
9999.
pf.console.bind.address
Defines the IP address over which the
PingFederate administrative console
communicates. Use for deployments where
multiple network interfaces are installed on
the machine running PingFederate.
pf.console.login.mode
Indicates whether more than one Admin
user may access the administrative console
at one time (see “Setting Administration
Options” on page 56). Values: Single |
Multiple. Default is Multiple.
pf.console.authentication
Indicates whether administrators log on to
PingFederate using credentials managed
internally, by PingFederate, or externally,
using your network LDAP data store. Values:
native | LDAP. Default is native. (See
“Using LDAP Authentication” in the
“Installation” chapter of Getting Started.)
ldap.properties.file
When LDAP administrative-console
authentication is enabled, indicates the
name of the file containing configuration
properties.
43
Chapter 2
System Administration
Table 3: PingFederate Configuration Properties (Continued)
Property
Description
pf.http.port
Defines the port on which PingFederate
listens for unencrypted HTTP traffic at
runtime. For security reasons, this port is
turned off by default.
Caution: This port should remain disabled in
production if your deployment configuration
directly exposes the PingFederate server to
the Internet.
pf.https.port
Defines the port on which PingFederate
listens for encrypted HTTPS (SSL/TLS)
traffic. Default is 9031.
pf.secondary.https.port
Defines a secondary HTTPS port, for use on
the back channel, to facilitate interoperability
with other federation software vendors. To
use this port, change the placeholder value
to the port number you want to use, if
needed.
Additional configuration of the listener ports
(including adding new listeners) is available
via the <pf_install>/pingfederate/
server/default/deploy/
jetty.sar/META-INF/jbossservice.xml file. Of particular value are
the WantClientAuth and
NeedClientAuth flags, which indicate to
a client the request or requirement,
respectively, for a client certificate. (For this
port, WantClientAuth is set to true by
default; NeedClientAuth is set to false.)
44
pf.engine.bind.address
Defines the IP address over which the
PingFederate server communicates with
partner federation gateways. Use for
deployments where multiple network
interfaces are installed on the machine
running PingFederate.
pf.monitor.bind.address
Defines the IP address over which an SNMP
agent and JMX communicate with
PingFederate (see “Configuring Runtime
Reporting” on page 59). Use for
deployments where multiple network
interfaces are installed on the machine
running PingFederate.
pf.hsm.mode
Enables or disables (the default) a FIPScompliance Hardware Security Module (see
Appendix A in Getting Started).
PingFederate 6
Installing a New License Key
Table 3: PingFederate Configuration Properties (Continued)
Property
Description
pf.provisioner.mode
Enables or disables (the default) SaaS
Provisioning (see “SaaS Provisioning” on
page 18). Also used to enable provisioning
failover (see the PingFederate Server
Clustering Guide).
Installing a New License Key
If your license expires, you must install a new license key.
Note: You can configure the server to send an email in advance (see
“Configuring Runtime Notifications” on page 58).
You will also need to install a new license key after you obtain PingFederate
software releases (other than patch releases).
When your license key has expired:
1. Request a license key from Ping Identity.
You will need your PingFederate version number.
2. You will receive the license key via email.
3. Save the pingfederate.lic file to pingfederate/server/
default/conf.
Important: The license key must be named pingfederate.lic.
It may take up to a minute for a running server to recognize the
new key.
Automating Configuration Migration
PingFederate provides a configuration-migration tool that can be used for
scripting the transfer of partner connections and adapter configurations from one
PingFederate server to another—for example, from a test environment to
production. The command-line utility, configcopy in <pf_install>/
pingfederate/bin, uses the PingFederate Connection Management Web
Service to export and import configurations (see “Connection Management
Service” on page 357).
Administrator’s Manual
45
Chapter 2
System Administration
This tool performs these functions:
1. Retrieves configuration data (XML) from a source PingFederate server.
2. Modifies the configuration with any changes required for the target
environment, according to settings in a properties file and/or command-line
arguments.
3. Imports the updated configuration into the PingFederate target server.
The configcopy tool can perform these functions at once, from server to
server, when both PingFederate servers are running and accessible from a
command console. Alternatively, an intermediate file may be created for
separately scripted import into the target server.
Filtered list commands of source connections and adapter instances are also
available.
Using the Migration Tool
The configuration-migration utility works in conjunction with a properties file,
which identifies the operational commands and provides a means of setting
source and/or target PingFederate servers, connection identifiers (for singleconnection operations), optional transport filenames, and any configuration
settings that may need to be modified for the target environment. A template for
the properties file, configcopy.conf, is located with the tool itself in
<pf_install>/pingfederate/bin.
Copies of the properties file can be configured as needed. Property-file settings
might include, for example: one connection at a time, all connections, one
adapter configuration at a time, all adapter configurations, and so on, using
multiple combinations. Use the applicable configuration filename as an
argument when running configcopy.bat or configcopy.sh (depending
on your operating system) for particular connections, using the following
command syntax:
configcopy -Dconfigcopy.conf.file=<properties_file>
You can also define any property values (except passwords) via commandexecution arguments, using the following syntax:
configcopy -D<property>=<value>
where <property> is any property named in the properties file and
<value> is a command option (or other operational data such as input/
output file path), or any connection/adapter configuration overrides you
want to use at the target.
46
PingFederate 6
SaaS Provisioning CLI
Command-line property designations take precedence over any values set in the
properties file.
Note: Access to the Connection Management Web Service is
username/password-protected (see “Application Authentication” on
page 99). Usernames and passwords may be set in the properties file
for both the source and target Web Services (passwords may be
obfuscated). If passwords are set in the properties file, they cannot be
overridden using the command line. If a password is not set, the
configcopy tool prompts for it. (Usernames always must be supplied,
either in the command line or in the properties file.)
For more detailed information, including a list of command options and all
connection Override Properties (configuration settings that can be modified),
refer to the configcopy.conf file.
SaaS Provisioning CLI
PingFederate provides as command-line interface (CLI) to help manage
automated provisioning for SaaS users at IdP sites (see “SaaS Provisioning” on
page 18). Administrators can use this tool to view the status of user provisioning,
either globally or one provisioning channel at a time, and to rectify unusual
situations where provisioning at the SaaS provider may get out of sync with the
enterprise user store (see “Configuring SaaS Provisioning” on page 177).
The CLI tool, provmgr.bat or provmgr.sh, is located in the directory
<pf_install>/pingfederate/bin. The tool interacts with the internal
data store PingFederate uses to maintain provisioning synchronization between
the LDAP user store and the target service (see “Configuring SaaS Provisioning
Settings” on page 69).
Note that the tool creates its own log file, provmgr.log, located in the
directory <pf_install>/pingfederate/log. You can control settings for
this log, as needed, in the file provmgr.log4j.properties, located in the
bin directory.
The following tables describes the available global and channel-specific
command arguments:
Table 4: SaaS Provisioning CLI Global Options
Administrator’s Manual
Command Argument
Description
--help
Describes the available options. The help is also
displayed if the command is run with no
arguments.
47
Chapter 2
System Administration
Table 4: SaaS Provisioning CLI Global Options
Command Argument
Description
--show-channels
Lists all channels in a table format, showing for
each:
• ID - A numeric channel ID (channel-specific
commands need this ID)
• Name - The channel name
• Connection ID
• Status (active/inactive) - Both the connection and
the channel status are shown (see “Channel
Activation and Summary” on page 188)
• User count/dirty-user-record count (e.g.: 5000/12
means 5000 users and 12 dirty records)
• Source (as LDAP URL)
• Target code
--show-nodes
Shows all the provisioning-server nodes with their
status and the last timestamp (applies only to a
failover configuration—see the PingFederate Server
Cluster Guide in the installation docs directory).
--force-node-backup
Sets the provisioner mode to FAILOVER for the
associated PingFederate server node (see the
Server Clustering Guide).
Use with node
number:
-n <node ID>
The table below describes the available channel-specific command arguments:
Note: With each command, specify the channel with the argument:
-c <channel-id-number>
Example:
provmgr -c 1 --show-source
You can determine channel ID numbers by using the global command:
provmgr --show-channels
48
PingFederate 6
SaaS Provisioning CLI
Table 5: SaaS Provisioning CLI Channel-Specific Options
Command Argument
Description
--reset-group-timestamp
Deletes the group timestamp, which forces the
provisioner to process the provisioning group on
the next cycle, even if the timestamp on that group
did not actually change.
Depending on your LDAP server and administrative
practices, you may want to schedule this command
to run periodically to catch up with any users that
may have been deleted (rather than deactivated) in
the directory server: some directory servers do not
update the group timestamp for deleted users.
Important: This option should seldom be needed if
users are deactivated rather than deleted. If it is
needed, you may wish to schedule it when other
network activity is low.
--reset-attribute-sync
Sets the attribute sync timestamp to 1, which
forces the provisioner to look at all users for
changes, not only those that have a newer
timestamp on their LDAP entry.
Important: This option should be needed rarely
and may consume considerable network
resources, depending on the number of users. If it
is needed, you may wish to schedule it when other
network activity is low.
--reset-values-hash
Removes the values hash for all users. (The
database stores a hash of attribute values for users
to determine whether any values have been
changed.)
This argument forces users that have a newer
timestamp on their LDAP entry to be updated at
the SaaS provider, regardless of the actual field
values. Note, however, that users whose recorded
timestamp is unchanged are not updated.
--reset-all
Equivalent to using all three of the arguments
above.
Important: This option should be needed rarely if
ever and may consume considerable network
resources, depending on the number of users. If it
is needed, you may wish to schedule it when other
network activity is low.
--show-dirty-records
Lists all users who have not been provisioned or
updated at the SaaS site. Each entry shows:
• LDAP GUID
• SaaS Username
• SaaS GUID
Administrator’s Manual
49
Chapter 2
System Administration
Table 5: SaaS Provisioning CLI Channel-Specific Options
Command Argument
Description
--show-user
Shows all internal database fields related to the
specified user, including transitory mapping fields
(fields waiting to be pushed to the SaaS provider);
also shows all LDAP attributes retrieved from the
directory server for this user.
Use with:
-u <SaaS Username>
Or:
-g <LDAP GUID>
Note: You can obtain usernames and GUIDs for
dirty user records, as needed, using the --showdirty-records option.
The LDAP GUID, if used and if it is binary, should be
entered in hexadecimal format (as shown in log
files).
Examples:
provmgr.sh --show-user -u
john@example,com
provmgr.sh --show-user -g
ffd448643f812b43a0bee2504173f0
--clear-dirty-records
Clears the dirty flag on all user records.
--delete-dirty-records
Removes all dirty user records from the internal
store.
--delete-all-users
Removes all users from the internal store and
deletes the provisioning group timestamp and the
last attribute-sync timestamp.
The effect of this command is to reset the channel
to its initial state. All user metadata is lost and
provisioning for the channel will start from the
beginning, picking up all users and pushing them to
the SaaS provider when the synchronization
frequency interval is expired (see “Configuring
SaaS Provisioning Settings” on page 69).
Important: This option should be needed rarely if
ever. If it is needed, you may wish to schedule it
when other network activity is low.
--show-target
Displays the target configuration.
--show-source
Displays all source LDAP configuration parameters,
including settings and location.
Customizing User-Facing Screens
PingFederate supplies HTML templates to provide information to the end user or
to request user input during SSO/SLO processing. These template pages utilize
the Velocity template engine, an open-source Apache project, and are located in
50
PingFederate 6
Customizing User-Facing Screens
the <pf_install>/pingfederate/server/default/conf/template
directory.
You can modify most of these pages in a text editor to suit the particular branding
and informational needs of your PingFederate installation. Each page contains
both Velocity constructs and standard HTML. The Velocity engine interprets
the commands embedded in the template page before the HTML is rendered in
the user’s browser. At runtime, the PingFederate server supplies values for the
Velocity variables used in the template.
Tip: Variables indicated in each file are the only variables that can be
used for rendering the associated Web-browser page.
For information about Velocity, please refer to the Velocity project
documentation on the Apache Web site:
http://velocity.apache.org/engine/releases/velocity-1.4
Changing Velocity or Javascript code is not recommended.
At runtime, the user’s browser is directed to the appropriate page, depending on
the operation being performed and where the related condition occurs (see tables
below). For example, if an SSO error occurs during IdP-initiated SSO, the user’s
browser is directed to the IdP’s SSO error-handling page.
Applications can override the PingFederate server-hosted pages provided
specifically for SSO and SLO errors by specifying a URL value in the relevant
endpoint’s InErrorResource parameter (see “Application Endpoints” on
page 347). Administrators can override SSO/SLO success pages by specifying
default URLs in the administrative console (for the IdP configuration, see
“Configuring a Default URL and Error Message” on page 112; for the SP, see
“Configuring Default URLs” on page 207).
The following tables describe each of the templates. To help identify the
templates from the end user’s point of view, the tables are organized by the titles
that appear at the top of the user’s browser window.
Note: Because the templates can be customized, the default titles
listed in the tables may not be accurate for your PingFederate
installation or your partner’s.
Table 6: IdP User-Facing Pages
Page Title
and template file name
Purpose
Type
Action
Error - Single Logout
Displayed when an SLO request fails and
no other SLO error landing page is
specified.
Error
User
should
close
browser
idp.slo.error.page.template.html
Administrator’s Manual
51
Chapter 2
System Administration
Table 6: IdP User-Facing Pages (Continued)
Page Title
and template file name
Purpose
Type
Action
Error - Single Sign-On
Displayed when IdP-initiated SSO fails and
no other SSO error landing page is
specified. Displays system errors and
information for the user.
Error
Consult log
and Web
developer
Displayed when the user must choose
from several IdP security domains. Based
on the user’s selection, the server
redirects the browser to the appropriate
adapter instance for authentication.
Normal
User must
make
selection
Indicates user signed out of the IdP under
the WS-Federation protocol and lists each
successful SP logout, when applicable.
Normal
None
WS-Federation IdP sign-out processing
page.
Normal
None
Displayed when an SLO request succeeds
but no other SLO landing page is
specified.
Normal
None
Used to auto-submit a WS-Federation
assertion to the SP. If Javascript is
disabled, the user is prompted to click a
button to POST the assertion directly.
Normal
None
idp.sso.error.page.template.html
Please Select Authentication System
sourceid-choose-idp-adapter-formtemplate.html
Signed Out
sourceid-wsfed-idp-signout-cleanuptemplate.html
Signing Out
sourceid-wsfed-idp-signout-cleanupinvisible-template.html
Note: No HTML is rendered in the
browser.
Success - Single Logout
idp.slo.success.page.template.html
Working . . .
sourceid-wsfed-http-post-template.html
Note: Normally not displayed if Javascript
executes properly.
Table 7: SP User-Facing Pages
Page Title
and template file name
Purpose
Type
Action
Account Link Removed
Communicates a user's successful
“defederation” operation.
Normal
None
Used to authenticate a user at the SP
when an account link needs to be
established.
Normal
None
Displayed when an authentication
challenge fails during WS-Federation
processing.
Error
Consult log
and Web
developer
Displayed when an SLO request fails
and no other SLO error landing page is
specified.
Error
User should
close the
browser
TerminateAccountLinks.page.template.html
Account Linking
LocalIdPasswordLookup.form.template.html
Authentication Failed
sourceid-wsfed-idp-exception-template.html
Error - Single Logout
sp.slo.error.page.template.html
52
PingFederate 6
Customizing User-Facing Screens
Table 7: SP User-Facing Pages (Continued)
Page Title
and template file name
Purpose
Type
Action
Error - Single Sign-On
Displayed when SP-initiated SSO fails
and no other SSO error landing page is
specified.
Error
Consult log
and Web
developer
The user requested SP-initiated SSO,
but the IdP partner was not specified in
the appropriate query parameter or
cookie. This page allows the user to
select the IdP manually. Based on the
user’s selection, the server redirects the
browser to the appropriate IdP partner’s
SSO service.
Normal
User must
make
selection
Displays the user's sign-out status.
Normal
None
Displayed when an SLO request
succeeds and no other SLO success
landing page is specified.
Normal
None
Displayed when an SSO request
succeeds but no target-resource
parameter is specified by the incoming
URL, and no default URL is set (see
“Configuring Default URLs” on
page 207).
Error
Consult
Web
developer,
or specify
default URL
sp.sso.error.page.template.html
Select Identity Provider
sourceid-saml2-idp-selection-template.html
Signed Out - Service Provider
sourceid-wsfed-sp-signout-cleanuptemplate.html
Success - Single Logout
sp.slo.success.page.template.html
Single Sign-On Target Unspecified
sp.sso.success.page.template.html
Table 8: Either IdP or SP User-Facing Pages
Page Title
and template file name
Purpose
Type
Action
Error - Single Sign-On
For an Auto-Connect SSO transaction,
indicates a range of possible error
conditions (see “Using Auto-Connect”
on page 15):
Error
Consult log,
check configuration, or
contact partner. If unresolved,
contact Ping
Identity support.
Error
Consult log,
contact Ping
Identity
support
generic.error.msg.page.template.html
• The requesting Auto-Connect partner is
not found in the PingFederate server’s
list of allowed domains.
• The partner’s metadata is not
accessible.
• The server is not configured for AutoConnect.
• General error, with error code.
Error
general.error.page.template.html
Administrator’s Manual
Indicates that an unknown error has
occurred and provides a error reference
number and (optionally) an error
message.
53
Chapter 2
System Administration
Table 8: Either IdP or SP User-Facing Pages (Continued)
Page Title
and template file name
Purpose
Type
Action
Sign On
Challenges user for credentials when
authentication can take place via HTTP
Basic Authentication or an HTML form,
depending on the operational mode.
Normal
User must
sign on
Whenever the server posts a form, this
template is used to auto-submit the
form. If Javascript is disabled, the user is
prompted to click a button to post the
form manually.
Normal
None
AbstractPasswordIdpAuthnAdapter.form.te
mplate.html
Submit Form
form.autopost.template.html
Note: Normally not displayed if
Javascript executes properly.
54
PingFederate 6
Chapter
3
System Settings
The System Settings links on the Main Menu (under My Server) provide
access to global settings that may apply to either an IdP or an SP federation
configuration.
This chapter covers:
•
“Managing Server Settings” on page 55
•
“Managing Data Stores” on page 72
•
“Configuring IdP Discovery” on page 83
Note: The information in this chapter is presented from the viewpoint
of an administrative user with “Admin” permissions (see “Account
Management” on page 36).
Managing Server Settings
Server settings include unique federation server identifiers, the designation of
your site’s federation role (SP, IdP, or both), and your enabled federation
protocols (see the “Supported Standards” chapter in Getting Started).
Server settings also include system-administration configuration (one-user or
multi-user), email notification options and setup, and a shortcut link to account
management (when multi-user administration is enabled).
If you have enabled Auto-Connect and/or a SaaS Connector, then you will need
to configure several parameters specific to those features in the System Settings
task flow.
You configure many of these settings initially during the installation setup (see
“Running PingFederate for the First Time” in the “Installation” chapter of
Administrator’s Manual
55
Chapter 3
System Settings
Getting Started), but you can change or add to them as needed from the Main
Menu.
Information in this section covers:
•
“Setting Administration Options” on page 56
•
“Entering System Information” on page 57
•
“Configuring Runtime Notifications” on page 58
•
“Configuring Runtime Reporting” on page 59
•
“Managing Accounts” on page 63
•
“Choosing Roles and Protocols” on page 64
•
“Specifying Federation Information” on page 67
•
“Configuring SaaS Provisioning Settings” on page 69
•
“Configuring Auto-Connect Metadata Signing” on page 71
•
“Configuring Auto-Connect Metadata Lifetime” on page 71
•
“Saving and Editing Server Settings” on page 72
Setting Administration Options
On the System Administration screen, PingFederate provides a choice of singleor multi-user access to the administrative console.
Note: If you are using your network’s LDAP user-data store for
administrative-console authentication, this option is not presented (see
“Using LDAP Authentication” in the “Installation” chapter of Getting
Started).
If you choose single-user administration, the console is accessible only by using
the default Administrator ID, for which full privileges are provided. If you
56
PingFederate 6
Managing Server Settings
choose multi-user administration, the system provides role-based access control
(see “Account Management” on page 36).
Note: To return to single-user administration after having previously
enabled multi-user, you must have only one user marked as active
under Account Management.
Also on this screen you can choose to use different SSL server certificates for the
administrative console and for PingFederate runtime processing. To fully
implement this choice, you must import two (or more) server certificates into
PingFederate (see “SSL Server Certificates” on page 91).
To reach this screen:
1. Click Server Settings on the Main Menu.
2. Click System Administration under the Server Settings tab.
Entering System Information
On the System Info screen, you provide general information about your
company.
To reach this screen:
1. Click Server Settings on the Main Menu.
2. Click System Info under the Server Settings tab.
Administrator’s Manual
57
Chapter 3
System Settings
Configuring Runtime Notifications
Depending on your licensing agreement, your PingFederate license may have an
expiration date. Under Runtime Notifications you can set up the server to send
an email warning when your license is about to expire.
Note: The license-notification option does not appear if you have a
perpetual license.
You can also configure the server to send an email notification to a specific
administrator (or a group) when a certificate used by PingFederate is about to
expire, or has expired.
Note: When a certificate expires, PingFederate always writes an error
in the server log, regardless of whether runtime notification is
configured (see “Log File Generation” on page 27).
To reach this screen:
1. Click Server Settings on the Main Menu.
2. Click Runtime Notifications on the Summary screen.
To configure notifications:
1. Click the checkbox next to the type of notification you want, and enter an
email address.
58
PingFederate 6
Managing Server Settings
2. If you are configuring certificate-expiration notification, enter an advancewarning time period in the Initial Warning field (optional) and in the Final
Warning field.
Note: When advance certificate-expiration notification is
configured, the server also sends notification if a license expires.
3. If you have not previously configured PingFederate to access your email
server, click Email Server Settings (see “Managing Email Configuration”
on page 40).
Configuring Runtime Reporting
PingFederate supports runtime monitoring and reporting through the Simple
Network Management Protocol (SNMP), a standard used by networkmanagement consoles to monitor network and server activity across an
enterprise.
In addition, PingFederate supports runtime monitoring and reporting through
Java Management Extensions (JMX) (see “Runtime Monitoring Using JMX” on
page 60).
Using SNMP Monitoring
The SNMP Management Information Base (MIB) is included in the docs/
SNMP directory of the PingFederate distribution. The MIB describes the object
identifiers that PingFederate uses to communicate information through SNMP.
These identifiers are globally unique and managed by IANA (Internet Assigned
Numbers Authority).
Configure details of SNMP monitoring, if your site uses this form of monitoring,
on the Runtime Reporting screen.
Administrator’s Manual
59
Chapter 3
System Settings
SNMP supports Gets and Traps. A Get is a request for status information sent by
a network-management console to an SNMP agent. Embedded within each
PingFederate server is an SNMP agent that brokers the communication between
the management console and PingFederate.
PingFederate responds to two types of Get requests:
•
The total number of transactions the server has processed since installation
•
The total number of failed transactions that the server has encountered since
installation
Note: Some operating systems (Solaris 10, for example) may not allow
the SNMP agent to bind to privileged ports: those below 1024. Consult
your operating system’s documentation on how to get around this
limitation, or change the default port 161 to a port above 1023.
A Trap is a spontaneous communication from an agent to a networkmanagement console. PingFederate generates a Trap at regular intervals—the
server “heartbeat.” Each Trap contains the amount of time the server instance
has been running since its most recent startup.
X If you configure Traps, change settings as needed and then click Test SNMP
Configuration to send a single Trap to your network-management console.
You can also use an HTTP call at any time to verify that the PingFederate server
is running (see “Maintenance Endpoint” on page 356).
Runtime Monitoring Using JMX
Similar to SNMP, JMX technology represents a Java-centric approach to
application management and monitoring. JMX exposes instrumented code in the
60
PingFederate 6
Managing Server Settings
form of Managed Beans (MBeans). Application management systems that
support JMX technology—for example, the standard Sun JDK client, JConsole—
may request runtime information from PingFederate’s JMX server.
PingFederate’s JMX server reports monitoring data for SSO and SLO
transactions as well as for SaaS Provisioning (see “SaaS Provisioning” on
page 18). In addition, because PingFederate is built within an existing JBoss
framework, numerous JBoss-standard MBeans are available to the PingFederate
server’s JMX clients.
Important: Authentication is required for JMX-client access to
PingFederate runtime data (see “Application Authentication” on
page 99).
SSO/SLO Monitoring
For SSO/SLO transaction processing, PingFederate provides these MBeans:
•
pingfederate:type=TOTAL_FAILED_TRANSACTIONS
•
pingfederate:type=TOTAL_TRANSACTIONS
Each type contains a single attribute, Count, which reports the same
information as an SNMP Get (see “Configuring Runtime Reporting” on
page 59).
Note: Counts are reset when the PingFederate server is restarted.
Provisioning Monitoring
For SaaS Provisioning, PingFederate provides an MBean called
pf.provisioning:type=saas.provisioning.events. The MBean
exposes four JMX Operations, each corresponding to the Java methods described
in Table 9. Each method returns a CompositeData object, which allows for the
Administrator’s Manual
61
Chapter 3
System Settings
retrieval of complex data without requiring application-specific code to reside
with the JMX client.
Table 9 SaaS Provisioning JMX Monitoring Options
Method
Description
Parameters
viewEvents(
Boolean wasSuccessful,
String eventTypeStr,
String fromDate,
String toDate)
Gets an array of specific
events based on the given
criteria. The parameters filter
the data collectively; that is,
they are joined logically by
“and”.
wasSuccessful – If true,
returns information only on
successful transactions;
false returns information
only on failed transactions;
null returns all transactions.
eventTypeStr – The type of
event. Valid values are:
CREATE, UPDATE, DISABLE,
ENABLE; null or an empty
string returns all types.
fromDate – See Note below.
toDate – See Note below.
eventSummaryReport(
String fromDate,
String toDate)
Gets a summary of
transactions counts for the
given time period. Counts are
provided for success, failure,
and total. Each count
includes a drill-down
capability, providing counts
by event type.
See Note below.
eventSummaryReportAllData()
Gets a summary of
transaction counts with no
time constraints (equivalent
to eventSummaryReport
with null or empty strings
used as parameters).
N/A.
eventSummaryRollup()
Gets a report representing an
aggregate of multiple
Summary Reports covering
the last 0, 1, 2, 7, 30, 60, 90,
180, and 360 days.
N/A.
Note: Date parameters may be formatted as either yyyy, yyyy-MM-dd, or yyyy-MM-dd
HH:mm:ss. A null value or empty string for a date parameter indicates no constraint for that end of
the range.
Advanced JMX Configuration
By default, PingFederate uses port 1099 for its JMX server. To change the port or
other JMS configuration items, if needed, modify the configuration file jmx-
62
PingFederate 6
Managing Server Settings
remote-config.xml in the directory <pf_install>/server/default/
data/config-store.
Note: When connecting to the JMX service using SSL (the default),
ensure that the client trusts the PingFederate SSL server certificate
presented (see “SSL Server Certificates” on page 91). (This should be a
consideration only during testing, when using the certificate installed
with PingFederate or another self-signed certificate.)
Managing Accounts
When you choose multi-user system administration, you can create users during
installation or while configuring Server Settings (see “Setting Administration
Options” on page 56).
Note: If you are using your network’s LDAP user-data store for
PingFederate authentication, the Account Management screen is not
presented (see “Using LDAP Authentication” in the “Installation”
chapter of Getting Started).
Alternatively, you can set up and maintain user accounts later as a separate task
(assuming you have user administration permissions—see “Account
Management” on page 36). By default for installation, the user “Administrator”
has full system permissions.
X To continue, click Next or Save.
X For information about adding or managing users, see “Account
Management” on page 36.
Administrator’s Manual
63
Chapter 3
System Settings
Choosing Roles and Protocols
On the Roles and Protocols screen, select which identity-federation role(s) your
organization plays and which sets of standards you will use with your federation
partner (see the “Supported Standards” chapter in Getting Started).
Note: If you are using the PingFederate WS-Trust STS, select WS-Trust
as one of the supported protocols for either an IdP, an SP, or both.
Notice that a new configuration step, WS-Trust STS Settings, appears
under the Server Settings tab. For information about this configuration,
see the “Server Settings” section under “WS-Trust STS Configuration”
on page 277
Also on this screen, you can choose any of several options:
64
•
As an IdP, if you have installed a PingFederate SaaS Connector, you can
enable the SaaS Provisioning option (see “SaaS Provisioning” on page 18).
•
As an SP, if you are using SAML 2.0 XASP for multiple IdP connections,
you may choose to have PingFederate determine dynamically which
connection to use (see “Attribute Query and XASP” in the “Supported
Standards” chapter of Getting Started).
•
For either role you can enable Auto-Connect for SAML 2.0 connections
(see “Using Auto-Connect” on page 15).
PingFederate 6
Managing Server Settings
X If you are installing PingFederate and are not sure of your selections, just
click Next.
Note: If you do not choose a role during installation, you must
return to this screen to do so before you can configure connections
to federation partners.
To reach this screen for editing:
1. On the Main Menu under System Settings, click Server Settings.
2. Click Roles and Protocols under the Server Settings tab.
Administrator’s Manual
65
Chapter 3
System Settings
To choose roles and protocols:
1. Select your federation role(s) and then select at least one protocol.
Note: SaaS Provisioning requires the use of the SAML 2.0. (For
more information, refer to the Quick Connection Guide contained in
the PingFederate SaaS Connector package for your service
provider.)
2. (Optional) If you are using SAML 2.0 and want to configure Auto-Connect,
select that feature for your role(s) (see “Using Auto-Connect” on page 15).
Note: Clearing this checkbox does not deactivate an existing AutoConnect configuration in production. If you have already deployed
Auto-Connect and wish to suspend the deployment for any reason,
use the Initial Setup Summary screens (accessible from the Main
Menu) for your respective role.
When you make this selection, two additional steps are added to the System
Settings task:
•
Metadata Signing (see “Configuring Auto-Connect Metadata Signing”
on page 71)
•
Metadata Lifetime (see “Configuring Auto-Connect Metadata
Lifetime” on page 71).
3. (Optional) If you are using PingFederate as an IdP and have installed a SaaS
Connector package, select the SaaS Provisioning checkbox.
(For more information, see “SaaS Provisioning” on page 18.)
Note: After provisioning is configured for a connection, you cannot
clear this checkbox—you must delete all provisioning
configurations first. To suspend provisioning for an SP partner, you
can deactivate the specific configuration (see “Channel Activation
and Summary” on page 188). Alternatively, you can deactivate the
associated SP connection; note, however, that this will also disable
SSO/SLO transactions (see “Connection Activation and Summary”
on page 189).
4. (Optional) If you are using SAML 2.0 XASP as an SP for multiple IdP
connections, you may select the option to determine dynamically which
66
PingFederate 6
Managing Server Settings
connection to use, based on the X.509 certificate presented (see “Attribute
Requester Mapping” on page 208).
Tip: After you make this selection and create XASP IdP
connections (see “Configuring the Attribute Query Profile” on
page 164), configure dynamic IdP discovery via the Attribute
Requester Mapping link on the Main Menu. Once the mapping is
configured, you cannot clear the checkbox on the Roles and
Protocols screen unless you first delete the mapping.
For general information about XASP, see “Attribute Query and XASP” in
the “Supported Standards” chapter of Getting Started.
5. Click Next (or Save, if you are modifying existing selections).
For information about configuring settings associated with your selections, see
these relevant portions of this manual:
•
Chapter 5, “Identity Provider SSO Configuration”
•
Chapter 6, “Service Provider SSO Configuration”
•
Chapter 7, “WS-Trust STS Configuration”
•
“Configuring IdP Discovery” on page 83
Specifying Federation Information
This information identifies your federation deployment to your partners,
according to the protocol(s) you support.
Notes: You must provide an ID that uniquely identifies your federation
gateway for each protocol you support. For WS-Trust STS, IDs are
required for both SAML 2.0 and SAML 1.x, regardless of browser-based
SSO protocol support or the type of token expected to be issued, to
ensure that the STS will perform correctly under all conditions.
Each ID normally applies across all connection partners for a given
protocol; however, if your implementation requires different IDs for the
same protocol, you can use virtual server IDs (see “Federation Server
Identification” on page 20).
You can also use a different ID for Auto-Connect transactions (see
“Using Auto-Connect” on page 15).
Administrator’s Manual
67
Chapter 3
System Settings
Field Descriptions
68
Field
Description
Base URL
The fully qualified host name, port, and path (if
applicable) on which the PingFederate server runs.
This field is used to populate configuration settings
in metadata files (see “Exporting Metadata” on
page 30).
SAML 2.0 Entity ID
This ID defines your organization as the entity
operating the server for SAML 2.0 transactions. It is
usually defined as an organization's URL or a DNS
address; for example: pingidentity.com. The
SAML SourceID used for artifact resolution is
derived from this ID using SHA1.
PingFederate 6
Managing Server Settings
Field
Description
Auto-Connect Entity ID
(Optional) If you are using Auto-Connect, you can
specify a unique ID here for Auto-Connect
processing. The value must be a fully qualified URL
and should match the CN of your Auto-Connect
certificates (see “Auto-Connect Security Model” on
page 17).
When a value is supplied, this ID is used instead of
the SAML 2.0 Entity ID in your server’s AutoConnect metadata, as well as in associated SSO/
SLO requests and responses. Use this field if you
have configured regular, static SAML 2.0
connections to other partners and your SAML 2.0
Entity ID is not a fully qualified URL (see “Using
Auto-Connect” on page 15).
SAML 1.x Issuer/
Audience
This ID identifies your federation server for SAML 1.x
transactions. As with SAML 2.0, it is usually defined
as an organization's URL or a DNS address. The
SourceID used for artifact resolution is derived from
this ID using SHA1.
SAML 1.x Source ID
(Optional) If supplied, the Source ID value entered
here is used for SAML 1.x, instead of being derived
from the SAML 1.x Issuer/Audience.
WS-Federation Realm
The URI of the realm associated with the
PingFederate server. A realm represents a single unit
of security administration or trust.
Note: The fields available on this screen depend on the federation
protocols enabled on your server (see “Choosing Roles and Protocols”
on page 64).
To reach this screen:
1. Click Server Settings on the Main Menu.
2. Click Federation Info under the Server Settings tab.
Configuring SaaS Provisioning Settings
On the SaaS Provisioning screen, you can select the database that PingFederate
uses internally to facilitate provisioning for SaaS providers when PingFederate is
configured as an IdP (see “SaaS Provisioning” on page 18).
Administrator’s Manual
69
Chapter 3
System Settings
This screen is presented only if you have installed a SaaS Connector package and
SaaS Provisioning is enabled for the IdP federation role (see “Choosing Roles
and Protocols” on page 64).
Caution: A pre-installed, default Hypersonic database is selected for
initial setup and testing. However, we strongly recommend that you
choose your own, secured database for production deployments.
On this screen, you can also change the provisioning synchronization
frequency—that is, how often PingFederate checks the local user store for
changes.
The database is used to stores the state of synchronization between the source
data store and the target data store, enabling periodic checking to determine
whether updates are required at the target SaaS site. (For information on
configuring provisioning as an IdP, see “Configuring SaaS Provisioning” on
page 177.)
Note: PingFederate has been tested using Hypersonic, Oracle, and
MySQL databases as internal provisioning data stores. However, any
relational database should work as well; adaptable setup scripts used
for Hypersonic, Oracle, and MySQL are provided in the directory:
<pf_install>/pingfederate/server/default/conf/
provisioner/sql-scripts
To configure the internal data store:
1. Select the data store from the drop-down list.
If the data store you want is not shown in the list, then PingFederate is not
yet configured to access the store; click Manage Data Stores to create a
connection to the data store (see “Managing Data Stores” on page 72).
2. (Optional) Change the Synchronization Frequency value.
70
PingFederate 6
Managing Server Settings
Configuring Auto-Connect Metadata Signing
When Auto-Connect is enabled, PingFederate generates publicly available,
signed metadata for partners to use. The metadata contains information about
your server configuration (see “Providing Metadata” on page 15).
On the Metadata Signing screen, you choose a certificate to use for signing the
metadata.
Important: The certificate CN must match the domain name
associated with the Entity ID configured in the previous screen (see
“Specifying Federation Information” on page 67).
This screen appears only if Auto-Connect is enabled for either an IdP or SP (see
“Choosing Roles and Protocols” on page 64).
If you have not yet imported the certificate you want, click Manage
Certificates (see “Security Management” on page 89).
Note: The signing certificate is included as part of the public metadata
and must be trusted by your partner (see “Auto-Connect Security
Model” on page 17).
Configuring Auto-Connect Metadata Lifetime
Partners using Auto-Connect metadata will cache it to use for the future requests
during the “lifetime” in which the metadata is valid, as configured on the
Metadata Lifetime screen. After the metadata lifetime is expired, the metadata
is retrieved again.
This metadata expiration ensures that partners always have reasonably up-todate information about your server. You may elect to use the default time period
or change it on the Metadata Lifetime screen.
Administrator’s Manual
71
Chapter 3
System Settings
This screen appears only if Auto-Connect is enabled for either an IdP or SP (see
“Choosing Roles and Protocols” on page 64).
Saving and Editing Server Settings
On the Server Settings Summary screen you can view, edit, and save your
configuration.
X Click Save if you are finished with this configuration, or click any heading
to make changes.
Managing Data Stores
PingFederate can connect to local data stores to retrieve user attributes on either
the IdP or SP side of an SSO transaction (or both).
Tip: Whenever attributes are retrieved from a data store at runtime,
PingFederate logs the activity (see “Log File Generation” on page 27).
When you set up access to a data store, you can choose to mask the
values of all retrieved attributes in the log files to enhance security and
privacy of personal information (see “Attribute Masking” on page 10).
As an IdP, you use this feature whenever you need to fulfill an attribute contract
that requires information beyond that which can be derived from the user’s
session (see “Configuring Attribute Sources and User Lookup” on page 138). For
example, this information may include such attributes as an email address, a job
title, or any data that can be used to customize a user’s experience at the SP site.
As an SP, you can use data stores to retrieve additional attributes to package with
the IdP’s assertion data to meet SP adapter requirements (see “SSO Integration
Kits and Adapters” on page 4). Such attributes may be needed, for example, to
establish authorization levels or to manage the local account.
Either IdP or SP organizations configuring PingFederate for user provisioning
must set up connections to data stores (see “User Provisioning” on page 18).
You can add data stores at any time. Standard data stores include JDBC-enabled
databases and LDAP v3-compliant directories. Alternatively, you can develop a
driver using the PingFederate Custom Source SDK to connect to non-JDBC
72
PingFederate 6
Managing Data Stores
databases (see the PingFederate SDK Developer’s Guide in the pingfederate/
sdk directory).
Note: You cannot delete or modify a data-store connection if it is
associated with an attribute source as part of a partner-connection
configuration. You must remove the association first.
To reach this screen:
X Click Data Stores on the Main Menu.
To add a data store:
1. Click Add New Data Store.
2. Select Database, LDAP, or Custom and click Next.
3. Continue the configuration:
•
For Database configuration information see “Configuring a JDBC
Database Connection” on page 74.
•
For LDAP configuration information see “Configuring an LDAP
Connection” on page 78.
•
For Custom configuration information see “Configuring a Custom Data
Store” on page 81.
4. Click Save when you return to this screen.
Important: Note this step; be sure to click Save.
To modify a data store:
X Click the data store Description.
Administrator’s Manual
•
For Database configuration information see “Configuring a JDBC
Database Connection” on page 74.
•
For LDAP configuration information see “Configuring an LDAP
Connection” on page 78.
73
Chapter 3
System Settings
•
For Custom configuration information see “Configuring a Custom Data
Store” on page 81.
Important: You must have current connectivity from PingFederate
to a data store in order to create or modify the configuration. If you
find that the configuration is not editable, then your connection has
been lost due to a system problem not related to the PingFederate
server. The problem must be identified and corrected before you
can continue.
To delete a data store:
1. Click delete under Action for the data store you want to delete.
(To undo the deletion, click undelete.)
2. Click Save.
Configuring a JDBC Database Connection
You configure access to a database by providing basic JDBC information.
Note: Ensure that your database driver JAR file is installed in the
pingfederate/server/default/lib directory. You must restart
the server after installing the driver.
74
PingFederate 6
Managing Data Stores
Field Descriptions
Field
Description
JDBC URL
The location of the JDBC database. For example,
jdbc:mysql://databaseservername/
databasename
where databaseservername is the DNS host
name (or IP) of the server hosting the database, and
databasename is the name of a database on that
server.
Driver Class
The name of the driver class used to communicate
with the source database. For example,
org.hsqldb.jdbcdriver. This class should
supplied by the database software vendor in a JAR file,
which must be present in the pingfederate/
server/default/lib directory.
Username
The name that identifies the user when connecting to
the database.
Password
The password needed to access the database.
Mask Values in Log
(Checkbox)
(Optional) Determines whether all attribute values
returned from this data store will be masked in
PingFederate log files (see “Attribute Masking” on
page 10).
Validate Connection
SQL
(Optional, but recommended) An SQL statement used
by JBoss at runtime to validate that the connection is
still active. Refer to your JDBC or JBoss
documentation for more information.
To reach this screen:
1. Click Data Stores on the Main Menu.
2. Click the Data Store Description link on the Manage Data Stores screen.
To configure a new data store:
1. Click Data Stores on the Main Menu.
2. Click Add New Data Store.
3. Select Database and click Next.
To establish access to a database:
1. Enter the applicable JDBC URL.
This URL is used to identify the data store in lists. Example:
jdbc:mysql://10.0.1.81:3306/idp
Administrator’s Manual
75
Chapter 3
System Settings
2. Enter the Driver Class.
Example: com.mysql.jdbc.Driver
Note: The driver JAR file must be loaded into the directory:
pingfederate/server/default/lib
3. Enter a valid Username and Password.
4. (Optional) Select Mask Values in Log.
For information see “Attribute Masking” on page 10.
5. (Optional) Click Advanced.
Use this option to change default sizes or look-up time-outs, or to validate
the connection using a specific SQL call (see “Setting Advanced Options”
on page 76).
6. Click Next.
Note: PingFederate will try to connect to the database at this point.
If it cannot, there may be a problem with your settings.
7. On the Summary screen, click Done.
8. Click Save on the Manage Data Stores screen.
Setting Advanced Options
Use the Advanced Database Options screen to change default pool sizes or lookup time-outs, or to validate the connection using a specific SQL call.
76
PingFederate 6
Managing Data Stores
Field Descriptions
Field
Description
Minimum Pool Size
The smallest number of database connections in the
connection pool for the given data store.
Maximum Pool Size
The largest number of database connections in the
connection pool for the given data store.
Blocking Timeout
(ms)
The amount of time a request waits to get a
connection from the connection pool before it fails.
Idle Timeout (ms)
The length of time the connection can be idle in the
pool before it is closed.
To reach this screen for editing:
1. Click Data Stores on the Main Menu.
2. Click the Data Store Description link on the Manage Data Stores screen.
3. Click the Advanced button on the Database Config screen.
To configure a new data store:
1. Click Data Stores on the Main Menu.
2. Click Add New Data Store.
3. Select Database and click Next.
4. Enter information on the Database Config screen and click the Advanced
button.
Internally, PingFederate is preconfigured to use published JBoss server
default values. To view or restore these values, click Apply Defaults.
Administrator’s Manual
77
Chapter 3
System Settings
Configuring an LDAP Connection
This screen establishes a connection between the PingFederate server and an
LDAP data store.
Field Descriptions
Field
Description
Hostname(s)
The DNS name or IP address of the data store, which
may include a port number; example:
181.20.42.130:389. For failover, you can enter
one or more backup LDAP servers, each separated by
a space.
Note: If more than one Hostname is entered, each
server must be accessible using the same User DN
and Password (or via Bind Anonymously).
LDAP Type
If you are using this data store for SaaS Provisioning
and your LDAP store is either Active Directory or Sun
Directory Server, select the applicable Type (see
“SaaS Provisioning” on page 18).
Identifying the LDAP type permits PingFederate to
configure many provisioning settings automatically
(see “Modifying Source Settings” on page 181).
Tip: If you are using SaaS Provisioning and your LDAP
server is not Active Directory or Sun, you may wish to
define a custom LDAP Type to streamline the
provisioning configuration (see “Defining an LDAP
Type” on page 80).
If you are not using SaaS Provisioning, the selection of
an LDAP Type has no effect.
78
PingFederate 6
Managing Data Stores
Field
Description
Bind Anonymously
(Checkbox)
(Optional) Username and password are not required
(see procedure below).
User DN
The username credential required to access the data
store.
Important: The user must have permission to search
the directory for user-account information. For
security, this user should have read-only access.
Password
The password credential required to access the data
store.
Use SSL (Checkbox)
(Optional) Connects to the LDAP data store using
secure SSL/TLS encryption. This selection applies
equally to any secondary servers specified in
Hostname(s).
Caution: We recommend that all LDAP connections
use SSL.
Mask Values in Log
(Checkbox)
(Optional) Determines whether all attribute values
returned from this data store will be masked in
PingFederate log files (see “Attribute Masking” on
page 10).
To establish a connection to an LDAP data store:
1. Enter the applicable Hostname(s).
For more information, see the description for this field in the table above.
Hostnames identify this LDAP configuration in selection lists elsewhere in
the administrative console.
2. (Optional) Select an LDAP Type from the drop-down list.
For more information, see the description for this selection in the table
above.
3. Either:
•
Check Bind Anonymously if your LDAP interface supports anonymous
binding and if no credentials are needed to access the data store.
Or:
•
Enter a valid User DN and Password.
Note: If you choose an anonymous binding, ensure that this access
level provides permission to search the directory for user-account
information.
4. (Optional) Select Use SSL.
For more information, see the description for this selection in the table
above.
Administrator’s Manual
79
Chapter 3
System Settings
5. (Optional) Select Mask Values in Log.
For more information, see the description for this selection in the table
above.
6. Click Next.
PingFederate will try to connect to the LDAP server at this point. If it
cannot, there may be a problem with your settings.
7. On the Summary screen, click Done.
8. Click Save on the Manage Data Stores screen.
Defining an LDAP Type
If you are using SaaS Provisioning and your user-management LDAP server is
not Active Directory or the Sun Directory Server, you can define a custom
LDAP Type for PingFederate to use to streamline the SaaS provisioning
configuration (see “SaaS Provisioning” on page 18).
When the LDAP server is defined, its type appears in the LDAP Type drop-down
list on the LDAP Configuration screen (see previous section). When the data
store is selected as the source for provisioning, a number of other settings can be
automatically configured (see “Modifying Source Settings” on page 181).
To define an LDAP Type:
1. If you are using the LDAP Configuration screen, click Previous or Cancel.
2. Copy and rename the file sample.template.txt:
<pf_install>/pingfederate/server/default/conf/template/
ldap-templates
3. Change the template.name in the new template file.
The template.name you specify will appear in the LDAP Type list on the
LDAP Configuration screen when you save the template.
4. Modify other property values in the file to match the corresponding
configuration of your LDAP server.
The properties are used in the SaaS Provisioning setup (see “Modifying
Source Settings” on page 181).
5. Save the new template file.
Setting Pooling Options
LDAP connection pooling is maintained by the Java runtime environment.
Normally, default settings are optimal. However, if you need to customize pooling
for particular applications, you can find a list of the properties controlling
pooling at:
http://java.sun.com/products/jndi/tutorial/ldap/connect/
config.html
Using the format <prop_name>=<value>, enter any of the properties into the
run.properties file located in the directory:
<pf_install>/pingfederate/bin
80
PingFederate 6
Managing Data Stores
Configuring a Custom Data Store
Developers can use the PingFederate Custom Source SDK to create specific
drivers for non-JDBC/LDAP data stores (or more sophisticated JDBC/LDAP
lookups) including, for example, flat files or SOAP-connected databases (see the
PingFederate SDK Developer’s Guide in the pingfederate/sdk directory).
Once the data-store driver is installed, you can select it on the Custom Data
Store Type page.
To start configuring a Custom Data Store:
1. Enter a unique Instance Name.
You can create more than one instance of the same Data Store Type for use
with different connection partners, as needed.
2. Select the Data Store Type.
3. (Optional) Select Mask Values in Log.
For information see “Attribute Masking” on page 10.
4. Click Next.
Configuring a Custom Data Store Instance
This screen will vary depending on the implementation. Below is a sample for a
SOAP-enabled database driver. The screen shown below is only an example of a
custom data store and is not available in the PingFederate distribution.
Administrator’s Manual
81
Chapter 3
System Settings
To configure the driver instance for use with a partner connection:
X Enter or select required information and click Next.
Invoking Adapter Actions
Custom data store adapters may be written to interface PingFederate to perform
configuration assistance or validation actions (for example, testing a connection
to a database). Actions may also include generation of parameters that might
need to be set manually in a configuration file.
X To invoke an adapter action (when applicable), click its link on the Adapter
Actions screen.
Editing and Saving a Data Store
On the Data Store Summary page, you can view or edit your configuration.
To modify the configuration:
X Click the heading above the information you want to change.
To save a new configuration:
X Click Done on the Summary screen and then Save on the Manage Data
Stores screen.
82
PingFederate 6
Configuring IdP Discovery
Configuring IdP Discovery
PingFederate provides two kinds of IdP discovery:
•
SAML 2.0 standard IdP Discovery (see “IdP Discovery” in the “Supported
Standards” chapter of Getting Started)
•
Proprietary IdP discovery using an persistent cookie written by an SP
PingFederate server
Standard IdP Discovery is configured in the administrative console (see the next
section).
Discovery based on a PingFederate proprietary cookie is configured in an XML
file (see “IdP Discovery Using a Persistent Cookie” on page 86). Note that this
method can be used in conjunction with any of the federation standards.
Standard IdP Discovery
SAML IdP Discovery provides a cookie-based look-up mechanism used to
identify a user’s IdP dynamically during an SP-initiated SSO event, when the IdP
is not otherwise specified. To enable this feature, IdP Discovery must be selected
on the Roles and Protocols screen in the System Settings configuration (see
“Choosing Roles and Protocols” on page 64). Then click IdP Discovery under
System Settings on the Main Menu to reach this screen:
For an overview of this SAML 2.0 profile, see “IdP Discovery” in the “Supported
Standards” chapter of Getting Started.
X To continue, click Configure IdP Discovery.
Choosing Domain Cookie Settings
On the Domain Cookie Settings screen, you choose the discovery role or roles
that PingFederate will play.
Administrator’s Manual
83
Chapter 3
System Settings
The choices that appear on this screen depend on whether PingFederate is acting
as an SP, an IdP, or both; or as an IdP Discovery server only (see “Choosing Roles
and Protocols” on page 64).
To reach this screen:
1. Click IdP Discovery under System Settings on the Main Menu.
If this link is not available, then IdP Discovery is not yet enabled (see
“Choosing Roles and Protocols” on page 64).
2. On the IdP Discovery screen, click Configure IdP Discovery.
For a detailed discussion of selections on this screen, see “IdP Discovery” in the
“Supported Standards” chapter of Getting Started.
Configuring a Common Domain Service
A Common Domain Service is where PingFederate reads and/or writes
authentication information contained in shared cookies, as determined by
whether your site is an SP or IdP, respectively. (The service is shared if your
PingFederate server is acting in both roles.)
84
PingFederate 6
Configuring IdP Discovery
To reach this screen:
1. Click IdP Discovery under System Settings on the Main Menu.
If this link is not available, then IdP Discovery is not yet enabled (see
“Choosing Roles and Protocols” on page 64).
2. On the IdP Discovery screen, click Configure IdP Discovery.
3. Click Common Domain Service under the Configure IdP Discovery tab.
This step is not available if your server is configured for IdP Discovery only
(see “Choosing Roles and Protocols” on page 64).
To configure the Common Domain Service:
1. Enter the Base URL.
You must use SSL/TLS (HTTPS) for a common domain.
2. Enter and confirm a Pass phrase that a Web application must use to access
the domain.
Configuring a Local Common Domain Server
A Local Common Domain Server is where PingFederate reads (as an SP) or
writes (as an IdP) cookies for IdP Discovery.
To reach this screen:
1. Click IdP Discovery under System Settings on the Main Menu.
If this link is not available, then IdP Discovery is not yet enabled (see
“Choosing Roles and Protocols” on page 64).
2. On the IdP Discovery screen, click Configure IdP Discovery.
3. Click Local Common Domain Server under the Configure IdP Discovery
tab.
This step is available only if the common-server option is selected under
Domain Cookie Settings (see “Configuring IdP Discovery” on page 83).
Administrator’s Manual
85
Chapter 3
System Settings
To configure the Local Common Domain Server:
1. Enter the Common Domain.
Your entry must include an initial period (.); for example:
.pingidentity.com
2. Enter the Cookie Lifetime.
The range is 1 to 1,825 days; or to indicate a nonpersistent, session cookie,
enter -1.
3. Enter and confirm a Pass phrase that a Web application must use to access
the domain.
Editing and Saving the Configuration
After configuring or modifying IdP Discovery settings, you can review the
configuration on the Summary screen.
X If you are finished with the configuration, click Save; otherwise, click any
heading to make changes.
IdP Discovery Using a Persistent Cookie
PingFederate’s proprietary IdP-discovery method makes use of an IdP Persistent
Reference Cookie (IPRC) to track the identity provider with whom a user last
authenticated. There are three significant differences between standard IdP
Discovery and the IPRC method:
•
Standard IdP Discovery may be used only with SAML 2.0; the IPRC may be
used with any federation protocol.
•
The Common Domain Cookie (CDC) may be configured as a temporary,
session-based cookie; the IPRC always persists for a configurable period of
time.
•
The CDC is set by the IdP and readable by both federation partners; the
IPRC is set by the SP, using information in the SAML assertion, and cannot
be accessed by the IdP.
Configuration
Enable the IPRC feature for your SP site using the configuration file
org.sourceid.websso.profiles.sp.IdpIdCookieSupport.xml
located in the directory <pf_install>/pingfederate/server/
default/data/config-store.
Note that the deployed connection configuration between SP and IdP partners
must include SP-initiated SSO (see “Configuring Protocol Settings” on
page 244).
To enable IPRC:
1. In the XML configuration file cited above, set the value of
EnableIdpIdCookie to true.
86
PingFederate 6
Configuring IdP Discovery
2. (Optional) Change the default value(s) of any of the remaining elements in
the configuration, as described in the following table:
IdpIdCookieName
The name of the IPRC set by the SP
installation (default: IdPId). Note that
the cookie name cannot contain any of
the following characters: &, >, <,
comma, semicolon, space.
IdpIdCookieLifeTimeInDays
The maximum lifetime for the cookie
(default 365 days). The browser will
delete the cookie when the period is
expired.
ShowIdpSelectionList
If set to true (the default), the SP
displays a list of IdPs that can be used
to initiate the SSO event if the cookie is
not set. If set to false, the SP
installation generates an error page.
3. Start or restart PingFederate.
Note: Once an IPRC cookie is set, the only way to change the IdP to
whom the SP will send Authentication Requests for the user is to do
one of the following: wait for the cookie to expire, delete the cookie, or
perform IdP-initiated SSO using the new IdP.
Administrator’s Manual
87
Chapter 3
System Settings
88
PingFederate 6
Chapter
4
Security Management
PingFederate provides built-in certificate management to handle security
considerations for SAML transactions. In addition, when you use the SAML 2.0
Attribute Query profile as an SP, password security is required between the
application requesting attributes and the SP PingFederate server. Basic
authentication is also required for applications making calls to PingFederate’s
Connection Management Service and optional for the SSO Directory Service
(see “Web Service Interfaces” on page 357).
Note: PingFederate does not support Certificate Extensions.
You manage certificates and application authentication via the Security section
under My Server on the Main Menu.
Note: The information in this chapter is presented from the viewpoint of
an administrative user with “Crypto Admin” permissions (see “Account
Management” on page 36).
Administrator’s Manual
89
Chapter 4
Security Management
Trusted CAs
You can import your federation partner’s CA-signed or self-signed SSL/TLS
server certificate(s) into PingFederate’s global trust list. If the CA is not one of
the major authorities, you may also need to import the certificate from the
Certificate Authority that signed the certificates into the global trust list.
To reach this screen:
X Click Trusted CAs on the Main Menu.
To import a certificate:
1. Click Import.
2. Click Browse to locate the certificate.
3. Highlight the file and click Open.
4. Click Next.
5. Click Done.
6. Click Save on the Manage Trusted CAs screen.
To export a certificate:
1. Click Export under Action for the certificate you want to export.
2. On the Summary page, click the Export button.
3. Save the file on your system.
To delete a certificate:
1. Click Delete under Action for the certificate you want to delete.
To undo the deletion, click Undelete.
2. Click Save.
To view certificate details:
X Click the certificate Serial number.
90
PingFederate 6
SSL Server Certificates
SSL Server Certificates
PingFederate provides built-in SSL/TLS certificate management. Use this
feature to establish and maintain the certificate(s) presented for access to the
PingFederate administrative console and for incoming SSL/TLS connections at
runtime (see “Setting Administration Options” on page 56).
To create a new certificate:
1. Click Create New.
2. Enter the requested information on the form.
3. Click Next.
4. On the Summary screen, click Done.
5. Click Save on the Manage SSL Server Certificates screen.
To import a certificate and private key:
1. Click Import.
2. Click Browse to locate the certificate.
3. Highlight the file and click Open.
4. Enter the certificate password.
5. Click Next.
6. Click Done.
7. Click Save on the Manage SSL Server Certificates screen.
To view certificate information:
X Click its Serial number.
Administrator’s Manual
91
Chapter 4
Security Management
Note: If a certificate has been revoked, PingFederate indicates this
problem in the certificate information window.
To activate a certificate:
1. Click Activate for Runtime Server or Activate for Admin Console
under Action for the certificate you want to activate.
These choices are enabled only if you have created or imported more than
one certificate. Otherwise, a single certificate is used for both the
administrative console and runtime operations.
2. Click Save on the Manage SSL Server Certificates screen.
To export a certificate:
1. Click Export under Action for the certificate you want to export.
2. Select Certificate Only on the Export Certificate screen.
Or:
Select Certificate and Private Key and enter an Encryption Password.
3. Click Next.
4. On the Certificate Summary screen, click Export.
5. Save the file on your system and click Done.
To create a certificate-authority signing request:
1. Click Certificate Signing under Action for the desired certificate.
Note: This selection is inactive if you have not yet saved a newly
created or imported certificate. Click Save and then return to this
screen from the Main Menu.
2. Select Generate Certificate Signing Request (CSR), if not already selected.
3. Click Next.
4. Click Generate CSR on the Generate CSR screen.
5. Click Next.
6. On the Certificate Summary screen, click Export.
7. Save the file on your system and click Done.
To import a certificate authority response:
1. Click Certificate Signing under Action for the relevant certificate.
2. Select Import CSR Response and click Next.
3. Click Browse and locate the CSR response to import.
4. Highlight the file and click Open.
5. Click Next.
92
PingFederate 6
SSL Server Certificates
6. Click Done on the Summary screen.
7. Click Save on the Manage SSL Server Certificates screen.
To delete a certificate:
1. Click Delete under Action for the certificate you want to delete.
To undo the deletion, click Undelete.
2. Click Save.
Create Certificate Field Descriptions
Administrator’s Manual
Field
Description
Common Name
The common name (CN) identifying the certificate.
Organization
The organization (O) or company name creating the
certificate.
Organizational Unit
The specific unit within the organization (OU).
City
The city or other primary location (L) where the
company operates.
State
The state (ST) or other political unit encompassing the
location.
Country
The country (C) where the company is based.
Validity (days)
The time during which the certificate is valid.
Key Algorithm (dropdown menu)
A mathematical formula used to generate a key.
PingFederate uses either of two algorithms, RSA or
DSA.
Key Size (bits)
The number of bits used in the key. (RSA-768 to 2048,
DSA-768 and 1024)
93
Chapter 4
Security Management
SSL Client Keys & Certificates
You can create and manage your authentication private keys and the certificates
your server presents as a client in an SSL/TLS transaction.
To reach this screen:
X Click SSL Client Keys & Certificates on the Main Menu.
To create a new certificate:
1. Click Create New.
2. Enter the information on the form.
3. Click Next.
4. On the Summary screen, click Done.
5. Click Save on the Manage SSL Auth Private Keys and Certificates screen.
To import a certificate:
1. Click Import.
2. Click Browse to locate the certificate.
3. Highlight the file and click Open.
4. Enter the certificate password.
5. Click Next.
6. Click Done on the Import Certificate Details screen.
7. Click Save on the Manage SSL Auth Private Keys and Certificates screen.
To view certificate information:
X Click the certificate Serial number.
Note: If a certificate has been revoked, PingFederate indicates this
problem in the certificate information window.
94
PingFederate 6
SSL Client Keys & Certificates
To export a certificate:
1. Click Export under Action for the certificate you want to export.
2. Select Certificate Only.
Or:
Select Certificate and Private Key and enter an Encryption Password.
3. Click Next.
4. On the Certificate Summary screen, click Export.
5. Save the file on your system and click Done.
To create a certificate-authority signing request:
1. Click Certificate Signing under Action for the desired certificate.
Note: This selection is inactive if you have not yet saved a newly
created or imported certificate. Click Save and then return to this
screen from the Main Menu.
2. Select Generate Certificate Signing Request (CSR), if not already selected.
3. Click Next.
4. Click Generate CSR on the Generate CSR screen.
5. Click Next.
6. On the Certificate Summary screen, click Export.
7. Save the file on your system and click Done.
To import a certificate authority response:
1. Click Certificate Signing under Action for the relevant certificate.
2. Select Import CSR Response and click Next.
3. Click Browse and locate the CSR response to import.
4. Highlight the file and click Open.
5. Click Next.
6. Click Done on the Summary screen.
7. Click Save on the Manage SSL Auth Private Keys and Certificates screen.
To delete a certificate:
1. Click Delete under Action for the certificate you want to delete.
(To undo the deletion, click Undelete.)
2. Click Save.
Administrator’s Manual
95
Chapter 4
Security Management
Create Certificate Field Descriptions
Field
Description
Common Name
The common name (CN) identifying the certificate.
Organization
The organization (O) or company name creating the
certificate.
Organizational Unit
The specific unit within the organization (OU).
City
The city or other primary location (L) where the
company operates.
State
The state (ST) or other political unit encompassing the
location.
Country
The country (C) where the company is based.
Validity (days)
The time during which the certificate is valid.
Key Algorithm (dropdown menu)
A mathematical formula used to generate a key.
PingFederate uses either of two algorithms, RSA or
DSA.
Key Size (bits)
The number of bits used in the key. (RSA-768 to 2048,
DSA-768 and 1024)
Digital Signing and Decryption Keys & Certificates
You can use PingFederate to create and maintain your server’s signing
certificates, which you may use to sign SAML requests, responses, and assertions.
You can also use these certificates for XML decryption (“XML Encryption” on
page 15).
To reach this screen:
X Click Digital Signing & XML Decryption Keys & Certificates on the
Main Menu.
96
PingFederate 6
Digital Signing and Decryption Keys & Certificates
To create a new certificate:
1. Click Create New.
2. Enter the information on the form.
3. Click Next.
4. On the Summary screen, click Done.
5. Click Save.
To import a certificate:
1. Click Import.
2. Click Browse to locate the certificate.
3. Highlight the file and click Open.
4. Enter the certificate password.
5. Click Next.
6. Click Done.
7. Click Save.
To view certificate information:
X Click the certificate Serial number.
Note: If a certificate has been revoked, PingFederate indicates this
problem in the certificate information window.
To export a certificate:
1. Click Export under Action for the certificate you want to export.
2. Select Certificate Only.
Or:
Select Certificate and Private Key and enter an Encryption Password.
3. Click Next.
4. On the Certificate Summary screen, click Export.
5. Save the file on your system and click Done.
To create a certificate-authority signing request:
1. Click Certificate Signing under Action for the desired certificate.
Note: This selection is inactive if you have not yet saved a newly
created or imported certificate. Click Save and then return to this
screen from the Main Menu.
2. Select Generate Certificate Signing Request (CSR), if not already selected.
3. Click Next.
Administrator’s Manual
97
Chapter 4
Security Management
4. Click Generate CSR on the Generate CSR screen.
5. Click Next.
6. On the Certificate Summary screen, click Export.
7. Save the file on your system and click Done.
To import a certificate authority response:
1. Click Certificate Signing under Action for the relevant certificate.
2. Select Import CSR Response and click Next.
3. Click Browse and locate the CSR response to import.
4. Highlight the file and click Open.
5. Click Next.
6. Click Done on the Summary screen.
7. Click Save on the Manage Digital Signing Certificates screen.
To delete a certificate:
1. Click Delete under Action for the certificate you want to delete.
(To undo the deletion, click Undelete.)
2. Click Save.
Create Certificate Field Descriptions
98
Field
Description
Common Name
The common name (CN) identifying the certificate.
Organization
The organization (O) or company name creating the
certificate.
Organizational Unit
The specific unit within the organization (OU).
City
The city or other primary location (L) where the
company operates.
State
The state (ST) or other political unit encompassing the
location.
Country
The country (C) where the company is based.
Validity (days)
The time during which the certificate is valid.
Key Algorithm (dropdown menu)
A mathematical formula used to generate a key.
PingFederate uses either of two algorithms, RSA or
DSA.
Key Size (bits)
The number of bits used in the key. (RSA-768 to 2048,
DSA-768 and 1024)
PingFederate 6
Application Authentication
Application Authentication
If you are using the SAML 2.0 Attribute Query profile as an SP, then the
requesting application(s) at your site must authenticate to the PingFederate
server (see “Attribute Query and XASP” in the “Supported Standards” chapter
of Getting Started and “/sp/startAttributeQuery.ping” on page 355).
In addition, authentication is required to access PingFederate runtime data via
JMX (see “Runtime Monitoring Using JMX” on page 60) or to make SOAP calls
to the Connection Management Web Service. Authentication is optional for the
SSO Directory Service (see “Web Service Interfaces” on page 357).
Note: To help ensure network security, access to all of these services
is deactivated when PingFederate is first installed.
Administrators can activate and configure authentication for any or all of the
services on the Application Authentication screen.
To reach this screen:
X On the Main Menu, click Application Authentication under Security in
the System Settings section.
To enable access to a service:
1. Click Activate for the Service under Action.
2. Where required, enter an Id, Shared Secret, and Confirm Shared Secret for
the service.
You and the application developer must agree to these values.
This step is optional for the SSO Directory Service; the Service can be
active without requiring authentication (the default setting).
3. Repeat the steps above for other Services, as needed.
Administrator’s Manual
99
Chapter 4
Security Management
4. Click Save.
To change an application ID or password:
X Replace the existing information in the necessary field(s) and click Save.
To block access to an active service:
X Click Deactivate for the Service under Action and then click Save.
Tip: Although not accessible when deactivated, the Connection
Management Service and the SSO Directory Service are still
deployed by default as part of PingFederate. If your organization
does not plan to use one (or either) of these services, you may
wish to remove the corresponding WAR file(s) from the
<pf_install>/pingfederate/server/deploy or (and) ../
deploy2 directories, respectively:
pf-ws.war
pf-mgmt-ws.war
Certificate Revocation Checking
By default at runtime, PingFederate attempts to retrieve a CRL to verify that a
signing certificate has not been revoked, whenever a CRL distribution-point
URL is included within the certificate (see “Certificate Validation” on page 11).
Optionally, on the Manage Certificate Revocation screen you can enable and
configure OCSP checking as the preferred verification method, depending on
your requirements (see “OCSP Revocation Checking” on page 12).
OCSP can be used in place of CRL checking, or CRLs can be retained as a
backup method (for failover).
Note: When OCSP is enabled, CRL checking is not done
independently—only as a failover option for one or more OCSP failure
conditions.
Also on the Manage Certificate Revocation screen, you can change systemdefault settings for CRL checking, as needed.
100
PingFederate 6
Certificate Revocation Checking
No configuration changes are necessary on this screen if OCSP is not required
for your federation deployment and the CRL defaults are acceptable.
To reach this screen:
X On the Main Menu under Security, click Certificate Revocation
Checking.
Administrator’s Manual
101
Chapter 4
Security Management
Field Descriptions (For OSCP Checking)
Field/Selection
Description
Enable OCSP
Turns on OCSP certificate-revocation checking.
Default OCSP
Responder URL
The location of a URL to use for certificate-revocation
checking, a backup used only if the OCSP Responder
URL is not contained in the certificate.
Default OCSP
Responder Signature
Verification
Certificate
Certificate used to verify that the returned certificate
status was sent from the Default OCSP Responder—
required if the certificate is not included in the
response (click Manage Certificates to import the
verification certificate, as needed).
Do NOT allow
Responder to use
cached responses
When unchecked (the default), the OCSP Responder
uses cached responses when available for the subject
certificate (for an indicated period of time—see the
description for “Next Update Grace Period,” below).
If checked, PingFederate sends a nonce in the request
to the Responder, effectively requiring that the status
of the certificate be determined in real time. This
option is intended to enhance the prevention of
Internet replay attacks (in addition to time stamping),
where required.
Important: Making this selection may slow down
OCSP response time for a request and will increase
general processing overhead at the Responder site.
102
This Update Grace
Period
For the response to be considered valid, the
PingFederate server-clock time must correspond to
the <thisUpdate> timestamp in the OCSP
response, plus or minus the number of minutes set for
this field (to compensate for clock variances).
Next Update Grace
Period
If the response includes a <nextUpdate>
timestamp indicating when updated certificate
statuses will be available, then PingFederate checks to
ensure that the timestamp is not earlier than the
current server time, adding this grace period to
compensate for clock variances.
Responder Timeout
The allowable response time before the OCSP
Responder URL is considered unavailable and
processing continues (see “OCSP Responder is
Unavailable,” below).
Certificate is
Unknown
The certificate does not fall under the purview of the
CA associated with the OCSP Responder. The dropdown choices indicate whether an unknown certificate
is to be considered valid or not, or whether to try CRL
checking.
OCSP Responder is
Unavailable
Indicates what action to take if the Responder cannot
be reached.
PingFederate 6
Certificate Revocation Checking
Field/Selection
Description
OCSP Responder
Returns Error
Indicates what action to take if the Responder returns
an error.
Proxy Settings
If OCSP messaging is routed through a proxy server,
specify the server's Host (DNS name or IP address)
and the Port number. The same proxy information
applies to CRL checking, when CRL is enabled for
failover.
Field Descriptions (For CRL Checking)
Field/Selection
Description
Enable CRL
Checking
Enables CRL revocation checking (the default).
Treat Unretrievable
CRLs as Revoked
If checked, PingFederate immediately aborts the
processing associated with the certificate.
Note: CRL checking must remain enabled if any
selections for OCSP Error Handling include failover. If
OCSP is enabled and no CRL failover is specified, then
this selection has no effect.
If unchecked, the server treats the certificate as valid
but continues trying to retrieve the CRL.
Administrator’s Manual
Next Retry on
Resolution Failure
Specifies the number of minutes the server waits
before trying to retrieve a CRL when the previous
attempt failed—applies only when the selection above
(Treat Unretrievable CRLs as Revoked) is unchecked.
Next Retry on Next
Update Expiration
How long the server waits before requesting a new
CRL when the most recently retrieved CRL (in cache)
has a next-update time in the past.
Verify CRL Signature
When checked (recommended), PingFederate verifies
the CRL signature using the public key of the issuer,
which must be in the certificate chain or in the list of
Trusted CAs (see “Trusted CAs” on page 90).
Proxy Settings
If CRL checking is routed through a proxy server,
specify the server's Host (DNS name or IP address)
and the Port number. The same proxy information
applies to OCSP checking, when enabled.
103
Chapter 4
Security Management
104
PingFederate 6
Chapter
5
Identity Provider
SSO Configuration
In an IdP role, you use the PingFederate administrative console to configure local
application-integration information and to manage connections to your SPpartner sites. You must configure Server Settings from the Main Menu to
establish your site as an IdP before configuring connections to SPs (see
“Choosing Roles and Protocols” on page 64).
Note that you generally configure only one connection per federation partner,
even if you are targeting more than one Web application at the destination SP
site. You can configure more than one connection, however, if your partner
supports multiple protocols, or supports multiple federation IDs for the same
protocol (see “Federation Server Identification” on page 20).
Note: This chapter applies to configuration settings needed for secure
Internet SSO (“Browser SSO”). While there is some cross-over
information also applicable to WS-Trust STS, if you are using
PingFederate exclusively as an STS, start with “WS-Trust STS
Configuration” on page 277.
Under some conditions, you can enable SSO for an unlimited number of partners
at once by configuring a single, common connection (see “Using Auto-Connect”
on page 15).
This chapter covers the following topics:
Administrator’s Manual
•
“Application Integration Settings” on page 106
•
“Viewing Protocol Endpoints” on page 113
•
“Managing SP Connections” on page 114
•
“Defining SP Affiliations” on page 190
•
“Configuring SP Auto-Connect” on page 194
105
Chapter 5
Identity Provider SSO Configuration
Application Integration Settings
The integration of local applications with PingFederate is the essential “firstmile” configuration that allows end-users to access protected resources across
domains. This process is facilitated through the use of application-integration
kits and a robust Software Development Kit (see “SSO Integration Kits and
Adapters” on page 4).
Under Application Integration Settings on the Main Menu, you configure the
IdP Adapters that PingFederate needs to interact with applications or accessmanagement systems used to authenticate users at your site. You can also set a
Default URL to which users may be directed during SLO, and you can look up
system endpoints that application developers at your site need to access
PingFederate’s SSO/SLO services.
Note: For PingFederate installations that include WS-Trust STS, the
selections under Application Integration Settings also include a link for
configuring plug-in Token Processors (see “WS-Trust STS
Configuration” on page 277).
Configuring IdP Adapters
An IdP adapter is used to look up session information and provide user
identification to PingFederate (see “SSO Integration Kits and Adapters” on
page 4).
You must configure at least one instance of an IdP adapter in order to set up
connections to SP partners.
Note: If you are configuring either the OpenToken or the LDAP Adapter,
see “Configuring the IdP OpenToken Adapter” on page 331 or
“Configuring the IdP LDAP Adapter” on page 339, respectively.
X You reach this screen by clicking Adapters under Application Integration
Settings in My IdP Configuration.
106
PingFederate 6
Application Integration Settings
To configure a new instance:
X Click Create New Instance.
To edit an existing adapter instance:
X Click the Instance Name and click the step you need to change.
To delete an adapter instance:
1. Click Delete next to the Instance Name. (To undo the deletion, click
Undelete.)
Note: This option is available only if the adapter instance is not in
use for a connection.
2. Click Save to confirm the deletion.
Selecting an IdP Adapter Type
The first step in creating an adapter instance is choosing an adapter type.
Available adapter types are determined by JAR files loaded in the
<pf_install>/pingfederate/server/default/deploy directory.
Some adapters are bundled with PingFederate (see “SSO Integration Kits and
Adapters” on page 4). Other adapters and integration kits are available from the
Ping Identity Web site (www.pingidentity.com).
Field Descriptions
Administrator’s Manual
Field
Description
Instance Name
A descriptive name for the adapter instance—for
example, an identity management system name.
Instance ID
An internal identifier for the adapter instance. Must
be alphanumeric with no spaces.
107
Chapter 5
Identity Provider SSO Configuration
Field
Description
Type
A list of deployed IdP adapter types available for
creating an adapter instance for the server. A
developer typically deploys any new adapter types
before an administrator sets up a connection partner.
To define an adapter instance:
1. Enter the Instance Name and Instance Id on the Type screen.
2. Select the Type from the drop-down menu.
If the adapter you need is not listed, click Visit PingIdentity.com for
additional types to see if a suitable adapter is available from the
PingFederate download site, or create your own adapter (see “SSO
Integration Kits and Adapters” on page 4).
3. Click Next and enter information on subsequent screens for this adapter
setup.
Tip: The setup steps and information needed at those steps vary
with the adapters deployed on your server (see “SSO Integration
Kits and Adapters” on page 4). For information about configuring
the adapters packaged with PingFederate, see “OpenToken
Adapter Configuration” on page 329 or “LDAP Adapter
Configuration” on page 337.
4. Click Done on the Adapter Summary screen.
5. Click Save on the Manage IdP Adapter Instances screen.
Configuring an IdP Adapter
Depending on the adapter you choose, different configuration parameters are
available on the IdP Adapter screen. These options are controlled by the adapter
software (see “SSO Integration Kits and Adapters” on page 4).
X For information about configuring the OpenToken Adapter, see
“OpenToken Adapter Configuration” on page 329.
X For information about configuring the LDAP Authentication Service, see
“LDAP Adapter Configuration” on page 337.
Important: If you change adapters that are used by existing partner
connections, you may need to reconfigure those connections. If so,
a Fix Errors link appears on the Manage IdP Adapter Instances
screen. Click the link to navigate to the screens you need to
reconfigure. You cannot save the changes to the adapter until the
existing connections have been repaired.
108
PingFederate 6
Application Integration Settings
Invoking Adapter Actions
Adapters may be written to provide configuration assistance or validation actions
(for example, testing a connection to LDAP). Actions may also include
generation of parameters that might need to be set manually in a configuration
file.
X For information about actions available using the OpenToken Adapter, see
“Configuring the IdP OpenToken Adapter” on page 331.
X For information about actions available using the LDAP Authentication
Service, see “Configuring the IdP LDAP Adapter” on page 339.
To reach this screen:
1. Click Adapters on the Main Menu.
2. Click an Instance Name on the Manage IdP Adapter Instances screen.
3. Click Actions (if available).
To generate a properties list:
X Click Download under Action Invocation Link.
Extending an Adapter Contract
Adapters may be written with an option allowing administrators to add to the
attributes that the adapter returns from a user’s session. The PingFederate
OpenToken Adapter, for example, provides such an option (see “OpenToken
Adapter Configuration” on page 329).
Administrator’s Manual
109
Chapter 5
Identity Provider SSO Configuration
To reach this screen:
1. Click Adapters on the Main Menu.
2. Click an Instance Name.
3. Click Extended Contract (if available).
To add an attribute:
X Enter the attribute name in the text box and click Add.
Setting Pseudonym Values and Masking
On the Adapter Attributes screen you must select attributes to use for generating
a pseudonym identifier (see “Account Linking” on page 5).
Optionally on this screen, you can also choose to mask the values of any or all
attributes that PingFederate logs from this adapter instance at runtime (see
“Attribute Masking” on page 10).
110
PingFederate 6
Application Integration Settings
To configure Pseudonym generation:
X Under Pseudonym select the value(s) to use.
Note: A selection is required regardless of whether you will use
pseudonyms for account linking. This allows account linking to be
used later without having to delete and reconfigure the adapter.
Ensure that you choose at least one attribute that is unique for each
user (for example, email) to prevent the same pseudonym from
being assigned to multiple users.
To mask attributes in log files:
X Under Mask Log Values select the attribute(s) whose value(s) you want to
mask.
If OGNL expressions might be used to map derived values into outgoing
assertions and you want those values masked, select the related checkbox
under the Attribute list (see “Using Attribute Mapping Expressions” on
page 367).
To reach this screen:
1. Click Adapters on the Main Menu.
2. Click an Instance Name.
3. Click Adapter Attributes.
Selecting an Authentication Context
If you have deployed an integration kit that supports authentication context, you
can specify the context in the IdP adapter configuration under Advanced Fields
(see “Authentication Context” in the “Supported Standards” chapter of Getting
Started).
For detailed information, see the OASIS SAML document: saml-authn-context2.0-os.pdf.
X To enter an authentication context URI for an adapter that supports this
feature, click Advanced Fields on the adapter configuration screen.
Editing and Saving Adapter Instances
From the Adapter Instance Summary screen, you can reach adapter settings for
editing.
To edit the configuration:
1. Click the heading above the information you want to change.
2. Make your changes.
3. Click Save on the configuration page and on the Manage IdP Adapter
Instances screen.
Administrator’s Manual
111
Chapter 5
Identity Provider SSO Configuration
To save an adapter instance:
1. Click Done on the Summary screen.
2. Click Save on the Manage IdP Adapter Instances screen.
Configuring a Default URL and Error Message
As an IdP, you can specify a default URL indicating a successful SLO to the enduser (if no other page is designated). On the IdP Default URL page, you can also
customize an error message to be displayed as part of the error page rendered in
the end-user’s browser if an error occurs during IdP-initiated SSO. For example,
you might consider modifying the default text to include useful information
regarding whom the user should contact or what their next step should be.
Note: The error message is displayed only when the application calling
the start-SSO endpoint does not explicitly provide its own error page
URL.
Your application or your partner’s application may supply the URL at runtime
(see “IdP Endpoints” on page 348; but if none is provided, PingFederate will use
the default value you enter on this screen.
Tip: If you leave the default URL blank, PingFederate provides a built-in
landing page for the user. This Web page is among the templates you
can modify with your own branding or other information (see
“Customizing User-Facing Screens” on page 50).
112
PingFederate 6
Viewing Protocol Endpoints
Viewing Application Endpoints
Click Application Endpoints on the Main Menu to see a list of endpoints and
descriptions applicable to your federation role (IdP or SP). These endpoints are
built into PingFederate and cannot be changed.
Web-application developers at your site need to know the application endpoints
to initiate transactions via PingFederate (see “SSO Integration Kits and
Adapters” on page 4).
Note: For specific parameters required or allowed for Application
Endpoints, see “IdP Endpoints” on page 348.
This screen also shows a Maintenance Endpoint that you can use to verify that
the PingFederate server is running (see “Maintenance Endpoint” on page 356).
Viewing Protocol Endpoints
Click Protocol Endpoints under Federation Settings in the IdP Configuration
section of the Main Menu to see a list of SAML, WS-Federation, and/or WSTrust STS endpoints—a pop-up window displays only those endpoints related to
the federation protocols you have chosen (see “Choosing Roles and Protocols”
on page 64). These endpoints are built into PingFederate and cannot be
changed.
Your federation partners or STS clients need to know the applicable IdP
Services endpoints to communicate with your PingFederate server. Configured
service endpoints for SAML connections are included in metadata export files
(see “Exporting Metadata” on page 30).
The table below describes each endpoint:
Table 10: PingFederate IdP Endpoints
Administrator’s Manual
Service
URL and Description
Single Logout Service (SAML
2.0)
/idp/SLO.saml2
Single Sign-on Service (SAML
2.0)
/idp/SSO.saml2
Artifact Resolution Service
(SAML 2.0)
/idp/ARS.ssaml2
The URL that receives and processes logout
requests and responses.
The SAML 2.0 implementation URL that
receives authentication requests for
processing.
The SOAP endpoint that processes artifacts
returned from a federation partner to
retrieve the referenced XML message on
the back channel.
113
Chapter 5
Identity Provider SSO Configuration
Table 10: PingFederate IdP Endpoints (Continued)
Service
URL and Description
Attribute Query Service (SAML
2.0)
/idp/attrsvc.ssaml2
Metadata Service
/
The SAML implementation that receives and
processes attribute requests.
The default endpoint (empty path) from
which partners can retrieve Auto-Connect
metadata (see “Using Auto-Connect” on
page 15).
Single Sign-on Service (SAML
1.x)
/idp/isx.saml1
Artifact Resolution Service
(SAML 1.x)
/idp/soap.ssaml1
Single Sign-on Service (WSFederation)
/idp/prp.wsf
WS-Trust STS
/idp/sts.wst
The SAML 1.x implementation of IdP
intersite transfer service (ISX) to which
clients are redirected for SSO requests.
The SOAP endpoint that processes artifacts
returned from a federation partner to
retrieve the referenced XML message on
the back channel.
The WS-Federation implementation URL
that receives and processes security-token
requests and SLO messages.
The SOAP endpoint that receives and
processes security-token requests from STS
clients (Web Service Clients at the IdP site).
Managing SP Connections
As an IdP, you manage connection settings to support the exchange of
federation-protocol messages (SAML, WS-Federation, or WS-Trust) with an SP
or STS client application at your site.
Note: If you are configuring a new connection only for WS-Trust STS,
follow the sections in this part of the manual up to and including
“General Information” on page 121. Then turn to “WS-Trust STS
Configuration” on page 277.
These settings include:
114
•
User attributes you expect to send in an SSO assertion (including STS
SAML tokens).
•
User attributes that may be sent using the Attribute Query profile (if that
profile is used).
PingFederate 6
Managing SP Connections
•
The protocol and, for SAML, the profile you will use, including detailed
security specifications (the use of digital signatures, signature verification,
XML encryption, and SSL). For more information see the “Supported
Standards” chapter in Getting Started.
To continue with the configuration, you and your connection partner must have
decided this information in advance (see “Federation Planning Checklist” on
page 20). Your federation partner must supply some connection settings and
other information (see “Configuration Data Exchange” on page 22).
Tip: If you are configuring connections to more than one partner under
SAML 2.0 specifications, or if you intend to add partners in the future,
consider using Auto-Connect (see “Configuring SP Auto-Connect” on
page 194).
If your agreement includes sending assertions containing attribute values from a
local data store, then you will need to define the data store during this
configuration if you have not done so already (see “Managing Data Stores” on
page 72).
Accessing Connections
You can create or modify connections directly via the Main Menu. Note that the
menu displays the four most-recently modified connections. To view a list of all
SP connections, click the Manage All SP link.
Using the Main Menu
From the Main Menu under My IdP Configuration, you can configure a new
connection, modify an existing connection, or view connections.
Tip: To copy or delete connections or to recover connection drafts, click
Manage All SP (see “Using the Manage Connections Screen” on
page 117).
Administrator’s Manual
115
Chapter 5
Identity Provider SSO Configuration
Note that long connection names are truncated for this display. The full
connection names are displayed on the Manage Connections screen (see “Using
the Manage Connections Screen” on page 117).
To begin configuring a new connection:
X Click Create New under SP Connections on the Main Menu.
Tip: If you want to use a virtual ID for a second connection to the same
partner, the fastest way is to click Manage All SP and copy the first
connection (see “Using the Manage Connections Screen” on
page 117). For information about virtual IDs, see “Federation Server
Identification” on page 20.
To modify a connection:
1. Click the connection name under SP Connections on the Main Menu.
Only the four most recently edited connections are displayed. To see all
connections, including drafts, click Manage All SP.
2. On the Activation & Summary screen, click the heading for the information
you want to change.
3. Make your change and click Save.
Note: If Save is not available, it means your modification requires
other changes or you are editing a screen that is part of a series of
subtasks. Click Next and continue making indicated changes. The
Done button indicates that further changes in the task are optional.
When you have no further changes, click Done and then click Save
on the task summary screen.
116
PingFederate 6
Managing SP Connections
Using the Manage Connections Screen
From the Manage Connections screen, you can configure a new connection,
modify or copy an existing connection or draft, or delete a connection (if it is not
active). An export function is also provided, which allows you save individual
connections.
S
Note: The connection export function results in an XML file that you
can modify and import into another PingFederate server acting in the
same federation role (IdP or SP) at your site (see “Connection
Management Service” on page 357).
From this screen, you can also globally override transaction logging levels set for
individual connections or restore connection-based logging (see “Runtime
Transaction Logging” on page 29).
To access the Manage Connections screen:
X Click Manage All SP under SP Connections on the Main Menu.
To begin configuring a new SP connection:
X Click Create Connection on the Manage Connections screen.
Tip: If you need to create a second connection to a partner using a
Virtual ID, copy the existing connection and make necessary changes,
including adding the Virtual ID on the General Info screen. For
information about Virtual IDs, see “Federation Server Identification” on
page 20.
Administrator’s Manual
117
Chapter 5
Identity Provider SSO Configuration
To copy a connection:
1. Click Copy under Action for the connection you want to copy.
2. Enter new General Information for the connection (see “General
Information” on page 121).
3. Make any further changes needed for the new connection.
Note: SaaS-Provisioning configurations are not copied for a
connection (see “SaaS Provisioning” on page 18).
To edit a connection or continue working on a draft:
X Click the Connection Name link.
For a draft, you will return to where you left off.
To export a connection:
1. Click Export under Action for the connection.
2. Save the XML file on your file system.
You can change the name of the file, but keep the XML extension.
Tip: You can import the connection programmatically or manually
into another instance of PingFederate acting in the same role (see
“Connection Management Service” on page 357).
To delete a connection:
1. Under Action, click Delete for the connection.
(To undo the deletion, click Undelete.)
Note: The Delete function is not available if the connection is
active.
2. To confirm the deletion, click Save.
To sort the list of connections:
X Click the arrow next to any column heading to sort the list based on that
column.
To filter the list by Protocol and/or Status:
X Select a filter criterion from either or both of the drop-down lists.
To override connection-based transaction logging:
1. Select On under Logging Mode Override.
2. Choose the logging mode you want to use for all connections.
To restore connection-based transaction logging:
X Select Off under Logging Mode Override.
118
PingFederate 6
Managing SP Connections
Choosing a Connection Type
On the Connection Type screen for a new connection, if your installation
includes an optional PingFederate SaaS Connector, choose the applicable SaaS
vendor as the Connection Template (see “SaaS Provisioning” on page 18).
Tip: When you select a Connection Template, many connection
settings are configured for you automatically. For more information
about this screen and subsequent steps, refer to the Quick Connection
Guide available with your PingFederate SaaS Connectors.
If you are not using a template (which preconfigures browser-based SSO),
indicate on this screen whether the connection to this partner is for Browser
SSO, WS-Trust STS, or both (see “Connection Types” on page 1).
Note: You can add STS support to new template-based connection. You
also can add STS support to any existing SSO connection, or vice versa,
at any time.
If your federation deployment supports multiple protocols and you are not using a
connection template, then for new SSO connections you can also select the
applicable protocol on the Connection Type screen (see “Choosing Roles and
Protocols” on page 64).
Note: If your partner’s deployment also supports multiple protocols and
you intend to communicate using more than one, then you must set up
a separate connection for each protocol.
X To configure a connection for secure Internet SSO, select Browser SSO
Profiles and the Protocol (if necessary).
Administrator’s Manual
119
Chapter 5
Identity Provider SSO Configuration
X To configure a connection for WS-Trust STS, make that selection and then
select a Default Token Type.
The Default Token Type, either SAML 1.1 or 2.0, is used when a Web
Service client does not specify in the token request what token type the STS
should issue.
Note: The Default Token Type does not need to match the Protocol
indicated on the screen for SSO (when applicable).
X (Optional) If your PingFederate license manages connections by groups,
then you can select a group for this connection.
This option is not displayed for unrestricted or other types of licenses.
Choosing Connection Options
On the Connection Options screen, if your installation includes a PingFederate
SaaS Connector and you have chosen a connection template on the previous
screen, you can indicate whether to configure provisioning for this connection
(see “SaaS Provisioning” on page 18).
Note: This screen is presented only for browser-based SSO
connections using the SAML 2.0 federation protocol (see “Choosing a
Connection Type” on page 119).
For SAML 2.0, you also have the option of configuring the Attribute Query
profile, with or without SSO (see “Attribute Query and XASP” in the
“Supported Standards” chapter of Getting Started).
X To create a connection for secure Internet SSO, ensure that Browser SSO is
selected and click Next.
X If you are using a connection template for a SaaS provider but do not want to
configure provisioning for this connection, clear the SaaS Provisioning
checkbox.
120
PingFederate 6
Managing SP Connections
Importing Metadata
If you are using one of the SAML protocols (without a connection template) and
have received a metadata file from your partner, click Browse on the Import
Metadata screen, select the file, and click Next. For more information, see
“Metadata” in the “Supported Standards” chapter of Getting Started.
Note: If the endpoints in the metadata file share the same base URL
(protocol, hostname, and port), PingFederate uses this information to
populate the Base URL field (see “General Information” on page 121).
Consequently, individual endpoints on other screens do not include this
information—only relative paths are shown.
Note: If you are importing a signed metadata file that does not include
the certificate and public key, you will be asked to import the certificate
needed to verify the XML signature (see the next section).
If you are not using a metadata file, click Next on the Import Metadata screen.
Importing a Verification Certificate
The Import Certificate screen appears only if the metadata file you have chosen
to import is signed and the certificate needed to verify the signature is not
contained in the file.
X Click Browse to locate and open the signature verification certificate for
this partner.
Viewing the Metadata Summary
The Metadata Summary screen provides security information about an
imported metadata file, including whether the file was signed and, if so, the trust
status of the certificate used to verify the signature.
General Information
On the General Info screen, you provide a required unique identifier and display
name for a connection, as well as optional contact information. In addition, on
this screen you can set the level of transaction logging for this connection
partner (see “Runtime Transaction Logging” on page 29).
Administrator’s Manual
121
Chapter 5
Identity Provider SSO Configuration
Field Descriptions
Field
Description
Partner’s Entity ID/
Audience/
Partner’s Realm
(Connection ID)
(Required) The published, protocol-dependent,
unique identifier of your partner. For a SAML 2.0
connection, this is your partner’s SAML Entity ID.
For a SAML 1.x connection, this is the Audience
your partner advertises. For a WS-Federation
connection, this is your partner's Realm. This ID
may have been obtained out-of-band or via a
metadata file if you are using a SAML protocol (see
“Exporting Metadata” on page 30).
For STS-only connections, this ID can be any unique
identifier.
Connection Name
122
(Required) A plain-language identifier for the
connection—for example, a company or
department name. This name is displayed in the
connection list on the Main Menu.
PingFederate 6
Managing SP Connections
Field
Description
Virtual Server ID
Enter a unique server ID in this field if you want to
identify your server to this connection partner using
an ID other than the one you specified under Server
Settings (see “Specifying Federation Information”
on page 67).
For information about Virtual Server IDs, see
“Federation Server Identification” on page 20.
Base URL
The fully qualified hostname and port on which your
partner’s federation deployment runs (e.g.,
https://www.pingidentity.com:9031). This
entry is an optional convenience, allowing you to
enter relative paths to specific endpoints, instead of
full URLs, during the configuration process.
Company
The name of the partner company to which you are
connecting.
Contact Name
The contact person at the partner company.
Contact Number
The phone number of the contact person at the
partner company.
Contact Email
The email address for the contact person at the
partner company.
Logging Mode
The level of transaction logging applicable for this
connection (see “Runtime Transaction Logging” on
page 29). Note that you can override connection
logging mode settings globally from the
connections list (see “Using the Manage
Connections Screen” on page 117).
To reach this screen:
1. Click a connection name on the Main Menu.
Click Manage All SP, if needed, to see a full list of connections.
2. Click General Info under the SP Connection tab.
For a new connection:
X Fill in the information needed and click Next.
Connection ID and Connection Name are required (see “Field Descriptions”
above).
Note that the Virtual ID identifies your own federation deployment for this
connection only and overrides the ID you specified under Server Settings
(see “Federation Server Identification” on page 20).
For an existing connection:
X If you are editing existing information, modify the fields as needed and click
Save.
Administrator’s Manual
123
Chapter 5
Identity Provider SSO Configuration
Configuring Browser-Based SSO
Browser-based SSO (also, Browser SSO) is another term for secure Internet
SSO, which relies on a user’s Web browser and HTTP to broker XML identityfederation messaging between an IdP and an SP (in contrast to WS-Trust STS
messaging, which is typically application-driven across the back channel and
does not require browser mediation).
X To continue, click Configure Browser SSO.
Configuration Steps
Many steps involved in setting up a federation connection are protocolindependent; that is, they are required steps for all connections, regardless of the
associated standards (see the “Supported Standards” chapter in Getting Started).
Also, for any given connection, some configuration steps are required under the
applicable protocol, while others are optional. Still others are required only
based on certain selections. The PingFederate administrative console determines
the required and optional steps based on the protocol and dynamically presents
additional requirements or options based on selections.
The following sections provides sequential information about every step you
might encounter while configuring browser-based SSO, regardless of the protocol
you are using for a particular connection.
Note: The configuration screens represented in this chapter show
“SAML 2.0” in their left corners, unless they are exclusive to WSFederation or SAML 1.x setup requirements. When the SAML 2.0
screens are also applicable to SAML 1.x and/or WS-Federation
connections, the SAML 2.0 representations and discussions also apply
to the other protocols, unless otherwise indicated.
After configuring SSO settings, you will normally need to configure
authentication credentials, the range of which depends on your SSO selections
(see “Configuring Credentials” on page 168). Also, other configuration tasks
124
PingFederate 6
Managing SP Connections
may remain to be configured for new or modified connections, depending on
selected connection options (see “Choosing Connection Options” on page 120).
Important: For new connections you must completely configure
these SSO settings and subsequent tasks before you can save the
connection on the Activation & Summary screen. Until then, the
configuration is temporary and can be lost; the console times out after
several minutes of inactivity. At any time, however, you can click Save
Draft, which is available on most screens after you enter General
Information (see “Console Buttons” in the “Console Navigation”
chapter of Getting Started).
Use the lists and links (or page references) below to find specific information
about steps that may apply to your SSO connection requirements:
SAML 2.0 SSO Configuration Steps
•
“Choosing Profiles (SAML 2.0)” on page 126
•
“Setting an Assertion Lifetime” on page 128
•
“Assertion Creation” on page 129
•
–
“Choosing an Identity Mapping Method” on page 130
–
“Creating an Attribute Contract” on page 132
–
“IdP Adapter Mapping” on page 134
“Configuring Protocol Settings” on page 154
–
“Setting Assertion Consumer Service URLs (SAML)” on page 154
–
“Specifying SLO Service URLs (SAML 2.0)” on page 157
–
“Choosing Allowable SAML Bindings (SAML 2.0)” on page 158
–
“Setting an Artifact Lifetime (SAML)” on page 159
–
“Specifying Artifact Resolver Locations (SAML 2.0)” on page 160
–
“Configuring Signature Policy” on page 161
–
“Configuring XML Encryption Policy (SAML 2.0)” on page 162
WS-Federation SSO Configuration Steps
•
“Setting an Assertion Lifetime” on page 128
•
“Assertion Creation” on page 129
•
–
“Choosing an Identity Mapping Method” on page 130
–
“Creating an Attribute Contract” on page 132
–
“IdP Adapter Mapping” on page 134
“Configuring Protocol Settings” on page 154
–
Administrator’s Manual
“Defining a Service URL (WS-Federation)” on page 156
125
Chapter 5
Identity Provider SSO Configuration
SAML 1.x SSO Configuration Steps
•
“Setting an Assertion Lifetime” on page 128
•
“Assertion Creation” on page 129
•
–
“Choosing an Identity Mapping Method” on page 130
–
“Creating an Attribute Contract” on page 132
–
“IdP Adapter Mapping” on page 134
“Configuring Protocol Settings” on page 154
–
“Setting Assertion Consumer Service URLs (SAML)” on page 154
–
“Setting a Default Target URL (SAML 1.x)” on page 156
–
“Setting an Artifact Lifetime (SAML)” on page 159
–
“Configuring Signature Policy” on page 161
Choosing Profiles (SAML 2.0)
A SAML profile is the message-interchange scenario that you and your
federation partner have agreed to use (see “Federation Planning Checklist” on
page 20). For SAML 2.0, PingFederate supports all IdP- and SP-initiated SSO
and SLO profiles.
For information on typical SSO/SLO profile configurations, including
illustrations, see the “Profiles” sections in the “Supported Standards” chapter in
Getting Started.
Note: This screen is not presented for SAML 1.x connections because
IdP SSO is assumed, the SLO profiles are not supported, and the
server supports SP-initiated SSO automatically (see “SAML 1.x
Profiles” in the “Supported Standards” chapter of Getting Started).
The screen is also not presented for WS-Federation connections
because profile selection is not required (see “WS-Federation” in the
“Supported Standards” chapter of Getting Started).
126
PingFederate 6
Managing SP Connections
To reach this screen for editing:
1. Click a connection name on the Main Menu.
Click Manage All SP, if needed, to see a full list of connections.
2. Click Browser SSO under the SP Connection tab.
3. Click Configure Browser SSO.
4. Click SAML Profiles on the Summary screen.
To configure profiles:
1. Select the profile(s) applicable to this connection and click Next.
You must select an SSO profile before you can enable SLO.
2. Continue through the remaining connection-configuration tasks.
The following sections provide more information on requirements for each
SAML profile:
Configuring IdP-Initiated SSO
When PingFederate is operating as an IdP, the IdP-initiated SSO profile
configuration defines the message-transport mechanisms (bindings) your
enterprise has agreed to use for this partner, plus optional digital signature
requirements for outbound assertions (see “Certificates, SSL, and XML
Encryption” on page 10).
For this configuration you need to know:
•
The transport binding(s) to which you and your partner have agreed
•
The certificate to be used for signing assertions (not always required for the
artifact binding)
•
The URL(s) of your partner’s Assertion Consumer Service(s)
Configuring SP-Initiated SSO
The SP-initiated profile configuration for SSO defines the message-transport
mechanisms (bindings) and security requirements for receiving authentication
requests and sending assertions when your SP partner initiates SSO transactions
(see “Single Sign-on” in the “Supported Standards” chapter of Getting Started).
For SAML 1.x, the SP-initiated SSO profile is also known as the “destinationfirst” profile, which was added as a supported “non-normative” use case after the
release of the SAML 2.0 specifications. As an IdP, you do not need to configure
this profile; when the SP sends an authentication request to your SSO Service
endpoint, PingFederate will handle the response automatically.
For this configuration you will need to know:
Administrator’s Manual
•
The endpoint URL(s) for your SP’s Assertion Consumer Service(s)
•
The transport bindings that you and your partner have agreed upon inbound
and outbound
•
The certificates you will use to sign outbound assertions and to verify
incoming digital signatures from your SP, when either is required
127
Chapter 5
Identity Provider SSO Configuration
When Artifact is an allowable inbound SAML binding, you also need to know
the endpoint(s) to your partner’s Artifact Resolution Service(s) and the SOAP
client authentication mechanism to use: either HTTP Basic, SSL client
certificates, a digital signature, or a combination of these mechanisms.
Configuring IdP-Initiated SLO
The SAML 2.0 IdP-initiated SLO profile configuration defines the messagetransport mechanisms (bindings) and security requirements for exchanging SLO
requests and responses.
For more information about SLO, see “Single Logout” in the “Supported
Standards” chapter of Getting Started.
For this configuration you need to know:
•
The transport bindings to which you and your partner have agreed to send
SLO requests and receive responses
•
The certificates to be used for signing outgoing messages and for verifying
incoming digital signatures from your SP (not always required for the artifact
binding)
•
The URL(s) of your SP’s Single Logout Service(s)
Configuring SP-Initiated SLO
The SAML 2.0 SP-initiated SLO profile configuration defines the messagetransport mechanisms (bindings) and security requirements that you and your
partner have agreed upon for exchanging SAML requests and responses.
For more information about SLO, see “Single Logout” in the “Supported
Standards” chapter of Getting Started.
For this configuration you need to know:
•
The transport bindings that you and your partner have agreed upon to send
SLO requests and receive responses
•
The certificates to be used for signing outgoing messages and for verifying
incoming digital signatures from your SP (not always required for the artifact
binding)
•
The URL(s) of your SP’s Single Logout Service(s)
•
The URL of your SP’s Artifact Resolution Service(s)—if this binding and
endpoint are different from your SSO configuration—and SOAP client
authentication requirements
Setting an Assertion Lifetime
Identity-federation standards require a window of time during which an assertion
is considered valid. Each assertion has a time-stamp XML element as well as
elements indicating the allowable lifetime of the assertion (in minutes) before
and after the assertion time stamp.
128
PingFederate 6
Managing SP Connections
Field Descriptions
Field
Description
Minutes Before
The amount of time before the assertion was issued
during which it is to be considered valid.
Minutes After
The amount of time after the assertion was issued
during which it is to be considered valid.
To change the default times:
X (Optional) Edit the desired setting(s) and click Next or Save.
Assertion Creation
As an IdP, you must specify how PingFederate will obtain user-authentication
information and use it to create assertions appropriate for your SP partner,
including additional user attributes as needed. This configuration includes:
Administrator’s Manual
•
Choosing an identity-mapping method (see “Choosing an Identity Mapping
Method” next).
•
Defining the attribute contract you will use with this partner, if any (see
“Creating an Attribute Contract” on page 132).
•
Configuring instances of one or more adapters (see “IdP Adapter Mapping”
on page 134) and specifying how they are used to fulfill the attribute
contract.
129
Chapter 5
Identity Provider SSO Configuration
X Click Configure Assertion Creation to continue.
Choosing an Identity Mapping Method
PingFederate allows your SP partner to use either account linking or account
mapping to associate remote users with local accounts for SSO between business
partners (see “Identity Mapping” on page 5). At the Identity Mapping step, you
choose the type of name identifier your partner needs to facilitate one of these
options. You and your partner may want to decide in advance which option to
use (see “Federation Planning Checklist” on page 20).
The choices of name-identifier types depend on which protocol you are using:
•
For information about SAML selections, see “SAML Name ID Selections”
next.
•
For information about WS-Federation selections, see “WS-Federation Name
ID Selections” on page 132.
SAML Name ID Selections
The allowable types of name identifiers for SAML connections are described
below. These choices affect how SPs make use of account mapping or account
linking.
130
PingFederate 6
Managing SP Connections
If your SP is using account linking, then establishing an attribute contract is not
required. Depending on your partner agreement, however, you may choose to
supplement the account link with an attribute contract. In this configuration the
account link is used to determine the user’s identity, while the additional
attributes might be used for authorization decisions, customized Web pages, and
so on, at the SP site (see “About Attributes” on page 7).
Important: If you have previously set up a configuration to use an
attribute contract and want to change the configuration to use account
linking without additional attributes, then the existing attribute
contract will be discarded.
Account linking can be used with either a clear, standard name identifier or an
opaque pseudonym.
X If you want to send a known attribute to identify a user—for example, a
username or email address—then select Standard.
X If you and your partner have agreed to use an opaque persistent name
identifier (often used for account linking), then select Pseudonym on the
Identity Mapping screen.
The pseudonym is based on values pulled from the IdP adapter instance used
to authenticate the user. You select these values when you configure IdP
adapter instances (see “Setting Pseudonym Values and Masking” on
page 110).
To set up an attribute contract to use in conjunction with an opaque
identifier, click the checkbox next to “Include attributes . . .” after selecting
Pseudonym.
Administrator’s Manual
131
Chapter 5
Identity Provider SSO Configuration
X Select Transient to enhance the privacy of a user’s identity. Unlike a
pseudonym, a transient identifier is different each time a user initiates SSO
(see “Account Linking” on page 5).
A typical application for this selection might be, for example, when an SP
provides generalized group accounts based on organizational rather than
individual identity.
To set up an attribute contract to use in conjunction with an opaque
identifier, click the checkbox next to “Include attributes . . .” after selecting
Transient.
To reach this screen for editing:
1. Click the connection name on the Main Menu.
Click Manage All SP, if needed, to see a full list of connections.
2. Click Browser SSO under the SP Connection tab.
3. Click Configure Browser SSO.
4. Click Assertion Creation under the Browser SSO tab.
5. Click Configure Assertion Creation.
6. Click Identity Mapping on the Summary screen.
WS-Federation Name ID Selections
For WS-Federation purposes a name identifier is a uniquely identifying user
attribute.
X Make one of the selections described below:
•
Email Address: This attribute is commonly used as a unique identifier
for SSO and SLO. Make this selection, for example, if a user logs in
using an email address or if the information is available for lookup in a
local data store.
•
User Principal Name: The username or other unique ID of the subject
initiating the transaction. Make this selection, for example, if a
username will be available from the current user session as part of a
cookie or can be derived from a local data store.
•
Common Name: This selection provides for anonymous SSO to your
SP, generally using a hard-coded generalized logon. Make this selection
if your partner agreement involves a many-to-one use case— for
example, if the SP has a group account set up for all users in a particular
domain.
Later, you will map your choice to the SAML_SUBJECT attribute in the SAML
assertion (see “Mapping Default Attribute Contract Fulfillment” on page 152).
Creating an Attribute Contract
An attribute contract is the set of user attributes that you and your partner have
agreed will be sent in SAML assertions for this connection (see “Attribute
Contracts” on page 7). You identify these attributes on this screen.
132
PingFederate 6
Managing SP Connections
If you are sending a “standard” name identifier (see “Choosing an Identity
Mapping Method” on page 130), then the contract includes the default
SAML_SUBJECT, which identifies the user in the assertion. You will configure
this variable later to contain a user ID or another agreed-upon attribute—for
instance, an email address—that uniquely identifies the user (see “Attribute
Contract Fulfillment” on page 149).
Note: Creating an attribute contract is optional if you are sending either
a pseudonym or a transient identifier to your connection partner (see
“Choosing an Identity Mapping Method” on page 130).
To reach this screen for editing:
1. Click the connection name on the Main Menu.
Click Manage All SP, if needed, to see a full list of connections.
2. Click Browser SSO under the SP Connection tab.
3. Click Configure Browser SSO.
4. Click Assertion Creation under the Browser SSO tab.
5. Click Configure Assertion Creation.
6. Click Attribute Contract on the Summary screen.
If this step is not in the list, then you have chosen to send either a
pseudonym or a transient identifier without additional attributes (see
“Choosing an Identity Mapping Method” on page 130).
To add an attribute:
X Enter the attribute name in the text box and click Add.
Attribute names are case-sensitive and must correspond to the names
configured by your federation partner.
Administrator’s Manual
133
Chapter 5
Identity Provider SSO Configuration
Note: In SAML assertions, the Format attribute associated with the
NameID element (as it is called for SAML 2.0; the corresponding
element is called NameIdentifier for SAML 1.x) can be set by
adding an attribute called SAML_NAME_FORMAT. The value of
that attribute can then be defined (see “Attribute Contract
Fulfillment” on page 149).
For information about the NameID or NameIdentier assertion
elements and applicable URI values, locate the relevant
specification at oasis-open.org/specs.
To modify an attribute name:
1. Click Edit under Action for the Attribute name.
2. Edit the name and click Update.
Note: If you change your mind, ensure that you click the Cancel
link in the Actions column, not the Cancel button, which discards
any other changes you might have made in the configuration steps.
To delete an attribute:
X Click Delete for the Attribute Name.
IdP Adapter Mapping
IdP adapters are responsible for handling user authentication as part of an SSO
operation (see “SSO Integration Kits and Adapters” on page 4). A configured
and deployed adapter in PingFederate is known as a adapter instance. The same
instance may be mapped by multiple connections.
Map one or more IdP adapter instances into each SP connection so that when a
user authenticates with a particular external identity management system the
user attributes are returned to PingFederate.
Regardless of how many IdP adapter instances are mapped in an SP connection,
PingFederate uses only one instance to authenticate a user. Because each
instance may return different user attributes, each IdP adapter mapping must
define how the attribute contract is fulfilled; you must map attributes from each
adapter—and/or attributes retrieved from your local data stores—into the
assertions PingFederate will send to this SP to fulfill the attribute contract.
You begin this configuration on the IdP Adapter Mapping screen, where you
choose to map instances of IdP adapters. If you have not yet configured an
instance of the adapter you intend to use within this SP connection, see
“Configuring IdP Adapters” on page 106.
134
PingFederate 6
Managing SP Connections
To reach this screen for editing:
1. Click the connection name on the Main Menu.
Click Manage All SP, if needed, to see a full list of connections.
2. Click Browser SSO under the SP Connection tab.
3. Click Configure Browser SSO.
4. Click Assertion Creation under the Browser SSO tab.
5. Click Configure Assertion Creation.
6. Click IdP Adapter Mapping on the Summary screen.
To modify an existing Adapter Instance:
1. Click its Name link.
To begin configuring an Adapter Instance for this connection:
X Click Map New Adapter Instance.
Selecting an Adapter Instance
A configured and deployed adapter in PingFederate is known as an adapter
instance. The same adapter instance may be mapped by multiple connections
(see “Configuring IdP Adapters” on page 106).
You can use attributes returned from the adapter (the adapter contract) to fulfill
the attribute contract with this partner, and/or use them to look up additional
attributes in a user data store. You make this choice on the next screen (see
“Selecting Assertion Mapping” on page 136).
Administrator’s Manual
135
Chapter 5
Identity Provider SSO Configuration
X Choose an Adapter Instance from the drop-down list and click Next to
continue.
To create or change an adapter instance, as needed, click Manage Adapter
Instances.
To reach this screen for editing:
1. Click the connection name on the Main Menu.
Click Manage All SP, if needed, to see a full list of connections.
2. Click Browser SSO under the SP Connection tab.
3. Click Configure Browser SSO.
4. Click Assertion Creation under the Browser SSO tab.
5. Click Configure Assertion Creation.
6. Click IdP Adapter Mapping on the Summary screen.
If this step is not available, you have chosen to pass either a pseudonym or
transient name identifier and not to use additional attributes (see “Choosing
an Identity Mapping Method” on page 130).
Selecting Assertion Mapping
For SAML assertions, you can query local user data stores to help fulfill the
attribute contract, in conjunction with attribute values supplied by the IdP
adapter you are using with PingFederate (see “SSO Integration Kits and
Adapters” on page 4).
The values supplied by the adapter you have chosen are shown under Adapter
Contract on the Assertion Mapping screen.
136
PingFederate 6
Managing SP Connections
To reach this screen for editing:
1. Click the connection name on the Main Menu.
Click Manage All SP, if needed, to see a full list of connections.
2. Click Browser SSO under the SP Connection tab.
3. Click Configure Browser SSO.
4. Click Assertion Creation under the Browser SSO tab.
5. Click Configure Assertion Creation.
6. Click IdP Adapter Mapping on the Summary screen.
If this step is not available, you have chosen to pass either a pseudonym or
transient name identifier and not to use additional attributes (see “Choosing
an Identity Mapping Method” on page 130).
7. Click the Adapter Instance Name.
8. Click Assertion Mapping on the Summary screen.
X If you choose to retrieve additional attributes, then you will identify data
stores and specify lookup queries next (see “Configuring Attribute Sources
and User Lookup” on page 138).
X If you use only the Adapter Contract values, then you will map values for the
attribute contract next (see “Mapping Default Attribute Contract
Fulfillment” on page 152).
Administrator’s Manual
137
Chapter 5
Identity Provider SSO Configuration
Tip: To determine whether you need to look up additional values,
compare the attribute contract against the adapter contract (see
“Creating an Attribute Contract” on page 132 and “IdP Adapter
Mapping” on page 134). If the attribute contract requires more
information, determine whether local data stores can supply it. (You
can also choose to use text constants or expressions for certain
information—see “Mapping Default Attribute Contract Fulfillment”
on page 152.)
Configuring Attribute Sources and User Lookup
Attribute sources are specific database or directory locations containing
information that may be needed for the attribute contract (see “Creating an
Attribute Contract” on page 132). Attribute sources can be reused across
connections to other SP partners.
This portion of the connection configuration allows you to set up search
parameters for your data stores, including “fall-through” searches. For example,
you can add the same data store more than once, using different search queries
for each instance, or you can search different data stores successively, either with
the same queries (for failover) or different ones.
If any search fails to find a user in the specified Attribute Source, the next search
is executed until a match is found.
Note: Queries are executed in the order of Attribute Sources shown.
Use the move up/move down controls as needed to adjust the order.
Note, however, that data can originate from only one source.
To reach this screen for editing:
1. Click the connection name on the Main Menu.
Click Manage All SP, if needed, to see a full list of connections.
2. Click Browser SSO under the SP Connection tab.
3. Click Configure Browser SSO.
138
PingFederate 6
Managing SP Connections
4. Click Assertion Creation under the Browser SSO tab.
5. Click Configure Assertion Creation.
6. Click IdP Adapter Mapping on the Summary screen.
If this step is not available, you have chosen to pass either a pseudonym or
transient name identifier and not to use additional attributes (see “Choosing
an Identity Mapping Method” on page 130).
7. Click the Adapter Instance Name.
8. Click Attribute Sources & User Lookup under the IdP Adapter Mapping
tab.
If this step is not listed, then this instance is configured to use adapter values
only (see “Selecting Assertion Mapping” on page 136).
To configure an attribute source:
X Click Add Attribute Source and complete the setup steps (see “Attribute
Source Setup” next).
To modify an attribute source configuration:
1. Click the attribute source Description link.
2. Click Save on the screen you change.
Note: Depending on what you change, you may need to modify
dependent data in subsequent steps, as indicated. Click Save or
Done when either of those options appears.
Attribute Source Setup
For attribute-source setup information, refer to the sections indicated in the
following steps.
Note: As you make selections on configuration screens, ensure that
you allow enough time for PingFederate to access your data store and
populate drop-down lists.
1. See “Selecting a Data Store” (next section).
2. See the following sections in this manual, depending on the type of data
store:
Data Store Type
Related Manual Sections
JDBC
• “Selecting a JDBC Database Table and Columns”
on page 141
• “Configuring a Database Filter (WHERE Clause)”
on page 143
LDAP
• “Configuring an LDAP Directory Search” on
page 145
• “Configuring an LDAP Filter” on page 146
Administrator’s Manual
139
Chapter 5
Identity Provider SSO Configuration
Data Store Type
Related Manual Sections
Custom
• “Configuring Custom Source Filters” on
page 148
• “Selecting Custom Source Fields” on page 148
3. See “Attribute Contract Fulfillment” on page 149.
Selecting a Data Store
This screen allows you to choose a data store from a previously configured list
(see “Managing Data Stores” on page 72). Attribute values extracted from this
data store will be used to help fulfill the attribute contract for this partner (see
“Creating an Attribute Contract” on page 132).
To reach this screen for editing:
1. Click the connection name on the Main Menu.
Click Manage All SP, if needed, to see a full list of connections.
2. Click Browser SSO under the SP Connection tab.
3. Click Configure Browser SSO.
4. Click Assertion Creation under the Browser SSO tab.
5. Click Configure Assertion Creation.
6. Click IdP Adapter Mapping on the Summary screen.
If this step is not available, you have chosen to pass either a pseudonym or
transient name identifier and not to use additional attributes (see “Choosing
an Identity Mapping Method” on page 130).
7. Click the Adapter Instance Name.
8. Click Attribute Sources & User Lookup under the IdP Adapter Mapping
tab.
If this step is not shown, you have elected not to look up attributes in data
stores (see “Selecting Assertion Mapping” on page 136).
9. Click the attribute source Description link.
140
PingFederate 6
Managing SP Connections
To choose a Data Store:
X Choose an Active Data Store and click Next.
A data store configuration must be defined under System Settings for use
within a connection. If the data store you want is not shown in the dropdown menu, click Manage Data Stores to add a new data store (see
“Managing Data Stores” on page 72).
Selecting a JDBC Database Table and Columns
When you choose to use a database source for attributes, you follow this path
through the configuration steps.
On this screen you begin to specify exactly where additional data can be found to
complete the attribute contract when you send an assertion to this SP (see
“Creating an Attribute Contract” on page 132). Only one table may be used as a
source of data for a JDBC lookup.
Field Descriptions
Administrator’s Manual
Field
Description
Schema
Lists the table structure that stores information within
a database. Some databases, such as Oracle, require
selection of a specific schema for a JDBC query. Other
databases, such as MySQL, do not require selection of
a schema.
Table
The name of the table contained in the database. Use
the drop-down to change the table.
Columns to return
from SELECT
Displays selected table columns. Select the columns
that are associated with the desired attributes you
would like to return from the JDBC query.
141
Chapter 5
Identity Provider SSO Configuration
To reach this screen for editing:
1. Click the connection name on the Main Menu.
Click Manage All SP, if needed, to see a full list of connections.
2. Click Browser SSO under the SP Connection tab.
3. Click Configure Browser SSO.
4. Click Assertion Creation under the Browser SSO tab.
5. Click Configure Assertion Creation.
6. Click IdP Adapter Mapping on the Summary screen.
If this step is not available, you have chosen to pass either a pseudonym or
transient name identifier and not to use additional attributes (see “Choosing
an Identity Mapping Method” on page 130).
7. Click the Adapter Instance Name.
8. Click Attribute Sources & User Lookup under the IdP Adapter Mapping
tab.
If this step is not shown, you have elected not to look up attributes in data
stores (see “Selecting Assertion Mapping” on page 136).
9. Click the attribute source Description link.
10. Click Database Table and Columns.
To select a database table and columns for queries:
1. Choose a Schema file (when applicable) from the drop-down list.
2. Choose a Table from the drop-down list.
3. Choose a name under Columns to Return from Select and click Add
Column.
Repeat this step for other columns as needed.
Note: You do not need to add a column here for it to be used as
part of a search key (see “Configuring a Database Filter (WHERE
Clause)” next). Add only attributes from which you need actual
values to pass in an assertion.
Tip: To determine what attributes to look up during a query, click the
View Attribute Contract link to see what information must be
collected (see “Creating an Attribute Contract” on page 132). Then
determine what information is coming in from the session lookup
adapter (see “Selecting Assertion Mapping” on page 136). Information
not contained in the adapter contract may be pulled from the data store
look-up query.
142
PingFederate 6
Managing SP Connections
Configuring a Database Filter (WHERE Clause)
The JDBC WHERE clause in PingFederate queries the data table you selected to
retrieve a record associated with a particular value (or values) from the assertion.
The clause is in the form:
WHERE column1=value1 [AND column2=value2] [OR ...]
The left side of the first variable pair uses a column name in the database table
you selected (see “Selecting a JDBC Database Table and Columns” on page 141).
The right side generally uses values passed in from your session lookup adapter
(variables, including the correct formatting, are listed under Adapter Values—
see “Configuring IdP Adapters” on page 106).
You can also apply additional search criteria from your own database, using any
other columns from the targeted table.
Tip: Click “View List of Columns . . .” to see a list from which to copy
and paste.
For general information about WHERE clauses, consult your DBMS
documentation.
EXAMPLE:
userid=’${username}’
In this example userid is the name of a column in the JDBC data store. On
the right side, ’${username}’ returns the value of the username
variable from the IdP adapter.
Important: You must use the ${} syntax to retrieve the value of
the enclosed variable and use single quotation marks around the
${} characters.
Administrator’s Manual
143
Chapter 5
Identity Provider SSO Configuration
Field Descriptions
Field
Description
Where
WHERE clause statements conditionally select data
from a table. Enter the WHERE clause statement in the
space provided. For example: WHERE
email='[email protected]'.
To reach this screen for editing:
1. Click the connection name on the Main Menu.
Click Manage All SP, if needed, to see a full list of connections.
2. Click Browser SSO under the SP Connection tab.
3. Click Configure Browser SSO.
4. Click Assertion Creation under the Browser SSO tab.
5. Click Configure Assertion Creation.
6. Click Attribute Sources & User Lookup under the IdP Adapter Mapping
tab.
If this step is not shown, you have elected not to look up attributes in data
stores (see “Selecting Assertion Mapping” on page 136).
7. Click the attribute source Description link.
8. Click Database Filter from the steps list.
144
PingFederate 6
Managing SP Connections
To construct the WHERE clause:
1. Enter the statement in the space provided, following the guidelines and
example above.
The initial WHERE is optional.
2. Ensure the syntax and variable names are correct.
When you click Next, you will map attribute values returned from the
database into the assertion (see “Attribute Contract Fulfillment” on
page 149).
Configuring an LDAP Directory Search
When you choose to use an LDAP source for attributes, you follow this path
through the configuration steps.
On this screen you specify the branch of your LDAP hierarchy where you want
PingFederate to look up user data.
Field Descriptions
Administrator’s Manual
Field
Description
Base DN
The base distinguished name of the tree structure in
which the search begins. This field is optional if
records are located at the LDAP root.
Search Scope
Determines the node depth of the query. Select
Subtree, One level or Object.
Root Object Class
The class containing the attributes you want.
Attributes to return
from search
A list of added from the drop-down list below. Subject
DN is a default attribute, which may be used as the
primary user identifier.
145
Chapter 5
Identity Provider SSO Configuration
To reach this screen for editing:
1. Click the connection name on the Main Menu.
Click Manage All SP, if needed, to see a full list of connections.
2. Click Browser SSO under the SP Connection tab.
3. Click Configure Browser SSO.
4. Click Assertion Creation under the Browser SSO tab.
5. Click Configure Assertion Creation.
6. Click IdP Adapter Mapping on the Summary screen.
If this step is not available, you have chosen to pass either a pseudonym or
transient name identifier and not to use additional attributes (see “Choosing
an Identity Mapping Method” on page 130).
7. Click the Adapter Instance Name.
8. Click Attribute Sources & User Lookup under the IdP Adapter Mapping
tab.
If this step is not shown, you have elected not to look up attributes in data
stores (see “Selecting Assertion Mapping” on page 136).
9. Click the attribute source Description link.
10. Click LDAP Directory Search from the steps list or fill out the appropriate
screens and advance to this screen.
If you have not yet defined an LDAP data store, see “Selecting a Data Store”
on page 140.
To select LDAP attributes:
1. (Optional) Enter a Base DN.
2. Select a Search Scope.
3. Select a Root Object Class.
4. Under Attributes to return from search, choose an attribute and click Add
Attribute.
Note that the attribute Subject DN is always returned by default.
5. Repeat the last step for other attributes as needed.
6. (Optional) Change the Search Scope or the Root Object Class if you want
attributes from other locations.
Note: You do not need to add an attribute here for it to be used in a
search filter (see “Configuring an LDAP Filter”). Add only attributes
from which you need actual values to pass in an assertion.
Configuring an LDAP Filter
The LDAP filter queries the data you selected to retrieve a record associated with
a particular value (or values) from the user’s session. The filter is in the form:
146
PingFederate 6
Managing SP Connections
(attribute=${value})
The left-side variable is an attribute you selected earlier (see “Configuring an
LDAP Directory Search” on page 145).
The right side generally uses values passed in from your session lookup adapter
(variables, including the correct syntax, are listed under Adapter Values—see
“Configuring IdP Adapters” on page 106).
You can also apply additional search criteria from your data store, using any other
attributes from the targeted object classes.
Tip: Click “View List of Available LDAP Attributes” for a list from
which you can copy and paste.
For general information about search filters, consult your LDAP documentation.
Field Descriptions
Administrator’s Manual
Field
Description
Filter
Narrows a search to locate requested data by either
including or excluding specific records. An LDAP filter
includes the attributes in the search and the value or
range of values that the search is attempting to match.
Searches are conducted by using three components:
1) at least one attribute (attribute data type) to search
on, 2) a search filter operator that will determine what
to match, and 3) the value of the attribute being
sought. Searches must have at least one of each of
these three components.
147
Chapter 5
Identity Provider SSO Configuration
To reach this screen for editing:
1. Click the connection name on the Main Menu.
Click Manage All SP, if needed, to see a full list of connections.
2. Click Browser SSO under the SP Connection tab.
3. Click Configure Browser SSO.
4. Click Assertion Creation under the Browser SSO tab.
5. Click Configure Assertion Creation.
6. Click IdP Adapter Mapping on the Summary screen.
If this step is not available, you have chosen to pass either a pseudonym or
transient name identifier and not to use additional attributes (see “Choosing
an Identity Mapping Method” on page 130).
7. Click the Adapter Instance Name.
8. Click Attribute Sources & User Lookup under the IdP Adapter Mapping
tab.
If this step is not shown, you have elected not to look up attributes in data
stores (see “Selecting Assertion Mapping” on page 136).
9. Click the attribute source Description link.
10. Click LDAP Filter from the steps list.
If you have not yet defined an LDAP data store, see “Selecting a Data Store”
on page 140.
To construct the LDAP filter:
1. Enter the statement in the space provided, following the guidelines and
example above.
Note: If you used an anonymous binding to create this LDAP
connection, your access might be restricted (see “Configuring an
LDAP Connection” on page 78).
2. Ensure the syntax and variable names are correct.
3. Click Next.
Configuring Custom Source Filters
When you choose to use a custom source for attributes, you follow this path
through the configuration steps.
On this screen you specify a filter, or lookup query, for your custom data source.
This screen display and the syntax of the filter depends on your developer’s
implementation of the custom source SDK.
Selecting Custom Source Fields
On the Configure Custom Source Fields screen, you can choose from among
the fields shown to map to the adapter contract. These choices are supplied by
148
PingFederate 6
Managing SP Connections
the driver implementation. Select only those needed to fulfill the attribute
contract for this partner connection.
Attribute Contract Fulfillment
The last step in configuring an attribute source is to map values into the attribute
contract (see “Creating an Attribute Contract” on page 132). These are the
values that will be included in assertions sent to this SP (provided the
information is found in this attribute source).
You map attributes on the Attribute Contract Fulfillment screen.
Map each attribute to fulfill the Attribute Contract from one of these
Sources:
•
Adapter
Values are returned from the session. When you make this selection, the
associated Value drop-down list is populated by the session-lookup adapter
(see “SSO Integration Kits and Adapters” on page 4).
For example, you might choose the adapter attribute username to map to
SAML_SUBJECT.
•
LDAP/JDBC/Custom
Values are returned from your attribute source. When you make this
selection, the Value list is populated by the LDAP, JDBC or Custom
attributes you identified for this Attribute Source (see “Configuring an
LDAP Directory Search” on page 145, “Selecting a JDBC Database Table
and Columns” on page 141, or “Configuring Custom Source Filters” on
page 148).
•
Text
The value is what you enter. This can be text only, or you can mix text with
references to any of the values from the adapter, using the ${attribute}
syntax.
Administrator’s Manual
149
Chapter 5
Identity Provider SSO Configuration
You can also enter values from your data store, when applicable, using this
syntax:
${ds.attribute}
where attribute is any of the data store attributes you have selected.
Tip: Two other variables are also available: ${SAML_SUBJECT} and
${TargetResource}. SAML_SUBJECT is the initiating user (or
other entity); TargetResource is a reference to the protected
application or other resource for which the user is requesting SSO
access (available only if specified in the relevant startSSO.ping
query parameter—see “Application Endpoints” on page 347).
There are a variety of reasons why you might hard code a text value. For
example, if your SP’s Web application provides a service based on your
company’s name, you might provide that attribute value as a constant.
Tip: Another selection in the Source drop-down menu, Expressions,
may be enabled (see “Using Attribute Mapping Expressions” on
page 367). This option provides more complex mapping capabilities—
for example, transforming incoming values into different formats. All of
the variables available for text entries are also available for expressions.
To reach this screen for editing:
1. Click the connection name on the Main Menu.
Click Manage All SP, if needed, to see a full list of connections.
2. Click Browser SSO under the SP Connection tab.
3. Click Configure Browser SSO.
4. Click Assertion Creation under the Browser SSO tab.
5. Click Configure Assertion Creation.
6. Click IdP Adapter Mapping on the Summary screen.
If this step is not available, you have chosen to pass either a pseudonym or
transient name identifier and not to use additional attributes (see “Choosing
an Identity Mapping Method” on page 130).
7. Click the Adapter Instance Name.
8. Click Attribute Sources & User Lookup under the IdP Adapter Mapping
tab.
If this step is not shown, you have elected not to look up attributes in data
stores (see “Selecting Assertion Mapping” on page 136).
9. Click the attribute source Description link.
10. Click Attribute Contract Fulfillment from the steps list.
If you have not yet defined a data store, see “Selecting a Data Store” on
page 140).
150
PingFederate 6
Managing SP Connections
To map attributes:
1. Choose a Source for each Target attribute.
2. Choose (or enter) a Value for each Attribute.
See “Map each attribute to fulfill the Attribute Contract from one of these
Sources:” on page 149. All values must be mapped.
3. Click Next.
Using the Attribute Source Summary Screen
When you have finished configuring Attribute Sources and User Lookup, you
can review the configuration on the Summary screen.
If you need to make any changes, click the heading over the information you
want to edit. When you are finished, click Done to continue with IdP Adapter
Mapping configuration. If you are editing an existing connection, click Done on
successive screens until you reach the Assertion Creation screen and then click
Save.
Specifying a Failsafe Attribute Source
If attributes needed to fulfill an attribute contract cannot be found in your data
stores, you can either map a default set of attribute values to send—identifying a
“guest” user, for example—or you can have PingFederate stop the SSO
transaction. This choice depends on your agreement with the SP.
To reach this screen for editing:
1. Click the connection name on the Main Menu.
Click Manage All SP, if needed, to see a full list of connections.
2. Click Browser SSO under the SP Connection tab.
3. Click Configure Browser SSO.
4. Click Assertion Creation under the Browser SSO tab.
5. Click Configure Assertion Creation.
Administrator’s Manual
151
Chapter 5
Identity Provider SSO Configuration
6. Click IdP Adapter Mapping on the Summary screen.
If this step is not available, you have chosen to pass either a pseudonym or
transient name identifier and not to use additional attributes (see “Choosing
an Identity Mapping Method” on page 130).
7. Click the Adapter Instance Name.
8. Click Failsafe Attribute Source on the Summary screen.
This step appears only if you are using data stores (see “Selecting Assertion
Mapping” on page 136).
To specify whether to use a failsafe attribute source:
X Make the relevant selection to use either a default set of attributes or to
terminate the SSO, and then click Next.
Mapping Default Attribute Contract Fulfillment
Fulfillment of the attribute contract must be specified whether or not data
sources are used. You accomplish this on the Attribute Contract Fulfillment
screen, either by choosing to configure default mappings after setting up attribute
sources (see “Specifying a Failsafe Attribute Source” on page 151) or if you
choose not to set up attribute sources (see “Selecting Assertion Mapping” on
page 136).
Map each attribute to fulfill the Attribute Contract from one of these
Sources:
•
Adapter
Values are returned from the session. When you make this selection, the
associated Value drop-down list is populated by the session-lookup adapter
(see “SSO Integration Kits and Adapters” on page 4).
For example, you might choose the adapter attribute username to map to
SAML_SUBJECT.
•
Text
The value is what you enter. This can be text only, or you can mix text with
references to any of the values from the adapter, using the ${attribute}
syntax.
There are a variety of reasons that you might hard code a text value. For
example, if your SP’s Web application provides a consumer service, you
might want to supply a particular promotion code.
Tip: Another selection in the Source drop-down menu, Expressions,
may be enabled (see “Using Attribute Mapping Expressions” on
page 367). This option provides more complex mapping capabilities—
for example, transforming incoming values into different formats. All of
the variables available for text entries are also available for expressions.
152
PingFederate 6
Managing SP Connections
To reach this screen for editing:
1. Click the connection name on the Main Menu.
Click Manage All SP, if needed, to see a full list of connections.
2. Click Browser SSO under the SP Connection tab.
3. Click Configure Browser SSO.
4. Click Assertion Creation under the Browser SSO tab.
5. Click Configure Assertion Creation.
6. Click IdP Adapter Mapping on the Summary screen.
If this step is not available, you have chosen to pass either a pseudonym or
transient name identifier and not to use additional attributes (see “Choosing
an Identity Mapping Method” on page 130).
7. Click the Adapter Instance Name.
8. Click Attribute Contract Fulfillment on the Summary screen.
If you are using data stores for attribute mapping and this step does not
appear, see “Specifying a Failsafe Attribute Source” on page 151.
To map attributes:
1. Choose a Source for each Target attribute (see descriptions of each Source
type above).
2. Choose (or enter) a Value for each Attribute.
All values must be mapped.
3. Click Next.
Administrator’s Manual
153
Chapter 5
Identity Provider SSO Configuration
Configuring Protocol Settings
The Protocol Settings screen provides the launching point for configuring
bindings, partner endpoints, and other settings needed for the selected SAML
profiles (if you are using SAML 2.0—see “Choosing Profiles (SAML 2.0)” on
page 126). The screen also displays configured information.
(For WS-Federation, the configuration of bindings is not applicable.)
To configure Protocol Settings, you need to know:
•
For SSO profiles, the URL(s) of your SP’s Assertion Consumer Service(s)
•
For SLO profiles, the URL(s) of your SP’s Single Logout Service(s)
•
When artifact is an allowable inbound binding, the URL of your SP’s
Artifact Resolution Service(s)
•
The transport configurations (bindings) that you will use to send and receive
data for SSO/SLO connections
•
Digital signature policies and certification requirements to which you
and your connection partner have agreed
•
XML encryption policies to which you and your connection partner have
agreed
Important: After modifying Protocol Settings, you must click Done
on the Protocol Settings screen and then Save on the Browser
SSO screen.
Setting Assertion Consumer Service URLs (SAML)
At this step for SAML connections, you associate bindings to the Assertion
Consumer Service (ACS) endpoint(s) where your SP will receive assertions.
This configuration applies to either SSO Profile (see “Choosing Profiles (SAML
2.0)” on page 126).
154
PingFederate 6
Managing SP Connections
Field Descriptions
Field
Description
Default (SAML 2.0)
A check in this checkbox indicates that the URL
configuration in that row will be used as a default.
Index (SAML 2.0)
Uniquely identifies multiple ACS endpoints.
Binding
The method of transmission: POST or Artifact.
Endpoint URL
A location to which the assertion is sent, according to
partner requirements.
To reach this screen for editing:
1. Click a connection name on the Main Menu.
Click Manage All SP, if needed, to see a full list of connections.
2. Click Browser SSO under the SP Connection tab.
3. Click Configure Browser SSO.
4. Click Protocol Settings on the Summary screen.
5. Click Configure Protocol Settings.
6. Click Assertion Consumer Service URL on the Summary screen.
To define an Endpoint URL:
1. Select the Binding your partner specifies for the Endpoint.
2. (Optional) Enter an Index value — 0 or 1, for example.
For SAML 2.0 the specifications provide for the use of index numbers to
identify multiple ACS endpoints. PingFederate supplies this number
automatically; however, you can manually set the number to match your
partner’s configuration as needed.
Administrator’s Manual
155
Chapter 5
Identity Provider SSO Configuration
3. Enter the fully qualified Endpoint URL or just a relative path if you have
defined a base URL (see “General Information” on page 121).
4. For SAML 2.0 connections, if this is the default (or only) endpoint, click the
checkbox under Default.
5. Click Add.
Setting a Default Target URL (SAML 1.x)
This URL is used whenever PingFederate receives an SSO request from a local
application that does not include the user’s target resource URL at the SP site.
The URL is required regardless of whether you expect your local application(s)
to specify the target—to ensure that the server functions correctly during SSO
events.
Field Descriptions
Field
Description
Default Target URL
The URL of the target SP resource.
To reach this screen for editing:
1. Click a connection name on the Main Menu.
Click Manage All SP, if needed, to see a full list of connections.
2. Click Browser SSO under the SP Connection tab.
3. Click Configure Browser SSO.
4. Click Protocol Settings on the Summary screen.
5. Click Configure Protocol Settings.
6. Click Default Target URL on the Summary screen.
Defining a Service URL (WS-Federation)
The Service URL is the WS-Federation endpoint of your SP partner where you
send SAML assertions and SLO cleanup messages. The assertions are transmitted
within an RSTR (Request for Security Token Response) message in response to a
156
PingFederate 6
Managing SP Connections
request for authentication from the SP. SLO cleanup messages are sent to WSFederation SP partners when the IdP receives a user’s SLO request. Such cleanup
messages indicate that the user’s local session has been terminated.
X Enter the fully qualified URL or just the relative path if you have defined a
base URL (see “General Information” on page 121).
You must include the initial slash if you are entering only a relative path.
Specifying SLO Service URLs (SAML 2.0)
At this step you associate bindings to the endpoints where your SP receives
logout requests when SLO is initiated at your site and where you send SLO
responses when you receive SLO requests from the SP.
This step applies only to SAML 2.0 connections when you select either SLO
profile (see “Configuring IdP-Initiated SLO” on page 128 or “Configuring SPInitiated SLO” on page 128).
Field Descriptions
Administrator’s Manual
Field
Description
Binding
The method of transmission: POST, Artifact, Redirect,
or SOAP.
157
Chapter 5
Identity Provider SSO Configuration
Field
Description
Endpoint URL
A location to which logout messages are sent,
according to SP requirements.
Response URL
(Optional) A location on this IdP to which logout
responses are sent.
To reach this screen for editing:
1. Click a connection name on the Main Menu.
Click Manage All SP, if needed, to see a full list of connections.
2. Click Browser SSO under the SP Connection tab.
3. Click Configure Browser SSO.
4. Click Protocol Settings on the Summary screen.
5. Click Configure Protocol Settings.
6. Click SLO Service URLs on the Summary screen.
To add a URL
1. Select the Binding type.
2. Enter the fully qualified URL (or the relative path, if you have specified a
base URL—see “General Information” on page 121).
3. (Optional) Enter the Response URL.
4. Click Add.
To edit an endpoint:
1. Click Edit under Action for the endpoint.
2. Make your change and click Update.
To delete an entry:
X Click Delete under Action for the endpoint.
Choosing Allowable SAML Bindings (SAML 2.0)
At this step for SAML 2.0 connections, you select the binding(s) that your SP
partner will use to send SAML authentication requests or SLO messages.
This configuration applies to SP-initiated SSO and to either SLO profile.
158
PingFederate 6
Managing SP Connections
To reach this screen for editing:
1. Click a connection name on the Main Menu.
Click Manage All SP, if needed, to see a full list of connections.
2. Click Browser SSO under the SP Connection tab.
3. Click Configure Browser SSO.
4. Click Protocol Settings on the Summary screen.
5. Click Configure Protocol Settings.
6. Click Allowable SAML Bindings on the Summary screen.
Setting an Artifact Lifetime (SAML)
When you send an artifact to your SP’s Assertion Consumer Service or SLO
service (for SAML 2.0), an element in the message indicates how long it should
be considered valid.
You can change the default value per your requirements, if needed. Also consider
synchronizing clocks between your server and your partner’s SAML gateway
server. If clocks are not synchronized, you might need to set the artifact lifetime
to a higher value.
Administrator’s Manual
159
Chapter 5
Identity Provider SSO Configuration
To reach this screen for editing:
1. Click a connection name on the Main Menu.
Click Manage All SP, if needed, to see a full list of connections.
2. Click Browser SSO under the SP Connection tab.
3. Click Configure Browser SSO.
4. Click Protocol Settings on the Summary screen.
5. Click Configure Protocol Settings.
6. Click Artifact Lifetime on the Summary screen.
This step appears only if you have selected the artifact binding for either an
SSO or SLO Service (under SAML 2.0) at the SP site.
Specifying Artifact Resolver Locations (SAML 2.0)
This endpoint or group of endpoints is where your server will send back-channel
requests to resolve artifacts received from your partner. The locations are also
known collectively under SAML specifications as the Artifact Resolution
Service.
To reach this screen for editing:
1. Click a connection name on the Main Menu.
Click Manage All SP, if needed, to see a full list of connections.
2. Click Browser SSO under the SP Connection tab.
3. Click Configure Browser SSO.
4. Click Protocol Settings on the Summary screen.
5. Click Configure Protocol Settings.
6. Click Artifact Resolver Locations on the Summary screen.
If this step does not appear, you do not have Artifact selected under
Allowable SAML Bindings.
160
PingFederate 6
Managing SP Connections
To configure the Artifact Resolver Location(s):
1. Enter a URL on the Artifact Resolver Locations screen and click Add.
The URL must be fully qualified (defining protocol, host, and port) unless
you have entered a base URL (see “General Information” on page 121).
Repeat this step if your SP supports multiple services. The SAML 2.0
specifications permit multiple artifact resolution services through the use of
Index numbers, which PingFederate automatically supplies when you add a
service. Alternatively, if needed per partner specifications, you may assign
these index numbers manually.
Note: When specifying multiple artifact resolution endpoints, each
endpoint must share the same transport protocol. That is, if one
endpoint uses HTTP, then all must use HTTP. Similarly, if one
endpoint uses HTTPS, then all must use HTTPS.
2. Click Next.
Configuring Signature Policy
The Signature Policy screen provides options controlling how digital signatures
are used for SSO Internet messaging. The choices made on this screen depend on
your partner agreement (see “Digital Signing Policy Coordination” on page 13).
Digital signing is required for SAML Response messages sent from your site via
POST (or Redirect for SAML 2.0). Optionally, SSO authentication requests
from the SP (SP-initiated SSO) may also be signed to enforce security. (This
option appears only for SAML 2.0 connections and only if you have enabled SPinitiated SSO using the POST or redirect bindings.)
The assertions inside SAML Responses may be also be signed. When you make
this choice, only the assertion portion of the Response is signed, not the
complete Response. (This is the only option that appears for SAML 1.x
connections.)
Administrator’s Manual
161
Chapter 5
Identity Provider SSO Configuration
X Make your selections and click Next, or just click Next if no additional
security is required.
Configuring XML Encryption Policy (SAML 2.0)
For SAML 2.0 configurations, in addition to using signed assertions to ensure
authenticity, you and your partner may also agree to encrypt all or part of an
assertion to improve privacy. This feature is commonly used if the assertion
might pass through an intermediary (such as a user’s browser) and HTTPS is not
used.
If the name identifier (or SAML_SUBJECT) of an assertion is encrypted, you and
your partner may also want to encrypt the identifier in subsequent single-logout
messages (if you are using an SLO profile).
Note that “The entire assertion” selection on the Encryption Policy screen
includes the SAML_SUBJECT and all attributes.
To reach this screen for editing:
1. Click a connection name on the Main Menu.
Click Manage All SP, if needed, to see a full list of connections.
2. Click Browser SSO under the SP Connection tab.
3. Click Configure Browser SSO.
4. Click Protocol Settings under the Browser SSO tab.
5. Click Configure Protocol Settings.
6. Click Encryption Policy on the Summary screen.
To define XML encryption:
1. Choose whether you want to encrypt the entire assertion or one or more
attributes.
162
PingFederate 6
Managing SP Connections
2. If you are encrypting the name-identifier attribute, use the checkboxes near
the bottom of the screen to indicate whether you will also encrypt this
attribute in outbound SLO messages and/or allow its encryption for inbound
messages.
3. Click Next or Done.
To disable previously configured XML encryption selections:
1. Select None and then Done.
2. Click Save on the Protocol Settings screen.
Editing and Saving Protocol Settings
On the Summary screen you can review or edit your Protocol Settings.
Important: When you finish editing existing settings, be sure to
click Done on the Summary screen and then Save on the Protocol
Settings screen. For a new connection, click Done and then click
Next on the Protocol Settings screen. Save the entire connection
on the Activation & Summary screen (see “Connection Activation
and Summary” on page 189).
To reconfigure saved settings:
1. Click the heading over the information you want to change.
2. Click Done on the screen containing your change.
If you need to make dependent or other changes, do so and continue by
clicking Done until you reach the Protocol Settings screen.
3. Click Save on the Protocol Settings screen.
Editing and Saving Browser SSO Settings
On the Summary screen for Browser SSO, you can review or edit your SSO
configuration.
Important: When you finish editing existing settings, be sure to
click Done on the Summary screen and then Save on the Browser
SSO screen. For a new connection, click Done and then click Next
on the Browser SSO screen. Save the entire connection on the
Activation & Summary screen (see “Connection Activation and
Summary” on page 189).
To reconfigure saved settings:
1. Click the heading over the information you want to change.
Administrator’s Manual
163
Chapter 5
Identity Provider SSO Configuration
2. Click Done on the screen containing your change.
If you need to make dependent or other changes, do so and continue by
clicking Done until you reach the Browser SSO screen.
3. Click Save on the Browser SSO screen.
Configuring the Attribute Query Profile
At the Attribute Query step you configure your connection to respond to
requests for user attributes from your partner SP, if you have chosen this option
(see “Choosing Connection Options” on page 120). Attribute queries are not
dependent on single sign-on but may be used independently or in conjunction
with Browser SSO or provisioning to provide flexibility in how a user
authenticates with SP applications (see “Attribute Query and XASP” in the
“Supported Standards” chapter of Getting Started).
X To continue, click Configure Attribute Query Profile.
Defining Retrievable Attributes
On this screen you specify the user attributes you and your partner have agreed to
allow in an attribute query transaction. Note that the SP may not necessarily
request all of these attributes in each attribute-query request. Instead, the list
simply limits the request to a subset of these attributes.
164
PingFederate 6
Managing SP Connections
To add an attribute:
X Enter the attribute name in the text box and click Add.
To edit an attribute name:
1. Click Edit and make your change.
2. Click Update.
To delete an attribute:
X Click Delete.
Choosing a Data Store
Because no user authentication is performed in response to an attribute-query
request, you cannot use attributes drawn from the user’s session (see “IdP Adapter
Mapping” on page 134). Therefore, you must identify a data store that contains
the attributes on your system.
Administrator’s Manual
165
Chapter 5
Identity Provider SSO Configuration
Configuring Data Store Lookup
The process of configuring PingFederate to look up attributes in a data store for
attribute-query responses is similar to that used for SSO Attribute Sources and
User Lookup. For detailed information, see the step-by-step procedures in the
sections indicated below.
If you use a JDBC data store, see:
– “Selecting a JDBC Database Table and Columns” on page 141
–
“Configuring a Database Filter (WHERE Clause)” on page 143
If you use a LDAP data store, see:
– “Configuring an LDAP Directory Search” on page 145
–
“Configuring an LDAP Filter” on page 146
If you use a Custom data store, see:
– “Configuring Custom Source Filters” on page 148
–
“Selecting Custom Source Fields” on page 148
Note that the screen text may differ slightly and only one data store may be
configured to supply user attributes. In addition, note that the variable
${SAML_SUBJECT} is available on the Database or LDAP Filter screens to
retrieve the subject identifier from the Attribute Query for use in data-store
query statements.
Important: When attribute queries are sent using XASP, use the
variable ${SubjectDN}—rather than ${SAML_SUBJECT}—to retrieve
the subject identifier. You may also use any of these DN-parsing
variables: ${CN}, ${OU}, ${O}, ${L}, ${S}, ${C}, and ${DC}.
If more than one value exists for any of the parsing variables, then they
are enumerated. For example, if the Subject DN is:
cn=John Smith,ou=service,ou=employee
then you could use any of these elements in your filter qualifier:
${SubjectDN}=cn=John Smith,ou=service,ou=employee
${ou}=service
${ou1}=employee
For more information about XASP, see “Attribute Query and XASP” in
the “Supported Standards” chapter of Getting Started.
Attribute Mapping Fulfillment
The last step in configuring an attribute source is to map values into the assertion
to be sent in response to an attribute query.
You map attributes on the Attribute Mapping Fulfillment screen.
166
PingFederate 6
Managing SP Connections
Map each attribute into the assertion from one of these Sources:
•
LDAP/JDBC/Custom
Values are returned from your attribute source. When you make this
selection, the Value list is populated by the LDAP, JDBC, or Custom
attributes you identified for this Attribute Source.
•
Text
This can be text only, or you can mix text with references to any of the
values from your user data store using this syntax:
${ds.attribute}
where attribute is any of the data store attributes you have selected.
There are a variety of reasons why you might hard code a text value. For
example, if your SP’s Web application provides a service based on your
company’s name, you might provide that attribute value as a constant.
Tip: Another selection in the Source drop-down menu, Expressions,
may be enabled (see “Using Attribute Mapping Expressions” on
page 367). This option provides more complex mapping capabilities—
for example, transforming incoming values into different formats. All of
the variables available for text entries are also available for expressions.
Specifying Security Policy
This screen allows you to specify the digital signing and encryption policy to
which you and your partner have agreed. These selections will trigger
requirements for setting up Credentials (see “Configuring Credentials” on
page 168).
Administrator’s Manual
167
Chapter 5
Identity Provider SSO Configuration
To configure attribute-query security policy for this partner:
X Check or clear the check boxes and click Next or Done.
Editing and Saving Attribute Query Configurations
To reconfigure saved profiles:
1. Click the heading over the information you want to change.
2. Click Done on the screen containing your change.
If you need to make additional changes, do so and continue by clicking
Done until you reach the Attribute Query screen.
3. Click Save on the Attribute Query screen.
Configuring Credentials
The Credentials screen presents a list of possible security requirements you might
need, depending on the federation protocol you are using and the choices you
have made.
Your connection configuration may involve any or all of the following:
168
•
Configuring Back-Channel Authentication
•
Configuring Digital Signature Settings
•
Selecting Signature Verification Certificates
•
Selecting an Encryption Certificate (SAML)
•
Selecting a Decryption Key (SAML)
PingFederate 6
Managing SP Connections
X To continue, click Configure Credentials.
Configuring Back-Channel Authentication
When you configure a profile for inbound SAML messages via the artifact
binding, you must specify authentication information for outbound artifact
resolution requests over SOAP to your SP’s Artifact Resolution Service.
Similarly, if you configure outbound Assertion Consumer Service or SLO Service
URLs to use the artifact binding, then you must configure SOAP authentication
requirements for inbound messages such as artifact resolution requests. If you
configure outbound SLO Service URLs to use the SOAP binding, then you must
also configure authentication requirements for outbound SOAP messages.
Administrator’s Manual
169
Chapter 5
Identity Provider SSO Configuration
To reach this screen:
1. Click a connection name on the Main Menu.
Click Manage All SP, if needed, to see a full list of connections.
2. Click Credentials under the SP Connection tab.
3. Click Configure Credentials.
4. Click Back-Channel Authentication on the Summary screen.
If this step is not present, then it is not applicable to your configuration—
you have not configured any profiles that use an artifact or SOAP binding or
allowed artifact as an inbound SAML binding.
To configure back-channel authentication requirements for sending
SOAP messages:
1. On the Back-Channel Configuration screen, click the Configure link to the
right of the list of messages to be sent to your partner.
2. Make one or more selections on the Outbound SOAP Authentication Type
screen:
•
•
Basic — you will enter SOAP Basic credentials on a later screen.
SSL Client Certificate — you will specify the certificate on a later
screen.
This option is enabled only if you have specified an endpoint that
uses SSL.
•
Use Digital Signatures . . . — you will sign the message.
You will be asked to select a signing certificate on a later screen.
For SAML 2.0, these options may be used in any combination or
independently. For SAML 1.x, you must use either Basic or SSL
authentication; digital signing may be added to ensure message integrity.
By default, PingFederate validates your partner’s SSL server certificate—
verifying that the certificate chain is rooted by a trusted Certificate
Authority and that the hostname matches the certificate’s Common Name.
Clear the associated checkbox if you do not want this validation to occur.
3. Click Next.
4. If you chose Basic at step 2, enter the SOAP Username and Password to
use for this partner under Basic SOAP Authentication.
You must obtain these credentials from your partner.
5. If you are using an SSL certificate, select the certificate under SSL
Authentication Certificate and click Next.
If you have not yet created or imported the client SSL certificate you need
into PingFederate, click Manage Certificates (see “SSL Client Keys &
Certificates” on page 94). You will need to export the certificate (only) and
send it your partner.
6. On the Summary screen, click Done.
170
PingFederate 6
Managing SP Connections
To configure back-channel authentication requirements for receiving
SOAP messages:
1. On the Back-Channel Configuration screen, click the Configure link to the
right of the list of messages to be received from your partner.
2. Select one or more options on the Inbound SOAP Authentication Type
screen:
•
Basic — Enter the logon username and password your partner will use
on the next screen.
•
SSL Certificate — Specify certificate verification information on a later
screen.
•
Use Digital Signatures . . . — Incoming messages must be signed.
You will be asked to select a signature verification certificate on a
later screen.
For SAML 2.0, these options may be used in any combination or
independently. For SAML 1.x, you must use either Basic or SSL
authentication; digital signing may be added to ensure message integrity.
3. Click Next.
4. If you chose Basic at step 2, enter the SOAP Username and Password
under Basic SOAP Authentication.
Important: If you are configuring more than one connection that
uses the artifact or SOAP profile, you must ensure that the
Username is unique for each connection.
5. If you are using an SSL certificate, select Anchored or Unanchored under
Certificate Verification Method.
•
Anchored — The certificate must be signed by a trusted Certificate
Authority, and the CA’s certificate must be imported into the
PingFederate Trusted CA store (see “Trusted CAs” on page 90).
•
Unanchored — The certificate is self-signed or you wish to trust a
specified certificate.
Note: When anchored certificates are used between partners,
certificates may be changed without sending the update to your
partner. If the certificate is unanchored, any changes must be
promulgated.
6. Click Next.
Administrator’s Manual
171
Chapter 5
Identity Provider SSO Configuration
7. If you chose anchored SSL certificate verification at step 5, enter the
Subject DN and click Next.
Tip: If you have not yet defined the certificate in PingFederate or
you do not know the DN, return to the previous screen and check
Unanchored. Then click Next and click Manage Certificates on the
SSL Verification Certificate screen to import the certificate, if
needed, or to view its DN.
8. If you chose unanchored SSL certificate verification at step 5, select the
certificate you will use to validate the SSL connection.
If you have not yet imported the certificate into PingFederate, click
Manage Certificates.
9. Click Next.
10. On the Summary screen, click Done.
Configuring Digital Signature Settings
This step defines the private key/certificate that you will use to sign assertions
and SLO messages for this SP.
Note: Digital signing is required for SSO assertions and SLO messages
sent via POST or redirect bindings. Signing is not always required for
profiles using the artifact or SOAP bindings.
The step applies to both IdP- and SP-initiated SSO and to either SLO profile
(see “” on page 124) whenever outbound POST or redirect bindings are used.
The step also is required for WS-Trust STS and for SSO if you chose to sign the
SAML assertion, SAML response, or artifact resolution messages (see
“Configuring Back-Channel Authentication” on page 169).
To reach this screen:
1. Click a connection name on the Main Menu.
Click Manage All SP, if needed, to see a full list of connections.
172
PingFederate 6
Managing SP Connections
2. Click Credentials under the SP Connection tab.
3. Click Configure Credentials.
4. Click Digital Signing Settings on the Summary screen.
This step does not appear if your connection’s configuration does not require
it.
To specify a certificate:
1. Select the certificate from the drop-down list.
If you have not yet created or imported your certificate into PingFederate,
click Manage Certificates (see “Digital Signing and Decryption Keys &
Certificates” on page 96).
2. (Optional) If you have agreed to send your public key with the SAML
message, click the checkbox to implement this requirement.
Selecting Signature Verification Certificates
Under SAML 2.0 specifications, when your site receives any SAML 2.0 messages
via the POST or Redirect bindings, the messages must be digitally signed.
Signing is also always required for the SAML 1.x POST binding and for WSFederation assertions, as well as incoming SAML 1.1 or 2.0 tokens for WS-Trust
STS processing.
Depending on your agreement with this SP, SSO assertions, SAML 2.0 artifacts,
or SOAP messages might also require signatures.
Whenever signatures are required, you must import your partner’s public key
certificate into the PingFederate store for signature verification.
Tip: To prevent any interruption of service due to an expired certificate,
you can ask your partner for a new certificate in advance and use it in
the Secondary certificate field. The PingFederate server will use the
primary certificate until it expires and then try the secondary.
Administrator’s Manual
173
Chapter 5
Identity Provider SSO Configuration
Note: This screen differs significantly between SAML 2.0 and SAML
1.x—see procedures below.
To reach this screen:
1. Click a connection name on the Main Menu.
Click Manage All SP, if needed, to see a full list of connections.
2. Click Credentials under the SP Connection tab.
3. Click Configure Credentials.
4. Click Signature Verification Certificate on the Summary screen.
If this step does not appear, then your configuration does not require a
verification certificate.
To specify a verification certificate for SAML 2.0:
1. Select the certificate from the drop-down list.
If you have not yet imported the certificate into PingFederate, click
Manage Certificates.
2. Optionally, select a Secondary certificate for backup.
Use this field if your partner has sent you a new certificate to replace one
that is ready to expire. The server will automatically verify against the
secondary certificate when the primary one expires.
Selecting an Encryption Certificate (SAML)
To enable XML encryption of all or part of an SSO assertion, you must identify
the encryption certificate you will use (see “Configuring XML Encryption Policy
(SAML 2.0)” on page 162).
You must also select a certificate if your requirements include encrypting an
assertion in response to an attribute query (see “Specifying Security Policy” on
page 167).
174
PingFederate 6
Managing SP Connections
To reach this screen:
1. Click a connection name on the Main Menu.
Click Manage All SP, if needed, to see a full list of connections.
2. Click Credentials under the SP Connection tab.
3. Click Configure Credentials.
4. Click Select XML Encryption Certificate.
If this step is not present, you have chosen not to encrypt the assertion or the
SAML_SUBJECT (see “Configuring XML Encryption Policy (SAML 2.0)”
on page 162).
To identify the encryption certificate:
1. (Optional) Change the default settings under Block Encryption Algorithm
and/or Key Transport Algorithm.
Due to import control restrictions, the standard JRE distribution supports
strong but not unlimited encryption. To use the strongest AES encryption,
when permissible, download and install the appropriate version of “Java
Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files”
from the Sun download Web site (http://java.sun.com/javase/downloads).
For more information about XML block encryption and key transport
algorithms, see the “XML Encryption Syntax and ProcessingW3C
Recommendation” at http://www.w3.org/TR/xmlenc-core/.
2. From the drop-down list, select the applicable certificate and click Next.
If the certificate is not in the list, click Manage Certificates to import it.
Note: If you have already imported a signature verification
certificate for this partner, you can reuse it for XML encryption as
long as it is an RSA certificate.
Administrator’s Manual
175
Chapter 5
Identity Provider SSO Configuration
Selecting a Decryption Key (SAML)
If SAML_SUBJECT is encrypted, either by itself or as part of a whole assertion,
then all references to this name identifier in SLO requests from your partner may
also be encrypted (if the connection uses SP-initiated SLO under SAML 2.0).
To enable XML encryption, you must identify a certificate for PingFederate to
use to decrypt incoming SLO messages.
To reach this screen:
1. Click a connection name on the Main Menu.
Click Manage All SP, if needed, to see a full list of connections.
2. Click Credentials under the SP Connection tab.
3. Click Configure Credentials.
4. Click Select XML Decryption Key.
If this step is not present, you have chosen not to encrypt the assertion or the
SAML_SUBJECT attribute (see “Configuring XML Encryption Policy
(SAML 2.0)” on page 162).
To identify the decryption key:
X From the drop-down list, select the applicable certificate and click Next.
If the certificate is not in the list, click Manage Certificates to import it
(see “Digital Signing and Decryption Keys & Certificates” on page 96).
Note: If you have imported a certificate to use for digital signing,
you can reuse it for XML decryption as long as it is an RSA
certificate.
176
PingFederate 6
Managing SP Connections
Editing and Saving Credential Configurations
From the Summary screen you can review or edit your credentials configuration.
Important: When you finish editing existing settings, you must
click Done on the Summary screen and then Save on the
Credentials screen. For a new connection, click Done and then click
Next on the Credentials screen. Save the entire connection on the
Activation screen (see “Connection Activation and Summary”
next).
Configuring SaaS Provisioning
PingFederate’s SaaS Provisioning (available separately) allows an IdP to create
and maintain user accounts at selected service-provider sites in order to
streamline SSO (see “SaaS Provisioning” on page 18). Detailed configuration of
this feature begins on the SaaS Provisioning screen.
Note: This configuration task is presented in the administrative console
only when SaaS Provisioning has been enabled and selected as an
option for the current connection (see “Choosing Connection Options”
on page 120). For new connections, you must first configure Browser
SSO and Credentials settings (see “Identity Provider SSO
Configuration” on page 105
X To continue, click Configure Provisioning.
Defining a Provisioning Target
Information on the Target screen indicates what account name and password
PingFederate will use for authentication to the provisioning API for either
Google Apps or salesforce.com. To use this screen, you must have a registered
Administrator’s Manual
177
Chapter 5
Identity Provider SSO Configuration
domain with the SaaS provider and a valid account and password that can be
used to access the provider’s public Web-service endpoint for provisioning.
For Salesforce, the screen also provides a choice of environments (production or
testing).
To configure the Target:
1. Enter a valid Admin Email (for Google) or Admin Username (for
Salesforce).
2. Enter the Admin Password.
3. For Salesforce channels, select the Environment.
4. Click Next.
Note: When you first enter or change credentials and click Next,
PingFederate immediately tests connectivity to the target.
Managing SaaS Channels
A provisioning channel is a mapping configuration between user attributes
contained in a source user store and attributes supported or required by the
targeted software-service application. You can have multiple channels to the
same target as needed—for example, if your organization has separate LDAP
stores (or different nodes in the same store) for various user groups needing SSO
access and provisioning to the same SaaS domain.
Tip: There can be only one target SaaS domain for a connection
(“Defining a Provisioning Target” on page 177). If your organization
subscribes to multiple SaaS domains for which you need provisioning
and SSO support, you will need a separate SP connection for each
domain.
178
PingFederate 6
Managing SP Connections
Channels are created and managed from the Manage Channels screen.
To access the Manage Channels screen:
1. In the task headings for a connection, click SaaS Provisioning.
If this task is not present, provisioning is not enabled (see “Choosing Roles
and Protocols” on page 64).
2. On the SaaS Provisioning screen, click Configure Provisioning.
To configure a new channel:
X Click Create and follow the configuration steps.
Tip: If you are creating a second channel to a SaaS vendor, you may
wish to copy an existing channel and make necessary changes.
To copy a channel:
1. Click Copy under Action for the channel you want to copy.
2. Enter new General Info for the channel (see “Specifying Channel
Information” on page 180).
3. Make any further changes needed for the new channel.
To edit a channel:
X Click the Channel Name link.
To delete a channel:
1. Under Action, click Delete for the channel.
(To undo the deletion, click Undelete.)
Note: The Delete function is not available if the channel is active
(see “Channel Activation and Summary” on page 188).
2. To confirm the deletion, click Done and then Save on the Configure SaaS
Provisioning screen.
Administrator’s Manual
179
Chapter 5
Identity Provider SSO Configuration
Specifying Channel Information
On the Channel Info screen, specify a unique identifier for the channel.
Tip: Adjust the Max Threads setting as needed to optimize datatransfer performance, particularly if large numbers of records need to
be provisioned at the target site.
Identifying the Source Data Store
PingFederate fully supports Active Directory and the Sun Directory Server as
source user repositories for SaaS Provisioning. However, you can use other types
of LDAP servers, either identifying them as Generic or registering them with
PingFederate (see “Configuring an LDAP Connection” on page 78).
Information from your user data store is used to supply mapped values for each
user attribute required by the SaaS provider (see “Mapping Attributes” on
page 185).
180
PingFederate 6
Managing SP Connections
X On the Source screen, choose the LDAP store to use for this channel.
Note: If the correct data store is not listed, then it has not yet been
identified to PingFederate; click Manage Data Stores to set a
connection to user store (see “Configuring an LDAP Connection”
on page 78).
Modifying Source Settings
The Source Settings screen shows the default configuration of the data store
selected on the previous screen, including settings used by the PingFederate
provisioner to determine when user information has been added, changed, or
removed.
Administrator’s Manual
181
Chapter 5
Identity Provider SSO Configuration
If you are using the Sun Directory Server or Active Directory, in most cases no
changes are needed on this screen unless your data store uses a customized
schema.
If you are using a different LDAP directory, you must supply the required
information on this screen unless you have defined a template for the data store
(see “Defining an LDAP Type” on page 80).
182
PingFederate 6
Managing SP Connections
Field Descriptions
Field
Description
Entry GUID Attribute
The name of the attribute in the data store
representing the user’s Globally Unique Identifier.
GUID Type
Indicates whether the GUID is stored in binary or
text format. Active Directory is always binary.
Other LDAP stores most often use text.
Member of Group
Attribute
A multi-value user attribute containing the DNs of
the groups to which an entry belongs. This
attribute does not apply to some LDAP servers,
including the Sun Directory Server. The attribute
below is used instead. Active Directory uses both
values to provide a two-way mapping between
User and Group objects.
Group Member Attribute
The name of a multi-value group attribute used to
track membership in the group using either DN or
GUID values.
User Object Class
The LDAP object class to which user entries
belong, used to restrict search results to user
entries only.
Changed Users
Algorithm
The method by which PingFederate determines if
user records have been updated or new records
added, thus requiring provisioning updates at the
target SaaS site. The three choices are:
Active Directory USN – For Active Directory
only, this algorithm queries for update sequence
numbers on user records that are larger than the
last time records were checked.
Timestamp – Queries for timestamps on user
records that are not older than the last time
records were checked. This check is more efficient
from the point of view of the PingFederate
provisioner but can be more time consuming on
the LDAP side, particularly with the Sun Directory
Server.
Timestamp No Negation – Queries for
timestamps on user records that are newer than
the last time records were checked. This algorithm
is recommended for the Sun Directory Server.
Administrator’s Manual
USN Attribute
The name of the attribute used to store the update
sequence number—applicable when the Active
Directory algorithm is chosen above.
Timestamp Attribute
The name of the attribute used to store the
timestamp on user records.
Account Status Attribute
The name of the attribute in which the user’s
account status (active or inactive) is stored.
183
Chapter 5
Identity Provider SSO Configuration
Field
Description
Default Status
Indicates the user’s status if the attribute is
missing.
Account Status Algorithm
The method by which PingFederate determines a
user’s account status. The values are:
Active Directory Bitmap – For Active Directory,
which uses a bitmap for each user entry.
Flag – For Sun and other LDAP directories, which
use a separate attribute to store the user’s status.
When this option is selected, the two fields below
are also used.
Flag Comparison Value
Indicates what value to check the flag against —
for example, ENABLED or ACTIVE.
Flag Comparison Status
Indicates whether the user is enabled or disabled
when the flag has the value specified in the Flag
Comparison Value field. For any other value the
user will have the opposite status.
Specifying a Source Location
Indicate on the Source Location screen where PingFederate should look for user
records in the data store.
After specifying the required Base DN, you have two options for indicating
which users are to be provisioned: the search can be based either on a specified
LDAP filter or on group membership. (If needed for special situations, both
methods can be used.)
184
PingFederate 6
Managing SP Connections
Field Descriptions
Field
Description
User Base DN
The base distinguished name of the tree structure
where user records are stored. PingFederate looks
only at this node level or below it for user accounts
that need to be provisioned.
Group DN
The group distinguished name associated with the
user store, if applicable—required if a Filter is not used
(see below).
Filter
An LDAP search filter—required if a Group DN is not
used. For information about LDAP filters, refer to your
LDAP documentation. Note that you may need to
escape any special characters.
To specify a location:
1. Enter the User Base DN.
2. Enter either a Filter, a Group DN (or both if needed).
Mapping Attributes
The Attribute Mapping screen provides a means of managing how attributes
from your user store are mapped to the provisioning fields supported for your
organization’s SaaS-customer account.
Tip: PingFederate automatically retrieves from the SaaS vendor the
Field Names shown on this screen, but only on the first pass through
the screen flow. If you are using this screen to modify an existing
mapping configuration, click Refresh Fields near the bottom of the
screen to synchronize the list with the target data store if needed.
Administrator’s Manual
185
Chapter 5
Identity Provider SSO Configuration
For each field, the screen provides a means of adding or modifying the mapping
details (see the next section, “Specifying Mapping Details”).
Note: All required attributes listed in the Field column, indicated with
asterisks, must be mapped. Click View Partner Field Specifications
near the bottom-left of the screen for a summary of requirements for all
fields specified for the target SaaS partner.
For some fields, PingFederate preselects LDAP attributes commonly
used to store the required values.
To configure attribute mapping:
1. Click Edit under Action for a field.
2. On the Specify Attribute Mapping screen, provide mapping details.
(For more information, see the next section, “Specifying Mapping Details”.)
3. Repeat for each attribute shown in the Field Name column as needed.
186
PingFederate 6
Managing SP Connections
Tip: If you need to map more than one attribute from your data store
into a single field at the target location, then you must use an OGNL
expression to indicate how the attribute values are to be combined.
The use of OGNL expressions may not be enabled for your
PingFederate installation (see “Using Attribute Mapping Expressions”
on page 367).
Specifying Mapping Details
On this screen, you define specific mapping information for each field required
for provisioning (and for any optional fields, as needed).
Caution: If end-users at your site are permitted to edit some of their
own attributes directly in the LDAP store, ensure that the attributes are
restricted and do not include any attributes needed by the SaaS
provider to grant permissions.
Administrator’s Manual
187
Chapter 5
Identity Provider SSO Configuration
To define mapping information for an attribute:
1. Select the Root Object Class containing a user-store attribute that you want
to map to the SaaS attribute shown under Field.
Note: For some required fields, you may not need to map specific
user attributes. If so, supply a Default Value instead—skip this step
and go to step 5. You can also do both as needed: specify LDAP
attributes as well as a Default Value.
2. Under Attribute, select an attribute from the class.
3. Click Add Attribute.
4. Repeat the steps above to add additional applicable attributes, as needed, to
use in a mapping expression.
5. Under Value Definition, enter or select a Default Value (optional, if one or
more attributes is specified above).
A drop-down list is shown for this field if the SaaS vendor requires a choice
among specified values. When an expression is also supplied, the default
value is sent during provisioning if an error occurs evaluating the expression.
6. If more than one attribute is used for mapping, enter an Expression.
Tip: Click Test to validate the expression.
For information about the expression language supported by PingFederate,
OGNL, see “Using Attribute Mapping Expressions” on page 367.
Important: The use of OGNL expressions may not be enabled for
your PingFederate installation (see “Enabling/Disabling
Expressions” on page 368).
7. (Optional) Select one or more processing Options, as defined below:
Create Only – The field is provisioned only once and not subsequently
updated.
Trim – Removes any white space from the attribute value(s).
Upper Case/Lower Case/None – Transforms the attribute value(s) to the
case indicated, unless None is selected (the default).
Channel Activation and Summary
When you finish setting up a channel, you may choose to activate it
immediately; or you can return to the Activation & Summary screen and activate
the channel when needed. Note that the overall SP connection for the SaaS
188
PingFederate 6
Managing SP Connections
partner also must be active for any provisioning channels to be enabled (see
“Connection Activation and Summary” on page 189).
Caution: When a connection containing a newly activated channel is
itself activated, initial provisioning occurs as soon as the
synchronization-frequency time period expires (see “Configuring SaaS
Provisioning Settings” on page 69). The default is 60 seconds. Initial
provisioning can consume considerable processing time, depending on
the amount of data that needs to be transmitted; administrators may
wish to plan accordingly.
Important: Regardless of whether you choose to activate a new
channel immediately or later, if you want to save the channel
configuration, click Done on the Summary screen and then Save on
the connection Activation and & Summary screen. (For a new channel
in an existing connection, click Save on the SaaS Provisioning screen.)
You can deactivate a channel at any time (for maintenance, for example). When
a channel is inactive, SSO/SLO transactions can still occur (if the connection is
active), but provisioning is suspended.
To change a channel status:
X Select either Active or Inactive and then click Done.
To modify a channel setting:
X If you know which step needs to be modified, click its link under the SaaS
Channels tab.
If you do not know where to change a setting, locate the currently
configured setting under one of the summary headings and then click the
subheading above the information.
Connection Activation and Summary
When you finish setting up a connection, you may choose to activate it
immediately.
Important: Regardless of whether you choose to activate a new
connection now or later, you must click Save on the Summary screen
for a new connection if you want to keep the configuration.
You can deactivate a connection at any time (for maintenance, for example).
When a connection is inactive, all SSO or SLO transactions to or from this
Administrator’s Manual
189
Chapter 5
Identity Provider SSO Configuration
partner are disabled, as well as access to the WS-Trust STS for Web Service
Clients associated with this connection.
Tip: The SSO Application Endpoint near the top of the Summary screen
is an example URL that webmasters or Web application developers at
your site might use to invoke SSO for the connection. For details about
SSO and other server endpoints, including optional query parameters,
see “Application Endpoints” on page 347.
To change a Connection Status:
X Select either Active or Inactive and then click Save.
To modify a connection setting:
1. If you know which step needs to be modified, click its link under the SP
Connection tab.
If you do not know where to change the setting, locate the currently
configured data under one of the summary headings and then click the
subheading above the data.
2. Change the information on the step screen and click Save, if available.
If Save is not available, you are in the middle of a task (see “About Tasks
and Steps” in the “Console Navigation” chapter of Getting Started); click
Next or Done until you reach a screen containing a Save button. Then
click Save and continue as needed until you return to the Main Menu.
If your modification requires related configuration changes, PingFederate
provides error messages indicating the necessary steps and then guides you to
the related screens (unless you click Cancel).
Important: Be sure to click Save whenever that button appears, if
you want to keep your changes.
Defining SP Affiliations
An SP affiliation is a SAML 2.0 specification that permits a group of service
providers to make use of the same persistent name identifier for account linking
(see “Account Linking” on page 5).
This may be of use when multiple service providers share a business relationship
in which users need services from each affiliated provider. By agreement among
the affiliation members, the same pseudonym can be used to populate the
SAML_SUBJECT of assertions sent to all of the SP partners contained in this
affiliation.
Important: Each connection in the affiliation must be configured to
use the same IdP adapter instance for generating account links
(see “IdP Adapter Mapping” on page 134).
190
PingFederate 6
Defining SP Affiliations
You can create or modify an SP affiliation from the Main Menu or from a list of
affiliations (click Manage All Affiliations).
To create an SP affiliation:
X Click Create New under SP Affiliations on the Main Menu.
Or:
X Click Manage All Affiliations and then click Create Affiliation on the
Select an Affiliation screen.
To delete an affiliation:
1. Click Manage All Affiliations under SP Affiliations on the Main Menu.
2. Click Delete under Action for the affiliation you want to delete.
3. Click Save to confirm the deletion (or click undelete).
To view or modify an affiliation:
X Click the affiliation name, or click Manage All Affiliations if the ID does
not appear.
Using the Manage Affiliations Screen
You can manage SP affiliations on this screen.
To reach this screen for editing:
X Click Manage All Affiliations under SP Affiliations on the Main Menu.
To begin creating a new affiliation:
X Click Create Affiliation (see the next sections for more information).
To delete an affiliation:
1. Click Delete under Action for the affiliation you want to delete.
2. Click Save to confirm the deletion (or click undelete).
To view or modify an affiliation:
X Click the affiliation ID.
Administrator’s Manual
191
Chapter 5
Identity Provider SSO Configuration
Importing Affiliation Metadata
An IdP may send a metadata file containing information that automatically
specifies members of an SP affiliation for use in PingFederate.
X If you do not have a metadata file, click Next.
To import metadata:
1. Click Browse to locate and import the file and then click Next.
2. Review the information on the Create Affiliation page (see the next
section).
3. Click Save on the Summary screen.
Entering Affiliation Information
Enter or modify basic information about an affiliation on the Affiliation General
Info screen.
If you imported a metadata file, this information is already supplied. However,
you may change the Affiliation ID or select a different Affiliation Owner, if
required.
Field Descriptions
Field
Description
Affiliation ID
A unique identifier for this affiliation. This value serves
as the Name ID qualifier for SAML assertions sent to
affiliated SP partners.
Affiliation Owner
Any SAML 2.0 SP connection may serve as the
Owner.
Managing Affiliation Membership
On the Affiliation Membership screen, you create and manage a list of SP
connections to be included in the affiliation.
192
PingFederate 6
Defining SP Affiliations
If you imported a metadata file, this information is already supplied. However,
you may add or remove connections from the affiliation.
X To add an SP partner connection to the affiliation, select the connection
from the drop-down list and click Add.
Important: Each connection in the affiliation must be configured to
use the same IdP adapter instance for generating account links
(see “IdP Adapter Mapping” on page 134).
X To remove a member of the affiliation, click Delete under Action for the
connection and click Save.
Note: If you delete an affiliation member supplied by an imported
metadata file and then save the affiliation, that connection will not
appear in the drop-down list for re-adding in the future.
Activating and Editing the Affiliation
From the Affiliation Management Summary screen you can activate or
deactivate an SP affiliation. You also save new affiliations on this screen, or you
can click heading links to go back and modify information.
To change an Affiliation Status:
X Select either Active or Inactive and then click Save.
Important: Be sure to click Save. Otherwise, the status will not be
changed.
To edit a connection:
1. Click the heading above the information you want to modify.
2. Make your change and click Save.
Administrator’s Manual
193
Chapter 5
Identity Provider SSO Configuration
Configuring SP Auto-Connect
When your SP partner is also using PingFederate 5 or higher (or is otherwise able
to provide interoperable SAML 2.0 metadata via HTTP on demand), you may
choose to use Auto-Connect for that partner (see “Using Auto-Connect” on
page 15). This configuration can be shared among an unlimited number of
SAML 2.0 partners.
Note: You enable the SAML 2.0 Auto-Connect profile under System
Settings (see “Choosing Roles and Protocols” on page 64).
Once Auto-Connect is enabled on your PingFederate server, you complete the
configuration from the Main Menu under My IdP Configuration. This
configuration entails:
•
Setting up a common connection for all Auto-Connect partners
•
Establishing a list of SP partner domains authorized to use the connection
Initial Setup
The basic configuration for SP Auto-Connect requires only:
•
Defining a period of validity for assertions (assertion lifetime)
•
Choosing a signing certificate for assertions and other SAML messages
•
Configuring assertion-creation information
All other partner-connection specifications are handled automatically at
runtime.
Setting an Assertion Lifetime
Identity-federation standards require a window of time during which an assertion
is considered valid. Each assertion has a time-stamp XML element as well as
elements indicating the allowable lifetime of the assertion (in minutes) before
and after the assertion time stamp.
194
PingFederate 6
Configuring SP Auto-Connect
Field Descriptions
Field
Description
Minutes Before
The amount of time before the assertion was issued
during which it is to be considered valid.
Minutes After
The amount of time after the assertion was issued
during which it is to be considered valid.
To change the default times:
X (Optional) Edit the desired setting(s) and click Next or Save.
Choosing a Signing Certificate
For Auto-Connect runtime processing, assertions and SLO messages must be
signed, since they are sent over either the POST or redirect bindings (see
“SAML 2.0 Profiles” in the “Supported Standards” chapter of Getting Started).
Note: The signing certificate is embedded in your server’s AutoConnect metadata (see “Using Auto-Connect” on page 15); there is no
need to exchange certificates with your partners.
You can use the same certificate used for signing metadata (see “Configuring
Auto-Connect Metadata Signing” on page 71). If you use a different certificate,
ensure that it meets Auto-Connect validation requirements (see “Auto-Connect
Security Model” on page 17).
Configuring Assertion Creation
Configuring assertion creation for Auto-Connect is similar to configuring the
same settings for regular partner connections.
Administrator’s Manual
195
Chapter 5
Identity Provider SSO Configuration
X Click Configure Assertion Creation to continue.
For configuration information, refer to sections under “Assertion Creation”
on page 129.
Auto-Connect Activation and Summary
When you finish configuring your SP Auto-Connect initial setup, you may
choose to activate the common connection immediately on the Activation &
Summary screen. (No runtime processing occurs until your partner’s AutoConnect gateway is also established and a user initiates an SSO or SLO event.)
Important: Regardless of whether you choose to activate a newly
configured connection now or later, you must click Save on the
Activation & Summary screen if you want to keep the configuration.
You can deactivate the connection at any time (for maintenance, for example).
While a connection is inactive, all SSO or SLO transactions to or from AutoConnect partners are disabled.
To change a Connection Status:
X Select Active or Inactive and then click Save.
To modify a setting:
1. Locate the currently configured setting under one of the summary headings
and then click the subheading above the data.
Note: Changes made to Auto-Connect settings will be out of sync,
temporarily, with metadata caches that any currently active
partners might be using. If your connection is in production, you
might wish to lower your server’s metadata lifetime in advance of
making configuration changes (see “Configuring Auto-Connect
Metadata Lifetime” on page 71).
196
PingFederate 6
Configuring SP Auto-Connect
2. Change the information and click Save, if available.
If Save is not available, additional, dependent changes are required; click
Next or Done until you reach a screen containing a Save button. Then
click Save and continue as needed until you return to the Main Menu.
Specifying Allowed SP Domains
This screen provides PingFederate with a list of trusted domain names of your
Auto-Connect partners.
Normally, when PingFederate receives an authentication request from a domain
in this list, the runtime engine completes the connection automatically using
metadata obtained from a standard, public location— http://
saml.<domain_name>. (See “Using Auto-Connect” on page 15.)
Alternatively, if an Auto-Connect partner elects not to use the standard
location, you can supply the applicable URL.
Administrator’s Manual
197
Chapter 5
Identity Provider SSO Configuration
198
PingFederate 6
Chapter
6
Service Provider
SSO Configuration
In an SP role, you use the PingFederate administrative console to configure local
application-integration information and to manage connections to your IdPpartner sites. You must configure Server Settings from the Main Menu to
establish your site as an SP before configuring connections to IdPs (see
“Choosing Roles and Protocols” on page 64).
Note that you generally configure only one connection per federation partner,
even if you are integrating more than one Web application. You can configure
more than one connection, however, if your partner supports multiple protocols,
or supports multiple federation IDs for the same protocol (see “Federation Server
Identification” on page 20).
Note: This chapter applies to configuration settings needed for secure
Internet SSO (“Browser SSO”). While there is some cross-over
information also applicable to WS-Trust STS, if you are using
PingFederate exclusively as an STS, start with “WS-Trust STS
Configuration” on page 277.
Under some conditions, you can enable SSO for an unlimited number of partners
at once by configuring a single, common connection (see “Using Auto-Connect”
on page 15).
This chapter covers the following major topics:
Administrator’s Manual
•
“Application Integration Settings” on page 200
•
“Federation Settings” on page 208
•
“Managing IdP Connections” on page 212
•
“Configuring IdP Auto-Connect” on page 272
199
Chapter 6
Service Provider SSO Configuration
Application Integration Settings
The integration of local applications with PingFederate is the essential “lastmile” configuration that allows end-users at your IdP partner’s Web site to access
your protected resources. This process is facilitated through the use of
application-integration kits and a robust Software Development Kit (see “SSO
Integration Kits and Adapters” on page 4).
Under Application Integration Settings on the Main Menu, you configure the
SP Adapters that PingFederate uses to create user sessions that allow SSO access
to your protected resources. You can also set Default URLs to which users may be
directed during SSO or SLO, and you can look up system endpoints that
application developers at your site need to access PingFederate’s SSO/SLO
services.
Note: For PingFederate installations that include WS-Trust STS, the
selections under Application Integration Settings also include a link for
configuring plug-in Token Generators (see “WS-Trust STS
Configuration” on page 277).
Configuring SP Adapters
SP adapters are used to create a local-application session for a user in order to
provide SSO access to your application(s) or other protected resources (see “SSO
Integration Kits and Adapters” on page 4). You can configure multiple instances
of adapters (based on one or more adapters) to accommodate the varying needs
of your IdP partners.
Note: If you are configuring either the OpenToken or the LDAP Adapter,
see “Configuring the IdP OpenToken Adapter” on page 331 or
“Configuring the IdP LDAP Adapter” on page 339, respectively.
If you configure more than one adapter instance, then you must map a target
URL to at least one instance (see “Mapping URLs to Adapter Instances” on
page 205).
SP adapter setup is available only if your server is configured as an SP (see
“Choosing Roles and Protocols” on page 64).
Important: If you install a new version of an adapter JAR file after
setting up connections to instances of that adapter, you might need
to reconfigure those connections. To find out, click each connection
that uses the adapter (see “Accessing Connections” on page 212).
Errors indicating reconfiguration points may be presented.
200
PingFederate 6
Application Integration Settings
X You reach this screen by clicking Adapters under Application Integration
Settings in My SP configuration.
To create a new adapter instance:
X Click Create New Instance.
See the next section.
To edit an adapter instance:
X Click the Instance Name link.
To delete an adapter instance:
1. Click Delete next to the Instance Name on the Manage SP Adapter
Instances screen. (To undo the deletion, click Undelete.)
Note: This option is available only if the adapter instance is not in
use for a connection.
2. Click Save to confirm the deletion.
Creating an Adapter Instance
On the Type screen, you begin creating an instance of an adapter that
PingFederate will use for creating security sessions for your applications.
Administrator’s Manual
201
Chapter 6
Service Provider SSO Configuration
Field Descriptions
Field
Description
Instance Name
A descriptive name for the adapter instance—for
example the target application or group of
applications.
Instance ID
An internal identifier for the adapter instance. Must be
alphanumeric with no spaces.
Type
A list of previously deployed session creation adapter
types that are available to create an adapter instance
for the server. You can configure any number of
instances for a server acting as an SP.
To reach this screen:
1. Click Adapters on the Main Menu.
2. Click Create New Instance on the Manage SP Adapter Instances screen.
To define an adapter instance:
1. Enter the Instance Name and Instance Id on the Type screen.
2. Select the Type from the drop-down menu.
If the adapter you need is not listed, click Visit PingIdentity.com for
additional types to see if a suitable adapter is available from the
PingFederate download site. You can also create your own adapter (see “SSO
Integration Kits and Adapters” on page 4).
202
PingFederate 6
Application Integration Settings
3. Click Next and enter information on subsequent screens for this adapter
setup, as indicated in the following sections.
Tip: The setup steps and information needed vary with the
adapters deployed on your server (see “SSO Integration Kits and
Adapters” on page 4). For information about configuring the
adapters packaged with PingFederate, see “OpenToken Adapter
Configuration” on page 329 or “LDAP Adapter Configuration” on
page 337.
4. Click Done on the Summary screen.
5. Click Save on the Manage SP Adapter Instances screen.
To view or modify adapter settings:
X Click the Instance Name.
To delete an adapter instance:
1. Click Delete next to the Instance Name on the Manage Adapter Instances
screen. (To undo the deletion, click Undelete.)
Note: This option is available only if the adapter instance is not in
use for any connection.
2. Click Save to confirm the deletion.
Configuring an Adapter Instance
Configuration parameters on the SP Adapter Instance screen vary according to
the adapter you choose. These options are controlled by the adapter software (see
“SSO Integration Kits and Adapters” on page 4).
X For information about configuring the OpenToken Adapter, see
“Configuring the SP OpenToken Adapter” on page 334.
X For information about configuring the LDAP Authentication Service, see
“Configuring the SP LDAP Adapter” on page 342.
Invoking Adapter Actions
Adapters can be written to perform configuration assistance or validation
actions—for example, testing a connection to an active directory. Actions may
also include generation of parameters that might need to be set manually in a
configuration file.
X For information about actions available using the OpenToken Adapter, see
“OpenToken Adapter Configuration” on page 329.
X For information about actions available using the LDAP Authentication
Service, see “LDAP Adapter Configuration” on page 337.
Administrator’s Manual
203
Chapter 6
Service Provider SSO Configuration
To reach this screen for editing:
1. On the Main Menu under Application Integration Settings for My SP
Configuration, click Adapters.
2. Click an Instance Name.
3. Click Actions (if available).
To generate a properties list:
X Click Download under Action Invocation Link.
Extending an Adapter Contract
Adapters may be written with an option allowing administrators to add to the
attributes required for creating usable sessions. This feature might be needed, for
example, by a legacy application that requires different authentication than
other applications under the same enterprise identity-management system.
To reach this screen for editing:
1. On the Main Menu under Application Integration Settings for My SP
Configuration, click Adapters.
2. Click an Instance Name.
3. Click Extended Contract (if available).
204
PingFederate 6
Application Integration Settings
To add an attribute:
1. Enter the attribute name in the text box and click Add.
2. Click Done then click Save on the Manage SP Adapter Instances page.
Editing and Saving SP Adapter Instances
From the Adapter Instance Summary screen, you can reach adapter settings for
editing.
To edit the configuration:
1. Click the heading above the information you want to change.
2. Click Save on the configuration page and on the Manage SP Adapter
Instances screen.
To save an adapter instance:
1. Click Done on the Summary screen.
2. Click Save on the Manage SP Adapter Instances screen.
Note: If this is the second adapter instance you have configured,
then Save is not yet available; you must choose whether to map
the new adapter instance to an application or resource URL. In this
case, click Next to continue (see “Mapping URLs to Adapter
Instances” next).
Mapping URLs to Adapter Instances
When you configure more than one SP adapter instance, you must map target
URLs to at least one adapter instance. Mapping enables you to direct inbound
SAML messages to the appropriate application.
For example, this mapping configuration may be necessary in an IdP-initiated
SSO scenario that connects to multiple applications at your site. For transactions
initiated at your site, this mapping is needed for default situations, in cases where
the target and adapter instance are not specified when the SSO/SLO is started
(see “SP Endpoints” on page 351). (When this information is provided with the
SP request, the mapping table is ignored.)
This screen is available only if your server is configured as an SP and if you are
using more than one adapter instance, or if you have previously mapped an
adapter instance on this screen.
Administrator’s Manual
205
Chapter 6
Service Provider SSO Configuration
Field Descriptions
Field
Description
URL
The target URLs that align with your configured
adapter instances. The URLs instruct the PingFederate
SP server to route session-creation processing
through an adapter instance. If the URL in the
incoming request is not matched by the first entry in
this table, subsequent entries are tried until a match is
found.
Adapter Instance
(drop-down menu)
A selection of configured SP adapter instances.
The order of mapping is significant in that the first matching mapping, from top
to bottom, determines which adapter instance receives the SAML message. For
example, if two URLs are mapped in the following order:
a. http://yourapp.com/subapp/* Adapter 1
b. http://yourapp.com/* Adapter 2
The URL http://yourapp.com/subapp/start will map to Adapter 1
because it matches mapping a. If the order of the mappings were reversed,
http://yourapp.com/subapp/start would map to Adapter 2 because it
it would find and match mapping b first. (No URLs would fall through if the
order were reversed.)
Note that you can use only one wildcard (*) per URL.
To reach this screen for editing:
1. On the Main Menu under Application Integration Settings for My SP
Configuration, click Adapters.
2. Click Map URLs to Adapter Instances.
If this step does not appear, then you have created only one adapter instance
(see “Configuring SP Adapters” on page 200).
206
PingFederate 6
Application Integration Settings
To create adapter mappings:
1. Enter the URL and select an adapter from the drop-down menu.
2. Click Add Mapping.
3. Click Save.
To edit adapter mappings:
1. Click Edit next to the Adapter Instance. You can change the URL or select
a different adapter from the drop-down menu.
2. Click Update.
3. Click Save.
To delete adapter mappings:
1. Click Delete next to the Adapter Instance.
2. Click Save.
(Click Cancel to abort the deletion.)
To change the order of adapter mappings:
1. Click the up or down arrows at the left to rearrange the order.
2. Click Save.
Configuring Default URLs
As an SP, you can supply a default URL that the end-user may see when SSO
succeeds (that is, a session is created at your site) but the target resource is not
available or not specified. Similarly, you can specify a default URL indicating a
successful SLO to the end-user (if no other page is designated).
Your application or your partner’s application may supply these URLs at runtime
(see “SP Endpoints” on page 351); but if none is provided, PingFederate will use
the default values you enter on this screen.
Tip: If you leave the default URLs blank, PingFederate provides built-in
landing pages for the user. These Web pages are among the templates
you can modify with your own branding or other information (see
“Customizing User-Facing Screens” on page 50).
Administrator’s Manual
207
Chapter 6
Service Provider SSO Configuration
Viewing Application Endpoints
Click Application Endpoints on the Main Menu to see a list of endpoints and
descriptions applicable to your federation role (IdP or SP). These endpoints are
built into PingFederate and cannot be changed.
Web-application developers at your site need to know the application endpoints
to initiate transactions via PingFederate (see “SSO Integration Kits and
Adapters” on page 4).
Note: For specific parameters required or allowed for Application
Endpoints, see “SP Endpoints” on page 351.
This screen also shows a Maintenance Endpoint that you can use to verify that
the PingFederate server is running (see “Maintenance Endpoint” on page 356).
Federation Settings
If your identity federation uses the SAML 2.0 XASP profile (see “Attribute
Query and XASP” in the “Supported Standards” chapter of Getting Started), you
may need to identify the IdP connection to which an attribute request applies. If
so, click Attribute Requester Mapping under the Federation Settings section
for the SP on the Main Menu.
Also under Federation Settings, you can view protocol endpoints that your
federation partners need to know to access your services via PingFederate.
Attribute Requester Mapping
If you are using the XASP profile, the application(s) at your site must supply the
Subject Distinguished Name (DN) to identify a user’s X.509 authentication
certificate (see “Attribute Query and XASP” in the “Supported Standards”
chapter of Getting Started). Optionally, an application may also supply an Issuer
208
PingFederate 6
Federation Settings
DN, which can be used to determine the correct IdP (Attribute Authority) to
use for a set of users associated with an IdP.
Note: A Format query parameter must be set to a specified value for
XASP (see “/sp/startAttributeQuery.ping” on page 355).
On the Attribute Requester Mapping screen, you can map X.509 identifying
information to connections and specify a default connection. You reach this
screen from the Main Menu under Federation Settings.
Note: The Attribute Requester Mapping link does not appear on the
Main Menu unless you have enabled the SAML 2.0 protocol for the SP
role (see “Choosing Roles and Protocols” on page 64). You must also
select the associated XASP checkbox.
At runtime, PingFederate tries to match the certificate’s Issuer DN (if provided)
against the list of Issuer DN(s), in the order shown on this screen, until a match
is found. If no match is found, the server tries the Subject DN(s) in order. If no
match is found, the Default connection is used.
Administrator’s Manual
209
Chapter 6
Service Provider SSO Configuration
For Issuer and Subject DNs, you can use a regular expression to match different
DNs to the same connection. Only one expression may be used in any single
entry. DN values must be entered in all lower-case characters.
To map attribute requesters to connections:
1. (Optional) Enter an Issuer DN when applicable, select a SAML 2.0 IdP
Connection Name, and click Add.
Repeat this step as needed for additional DNs.
2. Enter an Subject DN, select a SAML 2.0 IdP Connection Name, and click
Add.
Repeat this step as needed for additional DNs.
3. Select a Default IdP connection.
To edit a mapping:
1. Click Edit for the mapping in the Action column.
2. Make your changes and click Update in the Action column.
3. If you are editing an existing configuration, click Save to confirm the
change.
To reorder the mapping list:
X Click the up or down arrow next to a DN.
To delete a mapping:
1. Click Delete for the mapping in the Action column.
2. If you are editing an existing configuration, click Save to confirm the
deletion.
Viewing Protocol Endpoints
Click Protocol Endpoints under Federation Settings in the SP Configuration
section of the Main Menu to see a list of SAML, WS-Federation, and/or WSTrust STS endpoints—a pop-up window displays only those endpoints related to
the federation protocols you have chosen (see “Choosing Roles and Protocols”
on page 64). These endpoints are built into PingFederate and cannot be
changed.
Your federation partners or STS clients need to know the applicable SP Services
endpoints to communicate with your PingFederate server. Configured service
endpoints for SAML connections are included in metadata export files (see
“Exporting Metadata” on page 30).
210
PingFederate 6
Federation Settings
The table below describes each endpoint:
Table 11: PingFederate SP Endpoints
Service
URL and Description
Single Logout Service (SAML
2.0)
/sp/SLO.saml2
Assertion Consumer Service
(SAML 2.0)
/sp/ACS.saml2
Artifact Resolution Service
(SAML 2.0)
/sp/ARS.ssaml2
Metadata Service
/
The URL that receives and processes logout
requests and responses.
A SAML 2.0 implementation that receives
and processes assertions from an IdP. The
numbers reflect the index value
PingFederate uses to handle each binding.
The SOAP endpoint that processes artifacts
returned from a federation partner to
retrieve the referenced XML message on
the back channel.
The default endpoint (empty path) from
which partners can retrieve Auto-Connect
metadata (see “Using Auto-Connect” on
page 15).
Assertion Consumer Service
(SAML 1.x)
/sp/acs.saml1
Single Sign-on Service (WSFederation)
/sp/prp.wsf
WS-Trust STS
/sp/sts.wst
A SAML 1.x implementation URL that
receives and processes assertions from an
IdP.
The WS-Federation implementation URL
that receives and processes security tokens
and SLO messages.
The SOAP endpoint that receives and
processes security-token requests from STS
clients (Web Service Providers at the SP
site).
Administrator’s Manual
211
Chapter 6
Service Provider SSO Configuration
Managing IdP Connections
As an SP, you manage connection settings to support the exchange of
federation-protocol messages (SAML, WS-Federation, or WS-Trust) with an IdP
or STS client application at your site.
Note: If you are configuring a new connection only for WS-Trust STS,
follow the sections in this part of the manual up to and including
“General Information” on page 218. Then turn to “WS-Trust STS
Configuration” on page 277.
These settings include:
•
User attributes you expect to receive in an SSO assertion (including STS
SAML tokens).
•
User attributes that may be requested using the Attribute Query profile (if
that profile is used).
•
The protocol and, for SAML, the profile you will use, including detailed
security specifications (the use of digital signatures, signature verification,
XML encryption, and SSL). For more information see the “Supported
Standards” chapter in Getting Started.
To continue with the configuration, you and your connection partner must have
decided this information in advance (see “Federation Planning Checklist” on
page 20). Your federation partner must supply some connection settings and
other information (see “Configuration Data Exchange” on page 22).
Tip: If you are configuring connections to more than one partner under
SAML 2.0 specifications, or if you intend to add partners in the future,
consider using Auto-Connect (see “Configuring IdP Auto-Connect” on
page 272).
As an SP, you respond to user requests for SSO and SLO by creating or closing
user sessions, respectively, in local applications. You integrate these applications
with PingFederate by configuring them with SP adapter instances (see
“Configuring SP Adapters” on page 200). In preparation for configuring a new
SSO connection, you will need to know which adapter instance to use (see
“Configuring Adapter Mapping and User Lookup” on page 230). (No adapters
are required for a connection that uses only the Attribute Query profile—see
“Configuring the Attribute Query Profile” on page 260.)
If you intend to pass attribute values to an adapter instance from a local data
store, you must define the data store during this configuration, if you have not
done so already (see “Managing Data Stores” on page 72).
Accessing Connections
You can create or modify connections directly via the Main Menu. Note that the
menu displays the four most-recently modified connections. To view a list of all
IdP connections, click the Manage All IdP link.
212
PingFederate 6
Managing IdP Connections
Using the Main Menu
From the Main Menu, you can configure a new connection, modify an existing
connection, or view connections.
Tip: To copy or delete connections or to find connection drafts, click
Manage All IdP (see “Using the Manage Connections Screen” on
page 214).
Note that long connection names are truncated for this display. The full
connection names are displayed on the Manage Connections screen (see “Using
the Manage Connections Screen” on page 214).
To begin configuring a new connection:
X Click Create New under IdP Connections on the Main Menu.
Tip: If you want to use a virtual ID for a second connection to the same
partner, the fastest way is to click Manage All IdP and copy the first
connection (see “Using the Manage Connections Screen” on
page 214). For information about virtual IDs, see “Federation Server
Identification” on page 20.
To modify a connection:
1. Click the connection name under IdP Connections on the Main Menu.
Only the four most recently edited connections are displayed. To see all
connections, including drafts, click Manage All IdP.
2. On the Activation & Summary screen, click the heading for the information
you want to change.
Administrator’s Manual
213
Chapter 6
Service Provider SSO Configuration
3. Make your change and click Save.
Note: If Save is not available, it means your modification requires
other changes or you are editing a screen that is part of a series of
subtasks. Click Next and continue making indicated changes. The
Done button indicates that further changes in the task are optional.
When you have no further changes, click Done and then click Save
on the task summary screen.
Using the Manage Connections Screen
From the Manage Connections screen, you can configure a new connection,
modify or copy an existing connection or draft, or delete a connection (if it is not
active). An export function is also provided, which allows you save individual
connections.
S
Note: The connection export function results in an XML file that you
can modify and import into another PingFederate server acting in the
same federation role (IdP or SP) at your site (see “Connection
Management Service” on page 357).
From this screen, you can also globally override transaction logging levels set for
individual connections or restore connection-based logging (see “Runtime
Transaction Logging” on page 29).
To access the Manage Connections screen:
X Click Manage All IdP under IDP Connections on the Main Menu.
214
PingFederate 6
Managing IdP Connections
To begin configuring a new connection:
X Click Create Connection on the Manage Connections screen.
See “Managing IdP Connections” on page 212 for step-by-step information.
Tip: If you need to create a second connection to a partner using a
Virtual ID, copy the existing connection and make necessary changes,
including adding the Virtual ID on the General Info screen. For
information about Virtual IDs, see “Federation Server Identification” on
page 20.
To copy a connection:
1. Click Copy under Action for the connection you want to copy.
2. Enter new General Information for the connection (see “General
Information” on page 218).
3. Make any further changes needed for the new connection.
To edit a connection or continue working on a draft:
X Click the Connection Name link.
For a draft, you will return to where you left off.
To export a connection:
1. Click Export under Action for the connection.
2. Save the XML file on your file system.
You can change the name of the file, but keep the XML extension.
Tip: You can import the connection programmatically or manually
into another instance of PingFederate acting in the same role (see
“Connection Management Service” on page 357).
To delete a connection:
1. Under Action, click Delete for the connection.
(To undo the deletion, click Undelete.)
Note: The Delete function is not available if the connection is
active.
2. To confirm the deletion, click Save.
To sort the list of connections:
X Click the arrow next to any column heading to sort the list based on that
column.
To filter the list by Protocol and/or Status:
X Select a filter criterion from either or both of the drop-down lists.
Administrator’s Manual
215
Chapter 6
Service Provider SSO Configuration
To override connection-based transaction logging:
1. Select On under Logging Mode Override.
2. Choose the logging mode you want to use for all connections.
To restore connection-based transaction logging:
X Select Off under Logging Mode Override.
Choosing a Connection Type
Indicate on the Connection Type screen whether the connection to this partner
is for Browser SSO, WS-Trust STS, or both (see “Connection Types” on page 1).
Note: You can add STS support to any existing SSO connection, or vice
versa, at any time.
If your federation deployment supports multiple protocols, then for new SSO
connections you can also select the applicable protocol on the Connection Type
screen (see “Choosing Roles and Protocols” on page 64).
Note: If your partner’s deployment also supports multiple protocols and
you intend to communicate using more than one, then you must set up
a separate connection for each protocol.
X To configure a connection for secure Internet SSO, select Browser SSO
Profiles and the Protocol (if necessary).
X To configure a connection for WS-Trust STS, make that selection.
X (Optional) If your PingFederate license manages connections by groups,
then you can select a group for this connection.
This option is not displayed for unrestricted or other types of licenses.
216
PingFederate 6
Managing IdP Connections
Choosing Connection Options
On the Connection Options screen, you can choose to enable User Provisioning
in conjunction with Browser SSO (see “Express Provisioning” on page 19).
Note: This screen is presented only for browser-based SSO
connections (see “Choosing a Connection Type” on page 216).
For SAML 2.0, you also have the option of configuring the Attribute Query
profile, with or without SSO (see “Attribute Query and XASP” in the
“Supported Standards” chapter of Getting Started).
X To create a connection for secure Internet SSO, ensure that Browser SSO is
selected and click Next.
Importing Metadata
If you are using one of the SAML protocols and have received a metadata file
from your partner, click Browse on the Import Metadata screen, select the file,
and click Next. For more information, see “Metadata” in the “Supported
Standards” chapter of Getting Started.
Note: If the endpoints in the metadata file share the same base URL
(protocol, hostname, and port), PingFederate uses this information to
populate the Base URL field (see “General Information” on page 218).
Consequently, individual endpoints on other screens do not include this
information—only relative paths are shown.
Note: If you are importing a signed metadata file that does not include
the certificate and public key, you will be asked to import the certificate
needed to verify the XML signature (see the next section).
If you are not using a metadata file, click Next on the Import Metadata screen.
Administrator’s Manual
217
Chapter 6
Service Provider SSO Configuration
Importing a Verification Certificate
The Import Certificate screen appears only if the metadata file you have chosen
to import is signed and the certificate needed to verify the signature is not
contained in the file.
X Click Browse to locate and open the signature verification certificate for
this partner.
Viewing the Metadata Summary
The Metadata Summary screen provides security information about an
imported metadata file, including whether the file was signed and, if so, the trust
status of the certificate used to verify the signature.
General Information
On the General Info screen, you provide a required unique identifier and display
name for a connection, as well as optional contact information. In addition, on
this screen you can define a default error message that end users will see in the
event that SSO fails, and you can set the level of transaction logging for this
connection partner (see “Runtime Transaction Logging” on page 29).
218
PingFederate 6
Managing IdP Connections
Field Descriptions
Field
Description
Partner’s Entity ID/
Issuer/
Partner’s Realm
(Connection ID)
(Required) The published, protocol-dependent,
unique identifier of your partner. For a SAML 2.0
connection, this is your partner’s SAML Entity ID.
For a SAML 1.x connection, this is the Issuer your
partner advertises. For a WS-Federation connection,
this is your partner's Realm. This ID may have been
obtained out-of-band or via a metadata file if you are
using a SAML protocol (see “Exporting Metadata”
on page 30).
For STS-only connections, this ID can be any unique
identifier.
Administrator’s Manual
219
Chapter 6
Service Provider SSO Configuration
Field
Description
Connection Name
(Required) A plain-language identifier for the
connection—for example, a company or
department name. This name is displayed in the
connection list on the Main Menu.
Virtual Server ID
Enter a unique server ID in this field if you want to
identify your server to this connection partner using
an ID other than the one you specified under Server
Settings (see “Specifying Federation Information”
on page 67).
For information about Virtual Server IDs, see
“Federation Server Identification” on page 20.
Base URL
The fully qualified hostname and port on which your
partner’s federation deployment runs (e.g.,
https://www.pingidentity.com:9031). This
entry is an optional convenience, allowing you to
enter relative paths to specific endpoints, instead of
full URLs, during the configuration process.
Company
The name of the partner company to which you are
connecting.
Contact Name
The contact person at the partner company.
Contact Number
The phone number of the contact person at the
partner company.
Contact Email
The email address for the contact person at the
partner company.
Error Message
When an error occurs during an SSO operation on
this server, the end user's browser is redirected to
an error page hosted within . The text you enter
here is shown on that page and is intended to help
the user understand what he/she should do next.
Logging Mode
The level of transaction logging applicable for this
connection (see “Runtime Transaction Logging” on
page 29). Note that you can override connection
logging mode settings globally from the
connections list (see “Using the Manage
Connections Screen” on page 214).
For a new connection:
X Fill in the information needed and click Next.
Connection ID and Connection Name are required (see “Field Descriptions”
above).
Note that the Virtual ID identifies your own federation deployment for this
connection only and overrides the ID you specified under Server Settings
(see “Federation Server Identification” on page 20).
220
PingFederate 6
Managing IdP Connections
For an existing connection:
X If you are editing existing information, modify the fields as needed and click
Save.
Configuring Browser-Based SSO
Browser-based SSO (also, Browser SSO) is another term for secure Internet
SSO, which relies on a user’s Web browser and HTTP to broker XML identityfederation messaging between an IdP and an SP (in contrast to WS-Trust STS
messaging, which is typically application-driven across the back channel and
does not require browser mediation).
X To continue, click Configure Browser SSO.
Configuration Steps
Many steps involved in setting up a federation connection are protocolindependent; that is, they are required steps for all connections, regardless of the
associated standards (see the “Supported Standards” chapter in Getting Started).
Also, for any given connection, some configuration steps are required under the
applicable protocol, while others are optional. Still others are required only
based on certain selections. The PingFederate administrative console determines
the required and optional steps based on the protocol and dynamically presents
additional requirements or options based on selections.
The following sections provides sequential information about every step you
might encounter while configuring browser-based SSO, regardless of the protocol
you are using for a particular connection.
Note: The configuration screens represented in this chapter show
“SAML 2.0” in their left corners, unless they are exclusive to WSFederation or SAML 1.x setup requirements. When the SAML 2.0
screens are also applicable to SAML 1.x and/or WS-Federation
connections, the SAML 2.0 representations and discussions also apply
to the other protocols, unless otherwise indicated.
Administrator’s Manual
221
Chapter 6
Service Provider SSO Configuration
After configuring SSO settings, you will normally need to configure
authentication credentials, the range of which depends on your SSO selections
(see “Configuring Credentials” on page 263). Also, other configuration tasks
may remain to be configured for new or modified connections, depending on
selected connection options (see “Choosing Connection Options” on page 217).
Important: For new connections you must completely configure
these SSO settings and subsequent tasks before you can save the
connection on the Activation & Summary screen. Until then, the
configuration is temporary and can be lost; the console times out after
several minutes of inactivity. At any time, however, you can click Save
Draft, which is available on most screens after you enter General
Information (see “Console Buttons” in the “Console Navigation”
chapter of Getting Started).
Use the lists and links (or page references) below to find specific information
about steps that may apply to your SSO connection requirements:
SAML 2.0 SSO Configuration Steps
•
“Choosing SAML Profiles” on page 223
•
“User-Session Creation” on page 226
•
–
“Selecting an Identity-Mapping Method” on page 226
–
“Creating an Attribute Contract” on page 228
–
“Configuring Adapter Mapping and User Lookup” on page 230
“Configuring Protocol Settings” on page 244
–
“Specifying SSO Service URLs (SAML)” on page 245
–
“Specifying SLO Service URLs (SAML 2.0)” on page 247
–
“Choosing Allowable SAML Bindings (SAML)” on page 248
–
“Setting an Artifact Lifetime (SAML 2.0)” on page 249
–
“Specifying Artifact Resolver Locations” on page 249
–
“Configuring Signature Policy” on page 251
–
“Configuring XML Encryption Policy (SAML 2.0)” on page 252
WS-Federation SSO Configuration Steps
•
•
“User-Session Creation” on page 226
–
“Selecting an Identity-Mapping Method” on page 226
–
“Creating an Attribute Contract” on page 228
–
“Configuring Adapter Mapping and User Lookup” on page 230
“Configuring Protocol Settings” on page 244
–
“Specifying a Service URL (WS-Federation)” on page 246
SAML 1.x SSO Configuration Steps
•
222
“Choosing SAML Profiles” on page 223
PingFederate 6
Managing IdP Connections
•
•
“User-Session Creation” on page 226
–
“Selecting an Identity-Mapping Method” on page 226
–
“Creating an Attribute Contract” on page 228
–
“Configuring Adapter Mapping and User Lookup” on page 230
“Configuring Protocol Settings” on page 244
–
“Specifying SSO Service URLs (SAML)” on page 245
–
“Choosing Allowable SAML Bindings (SAML)” on page 248
–
“Specifying Artifact Resolver Locations” on page 249
–
“Configuring Signature Policy” on page 251
Choosing SAML Profiles
A SAML profile is the message-interchange scenario that you and your
federation partner have agreed to use (see “Federation Planning Checklist” on
page 20). For SAML 2.0, PingFederate supports all IdP- and SP-initiated SSO
and SLO profiles.
The SAML 1.x implementation supports standard IdP-initiated SSO as well as
nonstandard SP-initiated SSO.
For information on typical SSO/SLO profile configurations, including
illustrations, see the “Profiles” sections in the “Supported Standards” chapter in
Getting Started.
You can configure profiles individually or all together. PingFederate presents the
correct configuration steps to fit your choices. Steps that apply to one SSO or
SLO profile often apply to others and are reused automatically across profiles.
Note: For SAML 1.x, IdP-initiated SSO is assumed and the
specifications do not support SLO; the only choice on this screen is SPinitiated SSO (see “SAML 1.x Profiles” in the “Supported Standards”
chapter of Getting Started).
For WS-Federation, the SAML Profiles screen is not presented.
Administrator’s Manual
223
Chapter 6
Service Provider SSO Configuration
To reach this screen:
1. Click a connection name on the Main Menu.
Click Manage All IdP, if needed, to see a full list of connections.
2. Click Browser SSO under the IdP Connection tab.
3. Click SAML Profiles on the Summary screen.
To configure profiles:
1. Select the profile(s) applicable to this connection and click Next.
For SAML 2.0 connections, you must select an SSO profile before you can
enable SLO.
2. Continue through the remaining connection-configuration tasks.
Configuring IdP-Initiated SSO
When PingFederate is operating as an SP, the IdP-initiated SSO profile
configuration defines the message-transport mechanisms (bindings) your
enterprise has agreed to allow for receiving SAML assertions, plus any digital
signature verification requirements for inbound assertions (see “Certificates,
SSL, and XML Encryption” on page 10).
For this configuration you need to know:
•
The transport binding(s) to which you and your partner have agreed
•
The certificate to be used for verifying incoming digital signatures from your
IdP (optional for the artifact binding)
When Artifact is an allowable inbound SAML binding, you also need to know
the endpoint(s) to your partner’s Artifact Resolution Service(s) and the SOAP
client authentication mechanism to use: either HTTP Basic, SSL client
certificates, a digital signature, or a combination of these mechanisms.
Configuring SP-Initiated SSO
The SP-initiated SSO profile configuration defines the message-transport
mechanisms (bindings) and security requirements for sending authentication
requests and receiving assertions when your site initiates SSO transactions.
For SAML 1.x, the SP-initiated SSO profile is also known as the “destinationfirst” profile, which was added as a supported “non-normative” use case after the
release of the SAML 2.0 specifications.
For this configuration you will need to know:
•
The endpoint URL(s) for your IdP’s Single Sign-on Service(s)
•
The transport bindings to which you and your partner have agreed (inbound
and outbound)
•
The certificates you will use to sign outbound authentication requests and to
verify incoming digital signatures from your IdP
When Artifact is an allowable inbound SAML binding, you also need to know
the endpoint(s) to your partner’s Artifact Resolution Service(s) and the SOAP
224
PingFederate 6
Managing IdP Connections
client authentication mechanism to use: either HTTP Basic, SSL client
certificates, a digital signature, or a combination of these mechanisms.
Configuring IdP-Initiated SLO
The SAML 2.0 IdP-initiated SLO profile configuration defines the messagetransport mechanisms (bindings) and security requirements that you and your
partner have agreed upon for exchanging SLO requests and responses.
Note: SLO is not supported by the SAML 1.x specifications.
For more information about SLO, see “Single Logout” in the “Supported
Standards” chapter of Getting Started.
For this configuration you need to know:
•
The transport bindings that you and your partner have agreed upon to send
SLO requests and receive responses
•
The certificates to be used for signing outgoing messages and for verifying
incoming digital signatures from your IdP (optional for the artifact binding)
•
The URL(s) of your IdP’s Single Logout Service(s)
•
The URL of your IdP’s Artifact Resolution Service(s) (to resolve artifacts
from the IdP) and SOAP client authentication requirements
Configuring SP-Initiated SLO
The SAML 2.0 SP-initiated profile configuration for SLO defines the messagetransport mechanisms (bindings) and security requirements that you and your
partner have agreed upon for exchanging SAML requests and responses.
Note: SLO is not supported by the SAML 1.x specifications.
For more information about SLO, see “Single Logout” in the “Supported
Standards” chapter of Getting Started.
For this configuration you need to know:
Administrator’s Manual
•
The transport bindings that you and your partner have agreed upon to send
SLO requests and receive responses
•
The certificates to be used for signing outgoing messages and for verifying
incoming digital signatures from your IdP (optional for the artifact binding)
•
The URL(s) of your IdP’s Single Logout Service(s)
•
The URL of your IdP’s Artifact Resolution Service(s) (to resolve artifacts
from the IdP) and SOAP client authentication requirements
225
Chapter 6
Service Provider SSO Configuration
User-Session Creation
As an SP, you must specify how you will use information sent from the IdP in
SSO assertions to create user sessions for enabling access to protected resources
at your site. This configuration includes:
•
•
Choosing an identity-mapping method (see “Selecting an Identity-Mapping
Method” next).
Defining the attribute contract you will use with this partner, if any (see
“Creating an Attribute Contract” on page 228).
•
Configuring instances of one or more adapters (see “Configuring Adapter
Mapping and User Lookup” on page 230) and specifying how they are used
to fulfill the adapter contract.
X To continue, click Configure User-Session Creation.
Selecting an Identity-Mapping Method
PingFederate allows an SP to use either account linking or account mapping to
associate remote users with local accounts for SSO between business partners
(see “Identity Mapping” on page 5). At the Identity Mapping step, you choose
which method to use with a particular IdP connection. You and your partner may
want to decide in advance which option to use (see “Federation Planning
Checklist” on page 20).
226
PingFederate 6
Managing IdP Connections
If your site is using account linking, then establishing an attribute contract is not
required. Depending on your partner agreement, however, you may choose to
supplement the account link with an attribute contract. In this configuration the
account link is used to determine the user’s identity, while the additional
attributes might be used for authorization decisions, customized Web pages, and
so on, at your site (see “About Attributes” on page 7).
Important: If you have previously set up a configuration to use an
attribute contract and want to change the configuration to use account
linking without additional attributes, then the existing attribute
contract will be discarded.
Account linking can be used with either a clear, standard name identifier or an
opaque pseudonym.
X If you want to dynamically associate remote users with local accounts using a
known attribute to identify a user—for example, a username or email
address—then select Account Mapping.
Account mapping uses the value passed in the SAML assertion's
SAML_SUBJECT and associated user attributes to create an association
between a remote user and a local account.
Tip: if you are using PingFederate’s Express Provisioning, choose
Account Mapping (see “User Provisioning” on page 254).
Administrator’s Manual
227
Chapter 6
Service Provider SSO Configuration
X If you want to create a long-term association between a remote user and a
local account, then select Account Linking on the Identity Mapping
screen.
To set up an attribute contract to use in conjunction with account linking,
click the checkbox next to “The assertion includes attributes . . .” after
selecting Account Linking.
To reach this screen for editing:
1. Click the connection name on the Main Menu.
Click Manage All IdP, if needed, to see a full list of connections.
2. Click Browser SSO under the IdP Connection tab.
3. Click Configure Browser SSO.
4. Click User-Session Creation under the Browser SSO tab.
5. Click Configure User-Session Creation
6. Click Identity Mapping on the Summary screen.
Creating an Attribute Contract
An attribute contract is the set of user attributes that you and your partner have
agreed will be sent in SAML assertions for this connection (see “Attribute
Contracts” on page 7). You identify these attributes on this screen.
SAML_SUBJECT is always sent in a SAML assertion and contains the name
identifier of the user requesting SSO. When you select account mapping as the
identity mapping technique, the SAML_SUBJECT is available to help map the
incoming user to a local ID on your system (see “Selecting an Identity-Mapping
Method” on page 226).
For account linking, the SAML_SUBJECT contains an identifier that the SP
server uses to make a permanent association between the remote user and a local
account. The SAML_SUBJECT itself is not available to the SP application and
thus does not appear in the Attribute Contract on this screen.
Optionally, you can mask the values of attributes (other than SAML_SUBJECT)
in the log files that PingFederate writes when it receives assertions (see
“Attribute Masking” on page 10).
228
PingFederate 6
Managing IdP Connections
To reach this screen for editing:
1. Click the connection name on the Main Menu.
Click Manage All IdP, if needed, to see a full list of connections.
2. Click Browser SSO under the IdP Connection tab.
3. Click Configure Browser SSO.
4. Click User-Session Creation under the Browser SSO tab.
5. Click Configure User-Session Creation
6. Click Attribute Contract on the Summary screen.
If this step is not in the list, then you have chosen to use account linking and
specified that the IdP is not including additional attributes in the assertion
(see “Selecting an Identity-Mapping Method” on page 226).
To add an attribute:
1. Enter the attribute name in the text box.
Attribute names are case-sensitive and must correspond to the names
configured by your federation partner.
2. Optionally, select the checkbox under Mask Values in Log.
3. Click Add.
To modify an attribute name or masking status:
1. Click Edit under Action for the Attribute name.
2. Edit the name and/or change the masking status, and then click Update.
Note: If you change your mind, ensure that you click the Cancel
link in the Actions column, not the Cancel button, which discards
any other changes you might have made in the configuration steps.
Administrator’s Manual
229
Chapter 6
Service Provider SSO Configuration
To delete an attribute:
X Click Delete for the Attribute Name.
Configuring Adapter Mapping and User Lookup
Remote users arriving at your site via an SSO request do so in order to use
specific applications or gain access to protected resources. Based on the nature of
the business relationship and the agreement with your partner, you may be
expected to provide access to these applications. Therefore, integration between
your federation SP server and local applications is important.
The PingFederate server for an SP uses integration adapters to identify the user
to your applications based on attributes sent in an assertion. The server uses this
information to create a local session that enables access to user-requested
resources (the “target”) at your site. (See “SSO Integration Kits and Adapters”
on page 4.)
Each adapter instance requires a set of attributes into which you map values
found in the assertion. You can map additional attributes, as needed, from local
data stores, or you can use static or variable text values. An adapter instance will
fail to create a local session for the incoming user if it is unable to find values for
each of its required attributes.
You must associate at least one adapter instance with an IdP connection. If you
have multiple integration requirements—for example, if you are using more than
one IdM system or an application not covered by a centralized system—then you
should map multiple adapter instances.
Note: If you configure only one adapter instance for a connection, the
server will use that instance at runtime without checking for any
associated URLs (see “Mapping URLs to Adapter Instances” on
page 205).
230
PingFederate 6
Managing IdP Connections
To reach this screen for editing:
1. Click the connection name on the Main Menu.
Click Manage All IdP, if needed, to see a full list of connections.
2. Click Browser SSO under the IdP Connection tab.
3. Click Configure Browser SSO.
4. Click User-Session Creation under the Browser SSO tab.
5. Click Configure User-Session Creation
6. Click Adapter Mapping & User Lookup on the Summary screen.
To begin mapping an adapter:
X Click Map New Adapter Instance and follow the configuration screens
(see the following sections for more information).
To begin modifying an existing adapter mapping:
X Click the Adapter Instance Name and navigate through the steps to the
information you want to change.
Selecting an Adapter Instance
An SP adapter instance is available for use within an IdP connection only after it
has been deployed in PingFederate.
To select an adapter instance:
X Choose an adapter instance from the drop-down menu and click Next to
continue.
If the adapter instance you need is not available, click Manage Adapter
Instances to define one or more adapter instances you need for this
connection.
Note that an adapter instance can be mapped only once per connection.
Tip: Adapter contracts for some adapters can be customized for
individual connection requirements (see “Configuring SP Adapters”
on page 200).
Administrator’s Manual
231
Chapter 6
Service Provider SSO Configuration
Selecting an Adapter Data Store
To populate the attributes required by the adapter (the adapter contract), you
can use values supplied by SAML assertions from the IdP exclusively, or in
addition to values retrieved from local user data stores (see “Managing Data
Stores” on page 72).
X If you choose to look up additional values, click the applicable button and
then Next. This selection allows you to identify data sources and specify
lookup queries in subsequent screens (see “Data Store Setup” next).
Or:
If you choose not to look up additional values, click the applicable button (if
it is not already selected) and then Next. This selection takes you directly to
a screen where you can map attribute values from the assertion (see
“Configuring Adapter Contract Fulfillment” on page 242).
Tip: To determine whether you need to look up additional values,
compare your attribute contract against your adapter contract (see
“Creating an Attribute Contract” on page 228 and “Selecting an
Adapter Instance” on page 231). If the adapter requires more
information, determine whether your local data stores can supply
it. (You can also choose to use text constants or expressions for
certain information—see “Configuring Adapter Contract
Fulfillment” on page 242.)
Data Store Setup
For data-store setup information, refer to the sections indicated in the following
steps.
Note: As you make selections on configuration screens, ensure that
you allow enough time for PingFederate to access your data store and
populate drop-down lists.
232
PingFederate 6
Managing IdP Connections
1. See “Selecting a Data Store” on page 233.
2. See the following sections in this manual, depending on the type of data
store:
Data Store Type
Related Manual Sections
JDBC
• “Selecting a Database Table and Columns” on
page 234
• “Configuring a Database Filter (WHERE Clause)”
on page 236
LDAP
• “Configuring an LDAP Directory Search” on
page 238
• “Configuring an LDAP Filter” on page 239
Custom
• “Configuring Custom Source Filters” on
page 241
• “Selecting Custom Source Fields” on page 242
3. See “Configuring Adapter Contract Fulfillment” on page 242
Selecting a Data Store
This screen allows you to choose a data store from a previously configured list
(see “Managing Data Stores” on page 72). Attribute values extracted from this
data store will be used in combination with the values from the attribute
contract to fulfill the adapter contract for this adapter instance (see “Configuring
Adapter Mapping and User Lookup” on page 230).
To reach this screen for editing:
1. Click the connection name on the Main Menu.
Click Manage All IdP, if needed, to see a full list of connections.
2. Click Browser SSO under the IdP Connection tab.
3. Click Configure Browser SSO.
4. Click User-Session Creation under the Browser SSO tab.
5. Click Configure User-Session Creation
Administrator’s Manual
233
Chapter 6
Service Provider SSO Configuration
6. Click Adapter Mapping & User Lookup under the User-Session
Creation tab.
7. Click the Adapter Instance Name.
8. Click Data Store on the Summary screen.
If this step is not present, then the use of a data store has not been selected
(see “Selecting an Adapter Data Store” on page 232).
To choose a Data Store:
X Choose an Active Data Store and click Next.
A data store configuration must be defined under System Settings for use
within a connection. If the data store you want is not shown in the dropdown menu, click Manage Data Stores to add a new data store (see
“Managing Data Stores” on page 72).
Selecting a Database Table and Columns
When you choose to use a database source for attributes, you follow this path
through the configuration steps.
On this screen you specify the database column locations that will be retrieved
after a lookup query locates the user record. You will specify the user lookup
query next (see “Configuring a Database Filter (WHERE Clause)” on page 236).
Field Descriptions
234
Field
Description
Schema
Lists the table structure that stores information within
a database. Some databases, such as Oracle, require
selection of a specific schema for a JDBC query. Other
databases, such as MySQL, do not require selection of
a schema.
PingFederate 6
Managing IdP Connections
Field
Description
Table
The name of the table contained in the database. The
name is used to construct the SQL query to retrieve
data from the data store.
Add Attribute
Adds the column to be executed in the SQL query to
the data store to retrieve the attribute value.
(Drop-down menu)
The available columns of attribute names for the
selected table are displayed. Select the columns that
are associated with the desired attributes you would
like to return from the JDBC query.
To reach this screen for editing:
1. Click the connection name on the Main Menu.
Click Manage All IdP, if needed, to see a full list of connections.
2. Click Browser SSO under the IdP Connection tab.
3. Click Configure Browser SSO.
4. Click User-Session Creation under the Browser SSO tab.
5. Click Configure User-Session Creation
6. Click Adapter Mapping & User Lookup under the User-Session
Creation tab.
7. Click the Adapter Instance Name.
8. Click Database Tables and Columns on the Summary screen.
If this step is not shown, this connection is not yet configured to use a
database to look up attributes. For information about changing this
configuration, see “Selecting a Data Store” on page 233.
To select a database table and columns for queries:
1. Choose a Schema file (when applicable) from the drop-down list.
2. Choose a Table from the drop-down list.
3. Choose a name under Columns to Return from Select and click Add
Column.
Repeat this step for other columns as needed.
Note: You do not need to add a column here for it to be used as
part of a search key (see “Configuring a Database Filter (WHERE
Clause)” next). Add only attributes from which you need actual
values to pass to the adapter.
Administrator’s Manual
235
Chapter 6
Service Provider SSO Configuration
Tip: To determine which attributes to look up during a query, click
Adapter Contract to Fulfill to see what information must be collected
(see “Selecting an Adapter Instance” on page 231). Then determine
what information is coming in from the assertion (see “Creating an
Attribute Contract” on page 228). Information not contained in the
Attribute Contract may be pulled from the data store look-up query.
Configuring a Database Filter (WHERE Clause)
On this screen you begin to specify exactly where additional data can be found to
complete the attribute contract when you receive an assertion from this IdP (see
“Creating an Attribute Contract” on page 132).
The JDBC WHERE clause queries your data store to locate a user record. Once the
record is located, the configured SELECT statements retrieve the attribute
values.
The clause is in the form:
WHERE column1=value1 [AND column2=value2] [OR ...]
The left side of the first variable pair uses a column name in the database table
you selected (see “Selecting a Database Table and Columns” on page 234).
The right side generally uses values passed in from the assertion. Possible
variables for these, including the correct syntax, are listed under Assertion
Values.
236
PingFederate 6
Managing IdP Connections
You can also apply additional search criteria from your own database, using any
other columns from the targeted table.
Tip: Click “View List of Columns . . .” to see a list from which to copy
and paste.
For general information about WHERE clauses, consult your DBMS
documentation.
Example:
userid=’${username}’
In this example userid is the name of a column in the JDBC data store. On
the right side, ’${username}’ returns the value of the username from
the assertion.
Important: You must use the ${} syntax to retrieve the value of
the enclosed variable and use single quotation marks around the
${} characters.
To reach this screen for editing:
1. Click the connection name on the Main Menu.
Click Manage All IdP, if needed, to see a full list of connections.
2. Click Browser SSO under the IdP Connection tab.
3. Click Configure Browser SSO.
4. Click User-Session Creation under the Browser SSO tab.
5. Click Configure User-Session Creation
6. Click Adapter Mapping & User Lookup under the User-Session
Creation tab.
7. Click the Adapter Instance Name.
8. Click Database Filter on the Summary screen.
If this step is not shown, this connection is not yet configured to use a
database to look up attributes. For information about changing this
configuration, see “Selecting a Data Store” on page 233.
To construct the WHERE clause:
1. Enter the statement in the space provided, following the guidelines and
example above.
The initial WHERE is optional.
2. Ensure the syntax and variable names are correct.
When you click Next, you will map attribute values returned from the
database into the attribute contract (see “Selecting an Adapter Data Store”
on page 232).
Administrator’s Manual
237
Chapter 6
Service Provider SSO Configuration
Configuring an LDAP Directory Search
When you choose to use an LDAP source for attributes, you follow this path
through the configuration steps.
On this screen you begin to specify exactly where additional data can be found to
supply to the SP adapter in order to access a resource on your system (see “SSO
Integration Kits and Adapters” on page 4).
Field Descriptions
Field
Description
Base DN
The base distinguished name of the tree structure in
which the search begins. This field is optional if
records are located at the LDAP root.
Search Scope
Determines the node depth of the query. Select
Subtree, One level or Object.
Root Object Class
Specifies the object type within the LDAP hierarchy
from which attributes will be returned.
Attribute
The available attribute names for the selected
directory structure. Select the names associated with
the attributes that you would like to return from the
query.
To reach this screen for editing:
1. Click the connection name on the Main Menu.
Click Manage All IdP, if needed, to see a full list of connections.
2. Click Browser SSO under the IdP Connection tab.
3. Click Configure Browser SSO.
238
PingFederate 6
Managing IdP Connections
4. Click User-Session Creation under the Browser SSO tab.
5. Click Configure User-Session Creation
6. Click Adapter Mapping & User Lookup under the User-Session
Creation tab.
7. Click the Adapter Instance Name.
8. Click LDAP Directory Search on the Summary screen.
If this step is not shown, this connection is not yet configured to use LDAP
to look up attributes (see “Selecting a Data Store” on page 233).
To select LDAP attributes:
1. (Optional) Enter a Base DN.
2. Select a Search Scope.
3. Select a Root Object Class.
4. Under Attributes to return from search, choose an attribute and click Add
Attribute.
Note that the attribute Subject DN is always returned by default.
5. Repeat the last step for other attributes as needed.
6. (Optional) Change the Search Scope or the Root Object Class if you want
attributes from other locations.
Note: You do not need to add an attribute here for it to be used in a
search filter (see “Configuring an LDAP Filter”). Add only attributes
from which you need values to map to the adapter.
Configuring an LDAP Filter
The LDAP filter queries the data store to retrieve a user record associated with a
particular value (or values) from the assertion. The filter is in the form:
(attribute=${value})
Administrator’s Manual
239
Chapter 6
Service Provider SSO Configuration
The left-side variable is an attribute from the data store (see “Configuring an
LDAP Directory Search” on page 145).
The right side generally uses values passed in from the assertion.
You can also apply additional search criteria from your data store, using any other
attributes from the targeted object classes.
Tip: Click “View List of Available LDAP Attributes” for a list from
which you can copy and paste.
For general information about search filters, consult your LDAP documentation.
Example:
(UNAME=${username})
In this example UNAME is the name of an attribute in the LDAP data store.
On the right side, ${username} returns the value of username. in the
assertion.
Important: You must use the ${} syntax to retrieve the value of
the enclosed variable.
240
PingFederate 6
Managing IdP Connections
Field Description
Field
Description
Filter
A filter narrows a search to locate requested data by
either including or excluding specific records. An LDAP
filter includes the attributes in the search and the value
or range of values that the search is attempting to
match. Searches are conducted by using at least three
components: 1) at least one attribute (attribute data
type) to search on, 2) a search filter operator that will
determine what to match, and 3) the value of the
attribute being sought. Searches must have at least
one of each of these three components.
To reach this screen for editing:
1. Click the connection name on the Main Menu.
Click Manage All IdP, if needed, to see a full list of connections.
2. Click Browser SSO under the IdP Connection tab.
3. Click Configure Browser SSO.
4. Click User-Session Creation under the Browser SSO tab.
5. Click Configure User-Session Creation
6. Click Adapter Mapping & User Lookup under the User-Session
Creation tab.
7. Click the Adapter Instance Name.
8. Click LDAP Filter on the Summary screen.
If this step is not shown, this connection is not configured to use LDAP to
look up attributes (see “Selecting a Data Store” on page 233).
To construct the LDAP filter:
1. Enter the statement in the space provided, following the guidelines and
example above.
Note: If you used an anonymous binding to create this LDAP
connection, your access might be restricted (see “Configuring an
LDAP Connection” on page 78).
2. Ensure the syntax and variable names are correct.
3. Click Next.
Configuring Custom Source Filters
When you choose to use a custom source for attributes, you follow this path
through the configuration steps.
Administrator’s Manual
241
Chapter 6
Service Provider SSO Configuration
On this screen you specify a filter, or lookup query, for your custom data source.
This screen display and the syntax of the filter depends on your developer’s
implementation of the custom source SDK.
Selecting Custom Source Fields
On the Configure Custom Source Fields screen, you can choose from among
the fields shown to map to the adapter contract. These choices are supplied by
the driver implementation. Select only those needed to fulfill the attribute
contract for this partner connection.
Configuring Adapter Contract Fulfillment
The last step in configuring an adapter is to map each attribute required for the
adapter contract to a value (see “Selecting an Adapter Data Store” on page 232).
These are the values that will be used to create a local session. An SSO operation
fails if the SP is unable to fulfill the mapping requirements defined here.
Map attributes from one of these Sources:
•
Account Link
This source appears only if you have elected to use account linking (see
“Selecting an Identity-Mapping Method” on page 226). When you make
this selection, the associated Value drop-down list is populated with Local
User ID. Normally, you would map this identifier to target an adapter
attribute that represents the local user ID.
•
Assertion
Values are contained in the assertions from this IdP. When you make this
selection, the associated Value drop-down list is populated by the attribute
contract (see “Creating an Attribute Contract” on page 228).
•
JDBC/LDAP/Custom
Values are returned from your query. When you make this selection, the
Value list is populated by the database columns or LDAP or custom
attributes you identified for this data store (see “Selecting a Database Table
and Columns” on page 234, “Configuring an LDAP Directory Search” on
page 238, or “Selecting Custom Source Fields” on page 242).
•
Text
The value is what you enter. This can be text only, or you can mix text with
references to any of the values from the assertion, using the ${attribute}
syntax.
You can also enter values from your data store, when applicable, using this
syntax:
${ds.attribute}
where attribute is any of the data store attributes you have selected.
242
PingFederate 6
Managing IdP Connections
Tip: Two other variables are also available: ${SAML_SUBJECT} and
${TargetResource}. SAML_SUBJECT is the initiating user (or
other entity); TargetResource is a reference to the protected
application or other resource for which the user is requesting SSO
access (available only if specified in the relevant startSSO.ping
query parameter—see “Application Endpoints” on page 347).
There are a variety of reasons why you might hard code a text value. For
example, if your Web application provides a consumer service, you might
want to supply a particular promotion code for this partner.
Tip: Another selection in the Source drop-down menu, Expressions,
may be enabled (see “Using Attribute Mapping Expressions” on
page 367). This option provides more complex mapping capabilities—
for example, transforming incoming values into different formats. All of
the variables available for text entries are also available for expressions.
To reach this screen for editing:
1. Click the connection name on the Main Menu.
Click Manage All IdP, if needed, to see a full list of connections.
2. Click Browser SSO under the IdP Connection tab.
3. Click Configure Browser SSO.
4. Click User-Session Creation under the Browser SSO tab.
5. Click Configure User-Session Creation
6. Click Adapter Mapping & User Lookup under the User-Session
Creation tab.
7. Click the Adapter Instance Name.
8. Click Adapter Contract Fulfillment on the Summary screen.
Administrator’s Manual
243
Chapter 6
Service Provider SSO Configuration
To map attributes:
1. Choose a Source for each Target attribute (see descriptions of each Source
type above).
2. Choose (or enter) a Value for each Attribute.
All values must be mapped.
3. Click Done.
Configuring Protocol Settings
The Protocol Settings screen provides the launching point for configuring
bindings, partner endpoints, and other settings needed for the selected SAML
profiles (if you are using SAML—see “Choosing SAML Profiles” on page 223).
The screen also displays configured information.
(For WS-Federation, the configuration of bindings is not applicable.)
To configure Protocol Settings, you need to know:
•
For SP-initiated SSO profiles, the URL(s) of your IdP’s Single Sign-on
Service(s).
•
For SLO profiles, the URL(s) of your IdP’s Single Logout Service(s)
•
When artifact is an allowable inbound binding, the URL of your IdP’s
Artifact Resolution Service(s)
•
The transport configurations (bindings) that you will use to send and receive
data for SSO/SLO connections
•
Digital signature policies and certification requirements to which you
and your connection partner have agreed
•
XML encryption policies to which you and your connection partner have
agreed
X To continue, click Configure Protocol Settings.
244
PingFederate 6
Managing IdP Connections
Important: After modifying any settings, you must click Save on
the Protocol Settings screen.
Specifying SSO Service URLs (SAML)
At this step for SAML 2.0 connections, you associate bindings to the endpoints
where your IdP wants PingFederate to send authentication requests when SSO is
initiated at your site.
For SAML 1.x, only one endpoint is allowed, and the binding selection is not
required.
This configuration applies only to the SP-initiated SSO Profile (see
“Configuring SP-Initiated SSO” on page 224).
Field Descriptions
Field
Description
Binding (SAML 2.0)
The transport type agreed upon by you and your
partner: Artifact, POST, or Redirect.
Endpoint URL
The location where your IdP receives SSO messages.
To reach this screen for editing:
1. Click a connection name on the Main Menu.
Click Manage All IdP, if needed, to see a full list of connections.
2. Click Browser SSO under the IdP Connection tab.
3. Click Configure Browser SSO.
4. Click Protocol Settings on the Summary screen.
5. Click Configure Protocol Settings.
Administrator’s Manual
245
Chapter 6
Service Provider SSO Configuration
6. Click SSO Service URLs on the Summary screen.
If this step is not displayed, you have not selected SP-initiated SSO (see
“Choosing SAML Profiles” on page 223).
To define an Endpoint URL:
1. If you are using SAML 2.0, select the Binding your partner specifies for the
Endpoint.
2. Enter the fully qualified Endpoint URL or a relative path if you have defined
a base URL (see “General Information” on page 218).
3. If you are using SAML 2.0, click Add.
4. If your partner has additional SSO endpoints established under SAML 2.0,
repeat the steps above.
Specifying a Service URL (WS-Federation)
The Service URL is the WS-Federation endpoint of your IdP partner. This
endpoint is where you send RST (Request for Security Token) and SLO
messages.
X Enter the fully qualified URL or a relative path if you have defined a base
URL (see “General Information” on page 218).
To reach this screen for editing:
1. Click a connection name on the Main Menu.
Click Manage All IdP, if needed, to see a full list of connections.
2. Click Browser SSO under the IdP Connection tab.
3. Click Configure Browser SSO.
4. Click Protocol Settings under the Browser SSO tab.
5. Click Configure Protocol Settings.
6. Click Service URL on the Summary screen.
246
PingFederate 6
Managing IdP Connections
Specifying SLO Service URLs (SAML 2.0)
At this step you associate bindings to the endpoints where your IdP receives
logout requests when SLO is initiated at your site and where you send SLO
responses when you receive SLO requests from the IdP.
This step applies only for SAML 2.0 connections when you have selected an
SLO profile (see “Choosing SAML Profiles” on page 223).
Field Descriptions
Field
Description
Binding
The transport type agreed upon by you and your
partner: Artifact, POST, Redirect, or SOAP.
Endpoint URL
The location where your IdP receives SLO request
messages.
Response URL
(Optional) The location where the IdP receives logout
responses. Use this endpoint when you are part of a
chain of session participants.
To reach this screen for editing:
1. Click a connection name on the Main Menu.
Click Manage All IdP, if needed, to see a full list of connections.
2. Click Browser SSO under the IdP Connection tab.
3. Click Configure Browser SSO.
4. Click Protocol Settings on the Summary screen.
5. Click Configure Protocol Settings.
6. Click SLO Service on the Summary screen.
Administrator’s Manual
247
Chapter 6
Service Provider SSO Configuration
To define an Endpoint URL:
1. Select the Binding your partner specifies for the Endpoint.
2. Enter the fully qualified Endpoint URL or a relative path if you have defined
a base URL (see “General Information” on page 218).
3. (Optional) Enter the Response URL or a relative path and click Add.
4. If your partner provides additional endpoints for SLO, repeat the steps
above.
Choosing Allowable SAML Bindings (SAML)
At this step you configure binding(s) that the IdP will use to send SAML
assertions or SLO messages (under SAML 2.0) to your PingFederate server.
This configuration applies to all profile types (see “Choosing SAML Profiles” on
page 223). You and your partner can agree to standardize on one binding type or
select different bindings for different profile scenarios.
To reach this screen for editing:
1. Click a connection name on the Main Menu.
Click Manage All IdP, if needed, to see a full list of connections.
2. Click Browser SSO under the IdP Connection tab.
3. Click Configure Browser SSO.
4. Click Protocol Settings on the Summary screen.
5. Click Configure Protocol Settings.
6. Click Allowable SAML Bindings on the Summary screen.
To define binding requirements for this connection:
X Make your selections and click Next (or Done).
248
PingFederate 6
Managing IdP Connections
Setting an Artifact Lifetime (SAML 2.0)
When you send an artifact to your IdP’s SSO or SLO service, an element in the
message indicates how long it should be considered valid.
You can change the default value per your requirements, if needed. Also consider
synchronizing clocks between your server and your partner’s SAML gateway
server. If clocks are not synchronized, you might need to set the artifact lifetime
to a higher value.
To reach this screen for editing:
1. Click a connection name on the Main Menu.
Click Manage All IdP, if needed, to see a full list of connections.
2. Click Browser SSO under the IdP Connection tab.
3. Click Configure Browser SSO.
4. Click Protocol Settings on the Summary screen.
5. Click Configure Protocol Settings.
6. Click Artifact Lifetime on the Summary screen.
This step appears only if you have selected the artifact binding for either a
SSO or SLO Service at the IdP site.
Specifying Artifact Resolver Locations
This endpoint or group of endpoints is where your server will send back-channel
requests based on artifacts. The location or locations are also known under
SAML specifications as the Artifact Resolution Service. SAML 2.0 provides for
multiple, indexed endpoints for the service.
Administrator’s Manual
249
Chapter 6
Service Provider SSO Configuration
Note that this screen is different for SAML 1.x implementations, for which only
one endpoint is allowed.
To reach this screen for editing:
1. Click a connection name on the Main Menu.
Click Manage All IdP, if needed, to see a full list of connections.
2. Click Browser SSO under the IdP Connection tab.
3. Click Configure Browser SSO.
4. Click Protocol Settings on the Summary screen.
5. Click Configure Protocol Settings.
6. Click Artifact Resolver Locations on the Summary screen.
If this step does not appear, you do not have Artifact selected under
Allowable SAML Bindings.
For a SAML 2.0 connection:
1. Enter a URL on the Artifact Resolver Locations screen and click Add.
The URL must be fully qualified (defining protocol, host, and port) unless
you have entered a base URL (see “General Information” on page 218).
Repeat this step if your IdP supports multiple services. The SAML 2.0
specifications permit multiple artifact resolution services through the use of
Index numbers, which PingFederate automatically supplies when you add a
service. Alternatively, if needed per partner specifications, you may assign
these index numbers manually.
Note: When specifying multiple artifact resolution endpoints, each
endpoint must share the same transport protocol. That is, if one
endpoint uses HTTP, then all must use HTTP. Similarly, if one
endpoint uses HTTPS, then all must use HTTPS.
2. Click Next.
250
PingFederate 6
Managing IdP Connections
For a SAML 1.x connection:
1. Enter the Endpoint on the Artifact Resolution Location screen.
The URL must be fully qualified (defining transport protocol, host, and port)
unless you have entered a base URL (see “General Information” on
page 218).
2. (Optional) Enter your partner’s Source ID.
The Source ID is usually a generated value based on a federation partner’s
Connection ID; the SP will correctly generate the Source ID. If that is the
case for this partner, then leave this field blank. If your partner uses a Source
ID that is not based on their Issuer ID, then enter the Source ID supplied by
your IdP partner.
3. Click Next.
Configuring Signature Policy
The Signature Policy screen provides options controlling how digital signatures
are used for SSO Internet messaging. The choices made on this screen depend on
your partner agreement (see “Digital Signing Policy Coordination” on page 13).
Digital signing is required for SAML Response messages sent from the IdP via
POST (or Redirect for SAML 2.0). Optionally, SSO authentication requests
from the SP (SP-initiated SSO) may also be signed to enforce security. (This
option appears only for SAML 2.0 connections and only if you have enabled SPinitiated SSO using the POST or redirect bindings.)
The assertions inside SAML Responses may be also be signed. When you make
this choice, only the assertion portion of the Response is signed, not the
complete Response. (This is the only option that appears for SAML 1.x
connections.)
X To choose one or more enhancement options, select the second button,
make your selection(s), and click Next.
Administrator’s Manual
251
Chapter 6
Service Provider SSO Configuration
X Otherwise, select the first option (if not already selected) and click Next.
Configuring XML Encryption Policy (SAML 2.0)
For SAML 2.0 configurations, in addition to using signed assertions to ensure
authenticity, you and your partner may also agree to encrypt all or part of an
assertion to improve privacy. This feature is commonly used if the assertion
might pass through an intermediary (such as a user’s browser) and HTTPS is not
used.
If the name identifier (or SAML_SUBJECT) of an assertion is encrypted, you and
your partner may also want to encrypt the identifier in subsequent single-logout
messages (if you are using an SLO profile).
Note that “The entire assertion” selection on the Encryption Policy screen
includes the SAML_SUBJECT and all attributes.
s
To reach this screen for editing:
1. Click a connection name on the Main Menu.
Click Manage All IdP, if needed, to see a full list of connections.
2. Click Browser SSO under the IdP Connection tab.
3. Click Configure Browser SSO.
4. Click Protocol Settings under the Browser SSO tab.
5. Click Configure Protocol Settings.
6. Click Encryption Policy on the Summary screen.
To define XML encryption:
1. Select Allow encrypted SAML Assertions and SLO messages.
2. Choose whether this IdP partner will encrypt the entire assertion, the
SAML_SUBJECT, one or more other attributes, or some combination.
252
PingFederate 6
Managing IdP Connections
3. If your partner is encrypting the name-identifier attribute, use the
checkboxes near the bottom of the screen to indicate whether you will
encrypt this attribute in outbound SLO messages and/or allow its encryption
for inbound messages.
4. Click Next or Done.
To disable previously configured XML encryption selections:
1. Select None and then Done.
2. Click Save on the Browser SSO screen.
Editing and Saving Protocol Settings
On the Summary screen you can review or edit your Protocol Settings.
Important: When you finish editing existing settings, be sure to
click Done on the Summary screen and then Save on the Protocol
Settings screen. For a new connection, click Done and then click
Next on the Protocol Settings screen. Save the entire connection
on the Activation & Summary screen (see “Connection Activation
and Summary” on page 271).
To reconfigure saved settings:
1. Click the heading over the information you want to change.
2. Click Done on the screen containing your change.
If you need to make dependent or other changes, do so and continue by
clicking Done until you reach the Protocol Settings screen.
3. Click Save on the Protocol Settings screen.
Editing and Saving Browser SSO Settings
On the Summary screen for Browser SSO, you can review or edit your SSO
configuration.
Important: When you finish editing existing settings, be sure to
click Done on the Summary screen and then Save on the Browser
SSO screen. For a new connection, click Done and then click Next
on the Browser SSO screen. Save the entire connection on the
Activation & Summary screen (see “Connection Activation and
Summary” on page 271).
To reconfigure saved settings:
1. Click the heading over the information you want to change.
Administrator’s Manual
253
Chapter 6
Service Provider SSO Configuration
2. Click Done on the screen containing your change.
If you need to make dependent or other changes, do so and continue by
clicking Done until you reach the Browser SSO screen.
3. Click Save on the Browser SSO screen.
User Provisioning
PingFederate’s Express Provisioning allows SPs to create LDAP user accounts
“on the fly” during SSO events, based on attributes received from IdPs (see “User
Provisioning” on page 18). An SP can also use the feature to update existing user
records.
This configuration task is presented in the administrative console only when
User Provisioning is selected as an option (see “Choosing Connection Options”
on page 217).
X To continue, click Configure User Provisioning.
Choosing an Event Trigger
On the Event Trigger screen, choose whether PingFederate initiates user
provisioning only when the user identifier is new or every time your site receives
a SAML assertion. In the latter case, an existing user account is always updated
with incoming attributes.
254
PingFederate 6
Managing IdP Connections
Selecting Attribute Sources (SAML 2.0)
For SAML 2.0 connections, the server can be configured to use only assertion
attributes for user provisioning or to retrieve more attributes from the IdP in a
follow-on Attribute Query transaction (see “Attribute Query and XASP” in the
“Supported Standards” chapter of Getting Started). The User Attributes screen
displays the attributes expected in the assertion from this IdP (see “Creating an
Attribute Contract” on page 228).
Note: Attribute Query is a SAML 2.0 profile. For SAML 1.x and WSFederation connections, this screen is not presented; PingFederate
uses only attributes from the assertion for user provisioning.
X If you and your IdP partner have agreed to use the Attribute Query profile
for provisioning, select that option before leaving this screen.
You will configure the Attribute Query profile later in the task flow, if you
have not already done so (see “Configuring the Attribute Query Profile” on
page 260).
Administrator’s Manual
255
Chapter 6
Service Provider SSO Configuration
Identifying the User Repository
PingFederate’s provisioning feature currently supports only LDAP user stores.
Choose the data store to use on the User Repository screen.
If the correct data store is not shown in the drop-down list, then PingFederate is
not yet configured to access the store (see “Managing Data Stores” on page 72).
Specifying User-Record Location
After choosing a data store, indicate where in the store PingFederate should
write new user records or update existing ones (see “Choosing an Event Trigger”
on page 254). Start by specifying where user records are located in your data
store.
Field Description
256
Field
Description
Base DN
The base distinguished name of the tree structure in
which the search begins. Leave this field blank if
records are located at the LDAP root.
PingFederate 6
Managing IdP Connections
Specifying a Unique Identifier
On the Unique ID screen, create an LDAP filter to identify user accounts to be
provisioned (or updated) during SSO events. PingFederate uses this expression
in conjunction with the Base DN (see the previous section) to locate existing
account records and to add new ones.
The filter is in the form:
attribute=${value}
Note that the statement must not be enclosed in parentheses, unlike filters used
to retrieve LDAP attributes for adapter mapping (see “Configuring an LDAP
Filter” on page 239).
The left-side variable is an attribute in your user data store—click the link near
the left corner of the screen to see a list of available attributes. The right side of
the filter generally uses one or more attribute values passed in from the assertions
(see “Creating an Attribute Contract” on page 228). Variables for these
attributes, including the correct syntax, are listed under Assertion Values.
Identifying Provisioning Attributes
On the Attributes screen, select the data-store attributes to be provisioned.
Tip: Multiple-value IdP attributes are handled automatically: when you
map a multi-value assertion attribute to an LDAP attribute, each value is
stored separately for the LDAP attribute name. If you need to provide
additional values for particular attributes, add the same attribute name
to this list multiple times. You can then map the additional values on the
Attribute Fulfillment screen (see the next section).
Administrator’s Manual
257
Chapter 6
Service Provider SSO Configuration
To select attributes:
1. Choose a Root Object Class and an Attribute from the drop-down lists and
click Add Attribute.
Repeat this step for the same attribute if needed (see “Tip” above).
Important: For the Sun Directory Server or Active Directory, the
attribute objectClass must be among attributes added—select
<Show All Attributes> under Root Object Class to locate and add
this attribute.
2. Repeat the previous step for each attribute requiring provisioning.
Mapping Attributes to User Accounts
The Attribute Fulfillment screen provides a means of mapping the values of
incoming attributes to the local account attributes selected on the previous
screen. You can also provide values of your own for any attributes—either as
hard-coded text or derived values based on assertion attributes.
258
PingFederate 6
Managing IdP Connections
Map attributes from one of these Sources:
•
Assertion
Values are contained in the assertions from this IdP. When you make this
selection, the associated Value drop-down list is populated by the attribute
contract (see “Creating an Attribute Contract” on page 228).
•
Attribute Query
This choice appears only if you have chosen to use the Attribute Query
profile for provisioning (see “Selecting Attribute Sources (SAML 2.0)” on
page 255).
To map an attribute-query value, use this syntax:
${query_attribute}
You can also combine attribute-query values with references to attributes in
the attribute contract. For example:
${query_attribute}+${attribute}
References to attributes not contained in the attribute contract result in an
Attribute Query back to the IdP partner.
•
Text
The value is what you enter. This can be text only, or you can mix text with
references to any of the values from the assertion, using the ${attribute}
syntax.
Tip: Another selection in the Source drop-down menu, Expressions,
may be enabled (see “Using Attribute Mapping Expressions” on
page 367). This option provides more complex mapping capabilities—
for example, transforming incoming values into different formats. All of
the variables available for text entries are also available for expressions.
To map attributes:
1. Choose a Source for each Target attribute (see descriptions of each Source
type above).
Tip: Choose Text as the Source for the objectClass attribute.
2. Choose (or enter) a Value for each Attribute.
All values must be mapped.
Tip: For Active Directory, enter user in the text box for
objectClass. For the Sun Directory Server, enter
inetOrgPerson.
3. Click Done.
Administrator’s Manual
259
Chapter 6
Service Provider SSO Configuration
Error Handling
If user provisioning fails for any reason during SSO events, you can choose to
stop the SSO or continue the process by passing assertion attributes on to your
application (via the SP adapter configuration—see “Configuring Adapter
Mapping and User Lookup” on page 230).
When SSO is aborted, the user is redirected to an error page, and the failure is
written to the log and registered in the administrative console.
Using the Provisioning Summary Screen
The Summary screen provides an overview of your provisioning configuration.
X When you are finished with a new configuration, click Done and then Save
on the User Provisioning screen.
To change the configuration:
1. Click the heading over the information you want to change.
2. Click Done on the screen containing your change.
If you need to make additional changes, do so and continue by clicking
Done until you reach the User Provisioning screen.
3. Click Save on the User Provisioning screen.
Configuring the Attribute Query Profile
At the Attribute Query step you configure your connection to request user
attributes from your partner IdP, if you have chosen this option (see “Choosing
Connection Options” on page 217). Attribute queries are not dependent on
single sign-on but may be used independently or in conjunction with Browser
SSO or provisioning to provide flexibility in how a user authenticates with SP
applications (see “Attribute Query and XASP” in the “Supported Standards”
chapter of Getting Started).
260
PingFederate 6
Managing IdP Connections
Setting the Attribute Authority Service URL
Attribute Authority is the term used to refer to an IdP that provides user attributes
to an Attribute Requester (your SP site). The Attribute Authority Service URL
corresponds to the endpoint location where Attribute Query requests are
received by your IdP partner (see “Attribute Query and XASP” in the
“Supported Standards” chapter of Getting Started).
To configure the URL:
X Enter the fully qualified URL or a relative path if you have defined a base
URL (see “General Information” on page 218).
Mapping Attribute Names
If the application at your site uses different names for user attributes than the
names defined by the Attribute Authority, then you need to map them on this
screen. When the SP receives a request from a local application to send an
Attribute Query to this Attribute Authority partner, the requested user attributes
are replaced with the names mapped here.
This information must be predetermined in your agreement with this connection
partner.
To map attributes:
1. Enter the Local Name and Remote Name of an attribute and click Add.
Repeat this step for all attributes requiring mapping.
Administrator’s Manual
261
Chapter 6
Service Provider SSO Configuration
2. Click Next.
To edit a mapping:
1. Click Edit under Action for the mapping.
2. Make your change(s) and click Update.
Note: If you change your mind, ensure that you click the Cancel
link in the Actions column, not the Cancel button, which discards
any other changes you might have made in this configuration.
3. Click Done and then Save on the Attribute Query screen.
Specifying Security Policy
This screen allows you to specify the digital signing and encryption policy to
which you and your partner have agreed. These selections will trigger
requirements for setting up Credentials (see “Configuring Credentials” on
page 263).
This screen also allows you to mask incoming attribute values in log files (see
“Attribute Masking” on page 10). When you enable this selection, all user
attributes returned from this IdP are masked.
To configure attribute-query security policy for this partner:
X Check or clear the check boxes and click Next or Done.
Editing and Saving Attribute Query Configurations
On the Summary screen you can review the Attribute Query configuration.
To reconfigure saved profiles:
1. Click the heading over the information you want to change.
262
PingFederate 6
Managing IdP Connections
2. Click Done on the screen containing your change.
If you need to make additional changes, do so and continue by clicking
Done until you reach the Attribute Query screen.
3. Click Save on the Attribute Query screen.
Configuring Credentials
The Credentials screen presents a list of possible security requirements you might
need, depending on the federation protocol you are using and the choices you
have made.
Your connection configuration may involve any or all of the following:
•
Configuring Back-Channel Authentication
•
Configuring Digital Signature Settings
•
Selecting Signature Verification Certificates
•
Selecting an Encryption Certificate
•
Selecting a Decryption Key
X To configure or modify credentials, click Configure Credentials.
Configuring Back-Channel Authentication
When you configure a profile for the inbound artifact binding or the outbound
SOAP binding, you must specify back-channel authentication information for
sending SOAP messages or artifact resolution requests to your partner IdP.
Administrator’s Manual
263
Chapter 6
Service Provider SSO Configuration
Similarly, if you send artifacts or SOAP messages to your partner IdP, then you
must configure SOAP authentication requirements for receiving SOAP
responses or artifact resolution requests from your partner.
This step also applies to attribute-request configurations, since this profile always
uses the SOAP back channel (see “Choosing SAML Profiles” on page 223).
Note: A yellow triangle next to a listing indicates that you have not
completely configured back-channel authentication requirements.
To reach this screen:
1. Click a connection name on the Main Menu.
Click Manage All IdP, if needed, to see a full list of connections.
2. Click Credentials under the IdP Connection tab.
3. Click Configure Credentials.
If the Back-Channel Authentication step is not shown, then it is not
applicable to your configuration—you are not using the Attribute Query
profile and have not configured any profiles to use the artifact or SOAP
bindings.
To configure back-channel authentication requirements for sending
SOAP messages:
1. On the Back-Channel Configuration screen, click the Configure link to the
right of the list of messages to be sent to your partner.
264
PingFederate 6
Managing IdP Connections
2. Make one or more selections on the Outbound SOAP Authentication Type
screen:
•
•
Basic — you will enter SOAP Basic credentials on a later screen.
SSL Client Certificate — you will specify the certificate on a later
screen.
This option is enabled only if you have specified an endpoint that
uses SSL.
•
Use Digital Signatures . . . — you will sign the message.
You will be asked to select a signing certificate on a later screen.
For SAML 2.0, these options may be used in any combination or
independently. For SAML 1.x, you must use either Basic or SSL
authentication; digital signing may be added to ensure message integrity.
By default, PingFederate validates your partner’s SSL server certificate—
verifying that the certificate chain is rooted by a trusted Certificate
Authority and that the hostname matches the certificate’s Common Name.
Clear the associated checkbox if you do not want this validation to occur.
3. (Optional) On the Outbound SOAP Authentication Type screen, select the
checkbox requiring a valid certificate chain for your partner’s SSL
certificate.
Make this selection only if you and your partner have agreed that the chain
of authority is required for SSL federation transactions.
4. Click Next.
5. If you chose Basic at Step 2, enter the SOAP Username and Password to
use for this partner under Basic SOAP Authentication.
You must obtain these credentials from your partner.
6. If you are using an SSL certificate, select the certificate under SSL
Authentication Certificate and click Next.
If you have not yet created or imported the client SSL certificate you need
into PingFederate, click Manage Certificates (see “SSL Client Keys &
Certificates” on page 94). You will need to export the certificate (only) and
send it your partner.
7. On the Summary screen, click Done.
To configure back-channel authentication requirements for receiving
SOAP messages:
1. On the Back-Channel Configuration screen, click the Configure link to the
right of the list of messages to be received from your partner.
2. Select one or more options on the Inbound SOAP Authentication Type
screen:
•
Basic — Enter the logon username and password your partner will use
on the next screen.
•
SSL Certificate — Specify certificate verification information on a later
screen.
Administrator’s Manual
265
Chapter 6
Service Provider SSO Configuration
•
Use Digital Signatures . . . — Incoming messages must be signed.
You will be asked to select a signature verification certificate on a
later screen.
For SAML 2.0, these options may be used in any combination or
independently. For SAML 1.x, you must use either Basic or SSL
authentication; digital signing may be added to ensure message integrity.
3. Click Next.
4. If you chose Basic at Step 2, enter the SOAP Username and Password
under Basic SOAP Authentication.
Important: If you are configuring more than one connection that
uses the artifact or SOAP profile, you must ensure that the
Username is unique for each connection.
5. If you are using an SSL certificate, select Anchored or Unanchored under
Certificate Verification Method.
•
Anchored — The certificate must be signed by a trusted Certificate
Authority, and the CA’s certificate must be imported into the
PingFederate Trusted CA store (see “Trusted CAs” on page 90).
•
Unanchored — The certificate is self-signed or you wish to trust a
specified certificate.
Note: When anchored certificates are used between partners,
certificates may be changed without sending the update to your
partner. If the certificate is unanchored, any changes must be
promulgated.
6. Click Next.
7. If you chose anchored SSL certificate verification at Step 5, enter the
Subject DN and click Next.
Tip: If you have not yet defined the certificate in PingFederate or
you do not know the DN, return to the previous screen and check
Unanchored. Then click Next and click Manage Certificates on the
SSL Verification Certificate screen to import the certificate, if
needed, or to view its DN.
8. If you chose unanchored SSL certificate verification at Step 5, select the
certificate you will use to validate the SSL connection.
If you have not yet imported the certificate into PingFederate, click
Manage Certificates.
9. Click Next.
10. On the Summary screen, click Done.
266
PingFederate 6
Managing IdP Connections
Configuring Digital Signature Settings
This step defines the private key you will use to sign SSO authentication or
attribute requests (optionally) or SAML 2.0 SLO messages for this IdP. In
addition, the step allows you to include “Key Info” with the XML message if you
and your partner have agreed to this option.
Digital signing applies to SP-initiated SSO under SAML 2.0, when specified by
your partner agreement, and to either SLO profile (see “Choosing SAML
Profiles” on page 223) using the POST or redirect bindings. The step also applies
if you are configuring an Attribute Query profile and have specified that you will
sign attribute requests (see “Specifying Security Policy” on page 262).
The step is not required for SAML 1.x IdP connections.
To reach this screen:
1. Click a connection name on the Main Menu.
Click Manage All IdP, if needed, to see a full list of connections.
2. Click Credentials under the IdP Connection tab.
3. Click Configure Credentials.
4. Click Digital Signature Settings on the Summary screen.
If this step does not appear, then your configuration does not require digital
signatures. You do not have SLO configured using the POST or redirect
bindings, and you have not elected to sign either authentication or attribute
requests (see “Configuring Signature Policy” on page 251 and “Specifying
Security Policy” on page 262).
To specify a certificate:
1. Select the certificate from the drop-down list.
If you have not yet created or imported your certificate into PingFederate,
click Manage Certificates (see “Digital Signing and Decryption Keys &
Certificates” on page 96).
2. (Optional) If you have agreed to send your public key with the SAML
message, click the checkbox to implement this requirement.
Administrator’s Manual
267
Chapter 6
Service Provider SSO Configuration
Selecting Signature Verification Certificates
Under SAML 2.0 specifications, when your site receives any SAML 2.0 messages
via the POST or Redirect bindings, the messages must be digitally signed.
Signing is also always required for the SAML 1.x POST binding and for WSFederation assertions, as well as incoming SAML 1.1 or 2.0 tokens for WS-Trust
STS processing.
Depending on your agreement with this IdP, SSO assertions, SAML 2.0 artifacts,
or SOAP messages might also require signatures.
Whenever signatures are required, you must import your partner’s public key
certificate into the PingFederate store for signature verification.
Tip: To prevent any interruption of service due to an expired certificate,
you can ask your partner for a new certificate in advance and use it in
the Secondary certificate field. The PingFederate server will use the
primary certificate until it expires and then try the secondary.
To reach this screen:
1. Click a connection name on the Main Menu.
Click Manage All IdP, if needed, to see a full list of connections.
2. Click Credentials under the IdP Connection tab.
3. Click Configure Credentials.
4. Click Signature Verification Certificate on the Summary screen.
If this step does not appear for SAML 2.0, then your configuration does not
require a verification certificate. You are not using SLO POST or redirect
bindings; only the artifact or SOAP bindings with SSL/TLS endpoints are
configured under Allowable SAML Bindings, and signed assertions are not
required (see “Choosing Allowable SAML Bindings (SAML)” on page 248
and “Configuring Signature Policy” on page 251).
268
PingFederate 6
Managing IdP Connections
To specify a certificate:
1. Select the certificate from the drop-down list.
If you have not yet imported the certificate into PingFederate, click
Manage Certificates.
2. Optionally, select a Secondary certificate for backup.
Use this field if your partner has sent you a new certificate to replace one
that is ready to expire. The server will automatically verify against the
secondary certificate when the primary one expires.
Selecting an Encryption Certificate
If SAML_SUBJECT is encrypted, either by itself or as part of a whole assertion,
then all references to this name identifier in SAML 2.0 SLO requests from your
site may also be encrypted (if the connection uses SP-initiated SLO). For more
information, see “Configuring XML Encryption Policy (SAML 2.0)” on
page 252.
To enable this XML encryption, you must identify an encryption certificate for
this partner.
You must also choose a certificate if encryption of the Name Identifier is required
for an Attribute Request profile (see “Specifying Security Policy” on page 262).
To reach this screen:
1. Click a connection name on the Main Menu.
Click Manage All IdP, if needed, to see a full list of connections.
2. Click Credentials under the IdP Connection tab.
3. Click Configure Credentials.
Administrator’s Manual
269
Chapter 6
Service Provider SSO Configuration
4. Click Select XML Encryption Certificate on the Summary screen.
If this step is not present, then you have either not configured this
connection to use the SP-initiated SLO profile (see “Choosing SAML
Profiles” on page 223) or you have chosen not to encrypt the assertion or the
SAML_SUBJECT (see “Configuring XML Encryption Policy (SAML 2.0)”
on page 252).
To identify the encryption certificate:
1. (Optional) Change the default settings under Block Encryption Algorithm
and/or Key Transport Algorithm.
Due to import restrictions, the standard JRE distribution supports strong but
not unlimited encryption. To use the strongest AES encryption, when
permissible, download and install the appropriate version of “Java
Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files”
from the Sun download Web site (http://java.sun.com/javase/downloads).
For more information about XML block encryption and key transport
algorithms, see the “XML Encryption Syntax and ProcessingW3C
Recommendation” (http://www.w3.org/TR/xmlenc-core).
2. From the drop-down list, select the applicable certificate and click Next.
If the certificate is not in the list, click Manage Certificates to import it.
Note: If you have already imported a signature verification
certificate for this partner, you can reuse it for XML decryption as
long as it is an RSA certificate.
Selecting a Decryption Key
As part of XML encryption, you must identify a signing certificate and key for
PingFederate to use to decrypt incoming assertions or assertion elements (see
“Configuring XML Encryption Policy (SAML 2.0)” on page 252).
To reach this screen:
1. Click a connection name on the Main Menu.
Click Manage All IdP, if needed, to see a full list of connections.
270
PingFederate 6
Managing IdP Connections
2. Click Credentials under the IdP Connection tab.
3. Click Configure Credentials.
4. Click Select XML Decryption Key.
If this step is not present, you have not chosen to require encryption of all or
part of the SAML assertion (see “Configuring XML Encryption Policy
(SAML 2.0)” on page 252).
To identify the decryption key:
X From the drop-down list, select the applicable certificate and click Next.
If the certificate is not in the list, click Manage Certificates to import it
(see “Digital Signing and Decryption Keys & Certificates” on page 96).
Note: If you have imported a certificate for this partner to use for
digital signing, you can reuse it for XML decryption as long as it is
an RSA certificate.
Editing and Saving Credential Configurations
From the Summary screen you can review or edit your credentials configuration.
Important: When you finish editing existing settings, you must
click Done on the Summary screen and then Save on the
Credentials screen. For a new connection, click Done and then click
Next on the Credentials screen. Save the entire connection on the
Activation screen (see “Connection Activation and Summary”
next).
Connection Activation and Summary
When you finish setting up a connection, you may choose to activate it
immediately.
Important: Regardless of whether you choose to activate a new
connection now or later, you must click Save on the Summary screen
for a new connection if you want to keep the configuration.
You can deactivate a connection at any time (for maintenance, for example).
When a connection is inactive, all SSO or SLO transactions to or from this
Administrator’s Manual
271
Chapter 6
Service Provider SSO Configuration
partner are disabled, as well as access to the WS-Trust STS for Web Service
Providers associated with this connection.
Tip: The SSO Application Endpoint near the top of the Summary screen
is an example URL that webmasters or Web application developers at
your site might use to invoke SSO for the connection. For details about
SSO and other server endpoints, including optional query parameters,
see “Application Endpoints” on page 347.
To change a Connection Status:
X Select either Active or Inactive and then click Save.
To modify a connection setting:
1. If you know which step needs to be modified, click its link under the IdP
Connection tab.
If you do not know where to change the setting, locate the currently
configured data under one of the summary headings and then click the
subheading above the data.
2. Change the information on the step screen and click Save, if available.
If Save is not available, you are in the middle of a task (see “About Tasks
and Steps” in the “Console Navigation” chapter of Getting Started); click
Next or Done until you reach a screen containing a Save button. Then
click Save and continue as needed until you return to the Main Menu.
If your modification requires related configuration changes, PingFederate
provides error messages indicating the necessary steps and then guides you to
the related screens (unless you click Cancel).
Important: Be sure to click Save whenever that button appears, if
you want to keep your changes.
Configuring IdP Auto-Connect
When your IdP partner is also using PingFederate 5 or higher (or is otherwise
able to provide interoperable SAML 2.0 metadata via HTTP on demand), you
may choose to use Auto-Connect for that partner (see “Using Auto-Connect”
on page 15). This configuration can be shared among an unlimited number of
SAML 2.0 partners.
Note: You enable the SAML 2.0 Auto-Connect profile under System
Settings (see “Choosing Roles and Protocols” on page 64).
272
PingFederate 6
Configuring IdP Auto-Connect
Once Auto-Connect is enabled on your PingFederate server, you complete the
configuration from the Main Menu under My SP Configuration. This
configuration entails:
•
Setting up a common connection for all Auto-Connect partners
•
Establishing a list of IdP partner domains authorized to use the connection
Configuring the Initial Setup
The basic configuration for IdP Auto-Connect requires only:
•
Choosing a signing certificate for authentication requests and other SAML
messages
•
Configuring user-session creation information
All other partner-connection specifications are handled automatically at
runtime.
Choosing a Signing Certificate
For Auto-Connect runtime processing, authentication requests and SLO
messages must be signed, since they are sent over either the POST or redirect
bindings (see “SAML 2.0 Profiles” in the “Supported Standards” chapter of
Getting Started).
Note: The signing certificate is embedded in your server’s AutoConnect metadata (see “Using Auto-Connect” on page 15); there is no
need to exchange certificates with your partners.
You can use the same certificate used for signing metadata (see “Configuring
Auto-Connect Metadata Signing” on page 71). If you use a different certificate,
ensure that it meets Auto-Connect validation requirements (see “Auto-Connect
Security Model” on page 17).
Configuring User-Session Creation
Configuring user-session creation for Auto-Connect is similar to configuring the
same settings for regular partner connections.
Administrator’s Manual
273
Chapter 6
Service Provider SSO Configuration
X Click Configure User-Session Creation to continue.
For configuration information, refer to sections under “User-Session
Creation” on page 226.
Note: Attributes sent from the IdP via Auto-Connect are passed to your
applications, regardless of whether they are listed in the attribute
contract (see “Creating an Attribute Contract” on page 228).
Connection Activation and Summary
When you finish configuring your IdP Auto-Connect initial setup, you may
choose to activate the common connection immediately on the Activation &
Summary screen. (No runtime processing occurs until your partner’s AutoConnect gateway is also established and a user initiates an SSO or SLO event.)
Important: Regardless of whether you choose to activate a newly
configured connection now or later, you must click Save on the
Activation & Summary screen if you want to keep the configuration.
You can deactivate the connection at any time (for maintenance, for example).
While a connection is inactive, all SSO or SLO transactions to or from AutoConnect partners are disabled.
To change a Connection Status:
X Select Active or Inactive and then click Save.
274
PingFederate 6
Configuring IdP Auto-Connect
To modify a setting:
1. Locate the currently configured setting under one of the summary headings
and then click the subheading above the data.
Note: Changes made to Auto-Connect settings will be out of sync,
temporarily, with metadata caches that any currently active
partners might be using. If your connection is in production, you
might wish to lower your server’s metadata lifetime in advance of
making configuration changes (see “Configuring Auto-Connect
Metadata Lifetime” on page 71).
2. Change the information and click Save, if available.
If Save is not available, additional, dependent changes are required; click
Next or Done until you reach a screen containing a Save button. Then
click Save and continue as needed until you return to the Main Menu.
Specifying Allowed IdP Domains
This screen provides PingFederate with a list of trusted domain names of your
Auto-Connect partners.
Normally, when PingFederate receives an SSO request from a Web application at
your site (see “/sp/startSSO.ping” on page 351), the runtime engine completes
the connection automatically using metadata obtained from a standard, public
location— http://saml.<domain_name>. (See “Using Auto-Connect” on
page 15.) Alternatively, if an Auto-Connect partner elects not to use the
standard location, you can supply the applicable URL.
To add a domain:
X Enter a Domain Name and click Add.
To specify a URL for metadata retrieval:
1. Click Advanced View.
2. Enter the Domain Name if you have not already done so.
Administrator’s Manual
275
Chapter 6
Service Provider SSO Configuration
3. Enter the Metadata Service URL.
This entry must be obtained from your Auto-Connect partner.
4. Click Add.
Note: Once you have added the URL, you cannot return to the
Basic View unless you first remove the URL value using the
procedure below.
To edit an entry:
1. Click Edit under Action for the entry.
2. Make your change and click Update.
To delete an entry:
X Click Delete under Action for the entry.
276
PingFederate 6
Chapter
7
WS-Trust STS
Configuration
The PingFederate WS-Trust STS provides security-token validation and creation
to extend SSO access to identity-enabled Web Services (see “About WS-Trust
STS” on page 2).
The chapter provides instructions for configuring the WS-Trust STS in the
administrative console and covers these main topics:
•
“Server Settings”
•
“IdP Configuration”
•
“SP Configuration”
Server Settings
To use the PingFederate WS-Trust STS for partner connections, start by
enabling the WS-Trust protocol under Server Settings on the Roles and
Protocols screen (see “Choosing Roles and Protocols” on page 64). Once the
protocol is enabled, you must identify the STS server with a unique federation
identifier for both SAML 2.0 and SAML 1.1 tokens (unless these IDs are already
established for corresponding browser-based SSO protocols).
In addition, also under Server Settings, you have the option of requiring
authentication globally for access to STS endpoints—(see “Configuring STS
Authentication” on page 279).
Enabling the WS-Trust STS
You can enable the WS-Trust STS when you first install PingFederate (see
“Running PingFederate for the First Time” in the “Installation” chapter of
Getting Started). If you have already installed PingFederate or are upgrading to a
new version, use the following procedure.
Administrator’s Manual
277
Chapter 7
WS-Trust STS Configuration
To enable WS-Trust and make the STS available for partner
connections:
1. On the Main Menu under System Settings, click Server Settings.
2. Click Roles and Protocols under the Server Settings tab.
3. Select WS-Trust for either the IdP or the SP role, or both, depending on your
requirements.
Note: PingFederate fully supports the STS with or without
selections of any of the Browser SSO protocols listed above the
WS-Trust selections. SAML 1.1 and 2.0 token handling is
independent of supported SSO protocols chosen here.
4. Click Next.
278
PingFederate 6
Server Settings
5. On the Federation Info screen, ensure all required fields are completed.
Note: Identifiers are needed for both SAML 2.0 and SAML 1.x to
enable the STS to issue either type of token when requested. If
you have not established a federation ID for either of these
protocols or do not expect to use one or the other, enter a
placeholder (in any format) and return later if needed. (For more
information about the fields on this screen, see “Specifying
Federation Information” on page 67).
6. (Optional) Click Next to go to the WS-Trust STS Settings screen (see the
next section, “Configuring STS Authentication”).
7. Click Save (on any screen).
Configuring STS Authentication
Server settings may be configured to require that client applications provide
credentials to access the PingFederate STS. This is recommended for IdP
configurations using the Username Token Processor (available separately).
For other token processors and token generators, trust in the identity of the
client is conveyed within the token itself and verified as part of processing.
However, administrators may wish to add another layer of security by limiting
access to only authenticated clients.
Note: When STS authentication is configured, the configuration applies
globally for all IdP and SP partner connections configured for STS
clients and to all token formats.
X To continue, click Configure WS-Trust STS Authentication.
Administrator’s Manual
279
Chapter 7
WS-Trust STS Configuration
Selecting Authentication Methods
You can choose either HTTP Basic or mutual SSL/TLS authentication (or both)
on the Authentication Methods screen. (Note that if both methods are
configured, all clients must authenticate using both, not one or the other.)
Configuring Basic Authentication
For HTTP Basic authentication, create username/password pairs (“Users”) for all
client applications needing access to the STS.
On the HTTP Basic Authentication screen, you can also delete users and update
account passwords.
To add users:
1. Click Create User.
2. On the User Account screen, enter a Username and Password, and
confirm the password.
Passwords must be at least six characters long, containing at least one
uppercase, one lowercase, and one numeric character.
3. Click Done.
4. Repeat the preceding steps as needed.
280
PingFederate 6
Server Settings
5. On the HTTP Basic Authentication screen, click Next.
(If you are also configuring SSL authentication, complete that configuration
and click Next to reach the Summary screen (see “Configuring Mutual SSL
Authentication” on page 281).)
6. On the Summary screen, click Done.
7. On the WS-Trust STS Settings screen, click Save.
To update an account password:
1. Click the Username.
2. On the User Account screen, enter the Current User Password and a New
Password, with confirmation.
Passwords must be at least six characters long, containing at least one
uppercase, one lowercase, and one numeric character.
3. Click Done.
4. On the HTTP Basic Authentication screen, click Done.
5. On the WS-Trust STS Settings screen, click Save.
To delete a user:
1. Click Delete under Action for the Username.
2. Click Done (or Next for new configuration).
3. Click Save when you reach the WS-Trust STS Settings screen.
Configuring Mutual SSL Authentication
When SSL authentication is selected on the Authentication Methods screen,
the configuration begins on the Mutual SSL Authentication screen.
X To continue, click Configure Mutual SSL Authentication.
Administrator’s Manual
281
Chapter 7
WS-Trust STS Configuration
Choosing Certificate Authentication Options
On the Authentication Options screen, select whether to verify client SSL
certificates against a list of Subject Distinguished Names (DNs) or a list of issuer
public certificates imported into PingFederate.
Note: You can choose both options. However, note that they are not
used alternatively at runtime; both validations are applied.
X To continue, select one or both methods and click Next.
For information about restricting access by Subject DN, see the next section.
For information about restricting access by certificate, see “Managing
Allowed Issuer Certificates” on page 283.
Managing Allowed Subject DNs
On the Allowed Subject DNs screen you can add, edit, or delete Subject DNs for
clients allowed to access the PingFederate STS.
To add DNs:
1. Enter a valid Subject DN for a partner STS client and click Add.
2. Add other DNs as needed.
3. For a new configuration, click Next or Done to continue.
282
PingFederate 6
Server Settings
4. If you are finished with a new or existing configuration, continue clicking
Done until you reach the WS-Trust STS Settings screen and then click
Save.
To edit DNs:
1. Click Edit under Action for the Subject DN.
2. Make changes and click Update.
3. Click Done.
4. If you are finished with a new or existing configuration, continue clicking
Done until you reach the WS-Trust STS Settings screen and then click
Save.
To delete entries:
1. Click Delete under Action for the Subject DN.
2. Click Done.
3. If you are finished with a new or existing configuration, continue clicking
Done until you reach the WS-Trust STS Settings screen and then click
Save.
Managing Allowed Issuer Certificates
When STS access is restricted by issuer certificate, the Allowed Issuer
Certificates screen provides a means of maintaining a list of valid certificates.
On this screen you can add or remove certificates.
To add certificates:
1. Select the certificate from the drop-down list and click Add.
If the certificate you are looking for is not in the list, click Manage
Certificates to import it from your file system.
2. Add other certificates as needed.
3. For a new configuration, click Next or Done to continue.
Administrator’s Manual
283
Chapter 7
WS-Trust STS Configuration
4. If you are finished with a new or existing configuration, continue clicking
Done until you reach the WS-Trust STS Settings screen and then click
Save.
To delete a certificate from the list:
1. Click Remove under Action for the Issuer Certificate.
2. Click Done.
3. If you are finished with a new or existing configuration, continue clicking
Done until you reach the WS-Trust STS Settings screen and then click
Save.
Using the Summary Screen
When you have finished configuring Mutual SSL Authentication, you can
review the configuration on the Summary screen. If you need to make any
changes, click the heading over the information you want to edit.
X To save a new or modified configuration, click Done on successive screens
until you reach the WS-Trust STS Settings screen and then click Save.
Using the WS-Trust STS Settings Summary Screen
When you have finished configuring WS-Trust STS Settings, you can review the
configuration on the Summary screen. If you need to make any changes, click
the heading over the information you want to edit.
X If you are editing an existing connection, click Done and on the WS-Trust
STS Settings click Save.
IdP Configuration
This section covers the IdP configuration for the PingFederate WS-Trust STS,
which involves:
•
“Configuring Token Processors”
•
“Configuring SP Connections for STS”
Configuring Token Processors
Token Processors are used to validate incoming tokens and token requests to the
STS (see “Token Processors and Generators” on page 3). Token Processors for
SAML 2.0 and SAML 1.1 tokens are included with the PingFederate
installation. This section provides guidance on configuring “instances” of either
of the SAML Token Processors. You must configure at least one processor in
order to set up an STS connection.
Only one instance of any token processor may be configured.
Additional Token Processors are available from the Ping Identity Web site (at
www.pingidentity.com/products/PingFederate-Token-Translators.cfm).
284
PingFederate 6
IdP Configuration
To begin configuring SAML 1.1 or 2.0 Token Processors:
X On the Main Menu, click Token Processors under Application Integration
Settings for My IdP Configuration.
If this link is not shown, ensure that the WS-Trust STS is enabled in Server
Settings (see “Enabling the WS-Trust STS” on page 277).
To configure a new token-processor instance:
X Click Create New Instance.
To edit an existing instance:
X Click the Instance Name and click the step you need to change.
To delete an instance:
1. Click Delete next to the Instance Name. (To undo the deletion, click
Undelete.)
Note: This option is available only if the processor instance is not in
use for a connection.
2. Click Save to confirm the deletion.
Selecting a Token Processor Type
The first step in creating a SAML token-processor instance is choosing the
processor type.
Administrator’s Manual
285
Chapter 7
WS-Trust STS Configuration
To define an instance:
1. Enter the Instance Name and Instance Id on the Type screen.
2. Select SAML 1.1 Token Processor <version> or SAML 2.0 Token
Processor <version> from the drop-down menu.
3. Click Next.
Configuring a SAML Token Processor Instance
On the Instance Configuration screen, you may use signing-certificate DN
checking to limit the valid signatures and certificates for token requests accepted
for this SAML token type. (By default, the STS validates digital signatures using
all trusted Certificate Authorities (CAs) imported into PingFederate.)
At minimum on this screen, you must indicate a unique identifier for the
PingFederate STS. To be accepted, an incoming SAML token must contain this
ID in its <audience> element.
286
PingFederate 6
IdP Configuration
To configure the token-processor instance for certificate validation:
1. Enter a URI for Audience.
This the ID for the STS for either SAML 1.1 or SAML 2.0 tokens,
depending on which processor you are configuring (see “Specifying
Federation Information” on page 67).
2. (Optional) Click the Add a new . . . link under Action for either Valid
Certificate Issuer DNs or Valid Certificate Subject DNs.
You can use both lists.
Important: When both types of validation are configured, then the
certificate used to validate signatures must match an entry in both
lists. If only Subject DNs are listed on this screen, then the
certificate Issuer DN is not checked and its Subject DN must match
one of the entries in the Subject DNs list. If only Issuer DNs are
listed here, then the certificate Subject DN is not checked and its
Issuer DN must match one of the entries in the Issuer DNs list. If
neither Issuer DNs nor Subject DNs are listed, then all certificates
are treated as valid for purposes of verification.
3. (Optional) Enter a Valid DN and click Update.
Administrator’s Manual
287
Chapter 7
WS-Trust STS Configuration
4. (Optional) Repeat the previous steps as needed to add more DNs.
Extending a Processor Contract
Token processors allow administrators to add to a built-in list of user attributes
that the processor returns from an incoming token—an extended processorattribute contract.
To add an attribute:
X Enter the attribute name in the text box and click Add.
Setting Attribute Masking
On the Token Attributes screen, you can choose to mask attribute values that
PingFederate logs from this processor instance at runtime (see “Attribute
Masking” on page 10).
To mask an attribute in log files:
X Under Mask Log Values select the attribute whose value you want to mask.
If OGNL expressions might be used to map derived values into outgoing
tokens and you want those values masked, select the related checkbox under
the Attribute list (see “Using Attribute Mapping Expressions” on page 367).
288
PingFederate 6
IdP Configuration
Editing and Saving Processor Instances
From the Summary screen, you can reach processor settings for editing.
To edit the configuration:
1. Click the heading above the information you want to change.
2. Make your changes.
3. Click Done on the configuration page and Save on the Manage Token
Processors screen.
To save a processor instance:
1. Click Done on the Summary screen.
2. Click Save on the Manage Token Processors screen.
Configuring SP Connections for STS
You can configure an STS connection to an SP partner either in conjunction
with browser-based SSO or independently.
To enable STS for a new connection, or to add the capability to an
existing connection:
1. Select the WS-Trust STS option on the Connection Type screen (see
“Choosing a Connection Type” on page 119).
Note: Before this option can be selected, the WS-Trust protocol
must be enabled in Server Settings (see “Server Settings” on
page 277)
2. Select a Default Token Type.
The Default Token Type, either SAML 1.1 or 2.0, is used when a Web
Service client does not specify in the token request what token type the STS
should issue.
Note: The Default Token Type does not need to match the Protocol
indicated on the screen for SSO (when applicable).
When the option is enabled, the configuration starts on the WS-Trust STS
screen.
Administrator’s Manual
289
Chapter 7
WS-Trust STS Configuration
X To continue, click Configure WS-Trust STS.
Configuring Protocol Settings
On the Protocol Settings screen, enter a unique identifier for your partner’s Web
Service. This identifier corresponds to the element <AppliesTo> in Requests for
Security Tokens (RSTs).
Also on this screen, options are available for adding signature or encryption
protection to outgoing SAML tokens:
•
For SAML 1.1, you can choose to generate a public key to be used in
conjunction with the “Holder of Key” designation for the assertion’s Subject
Confirmation Method (for information about HoK assertions, see, for
example, http://docs.sun.com/app/docs/doc/820-1072/6ncp48v45?a=view).
•
For SAML 2.0, you can choose to encrypt the assertion.
Note: You can make both selections if you expect requests for either
type of token. These selections are independent of the Default Token
Type selected previously (see “Configuring SP Connections for STS” on
page 289)
290
PingFederate 6
IdP Configuration
When you make either (or both) of these selections, you will be asked to choose
a signing or XML encryption certificate later in the connection setup, unless
required certificates are already in place for an existing browser-based SSO
connection. (PingFederate uses the same certificates to handle signing/
encryption requirements for both Browser SSO and WS-Trust STS—for more
information, see “Configuring Credentials” on page 168.)
Setting a Token Lifetime
Standards require a window of time during which a security token is considered
valid. Each token has a time-stamp XML element as well as elements indicating
the allowable lifetime of the token (in minutes) before and after the token time
stamp.
Field Descriptions
Field
Description
Minutes Before
The amount of time before the token was issued
during which it is to be considered valid.
Minutes After
The amount of time after the token was issued during
which it is to be considered valid.
To change the default times:
X (Optional) Edit the desired setting(s) and click Next or Save.
Configuring Token Creation
For the PingFederate STS to issue a security token in response to requests for
partner services, you must indicate what user attributes are to be included in the
token (the “attribute contract”). The attribute values sent in the token are then
derived by mapping those available from the Token Processor you select (see
“Attribute Contract Fulfillment” on page 305). As with Browser SSO, the
mapping can be augmented using local data stores, variable or constant text, or
expressions.
Details of this configuration are handled under the Token Creation task.
Administrator’s Manual
291
Chapter 7
WS-Trust STS Configuration
X To continue, click Configure Token Creation.
Defining an Attribute Contract
An attribute contract is the set of user attributes that a Web Service Client at
your site expects to receive in security tokens issued for this connection (see
“Attribute Contracts” on page 7). You identify these attributes on this screen.
To reach this screen for editing:
1. Click the connection name on the Main Menu.
Click Manage All IdP, if needed, to see a full list of connections.
2. Click WS-Trust STS under the IdP Connection tab.
3. Click Configure WS-Trust STS.
4. Click Token Creation under the WS-Trust STS tab.
5. Click Configure Token Creation
6. Click Attribute Contract on the Summary screen.
292
PingFederate 6
IdP Configuration
To add an attribute:
X Enter the attribute name in the text box and click Add.
Attribute names are case-sensitive and must correspond to the names
configured by your federation partner.
Note: In SAML assertions, the Format attribute associated with the
NameID element (as it is called for SAML 2.0; the corresponding
element is called NameIdentifier for SAML 1.x) can be set by
adding an attribute called SAML_NAME_FORMAT. The value of
that attribute can then be defined (see “Attribute Contract
Fulfillment” on page 305).
For information about the NameID or NameIdentier assertion
elements and applicable URI values, locate the relevant
specification at oasis-open.org/specs.
To modify an attribute name:
1. Click Edit under Action for the Attribute name.
2. Edit the name and click Update.
To delete an attribute:
X Click Delete for the Attribute Name.
IdP Token Processor Mapping
IdP token processors are responsible for validating incoming security tokens as
part of an STS operation (see “Token Processors and Generators” on page 3). A
configured and deployed token processor in PingFederate is known as a token
processor instance. The same instance may be mapped by multiple connections.
Map one or more IdP token processor instances into each SP connection to
handle all the token types that may be received from Web Service Clients
associated with this SP partner.
You begin this configuration on the IdP Token Processor Mapping screen,
where you choose to map instances of IdP token processors. If you have not yet
configured an instance of the token processor you intend to use within this SP
connection, see “Configuring Token Processors” on page 284.
Administrator’s Manual
293
Chapter 7
WS-Trust STS Configuration
To reach this screen for editing:
1. Click the connection name on the Main Menu.
Click Manage All IdP, if needed, to see a full list of connections.
2. Click WS-Trust STS under the IdP Connection tab.
3. Click Configure WS-Trust STS.
4. Click Token Creation under the WS-Trust STS tab.
5. Click Configure Token Creation
6. Click IdP Token Processor Mapping on the Summary screen.
To modify an existing Token Processor Instance:
X Click its Name link.
To begin configuring an Token Processor Instance for this
connection:
X Click Map New Token Processor Instance.
Selecting a Token Processor Instance
On this screen for a new connection, choose an instance of the Token Processor
needed for this connection (see “Token Processors and Generators” on page 3).
You will use attributes returned from the token processor (the token-processor
contract) to fulfill the attribute contract required for this partner and/or use
them to look up additional attributes in a user data store. You make this choice
on the next screen (see “Retrieving Attributes” on page 316).
294
PingFederate 6
IdP Configuration
X Choose a Token Processor Instance from the drop-down list and click Next
to continue.
To create or change a processor instance, as needed, click Manage Token
Processor Instances.
To reach this screen for editing:
1. Click the connection name on the Main Menu.
Click Manage All IdP, if needed, to see a full list of connections.
2. Click WS-Trust STS under the IdP Connection tab.
3. Click Configure WS-Trust STS.
4. Click Token Creation under the WS-Trust STS tab.
5. Click Configure Token Creation
6. Click IdP Token Processor Mapping on the Summary screen.
7. Click the Token Processor Instance Name.
Retrieving Attributes
For token creation, you can query local user data stores to help fulfill the
attribute contract, in conjunction with attribute values supplied by the token
processor you are using with PingFederate (see “Configuring Token Processors”
on page 284).
The values supplied by the token processor are shown under Token Processor
Contract on the Attribute Retrieval screen.
Administrator’s Manual
295
Chapter 7
WS-Trust STS Configuration
To reach this screen for editing:
1. Click the connection name on the Main Menu.
Click Manage All IdP, if needed, to see a full list of connections.
2. Click WS-Trust STS under the IdP Connection tab.
3. Click Configure WS-Trust STS.
4. Click Token Creation under the WS-Trust STS tab.
5. Click Configure Token Creation
6. Click IdP Token Processor Mapping on the Summary screen.
7. Click the Token Processor Instance Name.
8. Click Attribute Retrieval on the Summary screen.
X If you choose to “Retrieve additional attributes . . .”, then you will identify a
data store and specify lookup queries next (see the next section “Configuring
Attribute Sources and User Lookup” on page 296).
X If you “Use only the Token Processor Contract values . . .”, then you will
map values for the attribute contract next (see “Attribute Contract
Fulfillment” on page 305).
Tip: To determine whether you need to look up additional values,
compare the token-processor contract against the attribute
contract (see “Defining an Attribute Contract” on page 292). If the
attribute contract requires more information, determine whether a
local data store can supply it. (You can also choose to use text
constants or expressions for certain information—see “Attribute
Contract Fulfillment” on page 305.)
Configuring Attribute Sources and User Lookup
Attribute sources are specific database or directory locations containing
information that may be needed for the attribute contract (see “Defining an
296
PingFederate 6
IdP Configuration
Attribute Contract” on page 292). Attribute sources can be reused across
connections to other SP partners.
This portion of the connection configuration allows you to set up search
parameters for a data store.
To reach this screen for editing:
1. Click the connection name on the Main Menu.
Click Manage All IdP, if needed, to see a full list of connections.
2. Click WS-Trust STS under the IdP Connection tab.
3. Click Configure WS-Trust STS.
4. Click Token Creation under the WS-Trust STS tab.
5. Click Configure Token Creation
6. Click IdP Token Processor Mapping on the Summary screen.
7. Click the Token Processor Instance Name.
8. Click Attribute Source & User Lookup under the IdP Token Processor
Mapping tab.
If this step is not listed, then this instance is configured to use tokenprocessor values only (see “Retrieving Attributes” on page 295).
To choose a Data Store:
X Choose an Active Data Store and click Next.
A data store configuration must be defined under System Settings for use
within a connection. If the data store you want is not shown in the dropdown menu, click Manage Data Stores to add a new data store (see
“Managing Data Stores” on page 72).
Attribute Source Setup
See the following sections in this manual, depending on the type of data store:
Administrator’s Manual
297
Chapter 7
WS-Trust STS Configuration
Data Store Type
Related Manual Sections
JDBC
• “Selecting a JDBC Database Table and Columns”
on page 298
• “Configuring a Database Filter (WHERE Clause)”
on page 300
LDAP
• “Configuring an LDAP Directory Search” on
page 301
• “Configuring an LDAP Filter” on page 303
Custom
• “Configuring Custom Source Filters” on
page 305
• “Selecting Custom Source Fields” on page 305
Selecting a JDBC Database Table and Columns
When you choose to use a database source for attributes, you follow this path
through the configuration steps.
On this screen you begin to specify exactly where additional data can be found to
complete the attribute contract when you send a security token to this SP (see
“Defining an Attribute Contract” on page 292). Only one table may be used as a
source of data for a JDBC lookup.
Field Descriptions
298
Field
Description
Schema
Lists the table structure that stores information within
a database. Some databases, such as Oracle, require
selection of a specific schema for a JDBC query. Other
databases, such as MySQL, do not require selection of
a schema.
PingFederate 6
IdP Configuration
Field
Description
Table
The name of the table contained in the database. Use
the drop-down to change the table.
Columns to return
from SELECT
Displays selected table columns. Select the columns
that are associated with the desired attributes you
would like to return from the JDBC query.
To reach this screen for editing:
1. Click the connection name on the Main Menu.
Click Manage All IdP, if needed, to see a full list of connections.
2. Click WS-Trust STS under the IdP Connection tab.
3. Click Configure WS-Trust STS.
4. Click Token Creation under the WS-Trust STS tab.
5. Click Configure Token Creation
6. Click IdP Token Processor Mapping on the Summary screen.
7. Click the Token Processor Instance Name.
8. Click Database Table and Columns under the IdP Token Processor
Mapping tab.
To select a database table and columns for queries:
1. Choose a Schema file (when applicable) from the drop-down list.
2. Choose a Table from the drop-down list.
3. Choose a name under Columns to Return from Select and click Add
Column.
Repeat this step for other columns as needed.
Note: You do not need to add a column here for it to be used as
part of a search key (see “Configuring a Database Filter (WHERE
Clause)” next). Add only attributes from which you need actual
values to pass in a token.
Tip: To determine what attributes to look up during a query, click the
View Attribute Contract link to see what information must be
collected (see “Defining an Attribute Contract” on page 292). Then
determine what information is coming in from the token processor (see
“Retrieving Attributes” on page 295). Information not contained in the
token-processor contract may be pulled from the data store look-up
query.
Administrator’s Manual
299
Chapter 7
WS-Trust STS Configuration
Configuring a Database Filter (WHERE Clause)
The JDBC WHERE clause in PingFederate queries the data table you selected to
retrieve a record associated with a particular value (or values) from the incoming
security token. The clause is in the form:
WHERE column1=value1 [AND column2=value2] [OR ...]
The left side of the first variable pair uses a column name in the database table
you selected (see “Selecting a JDBC Database Table and Columns” on page 298).
The right side generally uses values passed in from a token processor (variables,
including the correct formatting, are listed under Token Processor Values—see
“Configuring Token Processors” on page 284).
You can also apply additional search criteria from your own database, using any
other columns from the targeted table.
Tip: Click “View List of Columns . . .” to see a list from which to copy
and paste.
For general information about WHERE clauses, consult your DBMS
documentation.
EXAMPLE:
userid=’${username}’
In this example userid is the name of a column in the JDBC data store. On
the right side, ’${username}’ returns the value of the username
variable from the IdP token processor.
Important: You must use the ${} syntax to retrieve the value of
the enclosed variable and use single quotation marks around the
${} characters.
300
PingFederate 6
IdP Configuration
Field Descriptions
Field
Description
Where
WHERE clause statements conditionally select data
from a table. Enter the WHERE clause statement in the
space provided. For example: WHERE
email='[email protected]'.
To reach this screen for editing:
1. Click the connection name on the Main Menu.
Click Manage All IdP, if needed, to see a full list of connections.
2. Click WS-Trust STS under the IdP Connection tab.
3. Click Configure WS-Trust STS.
4. Click Token Creation under the WS-Trust STS tab.
5. Click Configure Token Creation
6. Click IdP Token Processor Mapping on the Summary screen.
7. Click the Token Processor Instance Name.
8. Click Database Filter under the IdP Token Processor Mapping tab.
To construct the WHERE clause:
1. Enter the statement in the space provided, following the guidelines and
example above.
The initial WHERE is optional.
2. Ensure the syntax and variable names are correct.
When you click Next, you will map attribute values returned from the
database into the security token (see “Attribute Contract Fulfillment” on
page 305).
Configuring an LDAP Directory Search
When you choose to use an LDAP source for attributes, you follow this path
through the configuration steps.
On this screen you specify the branch of your LDAP hierarchy where you want
PingFederate to look up user data.
Administrator’s Manual
301
Chapter 7
WS-Trust STS Configuration
Field Descriptions
Field
Description
Base DN
The base distinguished name of the tree structure in
which the search begins. This field is optional if
records are located at the LDAP root.
Search Scope
Determines the node depth of the query. Select
Subtree, One level or Object.
Root Object Class
The class containing the attributes you want.
Attributes to return
from search
A list of added from the drop-down list below. Subject
DN is a default attribute, which may be used as the
primary user identifier.
To reach this screen for editing:
1. Click the connection name on the Main Menu.
Click Manage All IdP, if needed, to see a full list of connections.
2. Click WS-Trust STS under the IdP Connection tab.
3. Click Configure WS-Trust STS.
4. Click Token Creation under the WS-Trust STS tab.
5. Click Configure Token Creation
6. Click IdP Token Processor Mapping on the Summary screen.
7. Click the Token Processor Instance Name.
8. Click LDAP Directory Search under the IdP Token Processor Mapping
tab.
302
PingFederate 6
IdP Configuration
To select LDAP attributes:
1. (Optional) Enter a Base DN.
2. Select a Search Scope.
3. Select a Root Object Class.
4. Under Attributes to return from search, choose an attribute and click Add
Attribute.
Note that the attribute Subject DN is always returned by default.
5. Repeat the last step for other attributes as needed.
6. (Optional) Change the Search Scope or the Root Object Class if you want
attributes from other locations.
Note: You do not need to add an attribute here for it to be used in a
search filter (see “Configuring an LDAP Filter”). Add only attributes
from which you need actual values to pass into the outgoing
security token.
Configuring an LDAP Filter
The LDAP filter queries the data you selected to retrieve a record associated with
a particular value (or values) from the incoming token. The filter is in the form:
attribute=${value}
The left-side variable is an attribute you selected earlier (see “Configuring an
LDAP Directory Search” on page 301).
The right side generally uses values passed in from the security token (variables,
including the correct syntax, are listed under Security Token Values—see
“Configuring Token Processors” on page 284).
You can also apply additional search criteria from your data store, using any other
attributes from the targeted object classes.
Tip: Click “View List of Available LDAP Attributes” for a list from
which you can copy and paste.
For general information about search filters, consult your LDAP documentation.
Administrator’s Manual
303
Chapter 7
WS-Trust STS Configuration
Field Descriptions
Field
Description
Filter
Narrows a search to locate requested data by either
including or excluding specific records. An LDAP filter
includes the attributes in the search and the value or
range of values that the search is attempting to match.
Searches are conducted by using three components:
1) at least one attribute (attribute data type) to search
on, 2) a search filter operator that will determine what
to match, and 3) the value of the attribute being
sought. Searches must have at least one of each of
these three components.
To reach this screen for editing:
1. Click the connection name on the Main Menu.
Click Manage All IdP, if needed, to see a full list of connections.
2. Click WS-Trust STS under the IdP Connection tab.
3. Click Configure WS-Trust STS.
4. Click Token Creation under the WS-Trust STS tab.
5. Click Configure Token Creation
6. Click IdP Token Processor Mapping on the Summary screen.
7. Click the Token Processor Instance Name.
8. Click LDAP Filter under the IdP Token Processor Mapping tab.
304
PingFederate 6
IdP Configuration
To construct the LDAP filter:
1. Enter the statement in the space provided, following the guidelines and
example above.
Note: If you used an anonymous binding to create this LDAP
connection, your access might be restricted (see “Configuring an
LDAP Connection” on page 78).
2. Ensure the syntax and variable names are correct.
3. Click Next.
Configuring Custom Source Filters
When you choose to use a custom source for attributes, you follow this path
through the configuration steps.
On this screen you specify a filter, or lookup query, for your custom data source.
This screen display and the syntax of the filter depends on your developer’s
implementation of the custom source SDK.
Selecting Custom Source Fields
On the Configure Custom Source Fields screen, you can choose from among
the fields shown to map to the attribute contract. These choices are supplied by
the driver implementation. Select only those needed to fulfill the attribute
contract for this partner connection.
Attribute Contract Fulfillment
You map attributes for outgoing security tokens for this partner on the Attribute
Contract Fulfillment screen.
Map each attribute to fulfill the Attribute Contract from one of these
Sources:
•
Token
When you make this selection, the associated Value drop-down list is
populated by the token processor.
Administrator’s Manual
305
Chapter 7
WS-Trust STS Configuration
•
LDAP/JDBC/Custom
Values are returned from your attribute source (if you are using data store—
see “Retrieving Attributes” on page 295). When you make this selection, the
Value list is populated by the LDAP, JDBC or Custom attributes you
identified as an Attribute Source (see “Configuring an LDAP Directory
Search” on page 301, “Selecting a JDBC Database Table and Columns” on
page 298, or “Configuring Custom Source Filters” on page 305).
•
Text
The value is what you enter. This can be text only, or you can mix text with
references to any of the values from the incoming token, using the
${attribute} syntax.
You can also enter values from your data store, when applicable, using this
syntax:
${ds.attribute}
where attribute is any of the data store attributes you have selected.
Tip: Another selection in the Source drop-down menu, Expressions,
may be enabled (see “Using Attribute Mapping Expressions” on
page 367). This option provides more complex mapping capabilities—
for example, transforming incoming values into different formats. All of
the variables available for text entries are also available for expressions.
To reach this screen for editing:
1. Click the connection name on the Main Menu.
Click Manage All IdP, if needed, to see a full list of connections.
2. Click WS-Trust STS under the IdP Connection tab.
3. Click Configure WS-Trust STS.
4. Click Token Creation under the WS-Trust STS tab.
5. Click Configure Token Creation
6. Click IdP Token Processor Mapping on the Summary screen.
7. Click the Token Processor Instance Name.
8. Click Attribute Contract Fulfillment under the IdP Token Processor
Mapping tab.
To map attributes:
1. Choose a Source for each Target attribute.
2. Choose (or enter) a Value for each Attribute.
See “Map each attribute to fulfill the Attribute Contract from one of these
Sources:” on page 305. All values must be mapped.
3. Click Next.
306
PingFederate 6
IdP Configuration
Using the Mapping Summary Screen
When you have finished configuring IdP Token Processor Mapping, you can
review the configuration on the Summary screen. If you need to make any
changes, click the heading over the information you want to edit.
X If you are editing an existing connection, click Done on successive screens
until you reach the WS-Trust STS screen, and then click Save.
To save a new configuration:
1. Click Done to return to the IdP Token Processor Mapping screen.
2. Click Next to go to the Token Creation Summary screen, and then click
Done.
3. On the Token Creation screen, click Done.
4. On the WS-Trust STS screen, click Save.
Using the Token Creation Summary Screen
When you have finished configuring Token Creation, you can review the
configuration on the Summary screen. If you need to make any changes, click
the heading over the information you want to edit.
X If you are editing an existing connection, click Done on successive screens
until you reach the WS-Trust STS screen, and then click Save.
Administrator’s Manual
307
Chapter 7
WS-Trust STS Configuration
SP Configuration
This section covers the SP configuration for STS, which involves:
•
“Configuring Token Generators”
•
“Configuring IdP Connections for STS”
Configuring Token Generators
Token Generators are used to issue security tokens that can be consumed by Web
Services at your site (see “Token Processors and Generators” on page 3). Token
Generators for SAML 2.0 and SAML 1.1 tokens are included with the
PingFederate installation. This section provides guidance on configuring
“instances” of either of the SAML Token Generators. You must configure at least
one generator in order to set up an STS connection.
Only one instance of any Token Generator may be configured.
Additional Token Generators are available from the Ping Identity Web site (at
www.pingidentity.com/products/PingFederate-Token-Translators.cfm).
To begin configuring SAML 1.1 or 2.0 Token Generators:
X On the Main Menu, click Token Generators under Application Integration
Settings for My SP Configuration.
If this link is not shown, ensure that the WS-Trust STS is enabled in Server
Settings (see “Enabling the WS-Trust STS” on page 277).
To configure a new token-generator instance:
X Click Create New Instance
To edit an existing instance:
X Click the Instance Name and click the step you need to change.
308
PingFederate 6
SP Configuration
To delete an instance:
1. Click Delete next to the Instance Name. (To undo the deletion, click
Undelete.)
Note: This option is available only if the generator instance is not in
use for a connection.
2. Click Save to confirm the deletion.
Selecting a Token Generator Type
The first step in creating a SAML token-generator instance is choosing the
generator type.
To define an instance:
1. Enter the Instance Name and Instance Id on the Type screen.
2. Select SAML 1.1 Token Generator <version> or SAML 2.0 Token
Generator <version> from the drop-down menu.
3. Click Next.
Configuring a Token Generator Instance
On the Instance Configuration screen, you specify parameters for generated
SAML tokens.
Administrator’s Manual
309
Chapter 7
WS-Trust STS Configuration
To configure the token-generator instance:
X Provide information for all required fields—refer to screen Descriptions for
information about each field.
If you have not yet imported a Signing Certificate, click Manage Signing
Certificates.
The Audience entry is used for the <audience> element of the generated
SAML token.
Extending a Generator Contract
Token generators allow administrators to add to a built-in list of user attributes
that the generator includes in the outgoing token—an extended generatorattribute contract.
310
PingFederate 6
SP Configuration
To add an attribute:
X Enter the attribute name in the text box and click Add.
Editing and Saving Generator Instances
From the Summary screen, you can reach token-generator settings for editing.
To edit the configuration:
1. Click the heading above the information you want to change.
2. Make your changes.
3. Click Done on the configuration page and Save on the Manage Token
Generators screen.
To save a generator instance:
1. Click Done on the Summary screen.
2. Click Save on the Manage Token Generators screen.
Configuring IdP Connections for STS
You can configure an STS connection to an IdP partner either in conjunction
with browser-based SSO or independently.
To enable STS for a new connection, or to add the capability to an
existing connection:
X Select the WS-Trust STS option on the Connection Type screen (see
“Choosing a Connection Type” on page 216).
Note: Before this option can be selected, the WS-Trust protocol
must be enabled in Server Settings (see “Server Settings” on
page 277)
Administrator’s Manual
311
Chapter 7
WS-Trust STS Configuration
When the option is enabled, the configuration starts on the WS-Trust STS
screen.
X To continue, click Configure WS-Trust STS.
Configuring Protocol Settings
On the Protocol Settings screen, choose whether to validate incoming SAML
tokens or to validate and then also generate different tokens to enable SSO
access to Web Services at your site.
Also on this screen, if incoming SAML 2.0 tokens for this connection are
required to be encrypted, select the checkbox for decrypting assertions. When
you make this selection, you will be required to choose a decryption certificate
for this partner later in the connection configuration (if one is not already
selected for Browser SSO purposes—see “Selecting a Decryption Key” on
page 270).
X If you choose not to generate new tokens, then no further settings are
needed for this task—click Next and refer to “Using the Token Generation
Summary Screen” on page 327 for instructions on saving this configuration.
You will be asked later to choose a certificate with which to verify the signature
on the incoming SAML token (see “Selecting Signature Verification
Certificates” on page 173).
312
PingFederate 6
SP Configuration
Configuring Token Generation
For the PingFederate STS to issue a security token that meets identity
requirements of Web Services at your site, you must indicate what user attributes
are included in the incoming token (the “attribute contract”). The attribute
values from the incoming token can be then mapped to attributes in the token
generator you select (see “Attribute Contract Fulfillment” on page 325). As with
Browser SSO, the mapping can be augmented using local data stores, variable or
constant text, or expressions.
Details of this configuration are handled under the Token Generation task.
X To continue, click Configure Token Creation.
Defining an Attribute Contract
An attribute contract is the set of user attributes expected in incoming security
tokens (see “Attribute Contracts” on page 7). You identify these attributes on
this screen.
Administrator’s Manual
313
Chapter 7
WS-Trust STS Configuration
To reach this screen for editing:
1. Click the connection name on the Main Menu.
Click Manage All SP, if needed, to see a full list of connections.
2. Click WS-Trust STS under the SP Connection tab.
3. Click Configure WS-Trust STS.
4. Click Token Generation under the WS-Trust STS tab.
If this step is not shown, token generation is not selected for the connection
(see “Configuring Protocol Settings” on page 312).
5. Click Configure Token Generation
6. Click Attribute Contract on the Summary screen.
To add an attribute:
1. Enter the attribute name in the text box.
Attribute names are case-sensitive and must correspond to the names
configured by your federation partner.
2. Optionally, select the checkbox under Mask Values in Log.
3. Click Add.
To modify an attribute name or masking status:
1. Click Edit under Action for the Attribute name.
2. Edit the name and/or change the masking status, and then click Update.
To delete an attribute:
X Click Delete for the Attribute Name.
Mapping Token Generators
Token generators provide a mechanism through which PingFederate can
generate a local token based upon an incoming SAML token, including mapping
user attributes to be included in the generated token. A configured and deployed
token generator in PingFederate is known as a token-generator instance.
You can map one or more token generator instances into each IdP connection to
satisfy multiple session-management requirements where needed. The same
instances may be mapped by multiple connections.
The configuration begins on the Token Generator Mapping & User Lookup
screen. If you have not yet configured an instance of a token generator you need
for this connection, see “Configuring Token Generators” on page 308.
314
PingFederate 6
SP Configuration
To reach this screen for editing:
1. Click the connection name on the Main Menu.
Click Manage All SP, if needed, to see a full list of connections.
2. Click WS-Trust STS under the SP Connection tab.
3. Click Configure WS-Trust STS.
4. Click Token Generation under the WS-Trust STS tab.
If this step is not shown, token generation is not selected for the connection
(see “Configuring Protocol Settings” on page 312).
5. Click Configure Token Generation
6. Click Token Generator Mapping & User Lookup on the Summary
screen.
To modify an existing Token Generator Instance:
X Click its Name link.
To begin configuring an Token Generator Instance for this
connection:
X Click Map New Token Generator Instance.
Selecting a Token Generator Instance
On this screen for a new connection, choose an instance of the Token Generator
needed for this connection (see “Token Processors and Generators” on page 3).
You will use attributes contained in the incoming security token to fulfill the
token generator contract for this STS connection and/or use them to look up
additional attributes in a user data store. You make this choice on the next screen
(see “Retrieving Attributes” on page 295).
Administrator’s Manual
315
Chapter 7
WS-Trust STS Configuration
X Choose a Token Generator Instance from the drop-down list and click Next
to continue.
To create or change a Token Generator Instance, as needed, click Manage
Token Generator Instances.
Retrieving Attributes
For token generation, you can query local user data stores to help fulfill the
token-generator contract, in conjunction with attribute values supplied by the
incoming token.
The values supplied by the token are shown under Attribute Contract on the
Attribute Retrieval screen.
To reach this screen for editing:
1. Click the connection name on the Main Menu.
Click Manage All SP, if needed, to see a full list of connections.
2. Click WS-Trust STS under the SP Connection tab.
3. Click Configure WS-Trust STS.
4. Click Token Generation under the WS-Trust STS tab.
If this step is not shown, token generation is not selected for the connection
(see “Configuring Protocol Settings” on page 312).
5. Click Configure Token Generation
316
PingFederate 6
SP Configuration
6. Click Token Generator Mapping & User Lookup on the Summary
screen.
7. Click the Token Generator Instance Name.
8. Click Attribute Retrieval on the Summary screen.
X If you choose to look up additional information, then you will identify a data
store and specify lookup queries next (see the next section “Choosing a Data
Store” on page 317).
X If you use only the attributes available (the default), then you will map
values for the attribute contract next (see “Attribute Contract Fulfillment”
on page 325).
Tip: To determine whether you need to look up additional values,
compare the attribute contract against the token-generator contract
on the previous screen (see “Selecting a Token Generator
Instance” on page 315). If the token-generator contract requires
more information, determine whether your local data stores can
supply it. (You can also choose to use text constants or expressions
for certain information—see “Attribute Contract Fulfillment” on
page 325.)
Choosing a Data Store
This portion of the connection configuration allows you to set up search
parameters for a data store.
To reach this screen for editing:
1. Click the connection name on the Main Menu.
Click Manage All SP, if needed, to see a full list of connections.
2. Click WS-Trust STS under the SP Connection tab.
3. Click Configure WS-Trust STS.
4. Click Token Generation under the WS-Trust STS tab.
If this step is not shown, token generation is not selected for the connection
(see “Configuring Protocol Settings” on page 312).
Administrator’s Manual
317
Chapter 7
WS-Trust STS Configuration
5. Click Configure Token Generation
6. Click Token Generator Mapping & User Lookup on the Summary
screen.
7. Click the Token Generator Instance Name.
8. Click Data Store under the Token Generator Mapping & User Lookup tab.
If this step is not presented, this Token Generator Instance is not configured
to look up user attributes in a data store (see “Retrieving Attributes” on
page 316).
To choose a Data Store:
X Choose an Active Data Store and click Next.
A data store configuration must be defined under System Settings for use
within a connection. If the data store you want is not shown in the dropdown menu, click Manage Data Stores to add a new data store (see
“Managing Data Stores” on page 72).
Attribute Source Setup
See the following sections in this manual, depending on the type of data store:
Data Store Type
Related Manual Sections
JDBC
• “Selecting a JDBC Database Table and Columns”
on page 318
• “Configuring a Database Filter (WHERE Clause)”
on page 320
LDAP
• “Configuring an LDAP Directory Search” on
page 322
• “Configuring an LDAP Filter” on page 324
Custom
• “Configuring Custom Source Filters” on
page 325
• “Selecting Custom Source Fields” on page 325
Selecting a JDBC Database Table and Columns
When you choose to use a database source for attributes, you follow this path
through the configuration steps.
On this screen you begin to specify exactly where additional data can be found to
complete the token-generator contract (see “Retrieving Attributes” on
page 316). Only one table may be used as a source of data for a JDBC lookup.
318
PingFederate 6
SP Configuration
Field Descriptions
Field
Description
Schema
Lists the table structure that stores information within
a database. Some databases, such as Oracle, require
selection of a specific schema for a JDBC query. Other
databases, such as MySQL, do not require selection of
a schema.
Table
The name of the table contained in the database. Use
the drop-down to change the table.
Columns to return
from SELECT
Displays selected table columns. Select the columns
that are associated with the desired attributes you
would like to return from the JDBC query.
To reach this screen for editing:
1. Click the connection name on the Main Menu.
Click Manage All SP, if needed, to see a full list of connections.
2. Click WS-Trust STS under the SP Connection tab.
3. Click Configure WS-Trust STS.
4. Click Token Generation under the WS-Trust STS tab.
If this step is not shown, token generation is not selected for the connection
(see “Configuring Protocol Settings” on page 312).
5. Click Configure Token Generation
6. Click Token Generator Mapping & User Lookup on the Summary
screen.
7. Click the Token Generator Instance Name.
8. Click Database Table and Columns under the Token Generator Mapping
& User Lookup tab.
Administrator’s Manual
319
Chapter 7
WS-Trust STS Configuration
To select a database table and columns for queries:
1. Choose a Schema file (when applicable) from the drop-down list.
2. Choose a Table from the drop-down list.
3. Choose a name under Columns to Return from Select and click Add
Column.
Repeat this step for other columns as needed.
Note: You do not need to add a column here for it to be used as
part of a search key (see “Configuring a Database Filter (WHERE
Clause)” next). Add only attributes from which you need actual
values to pass in a token.
Tip: To determine what attributes to look up during a query, click the
View Attribute Contract link to see what information must be
collected (see “Defining an Attribute Contract” on page 313). Then
determine what information is coming in from the token processor (see
“Retrieving Attributes” on page 316). Information not contained in the
token-processor contract may be pulled from the data store look-up
query.
Configuring a Database Filter (WHERE Clause)
The JDBC WHERE clause in PingFederate queries the data table you selected to
retrieve a record associated with a particular value (or values) from the incoming
security token. The clause is in the form:
WHERE column1=value1 [AND column2=value2] [OR ...]
The left side of the first variable pair uses a column name in the database table
you selected (see “Selecting a JDBC Database Table and Columns” on page 318).
The right side generally uses values passed in from the incoming SAML token
(variables, including the correct formatting, are listed under Assertion Values).
You can also apply additional search criteria from your own database, using any
other columns from the targeted table.
Tip: Click “View List of Columns . . .” to see a list from which to copy
and paste.
For general information about WHERE clauses, consult your DBMS
documentation.
320
PingFederate 6
SP Configuration
EXAMPLE:
userid=’${username}’
In this example userid is the name of a column in the JDBC data store. On
the right side, ’${username}’ returns the value of the username
variable from the IdP token processor.
Important: You must use the ${} syntax to retrieve the value of
the enclosed variable and use single quotation marks around the
${} characters.
Field Descriptions
Field
Description
Where
WHERE clause statements conditionally select data
from a table. Enter the WHERE clause statement in the
space provided. For example: WHERE
email='[email protected]'.
To reach this screen for editing:
1. Click the connection name on the Main Menu.
Click Manage All SP, if needed, to see a full list of connections.
2. Click WS-Trust STS under the SP Connection tab.
3. Click Configure WS-Trust STS.
4. Click Token Generation under the WS-Trust STS tab.
If this step is not shown, token generation is not selected for the connection
(see “Configuring Protocol Settings” on page 312).
5. Click Configure Token Generation
Administrator’s Manual
321
Chapter 7
WS-Trust STS Configuration
6. Click Token Generator Mapping & User Lookup on the Summary
screen.
7. Click the Token Generator Instance Name.
8. Click Database Filter from the steps list under the Token Generator
Mapping & User Lookup tab.
To construct the WHERE clause:
1. Enter the statement in the space provided, following the guidelines and
example above.
The initial WHERE is optional.
2. Ensure the syntax and variable names are correct.
When you click Next, you will map attribute values returned from the
database into the security token (see “Attribute Contract Fulfillment” on
page 325).
Configuring an LDAP Directory Search
When you choose to use an LDAP source for attributes, you follow this path
through the configuration steps.
On this screen you specify the branch of your LDAP hierarchy where you want
PingFederate to look up user data.
Field Descriptions
322
Field
Description
Base DN
The base distinguished name of the tree structure in
which the search begins. This field is optional if
records are located at the LDAP root.
PingFederate 6
SP Configuration
Field
Description
Search Scope
Determines the node depth of the query. Select
Subtree, One level or Object.
Root Object Class
The class containing the attributes you want.
Attributes to return
from search
A list of added from the drop-down list below. Subject
DN is a default attribute, which may be used as the
primary user identifier.
To reach this screen for editing:
1. Click the connection name on the Main Menu.
Click Manage All SP, if needed, to see a full list of connections.
2. Click WS-Trust STS under the SP Connection tab.
3. Click Configure WS-Trust STS.
4. Click Token Generation under the WS-Trust STS tab.
If this step is not shown, token generation is not selected for the connection
(see “Configuring Protocol Settings” on page 312).
5. Click Configure Token Generation
6. Click Token Generator Mapping & User Lookup on the Summary
screen.
7. Click the Token Generator Instance Name.
8. Click LDAP Directory Search under the Token Generator Mapping &
User Lookup tab.
To select LDAP attributes:
1. (Optional) Enter a Base DN.
2. Select a Search Scope.
3. Select a Root Object Class.
4. Under Attributes to return from search, choose an attribute and click Add
Attribute.
Note that the attribute Subject DN is always returned by default.
5. Repeat the last step for other attributes as needed.
6. (Optional) Change the Search Scope or the Root Object Class if you want
attributes from other locations.
Note: You do not need to add an attribute here for it to be used in a
search filter (see “Configuring an LDAP Filter”). Add only attributes
from which you need actual values to pass into the outgoing
security token.
Administrator’s Manual
323
Chapter 7
WS-Trust STS Configuration
Configuring an LDAP Filter
The LDAP filter queries the data you selected to retrieve a record associated with
a particular value (or values) from the incoming token. The filter is in the form:
attribute=${value}
The left-side variable is an attribute you selected earlier (see “Configuring an
LDAP Directory Search” on page 322).
The right side generally uses values passed in from the incoming SAML token
(variables, including the correct syntax, are listed under Assertion Values).
You can also apply additional search criteria from your data store, using any other
attributes from the targeted object classes.
Tip: Click “View List of Available LDAP Attributes” for a list from
which you can copy and paste.
For general information about search filters, consult your LDAP documentation.
Field Descriptions
324
Field
Description
Filter
Narrows a search to locate requested data by either
including or excluding specific records. An LDAP filter
includes the attributes in the search and the value or
range of values that the search is attempting to match.
Searches are conducted by using three components:
1) at least one attribute (attribute data type) to search
on, 2) a search filter operator that will determine what
to match, and 3) the value of the attribute being
sought. Searches must have at least one of each of
these three components.
PingFederate 6
SP Configuration
To reach this screen for editing:
1. Click the connection name on the Main Menu.
Click Manage All SP, if needed, to see a full list of connections.
2. Click WS-Trust STS under the SP Connection tab.
3. Click Configure WS-Trust STS.
4. Click Token Generation under the WS-Trust STS tab.
If this step is not shown, token generation is not selected for the connection
(see “Configuring Protocol Settings” on page 312).
5. Click Configure Token Generation
6. Click Token Generator Mapping & User Lookup on the Summary
screen.
7. Click the Token Generator Instance Name.
8. Click LDAP Filter under the Token Generator Mapping & User Lookup
tab.
To construct the LDAP filter:
1. Enter the statement in the space provided, following the guidelines and
example above.
Note: If you used an anonymous binding to create this LDAP
connection, your access might be restricted (see “Configuring an
LDAP Connection” on page 78).
2. Ensure the syntax and variable names are correct.
3. Click Next.
Configuring Custom Source Filters
When you choose to use a custom source for attributes, you follow this path
through the configuration steps.
On this screen you specify a filter, or lookup query, for your custom data source.
This screen display and the syntax of the filter depends on your developer’s
implementation of the custom source SDK.
Selecting Custom Source Fields
On the Configure Custom Source Fields screen, you can choose from among
the fields shown to map to the token processor contract. These choices are
supplied by the driver implementation. Select only those needed to fulfill the
attribute contract for this partner connection.
Attribute Contract Fulfillment
You map attributes for outgoing security tokens for this partner on the Attribute
Contract Fulfillment screen.
Administrator’s Manual
325
Chapter 7
WS-Trust STS Configuration
Map each attribute to fulfill the Token Generator Contract from one
of these Sources:
•
Assertion
When you make this selection, the associated Value drop-down list is
populated by the incoming SAML token (“Assertion”).
•
LDAP/JDBC/Custom
Values are returned from the selected data store (see “Retrieving Attributes”
on page 316). When you make this selection, the Value list is populated by
the LDAP, JDBC or Custom attributes specified in previous screens (see
“Configuring an LDAP Directory Search” on page 322, “Selecting a JDBC
Database Table and Columns” on page 318, or “Configuring Custom Source
Filters” on page 325).
•
Text
The value is what you enter. This can be text only, or you can mix text with
references to any of the values from the incoming token, using the
${attribute} syntax.
You can also enter values from your data store, when applicable, using this
syntax:
${ds.attribute}
where attribute is any of the data store attributes you have selected.
Tip: Another selection in the Source drop-down menu, Expressions,
may be enabled (see “Using Attribute Mapping Expressions” on
page 367). This option provides more complex mapping capabilities—
for example, transforming incoming values into different formats. All of
the variables available for text entries are also available for expressions.
To reach this screen for editing:
1. Click the connection name on the Main Menu.
Click Manage All SP, if needed, to see a full list of connections.
2. Click WS-Trust STS under the SP Connection tab.
3. Click Configure WS-Trust STS.
326
PingFederate 6
SP Configuration
4. Click Token Generation under the WS-Trust STS tab.
If this step is not shown, token generation is not selected for the connection
(see “Configuring Protocol Settings” on page 312).
5. Click Configure Token Generation
1. Click Token Generator Mapping & User Lookup on the Summary
screen.
2. Click the Token Generator Instance Name.
3. Click Attribute Contract Fulfillment under the Token Generator
Mapping & User Lookup tab.
To map attributes:
1. Choose a Source for each Target attribute.
2. Choose (or enter) a Value for each Attribute.
See “Map each attribute to fulfill the Token Generator Contract from one of
these Sources:” on page 326. All values must be mapped.
3. Click Next.
Using the Mapping Summary Screen
When you have finished configuring Token Generator Mapping & User Lookup,
you can review the configuration on the Summary screen. If you need to make
any changes, click the heading over the information you want to edit.
X If you are editing an existing connection, click Done on successive screens
until you reach the WS-Trust STS screen, and then click Save.
To save a new configuration:
1. Click Done to return to the Token Generator Mapping & User Lookup
screen.
2. Click Next to go to the Token Generation Summary screen, and then click
Done.
3. On the Token Generation screen, click Done.
4. On the WS-Trust STS screen, click Save.
Using the Token Generation Summary Screen
When you have finished configuring Token Generation, you can review the
configuration on the Summary screen. If you need to make any changes, click
the heading over the information you want to edit.
X If you are editing an existing connection, click Done on successive screens
until you reach the WS-Trust STS screen, and then click Save.
Administrator’s Manual
327
Chapter 7
WS-Trust STS Configuration
328
PingFederate 6
Appendix
A
OpenToken Adapter
Configuration
In order to transfer identity and other user information between the
PingFederate server and an end application, the product architecture allows for
custom adapters to be deployed with the server (see “SSO Integration Kits and
Adapters” on page 4).
PingFederate ships with a deployed OpenToken Adapter, which uses a secure
token format (OpenToken) to transfer user attributes between an application
and the PingFederate server. On the IdP side, the OpenToken Adapter allows
the PingFederate server to receive a user’s identity from the IdP application. On
the SP side, the OpenToken Adapter can be used to transfer user-identity
information to the target SP application.
Specialized application integration kits are available from www.pingidentity.com.
Many kits leverage the OpenToken Adapter to integrate applications with the
PingFederate server. The agent portions of the integration kits reside with the
application and use the OpenToken to communicate with the OpenToken
Adapter.
Note: To integrate applications for use with the OpenToken Adapter,
download an integration kit for PingFederate from
www.pingidentity.com and follow instructions for installing and using
Agent Toolkits in the accompanying documentation. Follow the
configuration instructions in this appendix to set up the OpenToken
Adapter to use with your applications.
Administrator’s Manual
329
Appendix A
OpenToken Adapter Configuration
The following figure shows a basic IdP-initiated SSO scenario using
PingFederate with the Java Integration Kit on both sides of an identity
federation.
*EFOUJUZ1SPWJEFS
4FSWJDF1SPWJEFS
'FEFSBUJPO4FSWFS
'FEFSBUJPO4FSWFS
2SHQ7RNHQ
$GDSWHU
2SHQ7RNHQ
$GDSWHU
$JHQW
7RRONLW
IRU-DYD
2SHQ7RNHQ
440
$JHQW
7RRONLW
IRU-DYD
2SHQ7RNHQ
4".-
#SPXTFS*OUFSGBDF
Processing Steps
1. A user initiates an SSO transaction.
2. The IdP application inserts attributes into the Agent Toolkit for Java, which
encrypts the data internally and generates an OpenToken.
Attributes are encrypted and decrypted using the Java Cryptography
Extension (JCE). For more information, see http://java.sun.com/products/
jce.
3. A request containing the OpenToken is redirected to the PingFederate IdP
server.
4. The server invokes the OpenToken IdP Adapter, which retrieves the
OpenToken, decrypts, parses, and passes it to the PingFederate IdP server.
The PingFederate IdP server then generates a Security Assertion Markup
Language (SAML) assertion.
5. The SAML assertion is sent to the SP site.
6. The PingFederate SP server parses the SAML assertion and passes the user
attributes to the OpenToken SP Adapter. The Adapter encrypts the data
internally and generates an OpenToken.
7. A request containing the OpenToken is redirected to the SP application.
8. The Agent Toolkit for Java decrypts and parses the OpenToken and makes
the attributes available to the SP Application.
330
PingFederate 6
Configuring the IdP OpenToken Adapter
Configuring the IdP OpenToken Adapter
1. If you have not already done so, log on to the PingFederate administrative
console and click Adapters under My IdP Configuration on the Main
Menu.
2. On the Manage Adapter Instances screen, click Create New Adapter
Instance.
3. On the Adapter Type screen, enter an Instance Name and Instance Id,
select OpenToken Adapter 2.3 (or higher) as the Type, and click Next.
The Instance Id may not contain spaces or underscores.
4. On the IdP Adapter screen, enter the values as described for the adapter
configuration.
These values are dependent on your developer’s implementation.
Administrator’s Manual
331
Appendix A
OpenToken Adapter Configuration
5. (Optional) Click Show Advanced Fields to reconfigure default settings for
the OpenToken, as needed.
Refer to the on-screen field descriptions for more information.
6. Click Next.
7. On the Actions screen, click Download under Action Invocation Link.
8. On the next screen, click Export and save the properties file.
The values in the resulting file, agent-config.txt, represents the
console configuration and are used by the IdP application. Refer to your
respective Integration Kit User Guide for more information.
9. (Optional) On the Extended Contract screen, you can configure additional
attributes for the adapter (see “Extending an Adapter Contract” on
page 109).
332
PingFederate 6
Configuring the IdP OpenToken Adapter
10. Click Next.
11. On the Adapter Attributes screen, select the subject checkbox under
Pseudonym (optionally, select other attributes, if you added any at Step 9).
This selection is used if any of your SP partners will make use of pseudonyms
for account linking (see “Account Linking” on page 5).
Note: A selection is required regardless of whether you will use
pseudonyms for account linking. This allows account linking to be
used later without having to delete and reconfigure the adapter.
Ensure that you choose at least one attribute that is unique for each
user (for example, email) to prevent the same pseudonym from
being assigned to multiple users.
You can also choose to mask the values of any or all attributes that
PingFederate logs from the adapter at runtime (see “Attribute Masking” on
page 10).
12. Click Next.
13. On the Summary screen, review the configuration and click Done.
You can also click any heading to go back and change information.
Administrator’s Manual
333
Appendix A
OpenToken Adapter Configuration
14. On the Manage Adapter Instances screen, click Save.
Important: You must click Save if you wish to retain the adapter
configuration.
Configuring the SP OpenToken Adapter
1. If you have not already done so, log on to the PingFederate administrative
console and click Adapters under My SP Configuration on the Main
Menu.
2. On the Manage Adapter Instances screen, click Create New Adapter
Instance.
3. Enter an Instance Name and Instance Id, select OpenToken Adapter 2.3
(or higher) as the Type, and click Next.
The Instance Id may not contain spaces or underscores.
4. Enter values for the adapter configuration on the Instance Configuration
screen.
These values are dependent on your developer’s implementation.
334
PingFederate 6
Configuring the SP OpenToken Adapter
5. (Optional) Click Show Advanced Fields to reconfigure default settings for
the OpenToken, as needed.
Refer to the on-screen descriptions for more information.
6. Click Next.
7. On the Actions screen, click Download under Action Invocation Link.
8. On the next screen, click Export and save the properties file.
The values in the resulting file, agent-config.txt, are set by the console
configuration and used by the SP application. Refer to your respective
Integration Kit User Guide for more information.
9. Click Next.
10. (Optional) On the Extended Contract screen, you can configure additional
attributes for the adapter (see “Extending an Adapter Contract” on
page 109).
11. Click Next.
12. On the Summary screen, review the configuration and click Done.
You can also click any heading to go back and change information.
Administrator’s Manual
335
Appendix A
OpenToken Adapter Configuration
13. On the Manage Adapter Instances screen, click Save.
Important: You must click Save if you wish to retain the adapter
configuration.
Note: If this is the second instance of an OpenToken Adapter
configuration, then you must first click Next and map target URLs
to adapter instances (see “Mapping URLs to Adapter Instances”
on page 205).
336
PingFederate 6
Appendix
B
LDAP Adapter
Configuration
Initial user authentication is normally handled outside of the PingFederate server
using an application or IdM system logon module. PingFederate’s adapter and
application agents are typically used to integrate with these local authentication
mechanisms (see “SSO Integration Kits and Adapters” on page 4).
PingFederate packages an LDAP Authentication Service Adapter (“LDAP
Adapter”) and logon form that can authenticate users directly against an LDAP
data store. This adapter may be used if your organization does not have a
centralized local authentication service and your user stores are maintained by
LDAP servers.
On the IdP side, when the PingFederate IdP server receives an authentication
request for SP-initiated SSO or the user clicks a link for IdP-initiated SSO, the
IdP server invokes the LDAP Adapter and prompts the user for local IdP
credentials. The credentials are then compared against the LDAP server and, if
validated, a SAML assertion is generated.
On the SP side, local user logon is needed only for account linking. In this
federation scenario, the IdP generates a name identifier (which may be a
pseudonym) that must be associated with a local user ID used at the SP (see
“Account Linking” on page 5).
PingFederate and the LDAP SP adapter handle account linking in the following
way:
1. The adapter prompts the user for local SP credentials and validates the
credentials against the data store.
2. The adapter passes the user ID to PingFederate to save in an embedded
account-linking data store. (You can use the SDK to extend account linking
to an external data store.)
Administrator’s Manual
337
Appendix B
LDAP Adapter Configuration
3. The LDAP SP adapter then uses the PingFederate Java, .NET, or PHP
Integration Kit to transfer user attributes to the SP application (see
“OpenToken Adapter Configuration” on page 329).
Note: Application-integration kits for Java, .NET, and PHP are available
separately from Ping Identity at www.pingidentity.com. To integrate SP
applications for the LDAP Adapter, unzip the respective integration kit
and follow instructions for installing and using the Agent Toolkits in the
accompanying documentation. Then follow the configuration
instructions in this appendix to set up the LDAP Adapter to use with
your application(s).
The SP application integration consists of two parts. The first is configuration of
the adapter, which runs on the PingFederate server and is the subject of this
appendix. The second part is an Agent Toolkit, which resides with the
application server.
The following figure shows a basic SP-initiated SSO scenario with PingFederate
servers using the LDAP Adapter, which is integrated on both sides of the identity
federation.
*EFOUJUZ1SPWJEFS
4FSWJDF1SPWJEFS
'FEFSBUJPO4FSWFS
'FEFSBUJPO4FSWFS
/'$3
6HUYHU
/'$363
$XWK1
$GDSWHU
/'$3,G3
$XWK1
$GDSWHU
/'$3
6HUYHU
63$JHQW
7RRONLW
4".-
440
#SPXTFS*OUFSGBDF
Processing Steps
1. The user initiates an SSO transaction from an external SP application.
2. The external SP application starts the SSO process through the federation
SP server.
3. The request is sent to the federation IdP server.
4. The LDAP IdP adapter authenticates the user against an LDAP server and
passes the authentication to the federation IdP server.
5. The federation IdP server generates a SAML assertion and the request is
redirected to the SP site.
338
PingFederate 6
Configuring the IdP LDAP Adapter
6. The federation SP server parses the SAML assertion and passes the user
attributes to the LDAP SP adapter. The LDAP SP adapter authenticates the
user against an LDAP server using account linking, encrypts the data
internally, and generates an OpenToken.
7. A request containing an OpenToken is redirected to the SP application.
8. The SP Agent Toolkit decrypts and parses the OpenToken and makes the
attributes available to the SP application.
Configuring the IdP LDAP Adapter
1. If you have not already done so, establish a connection between
PingFederate and your LDAP server (see “Configuring an LDAP
Connection” on page 78).
2. Click IdP Adapters on the Main Menu screen.
3. On the Manage Adapter Instances screen, click Create New Adapter
Instance.
4. On the Adapter Type screen, enter an Instance Name and Instance Id,
select LDAP Authentication Service 2.0 as the Type, and click Next.
The Instance Id may not contain spaces or underscores.
5. On the IdP Adapter screen, enter the values for adapter configuration
described below.
Note: If you do not know the values to enter at this time, select
your LDAP server and enter placeholders (in any format) for the
rest of the entry fields. You can return to this screen to enter the
correct values at any time (see “Configuring IdP Adapters” on
page 106). Click Manage Data Stores if you have not established a
connection to your LDAP server.
Administrator’s Manual
339
Appendix B
LDAP Adapter Configuration
340
Property
Description
LDAP
Datastore
The LDAP Data store configured in PingFederate.
Search Base
The location in the LDAP directory server from which the
search begins.
Search Filter
Query used to produce the desired set of matching records.
Realm
The name of a protected area. The value of this field is sent
as a part of the HTTP basic authentication request. It
appears in the dialog box that prompts the user for a
username and password.
PingFederate 6
Configuring the IdP LDAP Adapter
6. (Optional) Click Show Advanced Fields and change parameters as
needed.
Property
Description
Scope of
Search
The level of search to be performed in the search base.
One level indicates a search of objects immediately
subordinate to the base object, not including the base
object itself. Subtree indicates a search of the base object
and the entire subtree within the base object distinguished
name.
Connection
Pooling
A type of connection sharing supported by the LDAP
server, which maintains a pool of (possibly) previously
used connections and assigns them as needed.
Operational
Mode
The method of interaction between the adapter and user
agent. In HTTP Basic Authentication mode, the adapter
interacts with the user via HTTP basic authentication. In
HTML Form Authentication mode, the adapter uses an
HTML form.
Challenge
Retries
The number of attempts allowed for password
authentication.
7. Click Next.
8. On the Adapter Attributes screen, select the subject checkbox under
Pseudonym (and, optionally, other attributes, if available).
Administrator’s Manual
341
Appendix B
LDAP Adapter Configuration
This selection is used if any of your SP partners will make use of pseudonyms
for account linking (see “Account Linking” on page 5).
Note: A selection is required regardless of whether you will use
pseudonyms for account linking. This allows account linking to be
used later without having to delete and reconfigure the adapter.
Ensure that you choose at least one attribute that is unique for each
user (for example, email) to prevent the same pseudonym from
being assigned to multiple users.
You can also choose to mask the values of any or all attributes that
PingFederate logs from the adapter at runtime (see “Attribute Masking” on
page 10).
If OGNL expressions might be used to map derived values into outgoing
assertions and you want those values masked, select the related checkbox
under the Attribute list (see “Using Attribute Mapping Expressions” on
page 367).
9. Click Next.
10. On the Summary screen, review the configuration and click Done.
You can also click any heading to go back and change information.
11. On the Manage Adapter Instances screen, click Save.
Important: You must click Save if you wish to retain the adapter
configuration.
Configuring the SP LDAP Adapter
1. If you have not already done so, establish a connection between
PingFederate and your LDAP server (see “Configuring an LDAP
Connection” on page 78).
2. Click SP Adapters on the Main Menu.
342
PingFederate 6
Configuring the SP LDAP Adapter
3. On the Manage Adapter Instances screen, click Create New Adapter
Instance.
4. On the Type screen, enter an Instance Name and Instance Id, select LDAP
Authentication Service 2.0 as the Adapter Type, and click Next.
The Instance Id may not contain spaces or underscores.
5. On the Instance Configuration screen, enter the values for adapter
configuration as described on the screen and click Next.
Note: If you do not know the values to enter at this time, select the
“LDAP Datastore” and enter placeholders for other entries in valid
formats similar to those shown in the screen example below. You
can return to this screen to enter the correct values at any time
(see “Configuring SP Adapters” on page 200). Click Manage Data
Stores if you have not established a connection to your LDAP
server.
Administrator’s Manual
343
Appendix B
LDAP Adapter Configuration
6. (Optional) Click Show Advanced Fields and change default settings as
needed.
Due to import control restrictions, the standard JRE distribution supports
strong but not unlimited encryption. To use the strongest AES encryption,
when permissible, download and install the appropriate version of “Java
Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files”
from the Sun download Web site (http://java.sun.com/javase/downloads).
Ping Identity recommends that users apply strong password policies for
encryption of data passed via the adapter. There are many resources for
determining what constitutes a strong password. For more information, refer
to any of the following sites:
•
http://www.securityfocus.com/infocus/1192
•
http://www.cert.org/tech_tips/unix_configuration_guidelines.html#A
•
http://www.windowsecurity.com/articles/
Passwords_Improve_Windows_Security_Part1.html
7. Click Next.
8. On the Actions screen, click Download under Action Invocation Link.
9. On the next screen, click Export and save the properties file.
The properties must be available to your application. Refer to the User Guide
for your Integration Kit for details.
10. Click Next.
344
PingFederate 6
Configuring the SP LDAP Adapter
11. (Optional) On the Extended Contract screen, configure additional
attributes as needed for this adapter instance (see “Extending an Adapter
Contract” on page 204).
12. On the Summary screen, review the configuration and click Done.
You can also click any heading to go back and change information.
13. If this is a second adapter instance, click Next and map at least one target
URL to an adapter instance (see “Mapping URLs to Adapter Instances” on
page 205).
For a third and subsequent adapter instances, this step is optional
14. On the Manage Adapter Instances screen (or the Map URLs to Adapter
Instances screen), click Save.
Important: You must click Save if you wish to retain the adapter
configuration.
Administrator’s Manual
345
Appendix B
LDAP Adapter Configuration
346
PingFederate 6
Appendix
C
Application Endpoints
These endpoints provide a means, via standard HTTP, by which external
applications can communicate with the PingFederate server.
Note: Begin each URL with the fully qualified server name and port
number of your IdP or SP PingFederate server: for example:
https://www.pingidentity.com:9031/idp/startSSO.ping.
The SSO and SLO endpoints for an IdP and an SP include optional parameters
which you can use to specify error pages that users will see in the event of an
SSO or SLO failure. By default, PingFederate provides templates for these and
other errors or conditions (see “Customizing User-Facing Screens” on page 50).
For either SP or IdP servers, a maintenance endpoint is also provided for
administrators to verify that the server is running (see “Maintenance Endpoint”
on page 356).
Administrator’s Manual
347
Appendix C
Application Endpoints
IdP Endpoints
The following sections describe PingFederate IdP endpoints, including the query
parameters that each accepts or requires. These endpoints accept either the
HTTP GET or POST methods.
Important: When the parameter TargetResource (or Target) is
used and includes its own query parameters, the parameter value
must be URL-encoded. Any other parameters that contain restricted
characters (many SAML URNs, for example) also must be URLencoded.
For information about URL encoding, see, for example, “HTML URLencoding Reference” (www.w3schools.com/tags/ref_urlencode.asp).
/idp/startSSO.ping
This is the path used to initiate an unsolicited IdP-initiated SSO transaction
during which a SAML response containing an assertion is sent to an SP.
Typically, a systems integrator or developer creates one or more links to this
endpoint in the IdP application or portal to allow users to initiate SSO to various
SPs.
For information about allowing applications to retrieve configuration data from
the PingFederate server over SOAP, see “Web Service Interfaces” on page 357.
The following table shows the HTTP parameters for this endpoint.
PartnerSpId
or
PARTNER
The federation ID of the SP to whom the SAML
response containing an assertion should be issued.
One of these parameters is required unless the
federation ID can be derived from
TargetResource or TARGET (see below)
TargetResource
or
TARGET
(optional)
For SAML 2.0, the value of either parameter is
passed to the SP as the RelayState element of
a SAML response message. This is the
PingFederate implementation of the SAML 2.0
indicator for a desired resource at the SP during
IdP-initiated SSO.
For SAML 1.x, the value is sent to the SP as a
parameter named TARGET.
Note: If this parameter is not provided in the URL,
then the target resource should be specified in the
administrative console (see “Configuring a Default
URL and Error Message” on page 112).
348
PingFederate 6
IdP Endpoints
InErrorResource
(optional)
Indicates where the user is redirected after an
unsuccessful SSO. If this parameter is not included
in the request, PingFederate redirects the user to
the SSO error landing page hosted within
PingFederate (see “Customizing User-Facing
Screens” on page 50).
Binding (optional)
Indicates the binding to be used; allowed values are
URIs defined in the SAML specifications. For
example, the SAML 2.0 applicable URIs are:
urn:oasis:names:tc:SAML:2.0:
bindings:HTTP-Artifact
urn:oasis:names:tc:SAML:2.0:
bindings:HTTP-POST
When the parameter is not used, the default ACS
URL configured for the SP-partner connection is
used, unless an ACS index is specified (see the
next parameter, ACSIdx).
ACSIdx
(optional - SAML 2.0)
Specifies the index number of partner’s ACS (see
“Setting Assertion Consumer Service URLs
(SAML)” on page 154). Takes precedence over the
Binding parameter if both are specified. If neither
the binding nor index is specified in the call, the
default ACS is used.
IdpAdapterId
(optional)
Allows an application to call out what IdP adapter to
use for authentication (in a configuration with
multiple IdP adapters).
RequestedFormat
(optional - SAML 2.0)
Allows control over the NameId format.
/idp/startSLO.ping
This is the path used to initiate an IdP-initiated SLO (under SAML 2.0).
Typically, a systems integrator or developer creates one or more links to this
endpoint in the protected resources of their IdP application or portal to allow
users to end their sessions at various SPs. This endpoint uses the local
PingFederate session to determine which SPs have been issued an SSO assertion
and sends them a SAML logout request.
The following table shows the HTTP parameters for this endpoint.
TargetResource
(optional)
Administrator’s Manual
Indicates where the user is redirected after a
successful SLO. If this parameter is not included in
the request, PingFederate uses as a default the
URL for a successful SLO as entered on the IdP
Default URL screen.
349
Appendix C
Application Endpoints
InErrorResource
(optional)
Indicates where the user is redirected after an
unsuccessful SLO. If this parameter is not included
in the request, PingFederate redirects the user to
the SLO error landing page hosted within
PingFederate (see “Customizing User-Facing
Screens” on page 50).
Binding (optional -
Indicates the binding to be used; allowed values are
URIs defined in the SAML specifications. The
SAML 2.0 applicable URIs are:
SAML 2.0)
urn:oasis:names:tc:SAML:2.0:
bindings:HTTP-Artifact
urn:oasis:names:tc:SAML:2.0:
bindings:HTTP-POST
urn:oasis:names:tc:SAML:2.0:
bindings:HTTP-Redirect
urn:oasis:names:tc:SAML:2.0:
bindings:HTTP-SOAP
When the parameter is not used, the first SLO
Service URL configured for the SP-partner
connection is used (see “Specifying SLO Service
URLs (SAML 2.0)” on page 157).
/idp/writecdc.ping
This endpoint is used for SAML 2.0 IdP Discovery. This is the path used when
the IdP wants to write to the Common Domain Cookie (CDC) held within the
user’s browser. The information written to the cookie indicates from which IdP
this user has authenticated.
The following table shows the one HTTP query parameter for this endpoint.
TargetResource
(optional)
Indicates where the user is redirected after
successful IdP Discovery. If this parameter is not
included in the request, PingFederate redirects the
user to the referrer in the HTTP header. If there is
no TargetResource or referrer, the call to this
endpoint will fail.
/pf/heartbeat.ping
See “Maintenance Endpoint” on page 356.
350
PingFederate 6
SP Endpoints
SP Endpoints
The following sections describe the PingFederate SP endpoints, including the
query parameters that each accepts or requires. These endpoints accept either
the HTTP GET or POST methods.
Important: When the parameter TargetResource is used and
includes its own query parameters, the parameter value must be URLencoded. For information about URL encoding, see, for example,
“HTML URL-encoding Reference” (http://www.w3schools.com/tags/
ref_urlencode.asp).
/sp/startSSO.ping
This is the path used to initiate SP-initiated SSO. In this scenario, the SP issues
an SSO request to the IdP asking for an SSO authentication response. Typically,
a systems integrator or developer creates one or more links to this endpoint in SP
applications to allow users to access various protected resources via SSO using
the IdP as an authentication authority.
For information about allowing applications to retrieve configuration data from
the PingFederate server over SOAP, see “Web Service Interfaces” on page 357.
The following table shows the HTTP parameters for this endpoint.
Administrator’s Manual
PartnerIdpId
(required if more than
one IdP connection is
configured and Domain
is not used)
The federation ID of the IdP that will authenticate
the user and issue an assertion.
Domain
(required to invoke
Auto-Connect)
The domain name associated with the requesting
user’s IdP (see “Using Auto-Connect” on page 15).
In this case, PartnerIdpId cannot be used.
TargetResource
or
TARGET
(optional)
This parameter indicates where the end-user is
redirected after a successful SSO.
Note: If this parameter is not provided in the URL,
then the target resource should be specified in the
administrative console (see “Configuring Default
URLs” on page 207).
351
Appendix C
Application Endpoints
Binding (optional)
Indicates the binding to be used; allowed values are
URIs defined in the SAML specifications. For
example, the SAML 2.0 applicable URIs are:
urn:oasis:names:tc:SAML:2.0:
bindings:HTTP-Artifact
urn:oasis:names:tc:SAML:2.0:
bindings:HTTP-POST
urn:oasis:names:tc:SAML:2.0:
bindings:HTTP-Redirect
When the parameter is not used for SAML 2.0, the
first SSO Service URL configured for the IdPpartner connection is used (see “Specifying SSO
Service URLs (SAML)” on page 245).
InErrorResource
(optional)
This parameter indicates where the end-user is
redirected after an unsuccessful SSO. If this
parameter is not included in the request,
PingFederate redirects the user to the SLO error
landing page hosted within PingFederate (see
“Customizing User-Facing Screens” on page 50).
SpSessionAuthn
AdapterId (optional)
The explicit SP adapter instance ID indicating the
adapter to use to create an authenticated session
or security context.
ForceAuthn (optional
- SAML 2.0)
This parameter controls the attribute of the same
name in the AuthnRequest. (The default is
false.)
IsPassive (optional SAML 2.0)
This parameter controls the attribute of the same
name in the AuthnRequest. (The default is
false.)
AllowCreate
Controls the value of the AllowCreate attribute
of the NameIDPolicy element in the
AuthnRequest. (The default is true.)
(optional - SAML 2.0)
RequestedFormat
(optional - SAML 2.0)
Specifies the value for the Format attribute in the
NameIDPolicy element of the AuthnRequest.
If not specified, the attribute is not included in the
AuthnRequest.
RequestedACSIdx
(optional - SAML 2.0)
The index number of your site’s Assertion
Consumer Service, where you want to the
assertion be sent to be sent.
RequestedBinding
Indicates the binding requested for the response
containing the assertion; allowed values are URIs
defined in the SAML specifications.
(optional - SAML 2.0)
RequestedAuthnCtx
(optional - SAML 2.0)
352
Indicates the requested authentication context of
the assertion; allowed values are URIs defined in
the SAML specifications (see the OASIS SAML
document: saml-authn-context-2.0-os.pdf).
PingFederate 6
SP Endpoints
RequestedSPName
Qualifier
(optional - SAML 2.0)
Indicates that the IdP should return the given name
qualifier as part of the assertion (used primarily to
identify SP affiliations—see “Defining SP
Affiliations” on page 190).
If an adapter is specified in SpSessionAuthnAdapterId, then that adapter is
used to create an authenticated session for SP-initiated SSO. If there is no
SpSessionAuthnAdapterId, the ultimate destination of the user after SSO
(either the TargetResource or the default SSO success URL) is used along
with the mappings defined in the administrative console on the Map URLs to
Adapter Instances screen (see “Mapping URLs to Adapter Instances” on
page 205).
Note that adapter selection for SP-initiated SSO is similar to that for IdPinitiated SSO except that, because the adapter ID is dependent on the SAML
deployment, PingFederate cannot expect it from an IdP. Therefore, it uses only
the URL mapping for adapter selection for SSO.
/sp/startSLO.ping
This is the path used to initiate SP-initiated SLO. Typically, a systems integrator
or developer creates one or more links to this endpoint in the protected resources
of their SP application, which allows users to end a session by sending a logout
request to the IdP that authenticated the session.
Note that the IdP might send additional logout request messages to other SPs
when it receives a logout request from a PingFederate server acting as an SP.
The following table shows the HTTP parameters for this endpoint.
TargetResource
(optional)
Indicates where the user is redirected after a
successful SLO. If this parameter is not included in
the request, PingFederate uses as a default the
URL for a successful SLO, as entered on the SP
Default URLs screen.
Binding (optional -
Indicates the binding to be used; allowed values are
URIs defined in the SAML specifications. The
SAML 2.0 applicable URIs are:
SAML 2.0)
urn:oasis:names:tc:SAML:2.0:
bindings:HTTP-Artifact
urn:oasis:names:tc:SAML:2.0:
bindings:HTTP-POST
urn:oasis:names:tc:SAML:2.0:
bindings:HTTP-Redirect
urn:oasis:names:tc:SAML:2.0:
bindings:HTTP-SOAP
When the parameter is not used, the first SLO
Service URL configured for the IdP-partner
connection is used (see “Specifying SLO Service
URLs (SAML 2.0)” on page 247).
Administrator’s Manual
353
Appendix C
Application Endpoints
InErrorResource
(optional)
Indicates where the user is redirected after an
unsuccessful SLO. If this parameter is not included
in the request, PingFederate redirects the user to
the SLO error landing page hosted within
PingFederate (see “Customizing User-Facing
Screens” on page 50).
SpSessionAuthn
AdapterId (optional)
The SP adapter instance ID indicating which
session to terminate and which IdP will receive the
logout request.
SourceResource
(optional)
A URL indicating the origin of the logout request. It
is mapped to an adapter ID in order to designate
which session to terminate.
An SP PingFederate session can be associated with one or more application
sessions relying on any number of IdPs as the session authority. PingFederate
must choose one session to terminate and also send an SLO request to the IdP
that issued the assertion that created the session. Sessions are associated with the
ID of the adapter instance that created them. Once an adapter ID is determined,
the first session found with that ID is used. Determination of the adapter
instance ID occurs in the following order:
1. If there is a value for the SpSessionAuthnAdapterId parameter, it is
used.
2. If there is a value for the SourceResource parameter, PingFederate
attempts to map a URL to an adapter using that value to determine the
adapter ID.
3. If there is an HTTP header value for Referer [sic], PingFederate attempts
to map a URL to an adapter using that value to determine the adapter ID.
4. If none of the above is successful, the TargetResource parameter value or
the value for the default SLO success URL are used to map a URL to an
adapter.
5. Finally, if no adapter ID is determined, the first one in the list is used.
/sp/defederate.ping
This is the path used to terminate an account link created during SSO. Account
linking provides a means for subject identification on the SP side. Links are
created and terminated entirely by a user on the SP side. The link contains the
name identifier from the IdP, the IdP’s federation ID, the adapter instance ID,
and the local user identifier.
There are no HTTP parameters for this endpoint.
You can unlink a user session only if was established during SSO using an
existing account link on the SP side. If more than one SP session was established
via account linking on the same PingFederate session, each of those links will be
terminated by this endpoint. A local logout is also performed for any link that is
terminated.
354
PingFederate 6
SP Endpoints
/sp/cdcstartSSO.ping
This endpoint is used for IdP-Discovery implementations (see “IdP Discovery” in
the “Supported Standards” chapter of Getting Started). This endpoint is similar to
/sp/startSSO.ping and accepts the same parameters, with the exception of
PartnerIdpId (see “/sp/startSSO.ping” on page 351). Instead of this
parameter, the server attempts to use the common domain cookie to determine
the IdP.
/sp/startAttributeQuery.ping
This endpoint is used to initiate an Attribute Query with a SAML 2.0 IdP (see
“Attribute Query and XASP” in the “Supported Standards” chapter of Getting
Started).
The following table shows the HTTP parameters for this endpoint.
Subject
Uniquely identifies the user to the IdP. When user
authenticates with an x.509 certificate, this is the
Subject DN, which must be URL-encoded.
Issuer (optional)
The IssuerDN from the user’s x.509 certificate
(when XASP is used), which uniquely identifies the
entity that issued the user's certificate. The
parameter must be URL-encoded.
Note: When specified, this parameter overrides the
Subject parameter.
PartnerIdpId (except for
XASP)
Used to identify the specific IdP partner to which
the Attribute Query should be sent. If this
parameter is not present, the Subject and Issuer
are used to determine the correct IdP.
Note: For XASP, this parameter overrides both the
Subject and Issuer parameters.
Format (required for
XASP, otherwise
optional)
Identifies the name-identifier format of the Subject
query parameter. If included, the value must be one
of the SAML 2.0 Name Identifier Format URIs (see
section 8.3 of the SAML specifications (http://
docs.oasis-open.org/security/saml/v2.0/saml-core2.0-os.pdf).
Note: For XASP, this paramater must be set to:
urn:oasis:names:tc:SAML:1.1:nameidformat:X509SubjectName
If not specified, the parameter defaults to:
urn:oasis:names:tc:SAML:1.1:nameidformat:unspecified.
Note: The parameter must be URL-encoded.
AppId
Administrator’s Manual
The unique identifier of the initiating application.
355
Appendix C
Application Endpoints
SharedSecret
Used to authenticate the initiating application. The
AppId and SharedSecret must both match the
application authentication settings within the
PingFederate server.
RequestedAttrName
(optional)
A name of a user attribute requested from the IdP.
For each such desired user attribute, include this
parameter. If this parameter is not present, then all
allowable user attributes are returned from the IdP.
/pf/heartbeat.ping
See the next section, “Maintenance Endpoint”.
Maintenance Endpoint
For either an SP or an IdP PingFederate server, an endpoint is provided to report
whether the server is running.
/pf/heartbeat.ping
This endpoint returns an “OK” browser message and an HTTP 200 status
indication if the PingFederate server is running. If you receive an HTTP 404
error, the server associated with the endpoint is down.
Load balancers can use this endpoint to determine the status of PingFederate
independently of checks used to determine the status of the supporting hardware.
You can also configure the server to provide regular status information to a
network-management utility (see “Configuring Runtime Reporting” on page 59).
356
PingFederate 6
Appendix
D
Web Service Interfaces
PingFederate provides two Web Services for external clients. These services may
be used by client applications to manage partner connections and support
integration of Web applications, respectively:
•
Connection Management Service — Enables creation and deletion of single
connection configurations in PingFederate. This service may be used to
migrate connections from one server environment to another (for example,
from testing or staging to production) or to create new connections in a
single server programmatically.
Tip: PingFederate provides a command-line utility that can be used
to export and modify connections, and then import them to target
environments (see “Automating Configuration Migration” on
page 45).
•
SSO Directory Service — Provides Web application developers with
information regarding partner connections and adapter instances.
Tip: Applications accessing the Connection Management Service must
first authenticate themselves to the PingFederate server. SSO
Directory Service authentication is optional by default, but may be
required. For more information, see “Application Authentication” on
page 99.
Connection Management Service
The Connection Management Service supports basic connection management
capabilities and is accessible only on a PingFederate server running the
administrative console. This feature is useful in a variety of circumstances, but
the following primary use cases were considered:
Administrator’s Manual
357
Appendix D
Web Service Interfaces
•
As a utility to migrate changes to a partner connection though staging
environments (for example: development, test, production).
Changes to URLs and keys may be needed to make the connection
appropriate to the next environment.
•
As a way for an external application to update or delete connections
programmatically, or create new ones using an exported connection XML
file as a template.
The WAR file for this service, pf-mgmt-ws.war, is located in the
pingfederate/server/default/deploy2 directory.
Note: If you do not want to allow use of the service, it should not be
deployed: remove the WAR file from the deploy2 directory.
The SOAP-accessible service endpoint is pf-mgmt-ws/ws/
ConnectionMigrationMgr.
The Web Services Description Language (WSDL) document describing this
service can be retrieved from:
https://<host_server>:<admin_console_port>/pf-mgmt-ws/ws/
ConnectionMigrationMgr?wsdl
Exporting a Connection
You can export a connection either manually, using the administrative console,
or programmatically, via a call to the Connection Management Service.
In either case, the exported XML complies with the standard SAML 2.0
metadata format, with extensions to capture PingFederate’s proprietary
configuration. Most connection configuration information is contained in the
XML markup, with the exception of global configuration items such as adapter
instances, data stores, and keypairs. Adapter instances and data stores are
referenced by ID, and keypairs are referenced by the MD5 fingerprint of their
X.509 certificate. Public certificates, such as the partner’s signature verification
certificate, are included completely (base-64 encoded).
Exporting Manually
For information about using the administrative console to export SP connections
at an IdP site, see “Using the Manage Connections Screen” on page 117.
For information about exporting IdP connection at an SP site, see “Using the
Manage Connections Screen” on page 214.
Using the Connection Service
The Connection Web Service exposes the following method for exporting
connections:
public string getConnection(
String entityId,
String role,) throws IOException
358
PingFederate 6
Connection Management Service
Code Sample
Service service = new Service();
Call call = (Call)service.createCall();
call.setUsername("username");
call.setPassword("password");
call.setTargetEndpointAddress("https://localhost:9999/pf-mgmtws/ws/ConnectionMigrationMgr");
call.setOperationName("getConnection");
Object result = call.invoke(new Object[] {"entityId", "SP"});
Importing Connections
Moving a connection from one PingFederate server to another requires care, as
the target server must contain the global configuration items (data stores,
keypairs, and adapter instances) that the connection references. Changing the
references in the XML file—either manually or programmatically—may be
necessary to adjust the connection to the target PingFederate environment.
Once required changes are made to the XML file, developers can use the
Connection Management Service to import the connection into a different
instance of PingFederate.
Tip: Alternatively, you can import XML connection files into
PingFederate manually by copying them into the directory:
<pf_install>/pingfederate/server/default/
data/connection-deployer
PingFederate scans this directory periodically and imports connections
automatically.
Caution: Manually importing a connection always overwrites an
existing connection with the same ID (the Web Service provides a
switch to disallow this behavior, if desired—see below).
The Web Service exposes the following method for importing connections:
public void saveConnection(
String xml,
boolean allowUpdate) throws IOException
The xml parameter is the complete representation of the connection retrieved
by your application from an exported connection file (and optionally modified).
If allowUpdate is false, the Web Service can be used only to add a new
connection. An error occurs if a connection already exists with the same
connection ID and federation protocol in the XML. If allowUpdate is true and
the connection already exists, it will be overwritten.
Code Sample
Below is example client code using the Apache AXIS libraries that invokes this
Web Service to create a new connection:
Service service = new Service();
Administrator’s Manual
359
Appendix D
Web Service Interfaces
Call call = (Call) service.createCall();
call.setUsername("username");
call.setPassword("password");
String addr = "https://localhost:9999/pf-mgmt-ws/ws/
ConnectionMigrationMgr";
call.setTargetEndpointAddress(addr);
call.setOperationName("saveConnection");
String xml = "<EntityDescriptor entityID=\"some_entity_id\"
...
</EntityDescriptor>";
boolean allowUpdate = false;
call.invoke(new Object[]{xml, allowUpdate});
Deleting Connections
The Web Service exposes the following method for connection deletion:
public void deleteConnection(
String entityId,
String role) throws IOException
The entityId parameter is the Connection ID, which identifies the
connection to be deleted. The role parameter is the connection role—IDP or SP.
Code Sample
Below is example client code using the Apache AXIS libraries that invokes this
Web Service to delete a connection:
Service service = new Service();
Call call = (Call) service.createCall();
call.setUsername("username");
call.setPassword("password");
call.setTargetEndpointAddress(
"https://localhost:9999/pf-mgmt-ws/ws/
ConnectionMigrationMgr"
);
call.setOperationName("deleteConnection");
call.invoke(new Object[]{"entityid", "SP"});
Cluster Configuration Replication
A Web Service endpoint is available to replicate the administrative-console
configuration to other nodes in a PingFederate cluster. This allows a client of this
Web Service to create or update a new connection (or delete a connection) and
then push the new configuration to the other cluster nodes.
The service endpoint is:
/pf-mgmt-ws/ws/ConfigReplication
The WSDL document describing this service can be retrieved from:
https://<host_server>:<admin_console_port>/pf-mgmt-ws/ws/
ConfigReplication?wsdl
360
PingFederate 6
SSO Directory Service
The Web Service exposes the following method:
public void replicateConfiguration();
Code Sample
Below is example client code using the Apache AXIS libraries that invokes the
configuration replication functionality:
Call call2 = (Call) service.createCall();
call2.setUsername("joe");
call2.setPassword("test");
String addr2 = "https://localhost:9999/pf-mgmt-ws/ws/
ConfigReplication";
call2.setTargetEndpointAddress(addr2);
call2.setOperationName("replicateConfiguration");
call2.invoke(new Object[]{});
Validation Disclaimer
The import process is not subject to the same rigorous data validation performed
by the administrative user interface. Although some checks are made, it is
possible to create invalid connections using the connection-migration process.
Therefore, because the XML is complex and validation is limited, attempting to
create an XML connection from scratch is not recommended. Rather, the
administrative console should be used to create the initial connection. That way,
changes necessary to the exported connection’s XML representation can be held
to a minimum, reducing the risk of compromising data integrity.
SSO Directory Service
PingFederate SSO Directory Service allows applications to retrieve configuration
data from a runtime PingFederate server. (A PingFederate server in a cluster
configured as an administrative console does not support this Web Service.) This
service allows Web applications to avoid storing and maintaining the data
locally. These types of data can be retrieved:
•
A list of IdP partners
•
A list of SP partners
•
A list of IdP adapter instances
•
A list of SP adapter instances
The SSO Directory Service provides information useful for integrating an
application with a PingFederate server. It is a way for the application to find out
dynamically which partners can be used for SSO. This means applications need
not be modified when new partners are configured in PingFederate.
Administrator’s Manual
361
Appendix D
Web Service Interfaces
The WAR file for this module, pf-ws.war, is located in the pingfederate/
server/default/deploy directory.
Note: If you do not want to allow use of the service, it should not be
deployed: remove the WAR file from the deploy directory.
The service endpoint is pf-ws/services/SSODirectoryService.
The WSDL document describing this service can be retrieved from:
http(s)://<pf_runtime_host>:<runtime_port>/pf-ws/services/
SSODirectoryService?wsdl
You can retrieve a list using any of the following methods:
•
getIDPList – Returns a list of active IdP connections configured for SP-
initiated SSO. The list contains each IdP’s Connection ID and Connection
Name
•
getSPList – Returns a list of active SP connections configured for IdP-
initiated SSO. The list contains each SP’s Connection ID and Connection
Name
Note: For either IdP or SP lists, Connection IDs are returned as
values for the XML tag <entityId>. Connection Names are
returned as values for the XML tag <company> (see “SOAP
Request and Response Example” on page 364).
•
getAdapterInstanceList – Returns a list of SP adapter instances
containing an ID and name.
•
getIdpAdapterInstanceList – Returns a list of IdP adapter instances
containing an ID and name.
Note: These methods do not require input parameters.
The service is also available over HTTP. The query string for retrieving any of
the lists is:
/pf-ws/services/SSODirectoryService?method=<method_name>
Code Example
When you integrate a Web application with PingFederate, use the SSO
Directory Service to generate a connection or adapter list. The code needed to
create any of the lists is similar.
The following Java code example retrieves an IdP list from the Web Service. The
program calls the getIDPList method in the SSO Directory Service to
retrieve an IdP list and print it to the console. This example uses the Apache
Axis library and includes optional code for authentication to the PingFederate
362
PingFederate 6
SSO Directory Service
server (see “Application Authentication” on page 99). We recommend the use of
HTTPS when including credentials.
import
import
import
import
import
org.apache.axis.client.Call;
org.apache.axis.client.Service;
java.net.URL;
javax.xml.namespace.QName;
com.pingidentity.ws.SSOEntity;
public class SSODirectoryClientSample
{
public static void main(String[] args) throws Exception
{
Service service = new Service();
Call call = (Call) service.createCall();
call.setUsername("username");
call.setPassword("pass");
URL serviceUrl = new URL(
"https://localhost:9031/pf-ws/services/
SSODirectoryService");
QName qn = new QName("urn:BeanService", "SSOEntity");
call.registerTypeMapping(SSOEntity.class, qn,
new org.apache.axis.encoding.ser.BeanSerializerFactory(
SSOEntity.class, qn),
new
org.apache.axis.encoding.ser.BeanDeserializerFactory(
SSOEntity.class, qn));
call.setTargetEndpointAddress( serviceUrl );
call.setOperationName( new QName(
"http://www.pingidentity.com/
servicesSSODirectoryService",
"getIDPList"));
Object result = call.invoke( new Object[] {} );
if (result instanceof SSOEntity[])
{
SSOEntity[] idpArray = (SSOEntity[])result;
for (SSOEntity idp : idpArray)
{
System.out.println(idp.getEntityId() + " " +
idp.getCompany());
}
}
else
{
System.out.println("Received problem response from
server: " + result);
}
}
}
Administrator’s Manual
363
Appendix D
Web Service Interfaces
SOAP Request and Response Example
A client application must send a SOAP request to the PingFederate server
specifying the requested Web Service and the specific method. For example, the
following is a typical SOAP request for an IdP list using the SSO Directory
Service.
<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soapenv:Body>
<ns1:getIDPList
soapenv:encodingStyle=
"http://schemas.xmlsoap.org/soap/encoding/"
xmlns:ns1=
"https://localhost:9031/ssodir/services/
SSODirectoryService"/>
</soapenv:Body>
</soapenv:Envelope>
The PingFederate server’s Web Service will return a response containing the list
you requested. The following is an example of a typical SOAP response for an
IdP list:
<?xml version="1.0" encoding="UTF-8" ?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/
soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soapenv:Body>
<getIDPListResponse
soapenv:encodingStyle=
"http://schemas.xmlsoap.org/soap/encoding/">
<getIDPListReturn
soapenc:arrayType=
"ns1:IDP[2]" xsi:type="soapenc:Array"
xmlns:ns1="urn:BeanService"
xmlns:soapenc=
"http://schemas.xmlsoap.org/soap/encoding">
<getIDPListReturn href="#id0" />
<getIDPListReturn href="#id1" />
</getIDPListReturn>
</getIDPListResponse>
<multiRef id="id0" soapenc:root="0"
soapenv:encodingStyle=
"http://schemas.xmlsoap.org/soap/encoding/"
xsi:type="ns2:IDP"
xmlns:soapenc=
"http://schemas.xmlsoap.org/soap/encoding/"
xmlns:ns2="urn:BeanService">
<company xsi:type="xsd:string">MegaMarket</company>
364
PingFederate 6
SOAP Request and Response Example
<entityId xsi:type="xsd:string">www.megamarket.com
</entityId>
</multiRef>
<multiRef id="id1" soapenc:root="0"
soapenv:encodingStyle=
"http://schemas.xmlsoap.org/soap/encoding/"
xsi:type="ns3:IDP" xmlns:ns3="urn:BeanService"
xmlns:soapenc=
"http://schemas.xmlsoap.org/soap/encoding/">
<company xsi:type="xsd:string">Ping</company>
<entityId
xsi:type="xsd:string">pingfederate3:default:entityId
</entityId>
</multiRef>
</soapenv:Body>
</soapenv:Envelope>
Administrator’s Manual
365
Appendix D
Web Service Interfaces
366
PingFederate 6
Appendix
E
Using Attribute Mapping
Expressions
PingFederate provides an advanced option allowing administrators to map user
attributes by way of an expression language. Because the option carries with it a
potential for misuse, however, it is disabled in the administrative console for
security reasons.
Tip: If you are upgrading to PingFederate 5.1 or higher and importing a
configuration archive that uses expression mapping, the feature will be
enabled automatically.
This appendix describes the option, which is based on the Object-Graph
Navigation Language (OGNL), and how to enable or disable it.
Caution: The security concern posed by OGNL is related to a potential
for abuse by PingFederate administrative users within an organization;
the concern is not related to any known external threats. We
recommend, however, that the option be enabled only if required.
About OGNL
OGNL is based on the Java programming language. OGNL expressions are useful
for evaluating and manipulating attribute values and returning information based
on the results. You can also transform a range of values into a text description, or
do the same for a sequence of ranges.
In the expression below, for example, the value of the attribute “net-worth” is
transformed first to eliminate any dollar signs or commas, then the result is
Administrator’s Manual
367
Appendix E
Using Attribute Mapping Expressions
evaluated to determine whether the user’s net worth falls into a “bronze,”
“silver,” or “gold” category:
#result=#this.get("salary").toString(),
#result=#result.replace("$",""),
#result=#result.replace(",",""),
#result < 500000 ? "bronze" :
#result < 1000000 ? "silver" : "gold"
Use the # symbol to reference OGNL variables. For an IdP, PingFederate
provides predefined OGNL variables for IdP-adapter attributes as well as any
attributes retrieved from data stores. For an SP, variables are available for
attributes received in an assertion or an attribute query. For example, the
SAML_SUBJECT value may be retrieved using:
#SAML_SUBJECT
Important: Because OGNL uses the “at” symbol (@) to reference
static Java methods, expressions containing the symbol must be
enclosed in double quotes; otherwise, expression parsing will fail. For
example:
#SAML_SUBJECT="[email protected]"
not:
#[email protected]
For data-store attributes, use this syntax (for example):
#this.get("ds.amount")
For more information, see “Using the OGNL Edit Screen” on page 370.
For more information about OGNL, see the OGNL Web site, www.ognl.org.
Note: The PingFederate runtime engine uses OGNL version 2.6.7.
Enabling/Disabling Expressions
OGNL can be manually enabled or disabled for attribute mapping by editing a
configuration file located in:
<pf_install>/pingfederate/server/default/data/configstore/
Important: If OGNL is enabled and expressions configured anywhere
in the administrative console, disabling the feature will cause errors
during runtime processing.
368
PingFederate 6
Enabling/Disabling Expressions
To enable or disable OGNL expressions:
1. In the directory cited above, open the file:
org.sourceid.common.ExpressionManager.xml
2. Change the value of the element named evaluateExpressions to either
true or false and save the file. For example:
<item name="evaluateExpressions">true</item>
Note: The absence of a value (the installed default) does not
necessarily disable the use of OGNL expressions. To facilitate
backward compatibility, when no value is present, configuration
archives containing expressions can be imported successfully, and
further use of the feature is enabled. (The term “silent” is used for
this condition in the server log.)
3. Start or restart PingFederate.
Tip: If you are enabling OGNL to use for mapping SaaS-provisioning
attributes, it is not necessary to restart the PingFederate server.
When OGNL expressions are enabled, the selection Expression is available in
the drop-down menus under Source in each of the administrative-console
Fulfillment screens (see Figure 4), and the feature is available on the SaaSprovisioning attribute-mapping screen (when SaaS Provisioning itself is
enabled—see “SaaS Provisioning” on page 18).
Figure 4: Attribute Contract Fulfillment (Example)
When you make this selection, you can enter the expression in the text field
provided. You can also test expressions (see the next section).
Administrator’s Manual
369
Appendix E
Using Attribute Mapping Expressions
Using the OGNL Edit Screen
An in-line editor is available for OGNL expressions. The editor validates the
expression and allows an administrator to enter input values and test the
resulting output.
X To reach the OGNL editor, click Edit under Actions for an expression on
any of the attribute Fulfillment screens.
Here is an example of the edit screen, from the IdP configuration flow:
To test an expression:
1. Enter an input value in the Value text box associated with the attribute.
2. Click the Test link near the bottom right of the screen.
If the expression contains no errors, the result is displayed under Test
Results.
Important: If you make changes to an expression and want to save
them, click Update under Actions. To discard changes, click the
Cancel link under Actions; clicking the Cancel button near the bottom
of the screen discards all changes you have made in the current task.
370
PingFederate 6
Appendix
F
Troubleshooting
Basic troubleshooting tips are provided here to help overcome common
difficulties. Please contact Ping Identity at 877.898.2905 or
[email protected] for further information.
This appendix contains the following sections:
•
“Data Stores” on page 371
•
“Installation” on page 372
•
“Protocols” on page 372
•
“Server” on page 373
Data Stores
Table 12: Troubleshooting Data Stores
Administrator’s Manual
Problem
Solution
When setting up the
JDBC data store, a
connection cannot be
established.
Verify that the proper drivers and connectors have
been installed.
Also, verify the connection URL, username, and
password. If unsuccessful, contact your database
administrator.
371
Appendix F
Troubleshooting
Table 12: Troubleshooting Data Stores (Continued)
Problem
Solution
Cannot connect to a
Directory Service with
the LDAP protocol.
Verify the connection URL, port, principal, and
credentials. If unsuccessful, contact your system
administrator.
If using LDAP with SSL/TLS (ldaps://), ensure the
LDAP server’s SSL certificate is signed by a trusted
certificate authority or import the certificate into
your JAVA_HOME/jre/lib/security/
cacerts keystore (consult your Java
documentation and the Java keytool
documentation).
The trusted certificates stored and accessed
through the PingFederate console are used only
with SOAP connections, not other SSL/TLS
connections.
Installation
Table 13: Troubleshooting Installation
Problem
Solution
Error message “Not
enough memory on the
server”
Verify that there is at least 1,024 MB of RAM
installed on the server (see “System
Requirements” in the “Installation” chapter of
Getting Started).
Exception in thread
“main”
java.lang.NoClassDef
FoundError
Make sure PingFederate is installed in a directory
path that does not contain spaces.
Protocols
Table 14: Troubleshooting Protocols
372
Problem
Solution
Certificates
unexpectedly expire.
Verify that the server clocks are synchronized on
both sides of the federation. Note that you can
configure PingFederate to notify administrators in
advance of impending certificate expiration (see
“Configuring Runtime Notifications” on page 58).
PingFederate 6
Server
Server
Table 15: Troubleshooting the PingFederate Server
Administrator’s Manual
Problem
Solution
PingFederate does not
start.
Make sure that the Java SDK is installed (see
“Installing the JDK” in the “Installation” chapter of
Getting Started).
373
Appendix F
Troubleshooting
374
PingFederate 6
Glossary
account link
artifact
A persistent name identifier that enables federation of
separately established accounts among disparate
domains (see also account linking and pseudonym).
A reference to a SAML protocol message. The
federation partner that receives the artifact dereferences
it, identifying the sender, and requests the complete
message in a separate SOAP transaction.
account linking
A form of identity mapping among separate user
accounts managed under different Internet domains.
The mapping typically involves a name identifier—
which may be a pseudonym—used to link the user to
each account. The identifier is persisted at the SP site
to enable seamless SSO/SLO. Additional attributes may
be sent with the identifier.
Artifact Resolution Service
The SOAP endpoint that processes artifacts returned
from a federation partner to retrieve the referenced
XML message. Can be used to dereference
authentication requests, assertion responses, and SLO
messages.
assertion
account mapping
A form of identity mapping by which one or more user
attributes is passed in a single sign-on transaction. The
attributes are used at the destination site as a means
identifying the user and looking up local account
information.
A SAML XML document that contains identifying
information about a particular subject; i.e., a person,
company, application, or system. A SAML assertion
can contain authentication, authorization, and
attribute information about the subject.
Assertion Consumer Service
adapter
Supplementary software that allows PingFederate to
interact with Web applications and systems. Two
adapter choices are bundled with PingFederate: an
OpenToken Adapter for use with separately available
developer integration kits, and an LDAP adapter for use
with your active directory data store.
adapter contract
A list of attributes “hard-wired” to an adapter and
conveyed generally via cookies between the adapter and
application.
Administrator’s Manual
A SAML-compliant portion of PingFederate in an SP
role that receives and processes assertions from an IdP.
attributes
Distinct characteristics that describe a subject. If the
subject is a Web site user, attributes may include a
name, group affiliation, email address, etc.
attribute contract
A list of attributes, agreed to by the partners in an
identity federation, representing information about a
user (SAML subject). The attributes are sent from the
IdP to the SP during SSO or STS processing.
375
Glossary
attribute mapping
Database Management System
A form of identity mapping between IdP and SP user
accounts that uses attributes to identify the user or
provide supplemental information.
A system for storing and maintaining user account
information and attributes. The tables and columns in
the RDBMS are used by PingFederate to create user
look-up and attribute retrieval queries. (See Java
Database Connectivity.)
audience
The XML element in a SAML assertion that uniquely
identifies a Service Provider.
authentication context
An element in a SAML assertion indicating the
method or process used by an IdP to authenticate the
subject of the assertion; may be used for authorization
decisions or auditing compliance.
data store
A database or directory location containing user
account records and associated user attributes.
defederation
Optional user-initiated delinking of an identity
federation that uses a persistent name identifier or
pseudonym for account linking.
attribute source
Specific database or directory location containing data
needed by an IdP to fulfill a connection partner's
attribute contract or by an SP to look up additional
attributes to fulfill an adapter contract.
back-channel
Server-to-server, cross-domain communication path
using a protocol, typically SOAP, that does not rely on a
browser as an intermediary.
binding
A mapping of SAML request and response messages to
specific transport protocols (redirect, POST, or
artifact).
certificate
A digital file used for identity verification and other
security purposes. The certificate, which is often issued
by a Certificate Authority (CA), contains a public key,
which can be used to verify the originator’s identity.
digital signature
A process for verifying the identity of the originator of
an electronic document and whether the document has
been intercepted or altered. The process involves
message signing, signature validation, and signing
policy coordination between partners.
endpoint
A terminal or gateway that generates or terminates a
stream of information. For example, a PingFederate SP
server contains an endpoint for the Assertion
Consumer URL.
entity ID
The XML element in a SAML assertion that uniquely
identifies an Identity Provider.
Extensible Markup Language
A structured, hierarchical text format—based on
SGML (Standard Generalized Markup Language)—for
the flexible and organized exchange of data.
Certificate Revocation List
(CRL) A list of revoked signing certificates, maintained
by the issuing authority at a public URL.
HTTP cookie
A dedicated SaaS Provisioning configuration specific to
a particular service partner, data source, and target
service.
Information sent from a server to a Web browser to
identify a registered Web site user. Once the cookie is
placed in the browser, it is sent back to the server to
identify the user every time the user accesses the site.
PingFederate's integration adapters interface with the
cookie.
connection partner
HTTP header
channel
Entities, such as companies, that are part of an identity
federation. These entities are referred to as connection
partners in the PingFederate configuration process.
credential
Information used to identify a subject for access
purposes (e.g., username and password). A credential
can also be a certificate.
376
The section of an HTTP request or response containing
information about the client or the server. PingFederate
can use HTTP headers to look up session information
passed by the IdP’s Web application.
HTTP request parameter
A named parameter sent as part of a URL request from
a browser to a Web server.
PingFederate 6
identity federation
A trust agreement between or among organizations,
implemented using accepted standards, to provide userauthentication tokens and other user or system
attributes securely across Internet domains, primarily to
enable cross-domain SSO.
Identity Provider
The identity source or SAML authority that
authenticates a subject and provides an SP with a
security assertion vouching for that authentication.
IdP-initiated SSO or SLO
An identity federation transaction in which the initial
action requiring a security context from an IdP occurs
at a IdP’s site. For example, the user is logged on to the
IdP and requests protected resources on an SP. The IdP
sends authentication information to the SP.
inbound
A direction of message flow coming into a server
relative to the server’s identity federation role (IdP or
SP). For an IdP, inbound messages include SAML
authentication requests. For an SP, inbound messages
include SAML assertions.
Java Database Connectivity (JDBC)
A Java API that allows Java programs to interact with
databases.
keysize
The length (in bits) of each key in a keypair.
keypair
The private key and public key represented by a
certificate. PingFederate uses the private key of its
keypair(s) to generate signatures for assertions, requests,
and responses, as applicable.
Lightweight Directory Access Protocol
A set of protocols used for accessing information
directories. PingFederate uses the LDAP v3 protocol for
user look-up and attribute processing.
metadata
The SAML 2.0 standards define a metadata exchange
schema for conveying XML-formatted information
between two SAML entities. Metadata includes
endpoint URLs, binding types, attributes, and security
policy information.
Online Certificate Status Protocol
(OCSP) A standard developed by the Internet
Engineering Task Force that enables Internet
applications to obtain the current status of signing
Administrator’s Manual
certificates, indicating whether a certificate has been
revoked, via HTTP.
opaque
Not readable. If a user's subject identifier is opaque, the
an SSO partner cannot directly identify the user with
reference to the source. An persistent identifier, or
pseudonym, can be used for Account Linking.
outbound
A direction of message flow leaving a server. For an IdP,
outbound messages include SAML assertions. For an SP,
outbound messages include SAML authentication
requests.
partner
See connection partner.
portal
A Web-based application, accessed using a Web
browser, that often aggregates content from multiple
providers and/or serves as a central point of entry.
POST
An HTTP method of transmitting data contained in
HTML forms, by which the data appears in the message
body.
principal
A user, system, or process whose identity can be
authenticated. See subject.
profiles
Rules that describe how to embed SAML assertions
into and extract them out of other protocols in order to
enable SSO or SLO. Profiles describe SAML request
and response flows that fulfill specific use cases.
protected resource
Information, typically accessed via a Web URL, that is
protected by an access management system. See target
URL.
protocol
An agreed-upon format for transmitting data. XML
format of SAML request or response messages.
pseudonym
A persistent name identifier assigned to a user and
shared among entities, usually with the user’s
permission, to enable SSO and SLO. Pseudonyms are
often used with the SAML account linking protocol to
enable SSO while preventing the discovery of the user's
identity or activities.
377
Glossary
Public Key Infrastructure
Service Provider
(PKI) Enables users of an unsecured public network,
such as the Internet, to securely and privately exchange
data and money through the use of keypairs and
certificates. The PKI provides for a digital certificate
that can identify an individual or an organization and
directory services that can store and, when necessary,
revoke the certificates.
A system entity that provides access to a protected
resource based on authentication information supplied
by an IdP.
SP-initiated SSO or SLO
An identity-federation transaction in which the initial
action requiring a security context from an IdP occurs
at a SP’s site.
redirect
A SAML binding that conveys a request or response by
sending the user’s browser to another location. For
instance, an authentication request can be sent from an
SP through a browser to an IdP.
SAML
See Security Assertion Markup Language.
SAML authority
A security domain that issues SAML assertions.
Secure Sockets Layer
An encryption protocol that sends data between a
client and server over a secure HTTP connection.
Security Assertion Markup Language
(SAML) A standard, XML-based, message-exchange
framework enabling the secure transmittal of
authentication tokens and other user attributes across
Internet domains.
security domain
An application or group of applications that trust a
common security token used for authentication,
authorization, or session management. The token is
issued to a user after the user has authenticated to the
security domain.
session persistence
A mechanism for identifying a user or browser for
subsequent requests to a server, needed because the
HTTP protocol is stateless. This information is used to
lookup state information for the user—for example,
items in a shopping cart. PingFederate does not
implement session persistence; it facilitates the
communication of session information between systems
that do.
Simple Object Access Protocol
(SOAP) Defines the use of XML and HTTP to access
services, objects, and servers in a platform-independent
manner.
Single Logout
The process of logging a user out of multiple “session
participants” or sites where the user has started an SSO
session.
Single Logout Return Service
The SAML implementation endpoint URL that returns
logout requests.
Single Logout Service
The SAML implementation endpoint URL that
receives logout requests for processing.
security token
Single Sign-On
A collection of information used to establish acceptable
identity for security purposes. Tokens can be in binary
or XML format. A SAML assertion is one kind of
security token.
(SSO) The process of authenticating an identity
(signing on) at one Web site (usually with a user ID and
password) and then accessing resources secured by other
domains without re-authenticating.
Security Token Service
Single Sign-on Service
An entity responsible for responding to WS-Trust
requests for validation and issuance of security tokens
used for SSO authentication to Web Services.
The SAML implementation endpoint URL that
receives authentication requests for processing.
Source ID
service-oriented architecture
A loosely coupled application architecture in which all
functions or services are accessible via standard
protocols. Interfaces are platform and programminglanguage independent.
378
A 20-byte sequence used to determine an IdP’s identity.
subject
A person, computer system, or application. In the
SAML context, assertions make statements about
subjects. See principal.
PingFederate 6
target URL
WS-Trust
The SP’s protected resource; the end destination of an
SSO event. See protected resource.
A standard protocol by which an application can
request that an STS issue, validate, or exchange
security tokens.
transient name identifier
A temporary ID used to preserve user anonymity while
facilitating account linking.
token exchange
The process by which a security token is exchanged for
another security token.
Uniform Resource Identifier
Identifies an Internet resource with a string of
characters conforming to a specified format.
Uniform Resource Locator
Identifies an Internet resource according to its Internet
location.
virtual server ID
An optional unique identifier by which an identity
federation deployment can be known to a specific
connection partner.
Web Services Security
A standard mechanism for securing Web service
interactions, often by binding a security token to the
Web service request.
Web Services
Nonbrowser-based, loosely coupled applications that
provide modular, programming-language-independent
access to specific functions and data across the Internet,
via XML and standard protocols.
Web Service Client
An entity that requests a Web service interaction. In
the context of an STS, the Web service Client would
request that a security token be issued for the
interaction.
Web Service Enhancement
Supplemental software for the .NET framework
provided by Microsoft.
Web Service Provider
In the context of an STS, an entity that requests
validation of the security token sent with a client’s
request for service.
WS-SX
The OASIS committee working on WS-Trust.
Administrator’s Manual
379
Glossary
380
PingFederate 6
List of Acronyms
ACS
Assertion Consumer Service
LDAP
Lightweight Directory Access
Protocol
API
Application Programmer Interface
ARS
Artifact Resolution Service
O
Organization
CA
Certificate Authority
OASIS
Organization for the Advancement of
Structured Information Standards
CRL
Certificate Revocation List
OCSP
Online Certificate Status Protocol
CSR
Certificate Signing Request
OU
Organizational Unit
DBMS
Database Management System
PKI
Public Key Infrastructure
DMZ
Demilitarized Zone
RDBMS
DN
Distinguished Name (certificate
identifier)
Relational Database Management
System
RST
<RequestSecurityToken> WSFederation and WS-Trust XML
element
RSTR
<RequestSecurityTokenResponse>
WS-Federation and WS-Trust XML
element
SAML
Security Assertion Markup Language
SaaS
Software as a Service
SDK
Software Development Kit
SP
Service Provider
SLO
Single Logout
SOA
service-oriented architecture
DNS
Domain Name System
EIM
Enterprise Identity Management
GUI
Graphical User Interface
HTTP
HyperText Transfer Protocol
HTTPS
Secure HyperText Transfer Protocol
IdM
Identity Management
IdP
Identity Provider
IP
Internet Protocol
J2SDK
Java 2 Software Development Kit
JDBC
Java Database Connectivity (JDBC)
Administrator’s Manual
381
List of Acronyms
SOAP
Simple Object Access Protocol
SQL
Structured Query Language
SSL
Secure Sockets Layer
SSL/TLS
Secure Sockets Layer/Transport Level
Security
SSO
Single Sign-On
SSTC
Security Services Technical
Committee (of OASIS)
STS
Security Token Service
TCP
Transmission Control Protocol
URI
Uniform Resource Identifier
URL
Uniform Resource Locator
WSC
Web Service Client
WSP
Web Service Provider
WSS
Web Services Security
XASP
X.509 Attribute Sharing Profile
XML
Extensible Markup Language
382
PingFederate 6
Index
A
access control 36
account linking 5
configuring 226
account mapping 5
accounts, administrator 36
activation
for IdP connection 271
for SP connection 189
adapters
commercial 5
configuring
IdP 106
SP 200
integration 4
mapping URLs to SP 205
administrators, adding 37
affiliations, SP 190
application endpoints
IdP 113
SP 208
archiving data 35
artifact
lifetime, setting for IdP connections 249
lifetime, setting for SP connections 159
Assertion Consumer Service URLs 154
assertions
content 130
lifetime 128
mapping attributes to 136
attribute authority (XASP), configuring 261
attribute contract 7
default for SP connection 152
IdP connection 228
Administrator’s Manual
to SP 132
attribute query
configuring for IdP connection 260
configuring for SP connection 164
mapping names 261
attribute sources
custom 81
failover (for IdP) 138
for IdP 138
attributes
mapping
about 5
for SP connection 149, 166, 305, 325
for user provisioning 258
masking in log files 10, 27
overview 7
sources for express provisioning 255
audit logging 21
Auto-Connect
about 15
activation (IdP connection) 274
activation (SP connection) 196
allowed IdP domains 275
allowed SP domains 197
configuring (as an IdP) 194
configuring (as an SP) 272
metadata lifetime 71
metadata signing 71
B
back-channel settings
for IdP connections 263
for SP connections 169
backups, configuring 35
383
bindings
allowable
for IdP connection 248
for SP connection 158
configuring
for IdP connection 223
for SP connection 126
SOAP for IdP connection 263
SOAP for SP connection 169
C
certificate authority (CA) 90
certificates
authority, verifying 15
considerations 20
digital signing 96
expiration notification 58
for metadata 33
for SOAP authentication 20
management 10
revocation of 100
selecting XML decryption (SP-to-IdP) 270
selecting XML encryption (SP-to-IdP) 269
SSL 56, 91
SSL client 94
verifying 15
checklist, for federation 20
common domains 84
configuration
archive 35
connection list
for IdP connection 214
for SP connection 117
connections
migrating 45
connections, importing 357
cookies, common domain 84
cookies, for IdP Discovery 83
custom data stores
filters (IdP connections) 241
filters (SP connections) 148, 325
selecting fields (IdP connections) 242
selecting fields (SP connections) 148
D
data archiving 35
data exchange
automated 22
for IdP connection 22
for SP connection 22
data store 21
description 9
for attribute query profile 166
introduction 72
384
JDBC configuration 74
LDAP configuration 78
selecting
for express provisioning 69, 256
for IdP connection 233
for SaaS provisioning 180
for SP connection 140
troubleshooting 371
database
filter
for IdP connection 236
for IdP connection 234
for SP connection 141
database filter
for SP connection 143, 320
decryption keys
for IdP connections 270
for SP connections 176
defederation 6
digital signatures
about 10
keys and certificates 96
policy 13
digital signing
for IdP connection 267
for metadata 33
for SP connection 172
directory service
code example 362
SOAP example 364
SSO 361
discovery, IdP 83
domains
allowed for IdP Auto-Connect 275
allowed for SP Auto-Connect 197
E
email
addresses 58
notifications 58
server configuration 40
encryption, XML 162, 252
endpoints
IdP application 113
protocol, IdP 113
protocol, SP 210
SP application 208
entity ID 67
error message, SLO 112
event trigger, for provisioning 254
F
failover
for data stores (IdP) 138
PingFederate 6
failsafe attribute source 151
federation
checklist 20
defederation 6
ID 22
roles, choosing 64
URLs 67
filter, database
for IdP connection 236
for SP connection 143, 320
filter, LDAP
for IdP connection 239
for SP connection 146, 324
H
heartbeat, server
checking via HTTP 356
host names, virtual 42
I
identity mapping
about 5
IdP configuration 130
SP configuration 226
IdP
adapters 106
connections
activation 271
introduction 199
default URL 112
SLO error message 112
IdP Discovery
common domain service 84
configuring 83
cookies for 83
local domain service 85
selecting 64
IdP-initiated SLO
configuring
for IdP connection 225
for SP connection 128
IdP-initiated SSO
configuring
for IdP connection 224
for SP connection 127
importing
metadata
for IdP connection 217
importing connections 357
importing metadata
for SP connection 121
installation
license key 45
troubleshooting 372
Administrator’s Manual
integration kits 4
J
JDBC configuration 74
K
keys
for XML decryption (SP-to-IdP) 270
for XML encryption (IdP-to-SP) 176
keys and certificates
digital signature 96
SSL 94
L
LDAP
configuration 78
directory search
for SP connection 145, 322
filter 146, 239, 324
pooling options 80
SSL 79
using SSL 79
license key, installing 45
licensing
email address to notify 58
expiration notification 58
Lifetime 71
Linux
starting the server 26
stopping the server 26
log files 27
logging
administrator audit 28
files 27
modes 29
transaction 29
M
main menu
for IdP connection 213
for SP connection 115
mapping
adapters
URLs to SP 205
attributes
configuring for SP connection 149, 166, 305, 325
identity 5, 130, 226
masking attributes 10
masking attributes in logs 27
message
385
signing 11
validation 11, 20
metadata
exporting 30
exporting XML encryption certificates 33
importing
for IdP connection 217
for SP connection 121
lifetime for Auto-Connect 71
providing for Auto-Connect 15
signing 34
signing for Auto-Connect 71
use 22
migrating connections 45
monitoring
JMX 60
provisioning 60
server 59
enabling 223
event trigger for 254
mapping attributes for 258
provisioning, as SP
choosing data stores for 256
provisioning, SaaS
choosing internal data store 69
choosing source data stores for 180
pseudonyms
unique values for 110
R
requester mapping, for XASP 208
resetting passwords 39
roles, choosing IdP/SP 64
runtime
configuration 42
reporting 59
N
name identifiers
SAML 2.0 130
WS-Federation 132
notifications
runtime 58
O
Object-Graph Navigation Language (OGNL), editing 370
P
password notification 36
passwords
changing 40
resetting 39
planning checklist 20
pooliing options
database 76
pooling options
LDAP 80
profiles
configuring
for IdP connection 223
for SP connection 126
saving configuration
for IdP connection 163, 253
protocol endpoints
IdP 113
SP 210
protocols
choosing 64
troubleshooting 372
provisioning
386
S
SAML
selecting 64
SAML 1.1
SP connection steps 126, 222
SAML 2.0
SP connection steps 125, 222
SDK 5
security
back channel 20
considerations 10
server
troubleshooting 373
server HTTP checking 356
server ID 20
server monitoring 59
server status verification 356
service URL
IdP, for WS-Fed 246
SP, for WS-Fed 156
session integration considerations 21
Signing 71
signing XML files 34
SLO service URLs 157
SNMP configuration 59
SOAP responder URL 22
SP
adapters 200
connections
activation 189
introduction 105
default URL 207
SP-initiated SLO, configuring
for IdP connection 225
for SP connection 128
PingFederate 6
SP-initiated SSO, configuring
for IdP connection 224
for SP connection 127
SSL 10
about 13
certificates 91
keys and certificates 94
using for LDAP 79
SSO directory service 361
standards
choosing 64
starting the server
Linux 26
Windows 26
stopping the server
Linux 26
Windows 26
summary
for IdP connection 271
for SP connection 189
synchronization
clock 21
provisioning 69
system administration (single or multiple users) 56
T
time synchronization 21
transaction logging 21, 29
transport security considerations 20
trigger, for provisioning 254
troubleshooting 371
data store 371
installation 372
protocols 372
server 373
for SP servers 214
W
Web Services
connection management 357
SSO Directory 361
Web templates 50
where clause
for IdP connection 236
for SP connection 143, 320
WS-Federation
selecting 64
setting realm ID 67
SP connection steps 125, 222
SP service URL 156, 246
WS-Trust STS
enabling 277
IdP connections 311
SP connections 289
X
X.509 certificates 11
XASP
requester mapping 208
XML encryption 10
about 15
exporting keys to metadata 33
IdP-to-SP 162
SP-to-IdP 252
XML files, signing 34
U
unique IDs 20
unique values, for pseudonym creation 110
upgrading PingFederate 35
user management
setting 56
users
account management 36
adding 37
V
validating messages 20
verifying certificates 15
virtual host names 42
virtual IDs 20
for IdP servers 117
Administrator’s Manual
387
388
PingFederate 6

advertisement

Was this manual useful for you? Yes No
Thank you for your participation!

* Your assessment is very important for improving the workof artificial intelligence, which forms the content of this project

Download PDF

advertisement