Выбор и настройка Identity and Access Management

~ 60 минут

Вы изучили разные концепции в предыдущих уроках, и теперь пришло время приблизиться к реализации кейса BionicPRO. Вам предстоит настроить SSO и в последующем интеграцию пользователей с CRM. Сделать так, чтобы пользователь смог логиниться с одним и тем же логином и паролем и получать свои данные. Эти задачи будут решаться с помощью одного из сервисов — Keycloak.

🔍 Этот урок содержит практику, которую вам необходимо выполнить, чтобы подготовиться к проектной работе.

Практикуясь, вы повторите основные концепции, которые рассматривали раньше. Например, в работе мы вместе подготовим SSO через Keycloak, создадим для него пользователей и настроим работу фронтенда с ним. Мы будем настраивать авторизацию по протоколу Oauth2.0 и аутентификацию OpenID connect c помощью JWT по Code Grant.

Путь пользователя

Процесс аутентификации пользователя проходит через единую систему входа (SSO) с использованием Keycloak как провайдера аутентификации. Путь пользователя в целом выглядит так:

Переход на страницу: пользователь заходит на фронтенд-приложение.
Проверка аутентификации: если пользователь не авторизован, появляется кнопка «Логин».
Перенаправление на SSO: при нажатии на кнопку пользователь попадает на экран входа Keycloak. Этот сервис выполняет роль SSO, упрощая управление доступом для нескольких приложений.
Ввод данных: пользователь вводит свои учётные данные — логин и пароль — в Keycloak.
Возвращение на фронтенд: после успешного входа Keycloak перенаправляет пользователя обратно на фронтенд.
Получение токена: фронтенд использует временный код от Keycloak, чтобы запросить и получить токен для дальнейшей работы и доступов.

Наша задача заключается в том, чтобы пользователь прошёл все этапы без проблем.

Для этого нужно объединить все необходимые сервисы (Keycloak, базу данных и фронтенд), упростить их запуск и настройку с помощью docker-compose. В docker-compose настраиваются переменные и зависимости, обеспечивая согласованность между сервисами и облегчая локальную настройку приложения. Но для начала развернём Keycloak.

Реализация Keycloak: практика

🔍 Мы будем работать над кейсом компании BionicPRO, чтобы подготовить необходимое окружение для проекта.

Эта практика обязательна для успешного выполнения проектных заданий — выполняйте описанные ниже шаги по мере прохождения урока или поработайте с кодом после прочтения.

Полный код расположен по ссылке: https://github.com/Yandex-Practicum/architecture-sprint-8.

Шаг 1. Настройка базы данных

Мы будем использовать Postgres как базу для хранения данных Keycloak, чтобы можно было посмотреть на его структуру.

Создадим docker-compose.yaml и добавим в него данные:

YAML

version: '3.8'

services:
  keycloak_db:
    image: postgres:14
    environment:
      POSTGRES_DB: keycloak_db
      POSTGRES_USER: keycloak_user
      POSTGRES_PASSWORD: keycloak_password
    volumes:
      - ./postgres-keycloak-data:/var/lib/postgresql/data
    ports:
      - "5433:5432"

Мы используем Postgres 14 версии, обозначаем базу данных keycloak_db и пользователя для доступа в базу keycloak_user с паролем keycloak_password.

Чтобы данные при перезагрузке контейнеров не удалялись, мы выводим их в папку ./postgres-keycloak-data.

Ещё мы сделали переопределение порта с 5432 на 5433. Это не повлияет на взаимодействие между контейнерами, но может привести к конфликту, когда дальше появится другая база с таким же портом.

Шаг 2. Запуск Keycloak

Добавим данные о Keycloak:

YAML

  keycloak:
    image: quay.io/keycloak/keycloak:21.1
    environment:
      KEYCLOAK_ADMIN: admin
      KEYCLOAK_ADMIN_PASSWORD: admin
      KC_DB: postgres
      KC_DB_URL: jdbc:postgresql://keycloak_db:5432/keycloak_db
      KC_DB_USERNAME: keycloak_user
      KC_DB_PASSWORD: keycloak_password
    command: 
      - start-dev
      - --import-realm
    volumes:
      - ./keycloak/realm-export.json:/opt/keycloak/data/import/realm-export.json
    ports:
      - "8080:8080"
    depends_on:
      - keycloak_db

Мы задаём образ, логин и пароль для админки (по умолчанию используем admin, admin). Будем использовать базу Postgres, чтобы сохранять данные с указанием кредов для подключения к ней.

Также мы запускаем Keycloak в режиме разработчика (start-dev). Это решает следующие задачи:

Разрешает HTTP, то есть совершать небезопасные запросы без шифрования.
Убирает жёсткие требования к разрешению hostname, то есть не требуются строгие проверки безопасности.
Делает кеш локальным, так как в процессе разработки кеш неважен (в pежиме продакшн кеш может быть распределённым для обеспечения высокой доступности).
Не кеширует тему логина, так как она может измениться.

На этом этапе файл docker-compose.yaml готов.

Docker-compose.yaml полностью

YAML

version: '3.8'

services:
  keycloak_db:
    image: postgres:14
    environment:
      POSTGRES_DB: keycloak_db
      POSTGRES_USER: keycloak_user
      POSTGRES_PASSWORD: keycloak_password
    volumes:
      - ./postgres-keycloak-data:/var/lib/postgresql/data
    ports:
      - "5433:5432"
  keycloak:
    image: quay.io/keycloak/keycloak:21.1
    environment:
      KEYCLOAK_ADMIN: admin
      KEYCLOAK_ADMIN_PASSWORD: admin
      KC_DB: postgres
      KC_DB_URL: jdbc:postgresql://keycloak_db:5432/keycloak_db
      KC_DB_USERNAME: keycloak_user
      KC_DB_PASSWORD: keycloak_password
    command: 
      - start-dev
      - --import-realm
    volumes:
      - ./keycloak/realm-export.json:/opt/keycloak/data/import/realm-export.json
    ports:
      - "8080:8080"
    depends_on:
      - keycloak_db
  frontend:
    build:
      context: ./frontend
      dockerfile: Dockerfile
    ports:
      - "3000:3000"
    environment:
      REACT_APP_API_URL: http://localhost:8000
      REACT_APP_KEYCLOAK_URL: http://localhost:8080
      REACT_APP_KEYCLOAK_REALM: reports-realm
      REACT_APP_KEYCLOAK_CLIENT_ID: reports-frontend

В docker-compose указан --import-realm. Это означает, что данные о пользователях, ролях и клиентах загружаются при старте. С той же целью мы прикладываем ./keycloak/realm-export.json.

Давайте его напишем.

Шаг 3. Создание Realm

✏️ В Keycloak realm — это изолированная область, где управляются пользователи, роли, политики и клиенты. Каждый realm позволяет администратору настраивать параметры аутентификации, авторизации и контроля доступа для приложений.

По умолчанию Keycloak содержит master-realm. Это основная область, используемая для административных задач, таких как создание и управление другими realm в системе. Только администраторы имеют доступ к master-realm.

Для нашего проекта создан отдельный realm — reports-realm. Это пространство будет содержать все настройки, необходимые для аутентификации и авторизации пользователей, которые работают с нашими приложениями. Внутри reports-realm можно:

Создавать пользователей и назначать им роли, которые определяют их права доступа.
Настраивать клиентов (например, фронтенд и API), которые будут использовать SSO для доступа к ресурсам.
Определять политики безопасности, специфичные для reports-realm, не затрагивая другие realm или глобальные настройки Keycloak.

Почему это важно?

Разделение на realm полезно, если есть несколько проектов или команд, требующих разные политики безопасности. Reports-realm изолирует конфигурацию для вашего приложения и не конфликтует с другими realm, что делает систему более гибкой и безопасной.

Более подробно про концепцию можно узнать в разделе The master realm официальной документации Keycloak.

Начнём создавать файл realm-export.json:

JSX

"realm": "reports-realm"

Шаг 4. Определение ролей и пользователей

Роли

JSX

"roles": {
      "realm": [
        {
          "name": "user",
          "description": "Regular user role"
        },
        {
          "name": "administrator",
          "description": "Administrator role"
        },
        {
          "name": "prothetic_user",
          "description": "Prothetic user role with report access"
        }
      ]

Мы указали роли. Ориентируясь на кейс BionicPRO, будем считать, что основной пользователь будет иметь роль prothetic_user.

Пользователи

JSX

{
        "username": "prothetic1",
        "enabled": true,
        "email": "prothetic1@example.com",
        "firstName": "Prothetic",
        "lastName": "One",
        "credentials": [
          {
            "type": "password",
            "value": "prothetic123",
            "temporary": false
          }
        ],
        "realmRoles": ["prothetic_user"]
      },

Мы создали несколько пользователей протезов, назначили им роли и установили пароли. Их можно использовать, чтобы проверить работу.

Шаг 5. Конфигурация клиентов

JSX

"clients": [
      {
        "clientId": "reports-frontend",
        "enabled": true,
        "publicClient": true,
        "redirectUris": ["http://localhost:3000/*"],
        "webOrigins": ["http://localhost:3000"],
        "directAccessGrantsEnabled": true
      },
      {
        "clientId": "reports-api",
        "enabled": true,
        "clientAuthenticatorType": "client-secret",
        "secret": "oNwoLQdvJAvRcL89SydqCWCe5ry1jMgq", 
        "bearerOnly": true
      }

Первый клиент — это фронтенд. Следующие строки показывают, что он включён, доступен для использования и является публичным клиентом (не требует секрета доступа). Значение redirectUris указывает, куда Keycloak будет переводить пользователя. Параметр "directAccessGrantsEnabled": true разрешает клиенту использовать прямые гранты доступа, что позволяет входить в систему через API без перенаправления пользователя.
Второй клиент — это API, которое вы будете создавать в практической работе спринта. В этом клиенте указан секрет приложения, который надо будет передать API (через env variables). Параметр "bearerOnly": true указывает, что этот клиент только проверяет токены (bearer tokens) и не инициирует собственный поток аутентификации.

На этом этапе файл keycloak/realm-export.json готов.

keycloak/realm-export.json целиком

JSON

{
    "realm": "reports-realm",
    "enabled": true,
    "roles": {
      "realm": [
        {
          "name": "user",
          "description": "Regular user role"
        },
        {
          "name": "administrator",
          "description": "Administrator role"
        },
        {
          "name": "prothetic_user",
          "description": "Prothetic user role with report access"
        }
      ]
    },
    "users": [
      {
        "username": "user1",
        "enabled": true,
        "email": "user1@example.com",
        "firstName": "User",
        "lastName": "One",
        "credentials": [
          {
            "type": "password",
            "value": "password123",
            "temporary": false
          }
        ],
        "realmRoles": ["user"]
      },
      {
        "username": "user2",
        "enabled": true,
        "email": "user2@example.com",
        "firstName": "User",
        "lastName": "Two",
        "credentials": [
          {
            "type": "password",
            "value": "password123",
            "temporary": false
          }
        ],
        "realmRoles": ["user"]
      },
      {
        "username": "admin1",
        "enabled": true,
        "email": "admin1@example.com",
        "firstName": "Admin",
        "lastName": "One",
        "credentials": [
          {
            "type": "password",
            "value": "admin123",
            "temporary": false
          }
        ],
        "realmRoles": ["administrator"]
      },
      {
        "username": "prothetic1",
        "enabled": true,
        "email": "prothetic1@example.com",
        "firstName": "Prothetic",
        "lastName": "One",
        "credentials": [
          {
            "type": "password",
            "value": "prothetic123",
            "temporary": false
          }
        ],
        "realmRoles": ["prothetic_user"]
      },
      {
        "username": "prothetic2",
        "enabled": true,
        "email": "prothetic2@example.com",
        "firstName": "Prothetic",
        "lastName": "Two",
        "credentials": [
          {
            "type": "password",
            "value": "prothetic123",
            "temporary": false
          }
        ],
        "realmRoles": ["prothetic_user"]
      },
      {
        "username": "prothetic3",
        "enabled": true,
        "email": "prothetic3@example.com",
        "firstName": "Prothetic",
        "lastName": "Three",
        "credentials": [
          {
            "type": "password",
            "value": "prothetic123",
            "temporary": false
          }
        ],
        "realmRoles": ["prothetic_user"]
      }
    ],
    "clients": [
      {
        "clientId": "reports-frontend",
        "enabled": true,
        "publicClient": true,
        "redirectUris": ["http://localhost:3000/*"],
        "webOrigins": ["http://localhost:3000"],
        "directAccessGrantsEnabled": true
      },
      {
        "clientId": "reports-api",
        "enabled": true,
        "clientAuthenticatorType": "client-secret",
        "secret": "oNwoLQdvJAvRcL89SydqCWCe5ry1jMgq", 
        "bearerOnly": true
      }
    ]
  }

Настройка через интерфейс

Ранее мы импортировали файл через docker-compose. Но есть и другой способ — настроить новый realm вручную, вставив JSON в импорт или загрузив его же через интерфейс.

Для этого нужно:

Настроить docker-compose. Keycloak будет крутиться по адресу localhost:8080. С логином/паролем admin/admin.
Добавить код для каждого из сервисов. Код указан на GitHub.
Запустить docker-compose up -d build и ждать, когда всё соберётся и запустится.

Инструкция по настройке Realm через интерфейс

Мы будем работать в Reports-Realm. Выбираем «Create Realm», чтобы добавить новый Realm.

Подгружаем в поле Resourse file наш файл JSON.

После того как файл подгружен, Keycloak создаёт наших пользователей.

Также были созданы роли. Поскольку мы не убирали роли по умолчанию, они тоже присутствуют. Но на практике ненужные роли лучше убирать.

У каждой роли отображаются пользователи, которые ею обладают.

Во вкладке Clients есть список приложений — клиентов, которые мы указывали ранее: reports-frontend и reports-api.

По клику на клиента можно увидеть его параметры. Изменены только те, которые нужны для нашей работы. Важно, чтобы блок redirectUris был указан: после успешного логина пользователя переведут по этому адресу.

На этой же странице указаны настройки аутентификации.

По умолчанию используется протокол аутентификации OpenID Connect. А стандартный флоу — Authorization Code Grant (поток авторизации по коду). Аутентификация происходит на основе перенаправления с использованием OpenID Connect и кода авторизации. В терминах спецификаций OpenID Connect или OAuth 2.0 это обеспечивает поддержку Authorization Code Flow для данного клиента. И также Direct Access Grant, то есть клиент может послать креды на API сервера и получить токен обратно. Уберём этот последний, так как он нам не понадобится.

Вы можете посмотреть и другие настройки, но сейчас вам понадобятся только пользователи, роли, клиенты и их настройка для работы с Keycloak.

Ключи

Ключи нам понадобятся в практической работе для декодирования токена.

В безопасности токенов для OAuth2 и OpenID Connect используются два типа алгоритмов шифрования:

RS256 (RSA) ― асимметричный алгоритм. RS256 применяет пару ключей: приватный для подписи токена и публичный для его проверки. Это позволяет клиентам проверять подлинность токена, не запрашивая сервер, снижает нагрузку и подходит для масштабируемых систем.

В Keycloak RS256 используется по умолчанию, а публичный ключ доступен клиентам через конфигурацию .well-known/openid-configuration.

Почему в Keycloak RS256? RS256 удобен для распределённых систем: клиенты могут верифицировать токены самостоятельно. Публичный ключ может свободно распространяться, а приватный остаётся защищённым, что повышает безопасность.

HS256 (HMAC) ― симметричный алгоритм. HS256 использует один секретный ключ для создания и проверки токенов, что требует его наличия у обеих сторон. Этот метод подходит для закрытых систем. Но он менее безопасен, так как секретный ключ нужно передавать между участниками и его утечка ставит под угрозу все токены.

Давайте теперь перейдём к настройке клиента.

Шаг 6. Настройка клиента

Добавим данные в docker-compose.

YAML

  frontend:
    build:
      context: ./frontend
      dockerfile: Dockerfile
    ports:
      - "3000:3000"
    environment:
      REACT_APP_API_URL: http://localhost:8000
      REACT_APP_KEYCLOAK_URL: http://localhost:8080
      REACT_APP_KEYCLOAK_REALM: reports-realm
      REACT_APP_KEYCLOAK_CLIENT_ID: reports-frontend

Мы указываем, что он должен крутиться на порту 3000, и передаём в переменные окружения следующие параметры:

API (он нам понадобится в проекте),
URL Keycloak,
ID клиента,
Realm, который мы используем.

Шаг 7. Настройка фронтенда

Код для фронтенда достаточно простой:

index.tsx

TSX

import React from 'react';
import ReactDOM from 'react-dom/client';
import './index.css';
import App from './App';

const root = ReactDOM.createRoot(
  document.getElementById('root') as HTMLElement
);

root.render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);

App.tsx

TSX

    import React from 'react';
    import { ReactKeycloakProvider } from '@react-keycloak/web';
    import Keycloak, { KeycloakConfig } from 'keycloak-js';
    import ReportPage from './components/ReportPage';
    
    const keycloakConfig: KeycloakConfig = {
      url: process.env.REACT_APP_KEYCLOAK_URL,
      realm: process.env.REACT_APP_KEYCLOAK_REALM||"",
      clientId: process.env.REACT_APP_KEYCLOAK_CLIENT_ID||""
    };
    
    const keycloak = new Keycloak(keycloakConfig);
    
    const App: React.FC = () => {
      return (
        <ReactKeycloakProvider authClient={keycloak}>
          <div className="App">
            <ReportPage />
          </div>
        </ReactKeycloakProvider>
      );
    };
    
    export default App;

Мы используем несколько библиотек для работы с запросами. Они инкапсулируют всю логику редиректов и получения данных из токенов.

Заготовка страницы с репортами

TSX

    import React, { useState } from 'react';
    import { useKeycloak } from '@react-keycloak/web';
    
    const ReportPage: React.FC = () => {
      const { keycloak, initialized } = useKeycloak();
      const [loading, setLoading] = useState(false);
      const [error, setError] = useState<string | null>(null);
        const downloadReport = async () => {
        if (!keycloak?.token) {
          setError('Not authenticated');
          return;
        }
    
        try {
          setLoading(true);
          setError(null);
    
          const response = await fetch(`${process.env.REACT_APP_API_URL}/reports`, {
            headers: {
              'Authorization': `Bearer ${keycloak.token}`
            }
          });
    
        } catch (err) {
          setError(err instanceof Error ? err.message : 'An error occurred');
        } finally {
          setLoading(false);
        }
      };
      if (!initialized) {
        return <div>Loading...</div>;
      }
    
      if (!keycloak.authenticated) {
        return (
          <div className="flex flex-col items-center justify-center min-h-screen bg-gray-100">
            <button
              onClick={() => keycloak.login()}
              className="px-4 py-2 bg-blue-500 text-white rounded hover:bg-blue-600"
            >
              Login
            </button>
          </div>
        );
      }
    
      return (
        <div className="flex flex-col items-center justify-center min-h-screen bg-gray-100">
          <div className="p-8 bg-white rounded-lg shadow-md">
            <h1 className="text-2xl font-bold mb-6">Usage Reports</h1>
            
            <button
              onClick={downloadReport}
              disabled={loading}
              className={`px-4 py-2 bg-blue-500 text-white rounded hover:bg-blue-600 ${
                loading ? 'opacity-50 cursor-not-allowed' : ''
              }`}
            >
              {loading ? 'Generating Report...' : 'Download Report'}
            </button>
    
            {error && (
              <div className="mt-4 p-4 bg-red-100 text-red-700 rounded">
                {error}
              </div>
            )}
          </div>
        </div>
      );
    };
    
    export default ReportPage;

Конечно, нужны package.json и правильная структура файлов.

Итог настройки

При запуске docker-compose файла поднимается три приложения:

Выводится простая страница:

Кликнув по кнопке «Login», вы перейдёте на страницу, где можете ввести логин и пароль одного из созданных пользователей.

Как видите, мы передаём id клиента и то, куда надо перейти после успешного логина.

Попробуйте ввести логин и пароль одного из пользователей.

Фронтенд обратился на Keycloak за токеном, используя в POST-запросе code, и получил на это ответ в виде JWT.

Если вы попробуете скачать репорт, то увидите, что он не скачивается, так как мы пока не настраивали API. Но теперь в запросе присутствует access token, который мы получили ранее.

Задание 2

Какие из перечисленных действий выполняются при использовании Authorization Code Flow для авторизации пользователя через Keycloak? Выберите все правильные ответы.

Фронтенд перенаправляет пользователя на SSO для ввода учётных данных

Authorization Code Flow предполагает, что пользователь сначала вводит свои учётные данные на стороне SSO: в данном случае через Keycloak.

Keycloak возвращает токен доступа сразу после перенаправления

Пользователь получает JWT, используя временный код

После успешного входа пользователь получает временный код, который фронтенд использует для запроса токена доступа, в частности JWT.

Данные пользователя передаются через WebSocket

После успешной авторизации пользователь перенаправляется обратно на фронтенд

При успешной авторизации Keycloak перенаправляет пользователя обратно на фронтенд, что является частью потока авторизации.

Задание 3

Какие из следующих шагов обязательны для создания работающего Realm в Keycloak? Выберите все правильные ответы.

Определение имени Realm

Имя Realm определяет его пространство конфигурации и является обязательным при его создании.

Создание базового пользователя и назначение ему роли

Создание пользователя и назначение роли позволяет управлять правами доступа и контролировать, кто и как взаимодействует с Realm.

Установка конфигурации HTTP-сервера для Realm

Определение ролей и привязка их к пользователям

Роли позволяют настраивать права доступа, и привязка их к пользователям является обязательной для создания Realm в рамках IAM.

Добавление OAuth-политики безопасности

Что почитать про системы управления аутентификацией и авторизацией

Итоги

Процесс аутентификации пользователя проходит через единую систему входа (SSO) с использованием Keycloak как провайдера аутентификации. Пользователь проходит следующий путь: заходит на фронтенд-приложение и, если не авторизован, видит кнопку «Логин». Нажав на неё, он перенаправляется на экран входа Keycloak для ввода учётных данных. После успешного входа Keycloak возвращает пользователя на фронтенд, где приложение обменивает временный код на токен для дальнейшего доступа к ресурсам.
Для декодирования токенов в Keycloak используются ключи шифрования, которые могут быть синхронными (используют один ключ для шифрования и дешифрования) или асинхронными (с использованием пары закрытого и открытого ключей). Выбор метода шифрования зависит от требований безопасности и сценариев использования.
Для развёртывания Keycloak используется файл docker-compose.yml. В нём задаются конфигурации сервиса, тип базы данных, учётные данные для подключения, порты и основные параметры для работы. Это позволяет быстро и централизованно управлять конфигурацией и запуском сервиса.
В сервисе выделена отдельная область, где можно создавать пользователей, роли и настраивать клиентов — Realm. Realm определяет политики паролей, а также настройки для подключения клиентов, которые обращаются к Keycloak для аутентификации и авторизации.
Keycloak позволяет настраивать Realms и через веб-интерфейс. Это упрощает процесс настройки, позволяя администратору визуально добавлять пользователей, определять роли и устанавливать параметры без необходимости редактировать конфигурационные файлы.

Выбор и настройка Identity and Access Management

Путь пользователя

Реализация Keycloak: практика

Шаг 1. Настройка базы данных

Шаг 2. Запуск Keycloak

Шаг 3. Создание Realm

Шаг 4. Определение ролей и пользователей

Шаг 5. Конфигурация клиентов

Настройка через интерфейс

Ключи

Шаг 6. Настройка клиента

Шаг 7. Настройка фронтенда

Итог настройки

Задание 1

Задание 2

Задание 3

Что почитать про системы управления аутентификацией и авторизацией

Итоги