Identity Federation

Overview

Federation allows enterprise users to authenticate with Polystack using their existing corporate identity provider (IdP) — no separate Polystack password required. Polystack Identity supports SAML 2.0 and OpenID Connect (OIDC) protocols. Users authenticate at the IdP and receive Polystack tokens mapped from their IdP attributes, inheriting project membership and roles through attribute mapping rules.

Administrator Access Required — This operation requires the admin role. Contact your Polystack administrator if you do not have sufficient permissions.

Federation Architecture

SAML 2.0 Setup

Register Polystack as SP in your IdP

Provide your IdP with the Polystack SAML SP metadata URL:

https://api.<your-domain>:5000/v3/OS-FEDERATION/identity_providers/<IDP_ID>/protocols/saml2/auth

Configure the IdP to send the following SAML attributes:

ADFS_LOGIN or mail — the user’s login name
memberOf — group membership for role mapping

Register the IdP in Polystack

Create identity provider

openstack identity provider create \
  --remote-id https://idp.example.com/sso/saml \
  --description "Corporate Active Directory Federation" \
  corporate-idp

Create attribute mapping rules

Mapping rules translate IdP attributes into Polystack group memberships:

mapping-rules.json

[
  {
    "local": [
      {"user": {"name": "{0}", "domain": {"name": "Default"}}},
      {"group": {"id": "<POLYSTACK_GROUP_ID>"}}
    ],
    "remote": [
      {"type": "ADFS_LOGIN"},
      {
        "type": "memberOf",
        "any_one_of": ["CN=cloud-users,OU=Groups,DC=example,DC=com"]
      }
    ]
  }
]

Upload mapping rules

openstack mapping create \
  --rules mapping-rules.json \
  corporate-mapping

Create the federation protocol

Link IdP, mapping, and SAML protocol

openstack federation protocol create saml2 \
  --identity-provider corporate-idp \
  --mapping corporate-mapping

Federation protocol is active. Test by authenticating via the SSO URL.

OpenID Connect Setup

Register Polystack as OIDC client in your IdP

Redirect URI: https://api.<your-domain>:5000/v3/OS-FEDERATION/identity_providers/<IDP_ID>/protocols/openid/auth/callback
Grant type: Authorization Code
Scopes: openid, profile, email, groups

Register the OIDC IdP in Polystack

Create OIDC identity provider

openstack identity provider create \
  --remote-id https://accounts.google.com \
  --description "Google Workspace SSO" \
  google-oidc

Create OIDC mapping rules

oidc-mapping-rules.json

[
  {
    "local": [
      {"user": {"name": "{0}"}},
      {"group": {"id": "<POLYSTACK_GROUP_ID>"}}
    ],
    "remote": [
      {"type": "email"},
      {"type": "groups", "any_one_of": ["polystack-admins@example.com"]}
    ]
  }
]

Create OIDC mapping

openstack mapping create \
  --rules oidc-mapping-rules.json \
  google-mapping

Create the OIDC protocol

Create OIDC federation protocol

openstack federation protocol create openid \
  --identity-provider google-oidc \
  --mapping google-mapping

Mapping Rule Reference

Mapping Field	Description
`local.user.name`	Maps to the Polystack username for the federated session
`local.group.id`	Assigns the user to an Polystack group (inherits group’s role assignments)
`remote.type`	The IdP attribute name to match
`remote.any_one_of`	User must belong to at least one of these values
`remote.not_any_of`	User must not belong to any of these values

Next Steps

Authentication Backends

Compare federation with LDAP and SQL backend options.

Domain Management

Assign federation backends to specific organizational domains.

Security Hardening

Secure federation endpoints and enforce MFA for federated sessions.

Admin Troubleshooting

Debug SAML assertion errors and OIDC token mapping failures.

Core Services

Other Services

Overview

Federation Architecture

SAML 2.0 Setup

Register Polystack as SP in your IdP

Register the IdP in Polystack

Create attribute mapping rules

Create the federation protocol

OpenID Connect Setup

Register Polystack as OIDC client in your IdP

Register the OIDC IdP in Polystack

Create OIDC mapping rules

Create the OIDC protocol

Mapping Rule Reference

Next Steps

Authentication Backends

Domain Management

Security Hardening

Admin Troubleshooting

​Overview

​Federation Architecture

​SAML 2.0 Setup

Register Polystack as SP in your IdP

Register the IdP in Polystack

Create attribute mapping rules

Create the federation protocol

​OpenID Connect Setup

Register Polystack as OIDC client in your IdP

Register the OIDC IdP in Polystack

Create OIDC mapping rules

Create the OIDC protocol

​Mapping Rule Reference

​Next Steps

Authentication Backends

Domain Management

Security Hardening

Admin Troubleshooting

Overview

Federation Architecture

SAML 2.0 Setup

OpenID Connect Setup

Mapping Rule Reference

Next Steps