Implementing Federated Identity in OpenStack via SAML2

The Problem: Managing External Users in OpenStack

Managing local user accounts for external partners or different organizational units in OpenStack creates a significant administrative burden. Manually syncing passwords and managing lifecycle events (like employee offboarding) across separate identity silos leads to security gaps and operational overhead.

The solution is Federated Identity. By configuring OpenStack Keystone to trust an external Identity Provider (IdP) via the Security Assertion Markup Language (SAML2) protocol, you shift the burden of authentication to the external entity. Keystone no longer stores passwords; it simply trusts a signed digital assertion that a user is who they claim to be.

The Smallest Suitable Design

To implement federation, Keystone must be configured as a Service Provider (SP). The minimal architecture requires three components: an external SAML2-compliant IdP, a Keystone installation with the keystone-saml2 integration, and a mapping engine.

The workflow operates as follows:

• Redirection: The user attempts to access the OpenStack dashboard (Horizon) and selects an external IdP. Keystone redirects the browser to the IdP.
• Authentication: The IdP authenticates the user and generates a SAML assertion (an XML document) containing user attributes.
• Assertion: The browser posts this signed assertion back to Keystone.
• Mapping: Keystone validates the signature and uses a mapping rule to translate the IdP's attributes (e.g., groups=admins) into local OpenStack projects and roles.

Trust and Data Boundaries

In a federated model, the Trust Anchor is the external IdP. Keystone does not verify the user's password; it verifies the digital signature of the IdP using a public key exchanged during the metadata setup.

The data boundary is defined by the Attribute Mapping. This is the most critical security layer. If Keystone blindly maps any attribute provided by the IdP to a admin role, a compromised or loosely governed IdP could grant unauthorized administrative access to your cloud. Trust must be limited to specific, governed attributes (e.g., remote-group or eduPersonAffiliation).

Operational Configuration

Configuration occurs primarily in the keystone.conf file and through the creation of mapping files. You must exchange metadata XML files between the IdP and Keystone to establish the trust relationship.

Example Mapping Configuration

Assume your IdP sends an attribute called memberOf. You want users in the cloud-users group to be mapped to the member role in the Production project.

# Example mapping rule logic
# If attribute 'memberOf' contains 'cloud-users'
# Map to project 'Production' and role 'member'

[saml2]
# Path to the IdP metadata file
idp_metadata_file = /etc/keystone/idp_metadata.xml
# Path to the mapping file
mapping_file = /etc/keystone/mapping.json

Risk: Ensure the mapping_file is owned by the keystone user and has restricted permissions (e.g., 640) to prevent unauthorized modification of role assignments.

Failure Modes and Diagnostics

Federation introduces dependencies on external systems and precise timing.

Failure Mode	Root Cause	Diagnostic Check
Authentication Loop/Rejection	Clock Skew	Compare date -u on the Keystone node vs the IdP server. Differences > 5 mins often trigger SAML expiration.
"Invalid Signature" Error	Expired Certificate	Inspect the IdP metadata XML for the <X509Certificate> expiration date.
Login Success, No Permissions	Mapping Mismatch	Check Keystone logs for mapping_engine output to see if the IdP attributes matched any local rules.

Verification and Rollback

To verify the setup, use a test IdP (such as SimpleSAMLphp) to simulate an assertion. Attempt a login via the Horizon dashboard and monitor the Keystone API logs. A successful flow will show the transition from a SAML assertion to a Keystone token associated with a mapped project.

Verification Command: Run the following on the Keystone node to verify the service is picking up the SAML configuration:

# Check for SAML configuration loading in logs (requires sudo)
sudo grep "saml2" /var/log/keystone/keystone.log

Rollback: Since this configuration changes the keystone.conf and adds mapping files, rollback involves removing the [saml2] section from the config, deleting the mapping files, and restarting the apache2 or keystone service.

Design Pivots

This design is suitable for 1–5 trusted external organizations. If your environment grows to dozens of external partners, manual metadata exchange becomes unmanageable. In such cases, pivot the architecture toward:

• Centralized Identity Broker: A middleware layer (like Keycloak) that handles multiple IdPs and presents a single SAML/OIDC interface to Keystone.
• OpenID Connect (OIDC): If the IdPs support it, OIDC is generally easier to manage and more performant than the XML-heavy SAML2 protocol.