Skip to main content

​
Overview

Federation allows enterprise users to authenticate with Xloud using their existing corporate identity provider (IdP) — no separate Xloud password required. Xloud Identity supports SAML 2.0 and OpenID Connect (OIDC) protocols. Users authenticate at the IdP and receive Xloud 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 Xloud administrator if you do not have sufficient permissions.

​
Federation Architecture

​
SAML 2.0 Setup

Register Xloud as SP in your IdP

Provide your IdP with the Xloud 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 Xloud

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 Xloud group memberships:
mapping-rules.json
[
  {
    "local": [
      {"user": {"name": "{0}", "domain": {"name": "Default"}}},
      {"group": {"id": "<XLOUD_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 Xloud 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 Xloud

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": "<XLOUD_GROUP_ID>"}}
    ],
    "remote": [
      {"type": "email"},
      {"type": "groups", "any_one_of": ["xloud-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 Xloud username for the federated session
local.group.idAssigns the user to an Xloud 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.