Mirantis Container Cloud (MCC) becomes part of Mirantis OpenStack for Kubernetes (MOSK)!

Now, the MOSK documentation set covers all product layers, including MOSK management (formerly Container Cloud). This means everything you need is in one place. Some legacy names may remain in the code and documentation and will be updated in future releases. The separate Container Cloud documentation site will be retired, so please update your bookmarks for continued easy access to the latest content.

Configuration

This section outlines the essential configurations that need to be applied to the components for the successful integration of the enterprise directory with MOSK.

MOSK central IAM (Keycloak)

Keycloak serves as an intermediary between the enterprise directory and the MOSK Identity service (Keystone) and provides authentication, synchronization, and role mapping functions that enable federated access to OpenStack through OpenID Connect (OIDC).

Pre-provisioned configuration in MOSK

A standard MOSK deployment includes a pre-provisioned Keycloak realm iam and an OpenStack client client ID: os. They serve as the foundation for integrating external identity providers and for issuing OIDC tokens to MOSK clusters. Cloud operators typically extend this baseline configuration by connecting the enterprise directory, defining role mappers, and exposing the required identity claims in issued tokens.

The iam realm contains:

• A default OpenID Connect client os, preconfigured for OpenStack Keystone integration.

• Base authentication flows and token policies suitable for MOSK.

• The necessary endpoints for federated login and token exchange.

This pre-provisioned setup ensures a consistent starting point for all MOSK environments while allowing customization for organization-specific identity and security requirements.

LDAP user federation

• Add a read-only LDAP User Federation Provider to the iam realm. For details, refer to Official Keycloak documentation.

• Use LDAPS (TCP 636) with a read-only bind account restricted to relevant base DNs or organizational units (OUs).

• Make sure to adjust the value of the User Object Classes parameter (userObjectClasses) based on the directory type. In a non-Active Directory LDAP deployment, you may need to add inetOrgPerson to the list.

• Define user and group filters that limit synchronization to cloud-eligible users and groups, for example, those within a specific cloud access OU or meta-group.

• Enable periodic synchronization or provide manual sync triggers to ensure up-to-date user and group information.

LDAP role mapping

• Configure an LDAP role mapper under the provider to translate LDAP group memberships into Keycloak client roles.

• Make sure to select the value of the Role Object Class parameter (role.object.class) based on the directory type. In Active Directory it is usually group, while in a generic LDAP deployment it could be groupOfNames.

• Configure the mapper to create all its roles within the os client to clearly separate OpenStack-related roles from other enterprise applications.

  • Set the Use the realm role mappings parameter (use.realm.roles.mapping) to False.

  • Set the Client ID parameter (client.id) to os.

• Use a generic LDAP query, for example, scoped by OU, meta-group, or custom attribute, to identify and map all cloud-related groups without per-group configuration.

• Ensure Keycloak role names match 1:1 with their corresponding LDAP group names to maintain correct mapping and resolution during authentication in Keystone.

Scoping LDAP synchronization from Active Directory

When integrating large enterprise directories that have tens of thousands of records in them, it is often necessary to restrict synchronization to only those users and groups that are relevant to the OpenStack environment, to avoid system slowness.

A recommended practice for MOSK is to define a dedicated meta group, for example, OpenStack Groups, that serves as a logical container for all OpenStack-related access groups. Microsoft Active Directory (AD) supports the LDAP_MATCHING_RULE_IN_CHAIN (1.2.840.113556.1.4.1941) extended match operator, which allows queries to evaluate recursive membership relationships. The operator can be used for retrieving users who are members of groups that, in turn, belong to the higher-level meta group.

In this setup, each LDAP group related to an OpenStack project, for example, OPENSTACK_PROJECT1_MEMBER or OPENSTACK_PROJECT2_ADMIN, should have a memberOf relationship with the meta group. The groups themselves can reside in any organizational unit as only the memberOf link is required for discovery.

Example meta group relationship in AD:

Example LDAP filter for user synchronization:

"(&(objectClass=person)(memberOf:1.2.840.113556.1.4.1941:=CN=OpenStack Groups,OU=Cloud,DC=example,DC=com))"

This query retrieves all user objects that are members (directly or indirectly, through other groups) of any group linked to the OpenStack Groups meta group. The extended match operator allows AD to traverse the full membership chain automatically.

Example LDAP filter for group synchronization

"(&(objectClass=group)(memberOf=CN=OpenStack Groups,OU=Cloud,DC=example,DC=com))"

This query retrieves all groups that are direct members of the OpenStack Groups meta group, no extended match is required for this case.

When a new OpenStack project group is added to AD, linking it to the meta group is sufficient for its members to be automatically included in synchronization, with no changes required on the Keycloak side.

OIDC protocol mapper configuration

OIDC protocol mappers in Keycloak define which user attributes or roles are included as claims in the OpenID Connect (OIDC) token. They act as the bridge between Keycloak internal user model and the federated systems that consume the token, such as the MOSK Identity service (OpenStack Keystone). By controlling the content of these claims, Keycloak ensures that Keystone receives all necessary identity and authorization information during federated login.

In MOSK, the os client in the iam realm comes preconfigured with all OIDC protocol mappers required for integration with Keystone. These mappers define the claims embedded in the ID and Access tokens issued to clients. Keystone interprets these claims (automatically prefixed with OIDC-) according to its federation mapping configuration.

Pre-configured OIDC Claims:

• iam_username - identifies the federated user within Keystone:

  • Generated by the User Property Mapper (oidc-usermodel-property-mapper) using the Keycloak user attribute username.

  • Used by Keystone as OIDC-iam_username.

• iam_email - provides the user email address for audit and display:

  • Generated by the User Property Mapper (oidc-usermodel-property-mapper) using the Keycloak user attribute email.

  • Used by Keystone as OIDC-email.

• iam_roles - lists all OpenStack-related roles corresponding to the user LDAP-derived group memberships. Keystone uses this claim to map the user into the appropriate project groups and role assignments:

  • Mapping: Produced by the MOSK-specific script-based mapper (script-iam-mapper.js), which aggregates role information retrieved from the realm. The non-standard mapper is needed to combine the list of roles into a string suitable for Keystone.

  • Used by Keystone as OIDC-iam_roles.

  • Requirement: Role names must exactly match the Keystone group names provisioned by the external onboarding automation system.

  Caution

  In MOSK versions before 25.2.3, the built-in script-iam-mapper.js used to generate the iam_roles claim processes only the roles with names that begin with the m:os: prefix. This design limits its applicability in environments where group names in the enterprise directory (for example, Active Directory) do not follow that naming convention.

  Cloud operators running older MOSK releases can override the default mapper implementation by building a custom image for the Keycloak container. This approach allows you to accommodate arbitrary group-naming schemes until you update to MOSK 25.2.3 or later, where the bundled mapper automatically includes all roles under the os client, regardless of their names.

These mappers are enabled by default and configured to include their claims in:

• ID tokens (id.token.claim: true)

• Access tokens (access.token.claim: true)

• UserInfo responses (userinfo.token.claim: true)

As a result, no additional Keycloak configuration is required for standard MOSK deployments. Operators only need to ensure that the LDAP federation and the associated LDAP role mapper are configured correctly so that iam_roles accurately reflects OpenStack access groups for each user.

Authentication flow and token settings

Optionally, you can customise the authentication settings according to the policies of your organisation:

• Apply enterprise-wide policies such as Single Sign-On (SSO) and Multi-Factor Authentication (MFA) through Keycloak authentication flows.

• Adjust session and token lifetimes to align with organizational security and OpenStack operational standards.

Multi-cluster client strategy

MOSK supports multi-cluster environments in which a single Keycloak instance may serve as an identity provider for several MOSK clusters. The list of the supported configuration models includes:

Model A - Shared client across clusters

• Reuse the existing os client and extend it by adding multiple redirect URIs, post-logout redirect URIs, and web origins to cover all Keystone (and Horizon) endpoints across clusters.

• Advantages: Simplified configuration and consistent role mappings.

• Trade-offs: Shared client secret across clusters and broader redirect URI surface.

• Recommended for: Small or tightly controlled environments with identical policies across clusters.

Model B - Dedicated client per cluster (Recommended)

• Clone the os client to create os-<cluster> clients, each with its own secret and specific redirect URIs.

• Reuse the same LDAP federation provider and role mappers across clients.

• Advantages: Secret isolation, tighter redirect scope, independent policy tuning per cluster.

• Trade-offs: Slightly higher configuration overhead.

• Recommended for: Production environments requiring security isolation and independent secret rotation.

In both options, ensure that post-logout redirect URIs and web origins are configured for each Keystone endpoint, and that client secrets are rotated regularly following organizational security practices.

MOSK Identity service (OpenStack Keystone)

In MOSK, OpenStack Keystone acts as a federated identity consumer, relying on OpenID Connect (OIDC) tokens issued by Keycloak for authentication and authorization. When the Keycloak federation feature is enabled, MOSK automatically provisions all required Keystone federation objects, including the Identity Provider (IdP), Protocol definition, and Protocol mapping. No manual Keystone configuration or CLI actions are necessary.

Federation mapping

During login, Keystone validates the OIDC token received from Keycloak and extracts user identity and group information from the claims included in the token. Keystone then uses these claim values to construct a transient federated user session and determine project- and role-based access, mapping the received OIDC claims according to the MOSK default settings:

• iam_username - user name in Keystone

• iam_email - email attribute

• iam_roles - semicolon (;) separated names of Keystone groups to which the user belongs. The groups need to exist in Keystone by the time a cloud user logs in

This mapping is configured automatically by the MOSK when Keycloak federation is enabled. Cloud operators should not modify these mappings manually.

WebSSO and token handling

Keystone exposes standard OIDC WebSSO endpoints for browser-based authentication through Horizon and for CLI-based SSO flows.

The required redirect URIs are pre-registered in Keycloak os client configuration. Upon successful token validation, Keystone issues a scoped OpenStack token and authorizes the user according to the group-to-role assignments provisioned by the onboarding automation system.

Data entity lifecycle and synchronization

All structural entities required for authorization, such as projects, groups, and assignments, are provisioned externally by the external onboarding system by the time the cloud user logs in. The system must ensure that group names in Keystone exactly match those referenced in the iam_roles claim and corresponding groups in the directory.