Перейти к содержанию

Настройка подключения SAML SSO при использовании KeyCloak

Данная статья является примером базовой настройки SAML SSO подключения и может помочь начинающим специалистам.

Данная инструкция подходит для Enterprise версии. Протестировано на версии KeyCloak 23.0.4.

Предварительные условия

KeyCloak полностью настроен и функционирует, наполнена база пользователей.

Настройка подключения в GitFlic

Для настройки связи GitFlic и KeyCloak необходимо указать в настройках Админ-панели > Настройки SSO > SAML SSO > Создать (Редактировать) конфигурационные данные из вашего провайдера авторизации.

Metadata URL поставщика удостоверений можно найти в Realm Setting в разделе Endpoints.

Ссылка на Realm Setting

Для IssuerID поставщика удостоверений в KeyCloak следует использовать entityID. Его значение можно найти по эндпоинту из Metadata URL, в теге entityID. IssuerID представляет собой URL.

Значение для поля URL для входа через поставщик удостоверений со страницы авторизации GitFlic необходимо собрать исходя из вашей конфигурации KeyCloak. Поставщик удостоверений предлагает следующую форму получения URL для входа: {server-root}/realms/{realm}/protocol/saml/clients/{client-url-name}, где:

  • {server-root} - базовый URL KeyCloak;
  • {realm} - название окружения (указан в селекторе меню);
  • {client-url-name} - значение, указанное в поле в настройках клиента.

Настройка подключения в KeyCloak

Для работы кнопки входа со страницы авторизации GitFlic, необходимо заполнить поле IDP-Initiated SSO URL name, указав название для ссылки входа через KeyCloak.

В созданном Client для работы с GitFlic необходимо сопоставить атрибуты для корректной работы подключения. Для этого перейдите на вкладку "Client scopes" и в таблице перейдите в mapper конфигуратор, соответствующий подключению в GitFlic. Далее необходимо создать Add mapper > By configuration > User Property или отредактировать существующие mapper. Атрибуты, которые требуются для сопоставления с GitFlic совпадают по наименованию с SAML Attribute Name KeyCloak. Поля Name, Property, Friendly Name, SAML Attribute Name можно заполнять значением требуемого атрибута.

Ниже перечислены все атрибуты, которые принимает GitFlic:

  • nameID — сопоставляется через предопределенный маппер Add mapper > By predefined mapper > nameID (обязательный, уникальный)
  • email — email пользователя (обязательный, уникальный)
  • username — username пользователя (обязательный, уникальный)
  • firstname — Имя пользователя (необязательно)
  • surname — Фамилия пользователя (необязательно)
  • company — Компания пользователя (необязательно)

Добавление сертификатов для подписи запросов

Для настройки подключения с подписанием запросов необходимо загрузить из настройки подключения сертификат и провести с ним ряд преобразований для последующего использования. Конечной целью преобразований является сохранение отпечатка ключа в настройках подключения SAML в GitFlic.

Настройки расшифровки ответа SAML

В настройках клиента KeyCloak необходимо экспортировать приватный ключ в формате .jks, зафиксируйте все дополнительные данные при его экспорте

Далее требуется перевести экспортированный ключ к формату .pem через промежуточный формат .p12. Для этого необходимо использовать следующие команды (более подробно о конвертации можно прочитать тут):

Конвертация ключа к формату .p12

keytool -importkeystore -srckeystore keystore.jks \
   -destkeystore keystore.p12 \
   -srcstoretype jks \
   -deststoretype pkcs12

Конвертация ключа к формату .pem

openssl pkcs12 -in keystore.p12 -out keystore.pem

Чтение ключа в формате .pem

cat path/to/keystore.pem

После этого необходимо скопировать приватный ключ и использовать его в GitFlic. Укажите в соответствующем поле пароль от данного ключа и сохраните настройки.