Forem: Amrita Shrestha

Integrating oCIS With Keycloak

Amrita Shrestha — Tue, 20 Aug 2024 08:35:48 +0000

In the previous blog, we explored the general functionality of Keycloak.
In this blog, I demonstrate how we can integrate oCIS(file-sync and share platform) with Keycloak using the Keycloak WebUI.
This benefits anyone who is interested in getting hands-on experience with Keycloak.

Run Services

Make sure you've installed Docker Engine and Docker Compose.

Before setting up oCIS with Keycloak, it's essential to deploy both oCIS and Keycloak services. I'll describe how to achieve it with docker compose.
oCIS and Keycloak runs behind Traefik as reverse proxy. Traefik generates self-signed certificates for oCIS and Keycloak.

You have to create a csp.yaml file with the following contents:

directives:
  child-src:
    - '''self'''
  connect-src:
    - '''self'''
    # In contrast to bash and docker the default is given after the | character
    - 'https://${KEYCLOAK_DOMAIN|host.docker.internal:8443}'
  default-src:
    - '''none'''
  font-src:
    - '''self'''
  frame-ancestors:
    - '''none'''
  frame-src:
    - '''self'''
    - 'https://embed.diagrams.net/'
  img-src:
    - '''self'''
    - 'data:'
    - 'blob:'
  manifest-src:
    - '''self'''
  media-src:
    - '''self'''
  object-src:
    - '''self'''
    - 'blob:'
  script-src:
    - '''self'''
    - '''unsafe-inline'''
  style-src:
    - '''self'''
    - '''unsafe-inline'''

You can either download the docker code from GitHub or utilize the code provided below:

Note: PROXY_CSP_CONFIG_FILE_LOCATION should contain the exact location of a csp.yaml file

services:
  traefik:
    image: traefik:2.11.0
    command:
      [
        "--log.level=ERROR",
        "--api.insecure=true",
        "--api.dashboard=true",
        "--pilot.dashboard=false",
        "--providers.docker=true",
        "--entrypoints.ocis.address=:9200",
        "--entrypoints.keycloak.address=:8443",
        "--providers.docker.exposedbydefault=false",
        "--entrypoints.websecure.http.tls.options=default",
      ]
    ports:
      - 8080:8080
      - 9200:9200
      - 8443:8443
    volumes:
      - "/var/run/docker.sock:/var/run/docker.sock:ro"
    labels:
      traefik.enable: true
      traefik.http.routers.traefik.rule: HostRegexp(`{any:.+}`)
    restart: always

  ocis:
    image: owncloud/ocis:latest # ocis version = v5.0.5
    entrypoint:
      - /bin/sh
    command: ["-c", "ocis init || true; ocis server"]
    environment:
      # Keycloak IDP configuration
      PROXY_AUTOPROVISION_ACCOUNTS: true
      PROXY_ROLE_ASSIGNMENT_DRIVER: oidc
      OCIS_OIDC_ISSUER: https://host.docker.internal:8443/realms/oCIS # ocis is keycloak realm name
      PROXY_OIDC_REWRITE_WELLKNOWN: true
      WEB_OIDC_CLIENT_ID: web
      # general config
      OCIS_URL: https://host.docker.internal:9200
      OCIS_LOG_LEVEL: error
      OCIS_INSECURE: true
      OCIS_ADMIN_USER_ID: ""
      OCIS_EXCLUDE_RUN_SERVICES: idp
      GRAPH_ASSIGN_DEFAULT_USER_ROLE: false
      GRAPH_USERNAME_MATCH: none
      # PROXY
      PROXY_TLS: false
      PROXY_USER_OIDC_CLAIM: preferred_username
      PROXY_USER_CS3_CLAIM: username
      PROXY_CSP_CONFIG_FILE_LOCATION: /etc/ocis/csp.yaml
      KEYCLOAK_DOMAIN: ${KEYCLOAK_DOMAIN:-host.docker.internal:8443}
    volumes:
      - ./csp.yaml:/etc/ocis/csp.yaml
    extra_hosts:
      - host.docker.internal:host-gateway
    labels:
      traefik.enable: true
      traefik.http.routers.ocis.tls: true
      traefik.http.routers.ocis.rule: PathPrefix(`/`)
      traefik.http.routers.ocis.entrypoints: ocis
      traefik.http.services.ocis.loadbalancer.server.port: 9200

  postgres:
    image: postgres:alpine
    volumes:
      - postgres_data:/var/lib/postgresql/data
    environment:
      POSTGRES_DB: keycloak
      POSTGRES_USER: keycloak
      POSTGRES_PASSWORD: keycloak

  keycloak:
    image: quay.io/keycloak/keycloak:24.0.1
    command: ["start-dev", "--proxy=edge"]
    environment:
      KC_DB: postgres
      KC_DB_URL: "jdbc:postgresql://postgres:5432/keycloak"
      KC_DB_USERNAME: keycloak
      KC_DB_PASSWORD: keycloak
      KC_FEATURES: impersonation
      KEYCLOAK_ADMIN: admin
      KEYCLOAK_ADMIN_PASSWORD: admin
    extra_hosts:
      - host.docker.internal:host-gateway
    labels:
      traefik.enable: true
      traefik.http.routers.keycloak.tls: true
      traefik.http.routers.keycloak.rule: PathPrefix(`/`)
      traefik.http.routers.keycloak.entrypoints: keycloak
      traefik.http.services.keycloak.loadbalancer.server.port: 8080
    depends_on:
      - postgres

volumes:
  postgres_data:

Save the above code in compose.yaml file locally and run docker command docker compose up in a terminal.

Docker compose serves three services:

oCIS on https://host.docker.internal:9200
Keycloak on https://host.docker.internal:8443
Traefik dashboard on http://host.docker.internal:8080/

Manual Steps For Setting Up oCIS With Keycloak

Go to oCIS url: https://host.docker.internal:9200/ > Note: The oCIS WebUI will not be accessible until Keycloak and oCIS are fully integrated. The discovery endpoint is unavailable, which is why the web interface is inaccessible.

Go to Keycloak url: https://host.docker.internal:8443/

Create new realm:

Realm name: oCIS > Note: the realm name should be the name provided in the oCIS environment variable: OCIS_OIDC_ISSUER: https://host.docker.internal:8443/realms/oCIS

Add a new client:

Client ID: web

Root URL: https://host.docker.internal:9200

Add realm roles:

Role name: ocisAdmin

Note: oCIS has defined role names that have been documented under Automatic Quota Assignments. So, we can't create the role with a random name.

Create a new user:

With username: admin and other information:

Create password

Role Mapping: Assign ocisAdmin role

Update roles Client scope: Client Scopes -> roles

Mappers -> realm roles -> Token Claim Name=roles > Note: oCIS default role_claim is 'roles'

Go to url https://host.docker.internal:9200/, reload if already opened Enter username: admin and password: admin to log into oCIS

Setting Up oCIS With Keycloak Using JSON Files

Keycloak provides an Importing and Exporting Realms feature. If we have JSON configuration files, then we can avoid manually setting services in Keycloak.
oCIS provides documentation to set up oCIS with Keycloak which uses JSON configuration.
If you want to automate Keycloak integration with oCIS services, then you can use json files.

In this blog post, we've talked about putting Keycloak and oCIS together. We've shown how to set them up using Docker Compose, making sure they work smoothly with Traefik.
We've also given step-by-step instructions on setting up oCIS with Keycloak manually, like making realms, adding clients and roles, and creating users.
For those who like using JSON files, Keycloak lets you do that to set things up more easily.

Introduction to Keycloak

Amrita Shrestha — Tue, 20 Aug 2024 07:05:55 +0000

Keycloak is an open-source project created by RedHat for Single Sign-On. It provides an Identity and Access Management (IAM) solution designed to secure application services.
Additionally, it enables users to authenticate through various identity providers and use fine-grained permissions for regulating access to Software as a Service (SaaS) applications.

It facilitates the creation of a user database with customizable roles and groups, offering functionalities such as user management, registration, and password policy enforcement.
This makes it a comprehensive Identity and Access Management solution for contemporary applications. The Keycloak API enables the integration of all these features into your application
without the need for additional coding.

Keycloak Features

Identity Broker:
Identity Broker acts as a middleman, linking various service providers with different identity providers. It establishes trust with external identity providers to utilize their identities for accessing internal services offered by service providers.
Imagine a company, which has two Keycloak setups: one for customers and another for internal employees. If you want your employees to access external services without creating new accounts on the customer Keycloak, you can use the customer Keycloak as Broker and the internal Keycloak as Provider in this scenario.
User Federation:
Keycloak provides the ability to integrate with existing LDAP or Active Directory servers. It also supports implementation of your own provider such as a relational database.
Standard Protocols:
Keycloak is based on three standard protocols i.e., OpenID Connect, OAuth2.0, and SAML.
Password Policies:
Keycloak contains different password policies i.e., HashAlgorithm, Hashing Iterations, Digits, Lowercase Characters, Regular Expression and so on.
Single Sign-On:
Keycloak facilitates a seamless login experience where users only need to sign in once to access multiple applications, eliminating the need for repeated logins.
This not only streamlines the user experience but also simplifies identity management for administrators.
Social Login:
Keycloak has built-in support to login via Google, GitHub, and Facebook, which helps us to use social identity providers.

Keycloak Installation

In this blog, two different ways are discussed to install Keycloak.

By Docker

Make sure Docker Engine and Docker Compose has been installed in your system.

Keycloak using docker image
Run the following docker command to serve the Keycloak image. Keycloak will be available on http://localhost:8080.
```
 docker run -p 8080:8080 -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:24.0.2 start-dev
```

Keycloak with postgres database using docker-compose

 services:
   postgres:
     image: postgres:alpine
     volumes:
       - postgres_data:/var/lib/postgresql/data
     environment:
       POSTGRES_DB: keycloak
       POSTGRES_USER: keycloak
       POSTGRES_PASSWORD: keycloak

   keycloak:
     image: quay.io/keycloak/keycloak:24.0.1
     command: ["start-dev"]
     environment:
       KC_DB: postgres
       KC_DB_URL: "jdbc:postgresql://postgres:5432/keycloak"
       KC_DB_USERNAME: keycloak
       KC_DB_PASSWORD: keycloak
       KC_FEATURES: impersonation
       KEYCLOAK_ADMIN: admin
       KEYCLOAK_ADMIN_PASSWORD: admin
     ports:
       - 8001:8080 # map keycloak port 8080 to 8001
     depends_on:
       - postgres

 volumes:
   postgres_data:

Save the above code in compose.yaml file and run docker compose up in a terminal.

Docker compose serves Keycloak on http://localhost:8001.

By Distribution File

There is another way to set up Keycloak using the Keycloak distribution file.

Download the Keycloak distribution

export KC_VERSION=24.0.4
curl -LO  https://github.com/keycloak/keycloak/releases/download/"${KC_VERSION}"/keycloak-"${KC_VERSION}".zip

Unzip the Keycloak distribution package
```
unzip keycloak-${KC_VERSION}.zip
```
Install openjdk
```
sudo apt install openjdk-17-jdk
```
Navigate to the Keycloak directory
```
cd keycloak-${KC_VERSION}
```
When we start the server for the first time, we have to set the admin user and the admin password:
```
KEYCLOAK_ADMIN=admin KEYCLOAK_ADMIN_PASSWORD=admin ./bin/kc.sh start-dev
```
Note: if port 8080 is already used, then you can map the Keycloak port using the Keycloak environment variable 'KC_HTTP_PORT=8001'
When we start again, it is not necessary to set these variables again. You can start the server with:
```
./bin/kc.sh start-dev
```

Note: start-dev runs the Keycloak application in DEV-mode. Do not use this for production.

By default, the Keycloak server is on port 8080 for HTTP and 8084 for HTTPS. They are only served from the localhost loopback address 127.0.0.1:
Keycloak serves on http://localhost:<port>.

Why Keycloak Matters

Keycloak is open source.
Keycloak supports three different authentication protocols which gives you the possibility to cover many applications with different security demands with a single tool.
Keycloak provides a web-based GUI which makes any configuration changes easy.
Keycloak has huge community support.

Keycloak Drawbacks

Despite its extensive features, Keycloak does have certain limitations. One of these is the need for a more varied implementation approach.
Additionally, the following are some of the drawbacks associated with Keycloak:

Complex Server Deployment:
The manual process involved in deploying Keycloak on a server can be complicated, potentially affecting overall productivity.
Lack of Comprehensive Support Documentation:
Despite its robust functionalities, Keycloak could benefit from more efficient and extensive support documentation. This would make it easier for users to find suitable solutions to their problems.

When It May Not Be the Best Choice

Enterprises seeking robust guarantees or support may find Keycloak lacking in this regard. As an open-source project, there are no assurances provided by its producer regarding its functionality or roadmap. Support is community-driven, typically through platforms like Stack Overflow, with no guaranteed response times.
If your application consists of a single application with just one client in the Keycloak realm, you won't benefit from Single Sign-On (SSO) capabilities.
For applications solely reliant on a pure user database, Keycloak could be overkill. A database with specific tables may offer a simpler alternative, especially if you already have one set up.

In conclusion, when considering Identity Access Management solutions, Keycloak stands out as a robust option. However, it's essential to explore alternatives such as Auth0, Zluri, Microsoft Azure Active Directory, Okta, or WSO2 Identity Server to ensure you find the best fit for your specific needs and preferences.