Change2Twin Keycloak Documentation

What is Keycloak?

Keycloak is a robust, open-source identity and access management (IAM) platform designed to provide seamless authentication, authorization, and single sign-on (SSO) for a wide range of applications. Developed to support modern security standards like OAuth 2.0, OpenID Connect, and SAML, Keycloak enables organizations to integrate with various identity providers, including Google, LDAP, Active Directory, and social identity providers such as GitHub or Facebook. This flexibility makes Keycloak an ideal choice for both enterprise environments and cloud-native applications, where managing identity across multiple services is critical.

One of Keycloak's standout features is its built-in user federation capability, allowing organizations to connect to existing user directories, eliminating the need for users to manage multiple accounts across services. Additionally, Keycloak offers multi-factor authentication (MFA), further strengthening security by requiring users to authenticate through additional verification methods like OTP (one-time passwords) or hardware tokens.

Keycloak's powerful authorization services enable fine-grained access control, supporting RBAC (Role-Based Access Control) and ABAC (Attribute-Based Access Control) policies, which provide granular control over user permissions and resource access. Its flexible admin console and RESTful API allow administrators to efficiently manage users, roles, permissions, and session configurations, ensuring smooth scaling as systems grow in complexity.

For developers, Keycloak simplifies secure application development by offering easy-to-integrate adapters for popular frameworks like Spring Boot, Node.js, and Java EE, as well as client libraries for other languages. This allows quick integration of Keycloak’s authentication and authorization mechanisms into existing software, reducing the time and effort required to build custom security solutions.

By handling all the complexities of user sessions, login workflows, identity brokering, and account management, Keycloak greatly reduces the burden on development teams. Its support for social login, single sign-out, identity brokering, and customizable user interfaces ensures a cohesive and consistent user experience across all connected applications. Whether deployed in on-premise environments or cloud infrastructures like Kubernetes, Keycloak provides a scalable and secure platform for centralized identity management across diverse ecosystems.

In short, Keycloak simplifies the implementation of modern security protocols while enhancing the user experience and easing the burden of managing identity in distributed, multi-application environments.

Why Use Keycloak in Change2Twin?

In the context of Change2Twin, Keycloak streamlins identity and access management for users interacting with the platform. Here are the key reasons for choosing Keycloak:

• Comprehensive User Management: It provides ready-to-use features to manage user roles, sessions, and permissions without requiring the development of custom IAM solutions, significantly reducing implementation time.
• Single Sign-On (SSO): Keycloak enables seamless SSO across applications within the Change2Twin ecosystem, meaning users authenticate once and gain access to multiple services without the need to re-authenticate.
• Flexible Protocol Support: The platform’s support for OAuth 2.0, SAML, and OpenID Connect ensures it can be integrated with different third-party services and identity providers, enhancing its adaptability and interoperability with other tools and services.
• Scalability and Customization: Keycloak is designed to scale with your application, whether for small teams or enterprise-level deployments. Its extensibility allows it to be customized to meet specific needs, including custom authentication flows, themes, and client integrations.
• Open-Source and Actively Supported: Being open-source, Keycloak is free and continuously improved by a large community of developers. This ensures up-to-date security patches, new features, and strong community-driven support.

Downloading Keycloak

To get started with Keycloak, you can download it from the official Keycloak Downloads page. Keycloak can be deployed in various environments, including as a standalone server or through containerized environments such as Docker or Kubernetes, making it flexible for different infrastructure needs.

Middleware Client for Change2Twin

The middleware client is a pre-configured client designed to integrate with the Keycloak identity management system specifically for the Change2Twin platform. This client is configured using a middleware.json file, which contains all the necessary settings for establishing secure communication between Change2Twin applications and Keycloak.

The middleware client supports two primary authentication methods, making it suitable for various use cases:

• Authorization Code Flow (Standard Flow): This is the most secure and widely used flow for web applications. It works by exchanging an authorization code for an access token after the user authenticates. This method is recommended for applications where security is a priority, as it avoids exposing credentials directly.
• Direct Access Grants: This flow allows users to obtain access tokens by directly providing their credentials (username and password) without requiring a browser redirect. This method is suitable for command-line tools or mobile applications where user interaction is simplified.

Key Roles within the Middleware Client

The middleware client employs a role-based access control (RBAC) system to regulate user permissions and ensure secure access across the Change2Twin platform. These roles define the scope of actions that a user can perform within the system and must be carefully assigned based on the individual's responsibilities and required level of access. The RBAC structure is essential for maintaining the platform's security and efficient resource management.

The following predefined roles form the core of the RBAC system and ensure the platform's proper functioning:

• Admin: This role is the most powerful within the system, granting full administrative privileges. Admins can perform a wide array of tasks, including managing and viewing all users, monitoring all transactions, and accessing detailed purchase data. This level of control is crucial for overseeing the entire marketplace and ensuring that operations run smoothly. Admins also have the ability to modify or delete any resource, giving them complete control over the platform's management.
• Owner: The owner role is designed for users who need to manage specific resources but do not require full access to the system. Owners can manage their own assets, monitor their activities, and oversee the resources they are responsible for. Unlike admins, owners do not have access to the data or resources of other users, which ensures that responsibilities are segmented, and privacy is maintained across the platform. This role is often assigned to those who need a more focused level of control, such as resource managers or asset owners.
• User: The user role offers the most restricted level of access, designed for individuals who primarily interact with their own purchases and marketplace activities. Users can manage their personal transactions but are unable to access sensitive data or interact with other users’ resources. This role emphasizes privacy and security by limiting exposure to only the information that the user is directly involved with. It is ideal for regular marketplace participants who do not require access to administrative or resource management functionalities.

The RBAC system implemented by the middleware client ensures that users at different levels—from everyday users to high-level administrators—have the appropriate level of access to the platform. This division of roles allows for flexible, secure interactions while minimizing the risk of unauthorized access to sensitive data. Each role is carefully tailored to fit the responsibilities and needs of its assigned user, ensuring a clear, well-defined structure of control across the system.

This well-structured approach to access control makes the Change2Twin platform not only secure but also scalable, allowing it to accommodate a growing number of users while maintaining a high level of security. By aligning user permissions with specific roles, the platform can adapt to various user types, from general marketplace participants to system administrators, without compromising on performance or security.

Importing Middleware client

1. Log in to the Keycloak Admin Console

Open your browser and navigate to the URL of your Keycloak Admin Console, typically:

http://<your-keycloak-server>/admin

Enter your administrator username and password to log in.

2. Select Your Realm

After logging in, choose the appropriate Realm where you want to import the client. A realm is a logical grouping of resources in Keycloak (users, roles, clients, etc.).

If you are importing the client into an existing realm, select it from the dropdown at the top-left corner. Otherwise, click Add Realm to create a new one.

3. Navigate to the Clients Section

From the left-hand menu, click on Clients. This will display the list of clients configured for the selected realm.

4. Import the Client Configuration

Click the Import client button to start the process of adding a new client. This will present the option to manually configure a client or import one from a file.

Click the Browse... button. A file dialog will open, allowing you to select a configuration file like the pre-configured middleware.json file.

5. Review the Imported Configuration

Once the file is uploaded, Keycloak will automatically populate the client settings based on the configuration. Review the imported values, which may include:

• Client ID: The unique identifier for the client.
• Name: Name of realm on realm list.
• Authentication Flow: The type of flow used, such as Authorization Code or Direct Access Grants.

6. Save the Imported Client

Once you have reviewed the settings, click Save to finish importing the client into your Keycloak realm.

7. Configure Roles

If roles need to be configured for the client:

• In the top menu under the selected client, click Roles.

• If roles (like admin, owner, or user) were included in the JSON file, they will be listed. If not, create them manually by clicking Create role.

8. Test the Client Integration

After importing the client and configuring roles, test the integration by:

• Accessing the client’s application.
• Testing the login flow to ensure it correctly authenticates via Keycloak.
• Verifying that the appropriate roles are applied during user sessions.