Identity and Access (Keystone)
Overview
firstcloud uses the OpenStack component Keystone for identity and access. Further, an identity broker offers self-service user and identity provider management.
Identity Broker (Keycloak)
The identity broker is the central source for user and group information across all firstcloud related products (like also firstkube). Each customer organization has its own representation in the broker, so called REALM, which is self-managed. Within the REALM the customer's administrator can create user accounts, manage groups and link external identity providers like Microsoft Entra ID. A REALM is always bound 1:1 to a firstcloud domain with the same name. Moreover, a REALM has one or more e-Mail domains exclusively assigned to it, therefore using the same user e-Mail address in different REALMs is not possible.
The REALM admin console can be accessed via https://id.cloud-fc.de/admin/<realm-name>/console/.
Users
The first REALM manager account is created automatically with the e-Mail address provided during the onboarding process. A password reset link is sent to this e-Mail as well and after login the manager is able to create user accounts for colleagues manually or link an external identity provider.
When creating new users, it has to be ensured that the e-Mail address uses a domain which is assigned to the REALM. The e-Mail address does not need to be valid, as long as the password reset via e-Mail is not used.
Users can add a second authentication factor via the account console: https://id.cloud-fc.de/realms/<realm-name>/account/.
Info
Enabling 2FA is highly recommended for the REALM manager account, as a password-based authentication needs to stay enabled for disaster recovery purposes. It is also advertised to create a second REALM manager account.
Identity Providers
Inside a REALM, managers can link external identity providers, like Microsoft Entra ID, Google or GitHub.
Info
REALM manager accounts can also be linked with external identity providers for Single-Sign-On as long as password-based authentication stays enabled.
The setup process slightly varies from provider to provider. Step by step guides can be found in the official Keycloak documentation.
Note
After adding a new identity provider, make sure that the flag "Trust Email" in "Advanced settings" is enabled. Otherwise the REALM manager needs to manually verify all new users.
Service Accounts
Service accounts are identities for non-human entities. Within the REALM, the manager can create service accounts like every other local user account, although the name should have the prefix sa-. The user attribute firstcloud project is used to assign the service account to a firstcloud project, so the required role assignments will be created automatically during the first login.
Note
The user attribute firstcloud project must not be changed later on, because the old role assignments and firstcloud application credentials will stay active.
The service account can then be used to login to firstcloud and create application credentials.
To delete a service account properly, all application credentials should be removed first, before deleting or disabling the user account inside the REALM. Otherwise the application credentials will stay valid and can only be removed by an administrator. Please contact us if you run into this problem.
Groups and Projects
Based on the booked feature set, each REALM has pre-created groups for self-management:
| Group | REALM Roles | REALM Tier |
|---|---|---|
| realm-user-managers | manage users, groups and identity providers | All |
| realm-client-managers | manage OpenID and SAML clients | STANDARD |
Moreover, groups for every requested firstcloud project are created automatically:
| Group | firstcloud Project Roles |
|---|---|
| member,member,load-balancer_member | |
| reader,load-balancer_observer |
Note
A solution where project roles can be assigned to customer-created groups is work-in-progress. If there is an urgent need for this, please contact the support. The same applies to cross-domain role assignments.
Identity Service (Keystone)
Keystone is the identity service for all OpenStack-related services. There a different ways to authenticate towards Keystone. Upon successful authentication, the identity service provides the user with an authorization token used for subsequent service requests.
Supported authentication methods
| Method | Comment |
|---|---|
| Password | Deprecated in favor of OpenID |
| Token | - |
| Application Credentials | - |
| OpenID Federation (Keycloak) | Default |
Password
A common way for an user or service to authenticate towards Keystone is by using username and password. For an example, have a look at the API access tutorial.
Users can change their password either using the OpenStack CLI command openstack user password set, or via the OpenStack dashboard.
If you forgot your password, please contact our support.
Token
When you authenticate using a token, it is not necessary anymore to provide username and password. Tokens are valid for only one hour.
The OpenStack CLI allows you to create tokens with the command openstack token issue. It can also be manually revoked using openstack token revoke. For more information how to get started with the OpenStack CLI, have a look at the API access tutorial.
Many clients will switch to the token authentication methods with these environment variables in place:
export OS_TOKEN="ab4d1e500c5245e5a166892943118a44"
export OS_AUTH_TYPE="v3token"
unset OS_USER_DOMAIN_NAME
unset OS_USERNAME
Application Credentials
Users can create application credentials and use them instead of the password method. This is useful, if you want to configure third party software like Prometheus, Terraform or Kubernetes Managers to query the OpenStack API.
Using application credentials it can be avoided to put clear text passwords into the configuration of applications. They always belong to a user, and can inherit some or all roles of their owner.
Please refer to the application credentials tutorial to learn more about how to use these.
Note
Federated users authenticated via OpenID with project access via a group membership (default in current IAM model) can't create application credentials, because of technical reasons. See service accounts for how to create a service account which can be used to request application credentials.
OpenID Federation
Users can authenticate via OpenID federation by choosing the firstcloud identity broker at the dashboard login page. They get redirected to the corresponding REALM based on their e-Mail domain and can then either log in using username and password or an external identity provider configured within the REALM.
Info
Group memberships handed over by the identity broker are cached in a session cookie, so changes require a new OpenID session to become active. This can be achieved by waiting one hour for the timeout, or logging out of the dashboard and delete the cookie named "mod_auth_openidc_session" stored by the identity service.
The browser-based authentication flow can also be used with the OpenStack CLI by installing the keystoneauth-websso plugin. This can be done in a python virtual environment, for example:
python3 -m venv openstack-cli
source openstack-cli/bin/activate
pip install python-openstackclient keystoneauth-websso
Info
When installing the OpenStack CLI with the brew package manager, the plugin is already included.
To use the plugin, the following environment variables need to be set:
export OS_AUTH_URL="https://identity.cloud-fc.de/v3"
export OS_AUTH_TYPE="v3websso"
export OS_PROTOCOL="openid"
export OS_IDENTITY_API_VERSION="3"
export OS_IDENTITY_PROVIDER="firstcloud-id"
export OS_REGION_NAME="eu-central-1"
# change as needed
export OS_PROJECT_DOMAIN_NAME="<customer-a>"
export OS_PROJECT_NAME="<project-a>"
When running the first CLI command, a browser window with the dashboard login page opens and the usual authentication flow can be followed. The resulting authentication token will be cached by the CLI and is usually valid for one hour. The CLI will prompt for re-authentication if necessary.
Note
Non-python clients (e.g. gophercloud used by Terraform) do not support the websso plugin. In this case, the OpenStack CLI can be initialized like shown and be used to request an OpenStack API token by running export OS_TOKEN="$(openstack token issue -f value -c id)".
Projects
Every cloud resource, like virtual machines, belongs to a certain project. It might be good practice to separate unrelated pieces of infrastructure into different projects. If you need separate projects, please contact the support.
Roles
These are the project roles which can be assigned to users and groups within a firstcloud project. Additional roles with custom permissions are not possible at this time.
| Role | Access to cloud resources |
|---|---|
| reader | view all ressources in a project |
| member | manage all ressources in a project (except for Swift and Octavia) |
| member | manage Swift containers and objects |
| load-balancer_observer | view Octavia load balancers |
| load-balancer_member | manage Octavia load balancers |