LAB 03: SAML 2.0 Federation
and Identity Brokering

Lab Metadata

Lab Title and Description

Cross Domain Trust: Federating Two Identity Domains with SAML 2.0 and Dissecting the Assertion

Northgate Financial has acquired Harborview Wealth, a smaller advisory firm with its own identity infrastructure. The integration board's day one requirement is blunt: Harborview's applications must accept Northgate identities from the morning the deal closes, with no account migration, no password resets, and no shared directories. Harborview's platform speaks SAML 2.0, as an enormous share of enterprise software still does: Salesforce, Workday, ServiceNow, the AWS console, and most B2B SaaS all federate over SAML today, which is why the role this track targets lists SAML 2.0 alongside OIDC as required expertise.

In this lab you build that trust relationship end to end. A second Keycloak realm, harborview, plays the acquired company's identity platform and acts as the SAML Service Provider through Keycloak's identity brokering. Your existing northgate realm becomes a SAML Identity Provider, still authenticating users against the Lab 01 LDAP directory. You will exchange metadata between the two domains by hand, extract and pin the IdP's signing certificate, register the Service Provider, map attributes across the trust boundary, and then log in across domains as Amina Smith with a password that exists only in OpenLDAP.

Then comes the part most engineers never do: you will capture the live SAML Response in your browser's developer tools, decode it in the terminal, and read the assertion line by line, Issuer, Subject, Conditions, AudienceRestriction, AttributeStatement, Signature, mapping each XML element to the JWT claim you learned in Lab 02. Two protocols, one mental model. Estimated completion time is 3 to 3.5 hours.

Prerequisites

3.1 Prior labs required

# Bring the track containers up
docker start ib-openldap ib-keycloak ib-phpldapadmin

# Confirm the northgate realm answers
curl -s http://localhost:8081/realms/northgate/.well-known/openid-configuration | jq -r '.issuer'
# Expected: http://localhost:8081/realms/northgate

# Confirm LDAP still authenticates Amina
ldapwhoami -x -H ldap://localhost:389 \
  -D "uid=asmith,ou=people,dc=identitybytes,dc=lab" -w "<USER_PASSWORD>"

3.2 System requirements

3.3 Required tools and versions

3.4 Installation commands

# xmllint ships in the libxml2-utils package. It is to XML what jq is
# to JSON: the identity engineer's assertion reading tool.
sudo apt-get update && sudo apt-get install -y libxml2-utils

which xmllint
# Expected: /usr/bin/xmllint. macOS ships libxml2; nothing to install.

3.5 Verification of tools

echo '<a><b>ok</b></a>' | xmllint --format -

Real World Problem Statement

This lab solves the problem that appears the moment identity leaves one organisation's walls: cross domain trust. Mergers and acquisitions, partner portals, and above all SaaS adoption all pose the same question: how does system B, which you do not run, accept users from directory A, which you do, without ever seeing their passwords? Copying accounts fails immediately, because passwords cannot move, lifecycle events do not propagate, and the auditors who signed off on Lab 01's single source of truth would rightly object to a second one.

Federation is the answer, and SAML 2.0 is its incumbent language. One side, the Identity Provider, authenticates the user and issues a digitally signed XML assertion; the other side, the Service Provider, validates the signature against a pinned certificate and trusts the identity inside. No shared database, no password ever crossing the boundary, and trust that can be revoked by removing one certificate. OIDC, which you met in Lab 02, is the modern equivalent, but SAML predates it by a decade and remains the default federation protocol of enterprise SaaS and government platforms; a senior IAM architect who cannot read an assertion cannot debug half the SSO estate.

Why it matters, across four dimensions

Concrete scenario

Northgate Financial, 5,000 employees, completes the acquisition of Harborview Wealth, 400 employees, on the first of the month. The integration board mandates: Northgate staff shall access Harborview's platforms using Northgate credentials from day one; no Northgate password shall be stored or transmitted to Harborview systems; the trust shall be revocable unilaterally by either security team. Your task is the reference federation: Harborview's identity platform configured as a SAML Service Provider brokering to Northgate's Identity Provider, signature validation pinned to Northgate's published certificate, identity attributes mapped across the boundary, and the whole trust proven with a captured, decoded, signed assertion as evidence for the security review.

Skills Mapped to Production Solutions

Architecture Overview

Component breakdown

Data flow (SP initiated single sign-on)

1. User visits Harborview: the browser opens the harborview account console; its login page offers the Northgate SSO option. Why: SP initiated flow, where the destination triggers federation, is how the overwhelming majority of enterprise SSO logins begin.
2. AuthnRequest crosses the boundary: harborview redirects the browser to northgate's SAML single sign-on service carrying a SAML AuthnRequest that names the SP and where to respond. Why: SAML is front channel by design; the two platforms never talk directly, which is what lets federation cross company networks and firewalls.
3. The IdP authenticates the user: northgate shows its login page, and the submitted password is verified by an LDAP bind through the Lab 02 federation. Why: the security perimeter of the whole federation is the IdP's authentication, which is why MFA in IB-SIA-05 lands here and instantly protects every SP downstream.
4. A signed Response returns: northgate posts a SAML Response to harborview's Assertion Consumer Service, the broker endpoint, containing an assertion with the subject, validity conditions, audience restriction, attributes, and an XML signature over the whole document. Why: the signature and pinned certificate are the entire basis of trust; nothing else about the message is trustworthy on its own.
5. The SP validates and establishes a session: harborview verifies the signature, checks issuer, audience, and time conditions, runs the first login flow to provision or link the local user, imports mapped attributes, and issues its own session. Why: this local session is what makes the user "logged in" to the acquired estate, and its lifetime is now a harborview policy decision, a subtlety that matters in incident response.

Security considerations

Step by Step Implementation

# Create a workspace for this lab's artefacts
mkdir -p ~/ib-sia-03 && cd ~/ib-sia-03

# Fetch the northgate realm's SAML IdP metadata (the descriptor)
curl -s http://localhost:8081/realms/northgate/protocol/saml/descriptor \
  -o northgate-idp-metadata.xml

# Read it, pretty printed. Note three things as you scroll:
#   entityID          the IdP's identity in every assertion's Issuer
#   SingleSignOnService  the URL AuthnRequests go to
#   X509Certificate   the public key that verifies signatures
xmllint --format northgate-idp-metadata.xml | less

# Extract the certificate value into a file. The XPath below pulls the
# first X509Certificate element's text, and tr strips whitespace.
xmllint --xpath "//*[local-name()='X509Certificate'][1]/text()" \
  northgate-idp-metadata.xml | tr -d '[:space:]' > northgate-signing.cert

# Sanity check: a base64 blob several hundred characters long
wc -c northgate-signing.cert

# Decode base64 into XML and format it. If your paste was URL encoded,
# the python line below handles both decodings in one pass.
base64 -d ~/ib-sia-03/samlresponse.b64 | xmllint --format - \
  > ~/ib-sia-03/samlresponse.xml || \
python3 -c "import sys,base64,urllib.parse;d=open('/home/'+__import__('getpass').getuser()+'/ib-sia-03/samlresponse.b64').read().strip();print(base64.b64decode(urllib.parse.unquote(d)).decode())" \
  | xmllint --format - > ~/ib-sia-03/samlresponse.xml

# Read it
less ~/ib-sia-03/samlresponse.xml

<samlp:Response Destination="http://localhost:8081/realms/harborview/broker/northgate-saml/endpoint" ...>
  <saml:Issuer>http://localhost:8081/realms/northgate</saml:Issuer>
  <samlp:Status>
    <samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/>
  </samlp:Status>
  <saml:Assertion ...>
    <saml:Issuer>http://localhost:8081/realms/northgate</saml:Issuer>
    <dsig:Signature> ... <X509Certificate>MIICnzCC...</X509Certificate> ... </dsig:Signature>
    <saml:Subject>
      <saml:NameID Format="...:unspecified">jpatel</saml:NameID>
    </saml:Subject>
    <saml:Conditions NotBefore="2026-07-06T09:14:02Z" NotOnOrAfter="2026-07-06T09:15:02Z">
      <saml:AudienceRestriction>
        <saml:Audience>http://localhost:8081/realms/harborview</saml:Audience>
      </saml:AudienceRestriction>
    </saml:Conditions>
    <saml:AttributeStatement>
      <saml:Attribute Name="email"><saml:AttributeValue>jay.patel@identitybytes.lab</saml:AttributeValue></saml:Attribute>
      <saml:Attribute Name="firstName"><saml:AttributeValue>Jay</saml:AttributeValue></saml:Attribute>
      <saml:Attribute Name="lastName"><saml:AttributeValue>Patel</saml:AttributeValue></saml:Attribute>
    </saml:AttributeStatement>
  </saml:Assertion>
</samlp:Response>

Testing and Validation

End to end scenario: single sign-on across the merged estate

This validates the promise made to the integration board: one login, both domains, one password store, revocable trust.

# STAGE 1: fresh private window, log in to harborview via Northgate SSO
# as asmith. Expected: harborview account console, as in Phase 4.

# STAGE 2: single sign-on proof. In the SAME window, open
# http://localhost:8081/realms/northgate/account
# Expected: signed in WITHOUT a password prompt. The IdP session from
# Stage 1 is live, which is precisely what SSO means: one authentication,
# many destinations.

# STAGE 3: source of truth proof. Change Amina's password in LDAP:
ldappasswd -x -H ldap://localhost:389 \
  -D "cn=admin,dc=identitybytes,dc=lab" -w "<YOUR_ADMIN_PASSWORD>" \
  -s "<NEW_USER_PASSWORD>" "uid=asmith,ou=people,dc=identitybytes,dc=lab"
# Then, in a NEW private window, log in to harborview via Northgate SSO.
# Expected: the old password fails, the new one succeeds, and neither
# Keycloak realm was touched. Two federation hops, one enforcement point.

# STAGE 4: revocation drill. In realm northgate, open the harborview
# client and switch Enabled OFF, Save. In a new private window, attempt
# the SSO login. Expected: northgate refuses the AuthnRequest with an
# error page; the trust is severed by one toggle. Re-enable and confirm
# login works again. This is the unilateral revocation the integration
# board required, demonstrated.

Negative tests

# TEST N1: tampered trust anchor must break the federation.
# In realm harborview, Identity providers, northgate-saml: replace the
# validating certificate with the WRONG one. Generate a convincing decoy:
openssl req -x509 -newkey rsa:2048 -nodes -keyout /tmp/fake.key \
  -out /tmp/fake.crt -days 1 -subj "/CN=northgate" 2>/dev/null
grep -v "CERTIFICATE" /tmp/fake.crt | tr -d '\n'; echo
# Paste that base64 into Validating X509 certificates, Save, then attempt
# the SSO login in a fresh private window.
# Expected: login FAILS at the broker with an invalid signature error
# (northgate's events show success; harborview's show IDENTITY_PROVIDER
# login_error). Same CN, wrong key: names mean nothing, signatures mean
# everything. RESTORE the real certificate from
# ~/ib-sia-03/northgate-signing.cert and confirm login works again.

# TEST N2: unregistered Service Provider must be refused.
# In realm northgate, open the harborview SAML client and change the
# Client ID to http://localhost:8081/realms/harborview-WRONG, Save.
# Attempt the SSO login. Expected: northgate rejects the AuthnRequest
# (Invalid Requester style error) because no client matches the request's
# Issuer. Change the Client ID back and confirm recovery. This is the
# most common real world SAML fault, now seen from the inside.

# TEST N3: response replay must fail.
# After a successful login, use the browser back button to return to the
# POST and resubmit it (the browser will ask to resend the form data).
# Expected: an error page, not a second session. Assertions are single
# use and time boxed; the sixty second NotOnOrAfter you read in Phase 5
# is doing exactly this job.

Stretch exercise: carry groups across the boundary

Add a Group list mapper to the SAML client in northgate (SAML Attribute Name groups, single attribute ON, full path OFF), and an Attribute Importer mapper on the harborview broker mapping attribute groups to a user attribute of the same name. Log in again, re-capture the Response, and find finance-team inside an AttributeStatement, your Lab 01 LDIF group having now crossed a federation boundary. This is the mechanism behind role based access in federated SaaS.

Common failure modes and solutions

Security Analysis

What makes this implementation secure

• Trust is anchored in cryptography, not configuration names: the SP validates every assertion against a pinned certificate, and test N1 proved that a decoy certificate with an identical CN breaks the federation.
• Assertions are scoped and perishable: audience restriction names the one SP allowed to consume them, destination locks the ACS, and the sixty second conditions window plus single use semantics defeated the replay in test N3.
• Credentials are confined to the IdP: the SP realm provably stores no passwords, and the LDAP directory remained the sole enforcement point through a live password change.
• Registration is bidirectional and revocable: the IdP only answers registered SPs (test N2), responses only travel to registered endpoints, and either security team can sever the trust with one toggle (Stage 4).
• Both domains keep independent audit trails of every brokered login, satisfying the two company evidence requirement of the scenario.

What is intentionally simplified for the lab

• Everything rides HTTP on localhost; real federation runs exclusively over TLS, and SAML's bindings assume it.
• AuthnRequests are unsigned and assertions unencrypted: the SP has no signing or decryption keypair configured yet.
• Both realms share one Keycloak instance and one clock, which hides the clock skew and network failure classes that dominate real federation incidents.
• The first login flow auto provisions without email verification or approval, a deliberate M&A speed choice that is not universally appropriate.
• Single logout (SLO) is not configured, so logging out of one domain does not end the other's session.

Production hardening recommendations

Cleanup Instructions

Option A: pause the lab, keep everything (recommended, later labs reuse both realms)

docker stop ib-keycloak ib-openldap ib-phpldapadmin
# Resume later with:
docker start ib-openldap ib-keycloak ib-phpldapadmin

Option B: remove Lab 03 only, keep Labs 01 and 02

# All Lab 03 state lives inside Keycloak configuration, so removal is
# three admin console actions rather than container commands:
#   1. Realm northgate, Clients: delete the harborview entity ID client
#   2. Realm harborview, Identity providers: delete northgate-saml
#   3. Realm selector: delete the harborview realm entirely
#      (Realm settings, Action menu, Delete)

# Remove the captured artefacts from disk, keeping the metadata and
# certificate if you are publishing the portfolio first:
rm -f ~/ib-sia-03/samlresponse.b64 ~/ib-sia-03/samlresponse.xml /tmp/fake.key /tmp/fake.crt

Recommended Learning Links

• OASIS SAML 2.0 Core specification (the assertion and protocol definitions you read in Phase 5)
• OASIS SAML 2.0 Bindings (HTTP-Redirect and HTTP-POST, the two you used)
• OASIS SAML 2.0 Metadata (the descriptor format from Phase 2)
• Keycloak Server Administration Guide: Integrating identity providers (brokering)
• Keycloak Server Administration Guide: SAML clients
• W3C XML Signature Syntax and Processing (the dsig blocks in your captured Response)
• RFC 7522: SAML 2.0 Profile for OAuth 2.0 (where the SAML and OAuth worlds meet)
• NIST SP 800-63C: Digital Identity Guidelines, Federation and Assertions (the assurance framework behind every design choice in this lab)

Portfolio Publishing Guide: Evidence of a Trust You Built and Broke

Lab 03's portfolio value is different from the first two: the artefact is not a deployment but a trust relationship, and the evidence that sells it is the dissected assertion plus the negative tests. Interviewers meet many candidates who have configured SSO; they meet few who have deliberately broken signature validation with a decoy certificate and can narrate why it failed.

12.1 Prepare sanitised artefacts

cd ~/identity-bytes-architect-labs
mkdir -p lab-03-saml-federation/{docs,config,evidence,screenshots}

# The IdP metadata and signing certificate are public by design
# (any browser can fetch the descriptor), so they publish as-is:
cp ~/ib-sia-03/northgate-idp-metadata.xml lab-03-saml-federation/config/
cp ~/ib-sia-03/northgate-signing.cert lab-03-saml-federation/config/

# The captured Response needs redaction before it becomes evidence.
# Blank the signature and cut identifiers, keeping the structure that
# demonstrates your analysis:
sed -E 's/(<dsig:SignatureValue>)[^<]+/\1REDACTED/; s/(ID=")[^"]+/\1REDACTED/g; s/(SessionIndex=")[^"]+/\1REDACTED/g' \
  ~/ib-sia-03/samlresponse.xml > lab-03-saml-federation/evidence/samlresponse.redacted.xml

# Confirm nothing sensitive survived. Expected: no output.
grep -nE "SignatureValue>[A-Za-z0-9+/]" lab-03-saml-federation/evidence/samlresponse.redacted.xml

12.2 Add Lab 03 to the repository and push

cat > lab-03-saml-federation/README.md << 'EOF'
# Lab 03: SAML 2.0 Federation and Identity Brokering

Part of my Identity Bytes Senior IAM Architect lab series (IB-SIA-03).
Builds on Labs 01 and 02: the northgate realm (backed by OpenLDAP)
becomes a SAML Identity Provider trusted by a second identity domain.

## Problem this solves
Cross domain trust after an acquisition: day one access to the acquired
estate using acquirer credentials, no account migration, no password
ever crossing the boundary, and trust either side can revoke with one
change.

## What I built
- A second Keycloak realm (harborview) acting as SAML Service Provider
  via identity brokering
- Manual metadata exchange in both directions, with the IdP signing
  certificate extracted by XPath and pinned at the SP
- SP registration at the IdP with entity ID and ACS locked down
- Attribute mapping (email, names) across the trust boundary, plus a
  group attribute in the stretch exercise
- Live capture of the SAML Response in browser developer tools and a
  full element by element analysis (Issuer, NameID, Conditions,
  AudienceRestriction, AttributeStatement, Signature)

## What I broke on purpose
- Signature validation, using a decoy self signed certificate with the
  same CN: federation failed exactly as it should
- SP registration, by mutating the entity ID: the IdP refused the
  AuthnRequest
- Replay, by resubmitting a consumed Response: rejected

## Skills demonstrated
SAML 2.0 protocol fluency, federation onboarding and metadata literacy,
trust anchor management, identity brokering, first login flow
governance, front channel troubleshooting, and negative security
testing.

Full step by step guide: docs/IB-SIA-03-saml-federation.html
Redacted assertion evidence: evidence/samlresponse.redacted.xml
EOF

cp <PATH_TO>/IB-SIA-03-saml-federation.html lab-03-saml-federation/docs/

# Screenshots worth taking: the harborview login page with the
# Northgate SSO button, the Identity provider links tab on the brokered
# user, and the formatted assertion in your terminal.

git add .
git commit -m "Lab 03: SAML 2.0 federation, IdP to SP brokering with pinned trust anchor, assertion dissection, negative tests"
git push

# Update the track index in the root README:
# | 03 | SAML 2.0 federation, brokering, assertion analysis | Complete |

12.3 Share it on LinkedIn

Attach the terminal screenshot of the formatted assertion with the Signature block visible (redacted), because XML that people usually only fear, presented calmly annotated, stops the scroll of exactly the audience you want. GitHub link in the first comment. A draft in the Identity Bytes style:

Same cadence mechanics as before: Tuesday to Thursday morning UK time, replies within two hours, hashtags at the end (#IAM #SAML #Federation #Keycloak #CyberSecurity), and a comment linking Labs 01 and 02 so the series compounds.

12.4 Interview leverage from this lab

This lab evidences the federation and SSO lines of the target role directly, and it arms you for the classic architecture interview question, SAML or OIDC and why, with something better than a comparison table: you have decoded both credentials, mapped Issuer to iss and Audience to aud from your own captures, and can discuss where each protocol's failure modes live. When the follow up question is about certificate rotation or clock skew, you will be describing incidents you have already caused, on purpose, in an environment you built.