Keycloak

Keycloak is an open source Identity and Access Management (IAM) solution designed to provide centralized authentication, authorization, and user federation capabilities. This means it handles the creation of users and assigns permissions to the users through created roles, and offers access across multiple platforms. Keycloak also supports industry-standard protocols such as OpenID Connect (OIDC), OAuth 2.0, and Security Assertion Markup Language (SAML) 2.0. These protocols define how apps that outsource their authentication and authorization ask Keycloak to authenticate users.

​

Key features

Keycloak has the following key features:

• Authentication and authorization: Provides built-in support for user authentication, Multi-Factor Authentication (MFA) and fine-grained authorization. These ensures that apps can outsource authentication and authorization to a trusted, centralized system like Keycloak.
• Identity brokering and user federation: Integrates with external identity providers, such as Lightweight Directory Access Protocol (LDAP), Active Directory, and social login providers such as Google and GitHub, and lastly, SAML identity providers. This allows your organization to inherit existing identity directories without duplicating user accounts.
• Single Sign-On (SSO): Supports seamless access to authenticate once and gain access to multiple apps without re-entering credentials into each app. The login sessions are centrally managed in Keycloak to improve both user experience and security posture.
• Client and resource management: In Keycloak, an app represents a client within a specific realm. For each client, you can manage app permissions, allowed authentication flow, token configurations, and protocol configuration. This ensures flexible control and scoping of access rights within that realm.
• Security tokens and sessions: Keycloak generates the following types of tokens that manage identities and access:
  • ID token: Used by apps to know the authenticated user
  • Access token: Used to scope and authorize API access
  • Refresh token: Generates a new token to extend an app’s session
  The token formats, validity periods, and claims can be explicitly configured per client or per realm.

​

Keycloak components

Keycloak comprises several major components:

• Realm: Isolated namespace that groups users, roles, groups, and apps
• Clients: Apps or services that rely on Keycloak for authentication and authorization
• Identity providers: External authentication sources that Keycloak uses to authenticate users accessing an app.
• User storage providers: Connectors for external user directories
• Admin console: Browser-based interface for realm and user management

​

Types of Keycloak roles

Keycloak provides two main types of roles that reflect the role’s scope, this includes:

• Realm roles:These are global roles that apply across the entire realm, and any client can use them. You need them in the following scenarios:
  • Organizational-wide access for an administrator or manager
  • Setting permissions shared across multiple apps
  In tokens, realm roles appear under the realm_access claim.
• Client roles: These are app-specific roles defined within a single client. You need them in the following scenarios:
  • Fine-grained app-level permissions
  • Microservices that manage their own authorization models
  • Least-privilege access that isolates services
  In tokens, client roles appear under resource_access.<client_id>.roles.

​

Keycloak in the NexusOne platform

Within NexusOne, Keycloak serves as the central authoritative system for all apps. It provides the following capabilities:

• Centralizes user creation, provisioning, and de-provisioning
• Authenticates all internal and external users across all apps in NexusOne
• Manages sessions and SSO flows for a seamless login experience
• Issues tokens used by downstream services
• Enforces consistent security policies such as MFA, password policies, and session limits
• Externalized databases and integration with identity providers when deployed

​

Deployment

Keycloak runs on a container orchestration platform such as Kubernetes. The NexusOne deployments include the following capabilities

• High-availability configuration
• Externalized PostgreSQL database
• External identity providers
• Integrated secrets management

Terraform manages all Keycloak resources, including clients, roles, groups, identity providers, mappers, and any additional realm configuration. This ensures that the entire IAM configuration is declarative, version-controlled, and fully aligned with the NexusOne team’s infrastructure-as-code standards. As a NexusOne customer, you have three options:

• Self-managed deployment: Deploy and manage NexusOne inside your cluster
• Managed cluster by NexusOne: Allow the NexusOne team manage the cluster for you
• Web portal only: Use NexusOne entirely through the web portal

If you deploy and manage NexusOne yourself, use the pre-packaged Terraform modules to define your Keycloak clients and associated permissions rather than relying on manual configuration. Untracked Terraform modifications introduce configuration drift, reduce reliability, complicate troubleshooting, and might not be easily found during redeployments or upgrades. So, ensure you submit all updates through the IaC pipeline to maintain consistency and auditability across environments. By adhering to these practices, you are ensuring that Keycloak remains stable, predictable, and fully reproducible across all stages of deployment.

​

Keycloak client configuration

Apps within NexusOne act as a clients to Keycloak. These apps use the following OIDC-compliant authentication flows:

• Authorization code flow: User authenticates via the browser
• Client credentials flow: Service authenticates between themselves without a user
• Implicit flow: User authenticates via the browser in legacy web architectures

Before authentication, each client defines the following:

• Redirect URIs: Where Keycloak can send tokens after login
• Token policies: Rules for token lifespans, scopes, and refresh behavior
• Required roles: What claims the user must have to access the client
• Frontend and backend session settings: How long a user stays logged in, independent of the expiration of a token
• Proof Key for Code Exchange (PKCE)/constraints: Extra checks during the authentication flow

By unifying these configurations, NexusOne ensures that the policies it applies to each client are consistent and traceable.

​

User management and provisioning

When you need to create users within NexusOne, Keycloak serves as the central user directory. It manages the following:

• User attributes: Personal and system information stored for each user
• Roles and role mappings: Permissions and access levels assigned to users
• Group memberships: Collection of users grouped to simplify role assignment
• MFA configuration: Multi-factor authentication settings for stronger account security
• Password policies: Rules for password creation, such as its length, hash algorithm, and more

As an administrator, you manage users through the Keycloak Admin Console, while individual users manage their own accounts through the Account Console.

​

Security and compliance enhancements

Using Keycloak as a centralized identity provider enhances NexusOne’s security posture by enabling the following:

• Central auditing and event logging for all authentication attempts
• Consistent SSO session timeouts and rotation policies
• Centralized breach response, such as revoking all user sessions at once
• Reduced attack surface by eliminating custom authentication implementations in each app
• Compliance with organizational and regulatory requirements, such as password rotation policies, audit tracing, and more

​

Authorization code flow via Keycloak

The following diagram shows the Authorization Code Flow of a user within NexusOne logging in via Keycloak. It shows how the authentication of the user, exchange from an authorization code for tokens, and the establishment of a session for subsequent requests.

​

Keycloak hands-on examples

This section describes several hands-on examples of using Keycloak.

​

Manage roles

Roles define what a user or service account can do within a realm or app.

​

Create a realm role

Realm roles are global, and you can assign them to any user or group. Use the following steps to create a realm role:

1. Log in to the Keycloak Admin Console.
2. From the sidebar, navigate to Realm roles > Create role.
3. In the Role Name field, enter a role name.
4. In the Description field, enter an optional description.
5. Click Save.
6. Optionally configure Composite Roles to bundle multiple permissions.

​

Create a client role

Client roles are specific to an app and used for app-level authorizations. Use the following steps to create client roles:

1. Log in to the Keycloak Admin Console.
2. From the sidebar, click Clients and select a previously created client.
3. Click the Roles tab.
4. Click Create Role.
5. In the Role Name field, enter a role name.
6. In the Description field, enter an optional description.
7. Click Save.

​

Manage users

Managing users ensures that you can control access to NexusOne apps and maintain security. In Keycloak, it allows you to create user accounts, manage credentials, or enforce password policies.

​

Create a new user

Use the following steps to create a new user:

1. Log in to the Keycloak Admin Console.
2. At the top left corner, select the realm you want to manage.
3. Navigate to Users > Add user.
4. Provide the required fields:
   • Username is mandatory
   • Email, First Name, and Last Name are optional
5. Click Create.
6. After creating a user, click the Credentials tab to set an initial password.
7. Choose whether the user should update their password on first login.

​

Manage user credentials

Use the following steps to manage user credentials:

1. Log in to the Keycloak Admin Console.
2. From the sidebar, navigate to Users > username > Credentials.
   username is a user previously created
3. Within the credentials tab, you can do the following:
   • Reset passwords
   • Disable or enable credentials
   • Configure temporary or permanent passwords

​

Assign a role to a user

Use the following steps to assign roles to users:

1. Log in to the Keycloak Admin Console.
2. From the sidebar, click Users and select a previously created user.
3. Navigate to Role mappings > Assign role.
4. In the available roles table, select a realm or client role you want to assign.
5. Click Assign.

​

Manage groups

Groups allow administrators to combine multiple users and assign roles to them easily.

​

Create a group

Use the following steps to create a group:

1. Log in to the Keycloak Admin Console.
2. From the sidebar, navigate to Groups > Create group and assign roles or attributes to the group.
3. In the Name field, enter a group name.
4. Click Create.

​

Add a user to a group

Use the following steps to add a user to a group:

1. Log in to the Keycloak Admin Console.
2. From the sidebar, click Groups and select a previously created group.
3. Navigate to Members > Add member.
4. In the available member table, select a user you want to add.
5. Click Add.

​

Assign a role to a group

Use the following steps to assign a role to a group:

1. Log in to the Keycloak Admin Console.
2. From the sidebar, click Groups and select a previously created group.
3. Navigate to Role mappings > Assign role.
4. In the available roles table, select a realm or client role you want to assign.
5. Click Assign.

​

Create a client

Clients represent NexusOne apps or services that rely on Keycloak for authentication and authorization. These apps include, Apache Airflow, Superset, or JupyterHub. Use the following steps to create a client:

1. Log in to the Keycloak Admin Console.
2. From the sidebar, navigate to Clients > Create client.
3. In the Client type field, select a client type such as OIDC or SAML.
4. In the Client ID field, enter a client ID.
5. In the Name and Description field, optionally enter a name and description.
6. Click Next.
7. Select the authentication and authorization the client needs and click Next.
8. Optionally, enter URLs and URIs that define where the client runs and which endpoints Keycloak should redirect after authentication.
9. Click Save.

​

Additional resources

• For more details about Keycloak, refer to the Keycloak official documentation.
• If you are using the NexusOne portal and want to learn how to configure IAM using Keycloak, refer to the Govern page.