Skip to content

Commit cbf6ea1

Browse files
reqaJuanPTMgarloff
authored
Add documentation about the identity federation concept in SCS (#72)
Signed-off-by: Arvid Requate <requate@univention.de> Co-authored-by: Juan Pedro Torres <JuanP.95.torres@gmail.com> Co-authored-by: Kurt Garloff <kurt@garloff.de>
1 parent f1cae7a commit cbf6ea1

File tree

2 files changed

+129
-0
lines changed

2 files changed

+129
-0
lines changed

‎operations/iam/identity-federation-in-scs.md

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
---
2+
title: Identity Federation in SCS
3+
type:
4+
status: Draft
5+
track: Global
6+
---
7+
8+
SovereignCloudStack wants to make it possible for operators to delegate
9+
administration of user identities to the organizational entities that the
10+
users are part of. Usually that's customer organizations but it could also
11+
be the operator itself. Federation protocols like OpenID Connect can be used
12+
to achieve that goal. To simplify connecting the different parts of SCS
13+
to customer owned IAM solutions, SCS deploys Keycloak as central Identity
14+
Provider (IdP) service.
15+
16+
The following sections describe how this is done.
17+
18+
## 1. IaaS / OpenStack
19+
20+
To provide Infrastrucure as a Service SCS builds upon
21+
OpenStack. See the `openstack-federation-via-oidc` document
22+
in [the iam section of this documentation](https://docs-staging.scs.community/docs/iam/)
23+
for more details on identity federation for OpenStack.
24+
25+
## 2. CaaS
26+
27+
To provide Container as a Service SCS builds upon
28+
Kubernetes. There is
29+
[work in progress](https://github.com/SovereignCloudStack/issues/issues/373)
30+
to optionally connect Kubernetes to Keycloak and to
31+
map authorization decisions based on claims via cluster role bindings.

‎operations/iam/openstack-federation-via-oidc.md

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
---
2+
title: OpenStack Federation via OpenID-Connect
3+
type:
4+
status: Draft
5+
track: Global
6+
---
7+
8+
Keystone supports federating authentication and authorization decisions via several mechanisms
9+
as [documented by the project](https://docs.openstack.org/keystone/latest/admin/federation/introduction.html).
10+
11+
In SCS OpenID Connect is used for federation between Keystone and the IdP, which is
12+
[currently provided by Keycloak](https://docs.scs.community/standards/scs-0300-v1-requirements-for-sso-identity-federation)
13+
in SCS.
14+
15+
The following sections describe the setup.
16+
17+
## 1. Keystone
18+
19+
[Keystone supports federated identities](https://docs.openstack.org/keystone/latest/admin/federation/federated_identity.html).
20+
To allow SCS to consume identities managed in external IAM solutions,
21+
federation protocols like OpenID Connect or SAML can be used.
22+
Keystone currently makes use of third party apache modules like
23+
[mod\_auth\_openidc](https://github.com/OpenIDC/mod_auth_openidc),
24+
[mod\_oauth2](https://github.com/OpenIDC/mod_oauth2) and
25+
[mod\_auth\_mellon](https://github.com/UNINETT/mod_auth_mellon) to delegate
26+
authentication to a SSO IdP (i.e. SAML IdP or OpenID Connect provider).
27+
28+
In OpenStack the apache modules are configured using the
29+
[wsgi-keystone.conf template](https://github.com/openstack/kolla-ansible/tree/master/ansible/roles/keystone/templates).
30+
31+
In SCS we make use of the OAuth 2.0 Authorization Code Grant flow between Keystone and Keycloak
32+
and use PKCE (RFC 7636) with the S256 challenge method.
33+
34+
In addition to the usual SSL CA of the environment, Keycloak uses separate certificates to sign the OIDC tokens.
35+
36+
Due to the way the Keystone container image runs apache (in the foreground) and keystone itself (as WSGI module),
37+
reconfiguring the apache URL locations on the fly is not possible currently without a downtime of several seconds.
38+
That is the reason why SCS currently makes use of a single central proxy realm in Keycloak, to which Keystone
39+
connects.
40+
41+
### 1.1 Keycloak IdP realm discovery
42+
43+
Keycloak offers standard OIDC service discovery via `.well-known` documents to advertise its endpoints.
44+
45+
In SCS we want to represent each customer by a separate dedicated Keycloak realm, which can enventually be used
46+
for customer self service and to federate out to customer owned IAM external solutions.
47+
48+
In the SCS testbed we currently experiment with the implications of using a single central proxy realm in Keycloak
49+
and chaining federation from there to customer specific realms, also hosted in the same Keycloak instance.
50+
To make this usable, SCS makes use of the
51+
[Keycloak Home IdP Discovery](https://github.com/sventorben/keycloak-home-idp-discovery)
52+
extension.
53+
54+
### 1.2 Keystone mapping of token claims
55+
56+
Upon login of a user Keystone evaluates the credentials obtained from the ID token that the IdP issued.
57+
These include group memberships and roles, which can be used to assign the user to a certain project.
58+
Keystone maps these external identities to internal (shadow) users.
59+
It can either attempt to map the obtained information to a `local` type user, which needs to be
60+
provisioned before authentication by external tooling, or it can be instructed via the mapping to
61+
generate an `ephemeral` type user. `ephemeral` users are cleaned up automatically after some time
62+
of inactivity and with that, they lose access to projects, iff the access is granted indirectly
63+
via group membership rather than directly to the user itself.
64+
65+
Group memberships for `ephemeral` users are only represented via their tokens, but not stored in the
66+
Keystone backend database.
67+
68+
After successful authorization Keystone issues an OpenStack specific `fernet` token to the user,
69+
which is the currency that is understood by other OpenStack services and can be used to access them.
70+
71+
In SCS we want to represent each customer by a sepatate dedicated OpenStack domain to host
72+
their projects and (shadow) user accounts.
73+
74+
The processing of information from the OIDC tokens is configured by two parts. The first part is the
75+
`rules.json` mapping which is described in the
76+
[OpenStack federation mapping combinations](https://docs.openstack.org/keystone/latest/admin/federation/mapping_combinations.html)
77+
document. This file is used to configure Keystones internal mapping engine
78+
and it needs to be attached to some OpenStack domain, which is named `keycloak` by default in SCS.
79+
80+
The second (static) part is the `[auth]` and `[mapped]` sections in `keystone.conf` (see e.g.
81+
[the overlays currently used in the OSISM testbed](https://github.com/osism/testbed/tree/main/environments/kolla/files/overlays/keystone)
82+
).
83+
84+
### 1.3 Horizon WebSSO for federated users
85+
86+
The Horizon dashboard supports login via OpenID Connect via Keystone endpoint.
87+
SCS adjusted the logout behavior to invalidate both, the OpenID Connect session
88+
with the IdP and the Keystone token.
89+
90+
### 1.4 OpenStack CLI and API access for federated users
91+
92+
To support OpenStack CLI and API access, SCS implemented support for the OIDC Device Authorization Grant
93+
in Keystone. On top we added support for PKCE (RFC 7636) in combination with that.
94+
95+
### 1.5 SSO Federation between to SCS deployments
96+
97+
To show the potential of this approach to federation SCS created a
98+
[Howto for OIDC federation between SCS deployments](https://docs-staging.scs.community/docs/iam/intra-SCS-federation-setup-description-for-osism-doc-operations).

0 commit comments

Comments
 (0)