CIM Architecture Overview – PingFederate Integration

Date Recorded: August 12, 2025
Duration: 38m 30s
Participants:

• Matt Riek
• Michael Paterson

Purpose

This document outlines the architectural integration of PingFederate and PingOne with the CIAM (Customer Identity Management) system. It is intended to onboard developers and provide a high-level overview of the login flow, provisioning, and adapter configuration.

Overview of PingFederate Integration

Goals

• Provide a bird’s-eye view of the login flow through PingFederate.
• Explain how PingFederate interacts with CIAM components.
• Clarify the structure and purpose of key services: PF Adapters, Datastore Provisioner, and PingFederate Configuration.

Key Components

1. Policy Administration Point (PAP)

• Part of the CQRS pattern (Command Query Responsibility Segregation).
• Handles mutations (writes) and reads of policy data.
• Backed by PostgreSQL (LDAP was considered but rejected due to write limitations).

2. Policy Retrieval Point

• Represents the query side of CQRS.
• Used for access patterns similar to directory services.

Datastore Provisioner

Function

• A lightweight REST API service written in Go.
• Provisions identities for PingFederate during login.
• Talks to a secure endpoint on the PAP to retrieve or upsert user data.

Flow

1. User logs in via an upstream IDP (e.g., Gary from John Deere).
2. If the user doesn’t exist in CIAM, the provisioner creates or updates the identity.
3. PingFederate uses a predefined contract to communicate with this service.

PingFederate Configuration

Structure

• Located in the ping-federate-configuration folder.
• Built using JSON templates and Python tooling.
• Templates are extracted from PingFederate via its REST API and versioned.

Deployment

• Docker image of PingFederate is preconfigured with templates.
• The location of the Datastore Provisioner is embedded in the image.

Authentication Flow

Policies and Fragments

• Login flows are built using policies and fragments.
• Fragments are modular units that can call other fragments.
• Policies select fragments based on client ID and other selectors.

Fragment Mapping

• Each fragment has input/output mappings.
• Outputs are mapped to contracts, which are later used to generate access tokens.

Simplification Strategy

• Reducing the number of policies simplifies maintenance.
• As clients move through adoption phases, older policies are deprecated.

PF Adapters

Purpose

• Extend PingFederate’s login flow via REST-based agentless adapters.
• Located in the pf-adapters folder.

Types

• Reference IDP Adapter: REST API-based integration.
• Adapters include:
  • bp-selector
  • idp-chooser
  • login-as
  • select-org-unit (to be merged into PF Adapters)

Flow

1. PingFederate redirects to the adapter using a pickup parameter.
2. Adapter uses the parameter to fetch session data from PingFederate.
3. Adapter presents a form to the user.
4. User input is sent back via a dropoff to continue the flow.

Contract Mapping

Final Step

• Authentication results in a policy contract.
• Contracts are mapped to access tokens via the application configuration.
• This completes the login flow from IDP to token issuance.

Next Steps

• Future topics: contract mappings, adapter specifics, and CIAM internals.