Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.polystack.tech/llms.txt

Use this file to discover all available pages before exploring further.

​
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

Register a new application in your OIDC provider (Keycloak, Azure AD, Okta):
  • 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 FieldDescription
local.user.nameMaps to the Polystack username for the federated session
local.group.idAssigns the user to an Polystack group (inherits group’s role assignments)
remote.typeThe IdP attribute name to match
remote.any_one_ofUser must belong to at least one of these values
remote.not_any_ofUser 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.