Skip to content

Add OIDC federation guide for Keystone domains - #1090

Open
berendt wants to merge 1 commit into
mainfrom
keystone-oidc-federation-guide
Open

berendt wants to merge 1 commit into
mainfrom
keystone-oidc-federation-guide

Conversation

@berendt

@berendt berendt commented Sep 23, 2026

Copy link
Copy Markdown
Member

The "OIDC Federation" section of the Keystone configuration guide has been an
empty heading since 2023. This fills it with a guide that attaches a Keystone
domain to an external OpenID Connect identity provider, with Keycloak as the
example IdP.

The guide targets OSISM 10 (OpenStack 2025.1) and only relies on what
kolla-ansible provides (keystone_identity_providers,
keystone_identity_mappings, the mod_auth_openidc metadata directory). The
former OSISM Keycloak integration in testbed, cookiecutter and playbooks was
removed in February 2025, so nothing there is referenced.

Contents:

  • how the WebSSO and CLI flows work and which Keystone objects are involved
  • prerequisites and example values
  • Keycloak client, metadata files (.provider, .client, .conf), client
    secret encrypted with Ansible Vault
  • a group-based attribute mapping
  • configuration.yml, osism apply -a reconfigure for loadbalancer,
    keystone and horizon
  • groups and role assignments, verification including an offline
    keystone-manage mapping_engine test
  • CLI access with v3oidcdeviceauthz, further domains, limitations,
    troubleshooting with the actual Keystone error messages

OSISM-specific findings the guide accounts for:

  • enable_keystone_federation and keystone_enable_federation_openid are
    hard-coded to false in osism/defaults (all/099-kolla.yml) and must be
    enabled explicitly.
  • keystone_oidc_forward_header in osism/defaults is not read by
    kolla-ansible; the variable is keystone_federation_oidc_forwarded_headers.
    The dead default could be removed from osism/defaults separately.

The design follows CobaltCore (C5C3/cobaltcore, KeystoneIdentityBackend)
where it applies: one identity provider per domain, authorization through
pre-created groups, claims addressed as HTTP_OIDC_* (which keeps working
behind the separate keystone_httpd proxy container of 2025.2 and later), and
the Default domain is never federated. Unlike CobaltCore, which validates
bearer tokens by introspection, kolla-ansible only checks the signature against
the JWKS. The guide warns about this and suggests a dedicated realm or an azp
condition in the mapping.

Not tested against a live deployment. The azp condition, the device flow with
a separate public client and the mapping_engine invocation are derived from
the Keystone, keystoneauth and mod_auth_openidc sources. The markdown linter,
the codespell spell checker and a local Docusaurus build pass.

🤖 Generated with Claude Code

@github-actions

github-actions Bot commented Sep 23, 2026 •

Copy link
Copy Markdown

✅⚠️MegaLinter analysis: Success with warnings

Descriptor Linter Files Fixed Errors Max errors Warnings Elapsed time
✅ ACTION actionlint 5 0 0 0.04s
✅ JSON jsonlint 4 0 0 0.09s
✅ JSON prettier 4 0 0 0.3s
✅ JSON v8r 4 0 0 8.09s
✅ MARKDOWN markdownlint 184 0 0 3.16s
✅ MARKDOWN markdown-table-formatter 184 0 0 0.43s
✅ REPOSITORY betterleaks yes no no 0.74s
✅ REPOSITORY checkov yes no no 16.71s
✅ REPOSITORY git_diff yes no no 0.1s
✅ REPOSITORY secretlint yes no no 1.26s
✅ REPOSITORY trufflehog yes no no 3.53s
✅ SPELL codespell 194 0 0 0.7s
⚠️ SPELL lychee 194 6 0 13.2s
✅ YAML prettier 6 0 0 0.49s
✅ YAML v8r 6 0 0 6.53s
✅ YAML yamllint 6 0 0 0.47s

Detailed Issues

⚠️ SPELL / lychee - 6 errors
📝 Summary
---------------------
🔍 Total.........1316
🔗 Unique.........966
✅ Successful....1190
⏳ Timeouts.........0
🔀 Redirected.......9
👻 Excluded.......120
❓ Unknown..........0
🚫 Errors...........6
⛔ Unsupported......6

Errors in .claude/skills/security-advisory/reference/style.md
[ERROR] file://.claude/skills/guides/operations-guide/openstack/security-updates.md (at 189:3) | File not found. Check if file exists and path is correct

Errors in .claude/skills/security-advisory/SKILL.md
[400] https://cveawg.mitre.org/api/cve/ (at 16:18) | Rejected status code: 400 Bad Request
[404] https://raw.githubusercontent.com/osism/ (at 17:18) | Rejected status code: 404 Not Found
[400] https://registry.osism.tech/service/token (at 18:19) | Rejected status code: 400 Bad Request

Errors in docs/concepts/cluster-network.md
[ERROR] https://frrouting.org/ (at 27:2) | Network error: Connection reset by peer (os error 104)

Errors in docs/guides/developer-guide/style-guide.md
[ERROR] https://wiki.openstack.org/wiki/GitCommitMessages (at 79:1) | Network unreachable. Check internet connection or VPN settings

Hint: Followed 9 redirects. You might want to consider replacing redirecting URLs with the resolved URLs. Use verbose mode (`-v`/`-vv`) to see redirection details.

See detailed reports in MegaLinter artifacts

Your project could benefit from a custom flavor, which would allow you to run only the linters you need, and thus improve runtime performances. (Skip this info by defining FLAVOR_SUGGESTIONS: false)

  • Documentation: Custom Flavors
  • Command: npx mega-linter-runner@10.2.0 --custom-flavor-setup --custom-flavor-linters ACTION_ACTIONLINT,JSON_JSONLINT,JSON_V8R,JSON_PRETTIER,MARKDOWN_MARKDOWNLINT,MARKDOWN_MARKDOWN_TABLE_FORMATTER,REPOSITORY_CHECKOV,REPOSITORY_GIT_DIFF,REPOSITORY_BETTERLEAKS,REPOSITORY_SECRETLINT,REPOSITORY_TRUFFLEHOG,SPELL_LYCHEE,SPELL_CODESPELL,YAML_PRETTIER,YAML_YAMLLINT,YAML_V8R

MegaLinter is provided by OX Security
Show us your support by starring ⭐ the repository

@jklare

jklare commented Sep 28, 2026

Copy link
Copy Markdown
Contributor

@lnagelschmidt ^^ would be great to get your input here as well

@ideaship ideaship left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I tested this guide on live deployments: OSISM 10.3.0, OSISM 11.0.2, and a 10.3.0 deployment upgraded
to 11.0.2, with Keycloak 26.8 as the IdP. The Keycloak realm (step 1) was imported from a file with the
guide's client settings (the CLI client additionally allows direct access grants, for
v3oidcpassword), and steps 2 to 6 were applied by an automated test setup with the guide's files and
variables; the step 6 and step 7 commands were also run as written, and step 8's device authorization
flow ran with the parameters of the clouds.yaml example, with the browser part automated. The tests
covered Horizon web SSO, the CLI (device authorization flow and v3oidcpassword), a domain-scoped
login, bearer tokens, and two users who must be kept out.

The main issue is the mapping in step 3: its HTTP_OIDC_* names do not match on either release, so
every federated login fails with HTTP 401. With OIDC-<claim> names, which kolla-ansible's own docs
use, every tested login works on 10.3.0 and 11.0.2, and the same configuration covers both releases.
Most suggestions below follow from that; the others are corrections found while testing. Each says what
was observed.

Worked as written on 10.3.0 (with the OIDC-* mapping): the prerequisites, the issuer command, the
metadata file names, the vaulted .client, the kolla variables, the show commands, the device
authorization flow, the trusted dashboards default and the log paths. On 11.0.2 the same configuration
worked; the step 6 commands (run as written), the show commands, the device authorization flow and the
log paths were checked there.

Not tested: other IdPs, further domains, certificate_file per IdP, Horizon logout. The restart after a
metadata change was observed on OSISM 11 only; the suggested wording holds on both releases.

Comment on lines +182 to +184
This section applies to OSISM 10 with OpenStack 2025.1. As of OpenStack 2025.2, Kolla-Ansible runs
Apache with mod_auth_openidc in a separate `keystone_httpd` container. As of OpenStack 2026.1, the
metadata files are processed as Jinja templates.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

With OIDC-<claim> names (see the mapping below) the same configuration works on OSISM 10 and OSISM 11; tested on 10.3.0 and 11.0.2. Only where mod_auth_openidc runs differs.

Suggested change
This section applies to OSISM 10 with OpenStack 2025.1. As of OpenStack 2025.2, Kolla-Ansible runs
Apache with mod_auth_openidc in a separate `keystone_httpd` container. As of OpenStack 2026.1, the
metadata files are processed as Jinja templates.
This section applies to OSISM 10 (OpenStack 2025.1) and OSISM 11 (OpenStack 2026.1). On OSISM 10,
mod_auth_openidc runs in the Apache of the `keystone` container. On OSISM 11, Kolla-Ansible runs it
in a separate `keystone_httpd` container in front of Keystone, and the metadata files are processed
as Jinja templates. The configuration is the same on both.

Comment on lines +192 to +199
(`/v3/auth/OS-FEDERATION/identity_providers/<idp>/protocols/openid/websso`).
3. mod_auth_openidc, running in the Apache of the Keystone container, redirects the browser to the
IdP. After the login, the IdP sends the browser back to `<Keystone public endpoint>/redirect_uri`
(authorization code flow).
4. mod_auth_openidc validates the token of the IdP and passes its claims to Keystone as `HTTP_OIDC_*`
variables, for example `HTTP_OIDC_ISS` or `HTTP_OIDC_PREFERRED_USERNAME`.
5. Keystone looks up the IdP by the issuer in `HTTP_OIDC_ISS`, applies the mapping of the IdP and
creates or updates a federated user in the domain of the IdP.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Keystone receives each claim as OIDC-<claim>. The HTTP_OIDC_* form is missing every claim whose name contains an underscore (details at the mapping).

Suggested change
(`/v3/auth/OS-FEDERATION/identity_providers/<idp>/protocols/openid/websso`).
3. mod_auth_openidc, running in the Apache of the Keystone container, redirects the browser to the
IdP. After the login, the IdP sends the browser back to `<Keystone public endpoint>/redirect_uri`
(authorization code flow).
4. mod_auth_openidc validates the token of the IdP and passes its claims to Keystone as `HTTP_OIDC_*`
variables, for example `HTTP_OIDC_ISS` or `HTTP_OIDC_PREFERRED_USERNAME`.
5. Keystone looks up the IdP by the issuer in `HTTP_OIDC_ISS`, applies the mapping of the IdP and
creates or updates a federated user in the domain of the IdP.
3. mod_auth_openidc redirects the browser to the IdP. It runs in the `keystone_httpd` container
(OSISM 11) or in the Apache of the `keystone` container (OSISM 10). After the login, the IdP
sends the browser back to `<Keystone public endpoint>/redirect_uri` (authorization code flow).
4. mod_auth_openidc validates the token of the IdP and passes each claim to Keystone as a variable
named `OIDC-<claim>`, for example `OIDC-iss` or `OIDC-preferred_username`.
5. Keystone looks up the IdP by the issuer, applies the mapping of the IdP and creates or updates a
federated user in the domain of the IdP.

Comment on lines +297 to +298
The file names in `metadata` are the issuer without `https://` and without a trailing slash,
URL-encoded (`/` becomes `%2F`, `:` becomes `%3A`). All three files must exist for every IdP.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Observed on 11.0.2: with the .provider file removed (and keystone_httpd restarted), mod_auth_openidc logged no file found, fetched the discovery document from the issuer and wrote the file back at the next login; logins kept working. Removing .client or .conf was not tested, so the suggestion keeps them as an instruction.

Suggested change
The file names in `metadata` are the issuer without `https://` and without a trailing slash,
URL-encoded (`/` becomes `%2F`, `:` becomes `%3A`). All three files must exist for every IdP.
The file names in `metadata` are the issuer without `https://` and without a trailing slash,
URL-encoded (`/` becomes `%2F`, `:` becomes `%3A`). Create all three files for every IdP. If the
`.provider` file is missing, mod_auth_openidc fetches the discovery document from the issuer at the
next login.

Comment on lines +358 to +364
"type": "HTTP_OIDC_SUB"
},
{
"type": "HTTP_OIDC_PREFERRED_USERNAME"
},
{
"type": "HTTP_OIDC_GROUPS",

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This mapping does not match on OSISM 10 or OSISM 11: every federated login (Horizon, CLI, device flow, bearer) fails with HTTP 401 and Could not map any federated user properties to identity values in keystone.log. With keystone debug logging, the assertion contains every claim as OIDC-<claim>, but as HTTP_OIDC_<CLAIM> only the claims without an underscore: HTTP_OIDC_PREFERRED_USERNAME never arrives. Apache 2.4 drops request headers with characters other than letters, digits and - when it builds the HTTP_* variables, on OSISM 10 (keystone under mod_wsgi) as on OSISM 11 (keystone behind keystone_httpd). With these three remote types changed, every tested login works on 10.3.0 and 11.0.2. kolla-ansible's own identity provider docs and its 2026.1 federation test mapping use the OIDC-* names too.

Suggested change
"type": "HTTP_OIDC_SUB"
},
{
"type": "HTTP_OIDC_PREFERRED_USERNAME"
},
{
"type": "HTTP_OIDC_GROUPS",
"type": "OIDC-sub"
},
{
"type": "OIDC-preferred_username"
},
{
"type": "OIDC-groups",

Comment on lines +375 to +376
* The `remote` entries are the claims passed on by mod_auth_openidc: `HTTP_OIDC_` followed by the
claim name in upper case. `{0}`, `{1}` and `{2}` refer to the values of these entries in order.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Follows from the mapping change.

Suggested change
* The `remote` entries are the claims passed on by mod_auth_openidc: `HTTP_OIDC_` followed by the
claim name in upper case. `{0}`, `{1}` and `{2}` refer to the values of these entries in order.
* The `remote` entries are the claims passed on by mod_auth_openidc: `OIDC-` followed by the claim
name as the IdP sends it (`OIDC-preferred_username`). `{0}`, `{1}` and `{2}` refer to the values
of these entries in order. Do not use the `HTTP_OIDC_<CLAIM>` names that some examples show:
Apache drops every claim whose name contains an underscore from them, so a rule with
`HTTP_OIDC_PREFERRED_USERNAME` never matches and every login fails with HTTP 401.

Comment on lines +557 to +559
Other plugins are `v3oidcpassword` (username and password, requires **Direct access grants** at the
client), `v3oidcclientcredentials` (service accounts) and `v3oidcaccesstoken` (an existing access
token).

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

keystoneauth1 refuses v3oidcpassword without a client secret (OidcPassword.__init__() missing 1 required positional argument: 'client_secret'), also for a public client. With a placeholder value, the login against Keycloak's public client works (tested with unused).

Suggested change
Other plugins are `v3oidcpassword` (username and password, requires **Direct access grants** at the
client), `v3oidcclientcredentials` (service accounts) and `v3oidcaccesstoken` (an existing access
token).
Other plugins are `v3oidcpassword` (username and password, requires **Direct access grants** at the
client; keystoneauth requires a `client_secret` even for a public client, a placeholder value
works), `v3oidcclientcredentials` (service accounts) and `v3oidcaccesstoken` (an existing access
token).


```json
{
"type": "HTTP_OIDC_AZP",

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For consistency with the mapping. Tested on 10.3.0 and 11.0.2: with any_one_of: ["keystone"], every token of the openstack-cli client is refused (CLI, device flow, bearer) while Horizon works; with both clients listed, all of them work.

Suggested change
"type": "HTTP_OIDC_AZP",
"type": "OIDC-azp",

Comment on lines +607 to +611
* Federated users that get their roles only through mapped groups cannot create application
credentials. An authorization TTL on the identity provider keeps the group memberships for the
given number of minutes after the last login:
`openstack identity provider set --authorization-ttl 1440 keycloak-customer-a`. Application
credentials of the user stop working when the memberships expire.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The TTL advice works, but keystone caches role assignments ([cache] expiration_time, 600 s by default) and does not refresh them in these cases. Observed on 11.0.2 (keystone 29.1.1) with an application credential: refused right after the TTL was set and a fresh login, created 620 s later; after a lapsed membership, still refused right after the login that refreshed it; after the TTL was removed, still accepted until the cache expired. Same on 10.3.0 for the first case.

Suggested change
* Federated users that get their roles only through mapped groups cannot create application
credentials. An authorization TTL on the identity provider keeps the group memberships for the
given number of minutes after the last login:
`openstack identity provider set --authorization-ttl 1440 keycloak-customer-a`. Application
credentials of the user stop working when the memberships expire.
* Federated users that get their roles only through mapped groups cannot create application
credentials. An authorization TTL on the identity provider keeps the group memberships for the
given number of minutes after the last login:
`openstack identity provider set --authorization-ttl 1440 keycloak-customer-a`. Application
credentials of the user stop working when the memberships expire. Keystone caches role
assignments (10 minutes by default): a user who tried to create an application credential before
the TTL was set, or whose memberships had expired, gets the roles back up to 10 minutes after the
next login, and removing the TTL takes effect for such users only after the same time.

* Keystone only sends tokens to trusted dashboards. By default, these are `/auth/websso/` on
`kolla_external_fqdn` and on the Horizon endpoint. If Horizon is reachable under another name,
set `keystone_trusted_dashboards`. The entries must match exactly, including the trailing slash.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A short part for operators coming from OSISM 10, limited to what was tested: a 10.3.0 deployment with a mapping using HTTP_OIDC_SUB, HTTP_OIDC_EMAIL and HTTP_OIDC_GROUPS, upgraded by hand to 11.0.2 (manager first, then the services; Ceph left out). Every login worked afterwards without a change, before anything was reconfigured; keystone_httpd was created by osism apply -a upgrade keystone. The OIDC-* mapping was then registered and worked as well. That the upgrade does not register a changed mapping was observed with osism apply -a upgrade keystone on 11.0.2.

Suggested change
### Upgrading from OSISM 10
In a test upgrade from OSISM 10.3.0 to 11.0.2, OIDC federation kept working without a change: the
upgrade of Keystone (`osism apply -a upgrade keystone`) created the `keystone_httpd` container and
kept the identity provider and mapping registered in Keystone. The mapping used `HTTP_OIDC_<CLAIM>`
names of claims without an underscore (`HTTP_OIDC_SUB`, `HTTP_OIDC_EMAIL`, `HTTP_OIDC_GROUPS`); the
`OIDC-<claim>` names work on both releases and are recommended.
If you change the mapping during the upgrade, run `osism apply -a reconfigure keystone` afterwards:
`osism apply -a upgrade keystone` does not register it.

|:-------------------------------------------------------------------------------------|:-------------------------------------------------------------------------------------------------------------------------|
| Keycloak shows `Invalid parameter: redirect_uri` | The redirect URI of the client is not `https://api.example.com:5000/redirect_uri`. |
| `Could not find Identity Provider identifier in environment` | mod_auth_openidc did not pass the issuer. Check the metadata file names and the Apache error log. |
| `Incoming identity provider identifier not included among the accepted identifiers.` | `identifier` does not match the `iss` claim exactly. |

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Observed on 10.3.0 and 11.0.2 with a wrong remote ID: the CLI gets HTTP 403 and keystone.log shows only a generic Forbidden (keystone.exception.Forbidden: You are not authorized to perform the requested action.); the quoted message does not appear.

Suggested change
| `Incoming identity provider identifier not included among the accepted identifiers.` | `identifier` does not match the `iss` claim exactly. |
| The CLI gets HTTP 403 from `/v3/OS-FEDERATION/.../auth`, `keystone.log` shows `Forbidden` | `identifier` does not match the `iss` claim exactly. |

Comment on lines +554 to +555
The CLI prints a URL and a code. Open the URL in a browser, enter the code and log in. The device
authorization flow requires keystoneauth1 5.11.0 or later on the client.

@ideaship ideaship Oct 29, 2026 •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Observed on 10.3.0 and 11.0.2 with Keycloak 26.8: keystoneauth prints only a URL, with the code in it (To authenticate please go to: https://.../device?user_code=...); it prints a separate code only for an IdP without verification_uri_complete. After the login, Keycloak shows a page asking to grant the CLI access (with the client's default consent setting), and the token arrives only after accepting it.

Suggested change
The CLI prints a URL and a code. Open the URL in a browser, enter the code and log in. The device
authorization flow requires keystoneauth1 5.11.0 or later on the client.
The CLI prints a URL to open in a browser. With an IdP that supports it, such as Keycloak, the URL
already contains the code; otherwise the CLI also prints the code to enter. After the login,
Keycloak asks to grant the CLI access. The device authorization flow requires keystoneauth1 5.11.0
or later on the client.

The "OIDC Federation" section of the Keystone configuration guide has
been an empty heading since 2023. Fill it with a guide that attaches a
Keystone domain to an external OpenID Connect identity provider, using
Keycloak as the example.

The guide targets OSISM 10 (OpenStack 2025.1) and OSISM 11 (OpenStack
2026.1) and only uses what kolla-ansible provides:
keystone_identity_providers, keystone_identity_mappings and the
mod_auth_openidc metadata directory in
environments/kolla/files/overlays/keystone/federation/oidc. It covers
the Keycloak client, the metadata files, a group-based mapping, the
configuration, the reconfigure runs, groups and role assignments,
verification (including an offline mapping test), CLI access with the
device authorization flow, further domains, limitations, the upgrade
from OSISM 10 and troubleshooting.

OSISM-specific points:

- enable_keystone_federation and keystone_enable_federation_openid are
  hard-coded to false in the OSISM defaults and must be enabled
  explicitly.
- keystone_federation_oidc_forwarded_headers is set by the OSISM
  defaults as of OSISM 10.3.0 and has to be set explicitly on older
  releases.
- The .client file with the client secret can be encrypted with
  Ansible Vault, since Ansible decrypts it when the file is copied to
  the control nodes.
- On OSISM 11, mod_auth_openidc runs in the separate keystone_httpd
  container. This changes where the offline mapping test and the
  restart after a metadata change are run.

The design follows CobaltCore where it applies: one identity provider
per domain, authorization through pre-created groups, and the Default
domain is never federated. Claims are addressed as OIDC-<claim>, as in
the kolla-ansible documentation: the HTTP_OIDC_<CLAIM> form loses
every claim whose name contains an underscore. The guide also warns
that bearer tokens are only checked for their signature, not their
audience.

The guide includes the corrections from a test on OSISM 10.3.0, on
OSISM 11.0.2 and on an upgrade between the two.

Assisted-by: Claude:claude-opus-5-5[1m]
Assisted-by: Claude:claude-fable-5-2
Signed-off-by: Christian Berendt <berendt@osism.tech>
@berendt
berendt force-pushed the keystone-oidc-federation-guide branch from e2dff85 to e13723e Compare November 13, 2026 08:28
@berendt
berendt requested a review from ideaship November 13, 2026 10:33

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: In progress

Development

Successfully merging this pull request may close these issues.

3 participants