Keycloak‐migraatio 2025: palveluntuottajat

Vaihe 1: datan valmistelu

Tässä vaiheessa kerätään tarvittava data Keycloakin kannasta, siirretään data eVakan kantaan valmisteltavaksi, ja etsitään vastaavat käyttäjät eVakasta. Mikään oikea data ei muutu vielä tässä vaiheessa, joten tämän voi tehdä turvallisesti ja lopputulosta voi tutkia rauhassa ennen lopullista migraatiota.

1. Aja SQL-kysely 1 Keycloakin kannassa

Tässä kyselyssä on kaksi parametria jotka voivat vaihdella eri kunnissa: hetu-attribuutin nimi, ja Keycloak-realmin nimi. Nämä kannattaa tarkistaa, jos myöhemmässä vaiheessa selviää että yksikään käyttäjä ei migratoidu onnistuneesti.

2. Siirrä syntynyt keycloak_employee_migration taulu jollain tavalla eVakan tietokantaan

Datassa on mukana henkilötunnuksia joten siirtotapa täytyy toteuttaa tietoturvallisesti, esim. ajamalla psql-komentorivityökalua bastionilla, jossa CSV-tiedoston laittaminen levylle on ok.

Esimerkki bastion-dumppauksesta:

-- taulun dumppaus employees.csv -tiedostoon
\copy keycloak_employee_migration TO 'employees.csv' (FORMAT CSV, HEADER TRUE)

-- taulun pitää olla olemassa, joten kopioi tämä migraatio-SQL numero 1:stä
CREATE TABLE keycloak_employee_migration (...)
-- taulun luku employees.csv -tiedostosta
\copy keycloak_employee_migration FROM 'employees.csv' (FORMAT CSV, HEADER TRUE)

3. Aja SQL-kysely 2 eVakan kannassa

4. Tutki keycloak_employee_migration-taulua

Taulun keycloak_problem ja evaka_problem -sarakkeista voi lukea syitä miksi käyttäjää ei voi migratoida. Näistä saa hyvän yleiskäsityksen esim. ryhmittelemällä ongelmien määrien mukaan:

SELECT coalesce(keycloak_problem, evaka_problem) AS problem, count(*)
FROM keycloak_employee_migration
GROUP BY 1
ORDER BY 2 DESC

Mahdolliset ongelmat:

• user disabled: Käyttäjä on estetty Keycloakin päässä
• no ssn: Keycloakista ei löytynyt hetua käyttäjälle. Jos tämä tulee suurimmalle osalle käyttäjistä, tarkista hetu-attribuutin nimi SQL-kyselyssä 1!
• duplicate ssn: Sama hetu löytyy monta kertaa Keycloakista
• no match in evaka: Vastaavaa käyttäjää ei löydy eVakasta, eli käyttäjä ei ole koskaan kirjautunut sinne Keycloakin kautta
• ssn already in use: Hetu on jo toisella työntekijällä
• already has a different ssn: Käyttäjälle on jo asetettu hetu, ja se on eri kuin Keycloakissa

Ongelmia voi korjata tekemällä tarvittavia muutoksia Keycloakin / eVakan tietokantoihin, tai korjaamalla SQL-skriptiä 1 jos siellä on väärä hetu-attribuutin tai realmin nimi.

Vaihe 2: varsinainen migraatio eVakaan

Jos keycloak_employee_migration -taulu näyttää järkevältä, ja mahdolliset ongelmarivit voidaan jättää siirtämättä, aja SQL-kysely 3, joka siirtää kyseisestä taulusta ongelmattomat datat eVakaan.

Tämän kyselyn voi ajaa turvallisesti monta kertaa, ja koko migraationkin (kysely 1, siirto, kysely 2, kysely 3) voi ajaa uudestaan jos esim. hetuja käydään vielä lisäämässä Keycloakin puolelle jälkikäteen.

Kun migraatio on tehty, feature flag employeeSfiLogin voidaan kytkeä päälle. Tämän jälkeen Suomi.fi-kirjautuminen korvaa Keycloak-kirjautumisen käyttöliittymässä.

Liite: migraatio-SQL:t

Migraatio-SQL osa 1

Tämä ajetaan Keycloakin kannassa, ja tästä syntyvä keycloak_employee_migration -taulu pitää saada siirrettyä eVakan kantaan jollain tavalla.

DROP TABLE IF EXISTS keycloak_employee_migration;
CREATE TABLE keycloak_employee_migration (
    id uuid NOT NULL,
    evaka_external_id text NOT NULL GENERATED ALWAYS AS ('evaka:' || id) STORED,
    username text NOT NULL UNIQUE,
    ssn text,
    keycloak_problem text,
    evaka_problem text
);
CREATE OR REPLACE VIEW pg_temp.candidate_employee_users AS (
    SELECT
        ue.id::uuid AS id,
        ue.username,
        (
            SELECT ua.value FROM user_attribute ua
            WHERE ua.user_id = ue.id
            AND ua.name = 'suomi_nationalIdentificationNumber' -- HUOM: attribuutin nimi
        ) AS ssn,
        enabled
    FROM user_entity ue
    WHERE ue.realm_id = 'evaka' -- HUOM: realmin nimi
);

INSERT INTO keycloak_employee_migration (id, username, ssn, keycloak_problem)
SELECT id, username, ssn, CASE WHEN NOT enabled THEN 'user disabled' WHEN ssn IS NULL THEN 'no ssn' END
FROM pg_temp.candidate_employee_users;

UPDATE keycloak_employee_migration
SET keycloak_problem = 'duplicate ssn'
WHERE ssn IN (
    SELECT ssn
    FROM pg_temp.candidate_employee_users
    GROUP BY ssn
    HAVING count(*) > 1
);

Migraatio-SQL osa 2

Tämä ajetaan eVakan kannassa, kun osassa 1 syntynyt taulu on saatu siirrettyä sinne datoineen.

UPDATE keycloak_employee_migration
SET evaka_problem = NULL;
UPDATE keycloak_employee_migration kem
SET evaka_problem = 'no match in evaka'
WHERE NOT EXISTS (
    SELECT
    FROM employee e
    WHERE e.external_id = kem.evaka_external_id
);
UPDATE keycloak_employee_migration kem
SET evaka_problem = 'ssn already in use'
WHERE evaka_problem IS NULL
AND EXISTS (
    SELECT FROM employee e
    WHERE e.social_security_number = kem.ssn
    AND e.external_id != kem.evaka_external_id
);
UPDATE keycloak_employee_migration kem
SET evaka_problem = 'already has a different ssn'
WHERE evaka_problem IS NULL
AND EXISTS (
    SELECT FROM employee e
    WHERE e.social_security_number != kem.ssn
    AND e.external_id = kem.evaka_external_id
);

Migraatio-SQL osa 3

Tämä ajetaan eVakan kannassa, ja tämä päivittää lopulliset ongelmattomat käyttäjätiedot eVakaan.

UPDATE employee e
SET social_security_number = kem.ssn
FROM keycloak_employee_migration kem
WHERE e.external_id = kem.evaka_external_id
AND e.social_security_number IS NULL
AND kem.keycloak_problem IS NULL
AND kem.evaka_problem IS NULL;