Strong Authentication with Keycloak: SAML and Confluence Integration

Today, a significant majority of companies rely on modern identity management systems to authenticate and authorize users accessing their applications. In addition to being a leading manufacturer of biometric-based access control and security solutions, Ones Technology® uses Keycloak for identity authentication and authorization — providing secure access to product information, user guides, technical documents, customer and integrator resources, and developer content. By integrating diverse technologies, the company continues to deliver more flexible and secure solutions tailored to customer needs, while remaining committed to continuous improvement and innovation.

The use of Single Sign-On (SSO) strengthens resilience against cyberattacks by storing user credentials in a central, secure location and minimizing data sharing across systems. This approach serves as a critical security measure, particularly for organizations managing a large number of users and systems.

This article provides a detailed overview of how Keycloak is implemented at Ones Technology®, covering SAML integration, Jira-based user synchronization, and access management through Confluence Scroll Viewport. It delivers comprehensive insights into the company’s corporate identity authentication and authorization processes.

What is Keycloak?

Keycloak is an open-source, Java-based platform developed by Red Hat that provides identity and access management. Keycloak allows users to perform authentication and authorization through a central system and to access different applications via a Single Sign-On (SSO) mechanism. With the widespread use of the internet and the increasing number of applications today, it has become necessary to create a separate account for each service. Over time, managing these accounts can become complex and inefficient. This is where Single Sign-On comes into play, simplifying the user experience and enhancing security by providing access to multiple services with a single set of credentials.

Keycloak’s Core Components

Realm

Realms are isolated domains within Keycloak that manage independent sets of users, roles, and clients. Each realm has its own authentication and authorization rules, allowing for separate security policies to be applied to different user groups and applications.

Example

developer → The realm where company developers log in.

customer → The area where customers access.

integrator → The area where integrators log into the system.

Each of these is managed independently and can have separate user databases.

Clients

Clients are the applications and services that perform authentication through Keycloak.

• Web applications, mobile apps, or API services are defined as clients.
• Each client has specific authentication and authorization configurations.

Users

Users are the real individuals registered in the system who are authenticated.

• User information can be stored in Keycloak’s internal database or sourced from external directory services like LDAP or Active Directory.
• Additionally, in the solution we developed at Ones Technology, one-way user synchronization can be established from a Jira to Keycloak.

Roles

Roles define the access permissions granted to users. Thanks to roles, it is determined what actions each user can perform in the system.

Example Roles

• Admin → A user with all permissions.
• Editor → A user with permission to create and edit content.
• User → A user who can only view content.

Identity Providers

This is the component that enables user authentication from external systems.

• It can integrate with corporate directories like LDAP and Active Directory, as well as social identity providers like Google and Facebook.
• This structure makes it easy to implement authentication processes that are compatible with existing user systems.

What is SAML (Security Assertion Markup Language)?

SAML (Security Assertion Markup Language) is a federated identity authentication protocol generally used to enable users to securely access multiple applications or services. Working with an XML-based format, SAML carries authentication and authorization information. This protocol is used to verify user identities and provide authorization by transmitting data between an Identity Provider (IdP) and a Service Provider (SP). SAML is widely preferred for providing a single sign-on (SSO) experience, especially in corporate environments and for cloud-based services.

When a user attempts to access a Service Provider (SP) platform, the system first communicates with the Identity Provider (IdP) to verify the user’s identity. When the authentication is successful, the IdP sends a SAML Response. This response contains information about the user’s identity (e.g., username, email address, permissions), which is received by the SP to grant the user appropriate access permissions. Thus, the user can securely access all integrated platforms by signing in just once, without having to log in to each service separately.

An example SAML Response is as follows:

<?xml version="1.0" encoding="UTF-8"?>
<samlp:Response
    xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
    xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
    ID="response-12345"
    Version="2.0"
    IssueInstant="2025-03-16T12:34:56Z"
    Destination="https://customer-help.bioaffix.com/saml/acs"
    InResponseTo="request-12345">

    <saml:Issuer>https://sso.bioaffix.com/realms/BioAffix</saml:Issuer>

    <saml:Assertion ID="assertion-67890" IssueInstant="2025-03-16T12:34:56Z">
        
        <saml:Issuer>https://sso.bioaffix.com/realms/BioAffix</saml:Issuer>
        
        <saml:Subject>
            <saml:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">[email protected]</saml:NameID>
            <saml:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
                <saml:SubjectConfirmationData 
                    NotOnOrAfter="2025-03-16T12:44:56Z" 
                    Recipient="https://customer-help.bioaffix.com/saml/acs"/>
            </saml:SubjectConfirmation>
        </saml:Subject>

        <saml:Conditions NotBefore="2025-03-16T12:34:56Z" NotOnOrAfter="2025-03-16T12:44:56Z">
            <saml:AudienceRestriction>
                <saml:Audience>https://customer-help.bioaffix.com</saml:Audience>
            </saml:AudienceRestriction>
        </saml:Conditions>

        <saml:AuthnStatement AuthnInstant="2025-03-16T12:34:56Z" SessionIndex="session-12345">
            <saml:AuthnContext>
                <saml:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport</saml:AuthnContextClassRef>
            </saml:AuthnContext>
        </saml:AuthnStatement>
        
        <saml:AttributeStatement>
            <saml:Attribute Name="email">
                <saml:AttributeValue>[email protected]</saml:AttributeValue>
            </saml:Attribute>
            <saml:Attribute Name="role">
                <saml:AttributeValue>user</saml:AttributeValue>
            </saml:Attribute>
        </saml:AttributeStatement>

    </saml:Assertion>
</samlp:Response>

Confluence Scroll Viewport is a tool used to publish Confluence content in a website format. Users (for customer, developer, and integrator documentation) who want to access the help portal are authenticated via Keycloak and log in with differently authorized groups.

Distinction Between Roles and Authorization in Keycloak

Keycloak provides flexible and secure access control by separating role management and authorization processes. Understanding the difference between these two concepts will help you make the right configurations.

Role Management

A Role is a construct used to assign specific permissions to users. In Keycloak, roles are generally used to determine users’ access levels. For example:

• A customer role might only have access to customer data.
• A developer role might have access to more technical resources and administrative permissions on the system.
• An integrator role might carry the authority to integrate with third-party systems.

A user can have multiple roles; for instance, a developer can also have a customer role. This way, the user’s access to different parts of the system can be authorized. Keycloak allows roles to be created in a hierarchical structure, meaning a parent role can inherit the permissions of its child roles.

Authorization

Authorization determines which resources, services, or data a user can access. Authorization is used to further specialize roles and ensure users access the correct resources. In Keycloak, a user is authorized with a role, but the authorization process is controlled not only at the role level but also at the group and permission levels.

For example, if you use different groups, each group can have access to different resources:

• Customer group: A user in this group can only access customer information and reports.
• Developer group: A user in this group can access the system’s technical infrastructure.
• Integrator group: A user in this group can access APIs and data for integration with external systems.

Keycloak allows you to manage authorization on a realm and group basis, enabling you to create custom roles and access levels for each. This way, you can create different user types for different projects and apply separate authorization policies for each project.

Example Scenario

Let’s say we have three groups: customer, developer, and integrator. The roles and authorization for these groups could be as follows:

Customer

• customer_role: Access to customer data (BioAffix User and Installation Guide).
• customer_admin_role: Permission to manage and edit customer data.

Developer

• developer_role: Access to the application and software infrastructure, permission to report bugs.
• developer_admin_role: Ability to perform software updates and administrative actions on the system.

Integrator

• integrator_role: Ability to connect with third-party systems, access to APIs.
• integrator_admin_role: Permission to manage and configure external system integrations.

For each realm, roles and the users assigned to these roles can be configured with different authorization levels. For instance, a developer user can access technical data associated with the developer group, while the customer group can only access customer data and may not have permission to use the APIs in the integrator group. In this way, custom roles and authorization processes can be designed for each group.

Using the Keycloak REST API

In addition to creating users with the REST API in Keycloak, you can also programmatically perform all the actions you can do in the management interface via the API. Below are the basic steps to obtain a token and create a user.

To get a token, you first need to send a request to Keycloak’s token endpoint. This is usually located at the /protocol/openid-connect/token endpoint.

From this response, you can extract the access_token and use it in your API requests. If you want to examine the provided access token, the JWT Token Description from the website http://jwt.io is as follows:

1. Header: Specifies how the JWT is signed and which algorithm is used.
2. Payload: Contains the user’s identity, permissions, and other metadata. For example, exp (expiration) and iat (issued at) give the token’s validity period as a Unix timestamp value, while sid (session id) is a unique identifier assigned for the session, and scope indicates what permissions the token contains.
3. Signature: The formula created to understand whether the JWT is trustworthy. RSASHA256(base64UrlEncode(header) + “.” + base64UrlEncode(payload), Private Key)
   • Public Key → Used to verify the JWT and can be obtained from Keycloak’s openid-configuration address.
   • Private Key → Used to sign the JWT and is stored on the Keycloak server.

User Creation Example

To create a new user, perform the authorization process using the access_token you obtained in the previous step. Specify this token in the Authorization header and add the new user’s information in JSON format to the Body section. Then, you can create a new user by sending a POST request.

And that’s it! We have successfully obtained our token and created a user.

At Ones Technology®, we developed a structure that synchronizes users from our Jira system to the Keycloak server via the API. When the user synchronization is complete, we send them an informational email with details of the portals they can access, their randomly generated password, and their email address. After the user logs into the portal with this information, they are required to change their password. Thanks to this approach, we do not store user data in our own system; instead, we ensure the process remains secure and fully controlled.

Below is an example Jira user entry and the corresponding notification email:

Easy Installation and Integration

Keycloak offers a powerful solution that simplifies the management of authentication and authorization processes. Its installation is straightforward and can typically be completed with just a few commands. You can get a Keycloak server up and running with a single command, whether using a setup (exe) (which we use) or Docker:

docker run -d -p 8080:8080 --name keycloak -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:latest start-dev 

This way, it becomes operational within minutes, and you can use it as an Identity Provider (IdP) without any additional configuration. After completing the installation, you can either install it on your own servers (on-premise) or host it on cloud services like Azure Kubernetes, AWS ECS, or Google Cloud Run.

User-Friendly Authentication Pages

On the front-end, thanks to the ready-made authentication pages that come with Keycloak, you don’t have to design a login screen from scratch. For example, it provides customizable login pages, password reset forms, and session management panels for your users. Large technology firms like Ones Technology can make the login process more user-friendly and faster by offering customized login pages for their employees and users. Additionally, you can enable your users to log in with their Facebook or Google accounts, which can speed up the registration process, especially for external users, and improve the user experience.

Backend Integration

On the back-end, thanks to Keycloak’s REST API and OpenID Connect support, you can easily integrate it with any backend service. For example, a .NET Core API application can perform user authentication with Keycloak and carry out JWT token validation. A mobile application (Android / iOS) can securely log in using Keycloak’s OAuth 2.0 flows.

Integration with Various Identity Providers

Keycloak supports different identity providers. For example, it can be integrated with LDAP or Active Directory to allow employees in large corporations to log in with their company email and password.

Flexibility and Scalability

Keycloak provides a flexible, powerful, and scalable identity management solution, making it an ideal infrastructure for both small-scale projects and large corporate systems.

Conclusion

In today’s digital world, as organizations connect to various applications and systems, entering and constantly updating user information separately for each system leads to both a loss of time and increased security risks. Sharing users’ sensitive information with different systems causes this information to be stored in multiple locations, and each location becomes a potential attack surface.

With Single Sign-On (SSO), user information is stored centrally in one secure platform. Each connected application receives only the verification details it needs, reducing redundant data storage and minimizing vulnerabilities. The recent TurkNet cyber-attack illustrates why this matters: with a centralized identity provider in place, attackers would have been limited to a single target. Instead of compromising user data across multiple systems, the impact could have been contained within one isolated point — making defense stronger, simpler, and far more effective.

In conclusion, the use of SSO creates a more resilient structure against cyber-attacks by keeping user credentials in a central, secure location and limiting data sharing across all systems. This approach is a critical security measure, especially for organizations with a large number of users and systems.