Keycloak

 Keycloak 

Do czego służy keycloak

Keycloak to narzędzie służące do bezpiecznego ustalania tożsamości użytkownika i zarządzania dokąd on ma dostęp. Jedną z głównych jego zalet, jest jego wszechstronność, wspiera on wiele protokół, i jego api jest dostępne w wielu językach przez specialne adaptery (dla reszty zawsze jest możliwość komunikacji przez wystawiane przez keycloak REST api)

Kiedy używać keycloak?

Przed wybraniem narzędzia, warto zapoznać się z jego cechami. Co wyróżnia keycloak na tle innych systemów? Zostało ono stworzone z myślą o systemach gdzie wiele użytkowników może się logować do wielu aplikacji, tak więc nie ma sensu używać tego narzędzia do małych projektów (z wyjątkiem aby je sprawdzić)

Przykład użycia keycloak, w środku Realm "Test" znajduje się wiele Klientów - naszych aplikacji (reactApp) i narzędzi keycloak (admin-cli). Do nich mogą logować się użytkownicy  którzy są przydzieleni do odpowiednich grup

Instalacja keycloak

Narzędzie można zainstalować na wiele sposobów, w oficjalnych poradnikach opisane jest jak zainicjować je na strukturze bare-metal, czy na kubernetesie. Ja jednak pokażę jak to zrobić na dockerze. Jest to dosyć proste, gdyż udostępniony jest dockerowy image, a w poradnikach opisane są wszystkie możliwe opcje. Od razu należy dodać, że keycloak nie posiada własnej instancji bazy danych, tak więc musi otrzymać informację jak się do jakiejś dostać w parametrach. Nie wszystkie bazy danych są wspierane, tak więc przed wyborem własnej należy zobaczyć czy znajduje się ona na liście. Poniższa prezentacja będzie pokazana na bazie mysql

version: "3.6"

services:

  project-db:

    container_name: mySql

    image: mysql

    restart: always

    ports:

      - 3306:3306

    environment:

      MYSQL_ROOT_PASSWORD: password

      MYSQL_USER: database

      MYSQL_PASSWORD: database

    networks:

      - app-network

  project-keycloak:

    container_name: project-keycloak

    image: quay.io/keycloak/keycloak:23.0.3

    restart: always

    ports:

      - 8180:8080

    environment:

      PROXY_ADDRESS_FORWARDING: "true"

      DB_VENDOR: mysql

      DB_ADDR: project-db

      DB_PORT: 3306

      DB_DATABASE: project_keycloak

      DB_USER: database

      DB_PASSWORD: database

      KEYCLOAK_USER: user

      KEYCLOAK_PASSWORD: user

      KEYCLOAK_ADMIN: admin

      KEYCLOAK_ADMIN_PASSWORD: admin

    depends_on:

      - project-db

    networks:

      - app-network

    command:

      - start-dev

networks:

  app-network:

    driver: bridge

przykład docker-compose z komunikującymi się dwoma dockerami, z serwerem mysql oraz keycloak, należy tutaj dodać że keycloak zostało wystartowane w wersji nie-produkcyjnej, ponieważ brakuje argumentu hostname.

strona witająca nas po wejściu na localhost:8180

Konfiguracja nowej aplikacji

Należy pamiętać aby nie tworzyć nowych klientów na realm "master". zamiast tego przed użyciem powinniśmy stworzyć swój własny realm

Na naszym realm, możemy wykonywać następujące akcje:

1. dodawać nową aplikację.
2. tworzyć nowe role.
3. tworzyć konta użytkownika, ustawiać im hasła i role.
4. sprawdzać aktualnie aktywne sesje.
5. sprawdzać "logi" serwera.

A także wiele innych opcji, związanych między innemi z ustalaniem bezpieczeństwa.

Użycie adapteru javascript

npm umożliwia nam pobranie adapteru przez komendę:

npm install keycloak-js

Najpierw potrzebnym jest inicjalizacja apatera, następująco:

import Keycloak from 'keycloak-js';

const keycloak = new Keycloak({
    url: 'http://localhost:8180',
    realm: 'test',
    clientId: 'reactApp'
});

try {
    const authenticated = await keycloak.init();
    console.log(`User is ${authenticated ? 'authenticated' : 'not authenticated'}`);
} catch (error) {
    console.error('Failed to initialize adapter:', error);
}

W przypadku poprawnej inicjalizacji, możemy korzystać z rest-owego api dawanego nam przez keycloak. Należy jednak pamiętać, że musimy posiadać odpowiedni "access token". ten access token ma krótki czas życia, prawdopodobnym jest więc, że będziemy potrzebować często prosić o niego serwer.
Przykład użycia adaptera:

try {
    await keycloak.updateToken(30);
} catch (error) {
    console.error('Failed to refresh token:', error);
}
 

const users = await fetchUsers(); 

i funkcja fetchUsers

async function fetchUsers() {
    const response = await fetch('/api/users', {
        headers: {
            accept: 'application/json',
            authorization: `Bearer ${keycloak.token}`
        }
    });

    return response.json();
}

Podsumowanie:

Założenie serwera keycloak może nie należeć do najprostszych czynności, i może upłynąć jeszcze parę wieczorów, nim keycloak.init zwróci wam Promise<boolean> o pożądanej wartości, aczkolwiek jest to niezbędne narzędzie, które znacznia ułatwia wprowadzanie nowych aplikacji, w miarę jak rozrasta się ekosystem danej firmy.