Интеграция с OpenId Connect

В YouGile встроена возможность использовать OpenId Connect для аутентификации пользователей, например, можно реализовать вход в систему пользователей через KeyCloak и другие сервисы, позволяющие настроить SSO через OpenId Connect. Пользователи при этом будут входить в аккаунт YouGile по кнопке, которая будет переводить пользователя на страницу аутентификации OpenId провайдера и после успешной аутентификации перенаправит пользователя в YouGile.

При этом можно выбрать 2 варианта для входа пользователей:

• использовать только OpenId для входа
• наряду с OpenId использовать вход через логин и пароль для пользователей, которые добавляются отдельно через интерфейс приглашения пользователей или через команды на сервере

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

Когда пользователь входит первый раз, то автоматически создаётся его учётная запись в YouGile с именем и фамилией и email, которые предоставляются через OpenId (используются поля family_name, given_name и email, обычно эти поля доступны из скоупов openid и email, обязательным является email для создания учётной записи) и эта учётная запись автоматически добавляется в основную компанию (та компания в YouGile, которая была создана первой).

Если сессия OpenId истекла или была удалена вручную администратором, то пользователя разлогинит из YouGile. Также если пользователь будет удалён из OpenId или изменятся условия, по которым ограничивается вход (напр. участие в группе), то пользователя также разлогинит. Сама учётная запись в YouGile при этом не удаляется, в неё нельзя войти, но она сохраняется – это делается специально, чтобы можно было после удаления пользователя найти его задачи и переназначить, а также восстановить его при необходимости. Чтобы удалить ненужных пользователей, можно использовать команду remove-user, см. Специальные команды YouGile.

Пример настройки интеграции

Необходимо создать Client в OpenId провайдере и получить id клиента и секрет клиента.

Далее нужно в conf.json добавить настройки интеграции, пример:

{
  // стандартные настройки
  "port": 8001,
  "mainPageUrl": "https://yougile.mysite.org",
  // ...

  // настройки интеграции с OpenId
  "openId": {
    "issuer": "https://keycloak.mysite.org/realms/Yougile",
    "signInButtonText": "Войти через OpenId",

    "allowOnlyOpenId": true,

    "config": {
      "client_id": "yougile-oidc",
      "client_secret": "2OT0XXzffAbPINZVk0An49AM8uQwcTyG"
    },
    "scope": "openid email my-custom-scope",

    // дополнительные параметры, нужны не всегда

    "filterUser": "user.myvalue?.includes('/yg-members')",
    "tokenTtl": 60000
  }
}

В этом примере:

• issuer – адрес OpenId провайдера, который будет использоваться для аутентификации пользователей. Пример для keycloak: https://kc.my_site.org/realms/MyRealm
• signInButtonText – текст кнопки входа в систему пользователей YouGile.
• allowOnlyOpenId – разрешить вход в YouGile только через OpenId провайдер, войти через login/пароль становится невозможно, даже для зарегистрированных пользователей, если этот парамерт false, то можно входить обоими способами.
• client_id и client_secret – id и секрет клиента в OpenId провайдере.
• scope – набор scope-ов, которые предоставляются YouGile при аутентификации. openid и email – обязательные scope-ы, они нужны для создания учётной записи в YouGile, также можно добавить дополнительные scope-ы и использовать их для ограничения входа (напр. по группе пользователя) через фильтр filterUser.
• filterUser – если не указывать этот параметр, то все пользователи, которые есть в OpenId провайдере, смогут войти в YouGile. В этом параметре можно указать javascript-выражение, которое может использовать переменную user, в которой находятся данные, предоставляемые о пользователе OpenId (согласно scope-ам), см. также ниже «Частые вопросы по настройке».
• tokenTtl – время жизни токена в миллисекундах, если не указывать этот параметр, то при каждом запросе YouGile будет обращаться в OpenId провайдер с access_token (или refresh_token), в случае, когда пользователей много – это может негативно влиять на производительность провайдера и тогда рекомендуется указать этот параметр. Если параметр указан, то, например, в случае удаления сессии пользователя в OpenId провайдере, он не сразу будет разлогинен в YouGile, а через некоторое время (примерно, равное tokenTtl).

Частые вопросы по настройке

• чтобы изменения в conf.json применились, необходимо перезапустить сервис YouGile.
• если для шифрования используется самоподписанный сертификат или сертификат, подписанный своим центром сертификации, то нужно использовать NODE_EXTRA_CA_CERTS=путь_к_сертификату – в качестве переменной окружения при запуске YouGile. На время настройки и отладки можно использовать переменную окружения NODE_TLS_REJECT_UNAUTHORIZED=0, чтобы убрать ошибки с сертификатами, но при переходе на боевой режим этот вариант использовать нельзя.
• если возникают проблемы с использованием filterUser, напр. мы хотим, чтобы могли входить только пользователи с email-ом из домена mycompany.com, и мы пытаемся указать это в filterUser: user.email.includes('@mycompany.com'), но это не работает как надо, тогда можно указать выражение, которое будет также логировать значение user или какие-то выражения для отладки фильра, например: console.log(user) || user.email.includes('@mycompany.com'), чтобы понять причину неправильной работы.
• чтобы добавить информацию о группе пользователя в keycloak, необходимо в нужном realm добавить в Client scopes (Create client scope), затем перейти в добавленный scope, во вкладке Mappers добавить mapper, выбрав далее By configuration и выбрать Group Membership, причём, необходимо обязательно указать Token claim name – это имя будет доступно в объекте user в filterUser. После этого, необходимо перейти в Clients, выбрать нужного клиента и перейти во вкладку Client scopes и добавить созданный scope. Если пользователя нет ни в одной группе, то поле с группами будет отсутствовать, поэтому filterUser лучше указывать таким образом: user.my_group_claim_name?.includes('/yougile-users')

Дополнительная интеграция с SSO провайдерами

Это более старый вариант интеграции, рекомендованный вариант описан выше.

Этот вариант интеграции с OpenId Connect работает по схожей механике, что и интеграция с ActiveDirectory – система сразу создаёт все учётные записи, которые может получить от OpenId провайдера и поддерживает этот список в актуальном состоянии, при этом вход производится по логину и паролю, которые проверяются OpenId провайдером (напр. KeyCloak).

• Для активации провайдера нужно заполнить его параметры в conf.json, а также указать название провайдера в параметре provider
• URL для параметров tokenUrl и userInfoUrl вы можете найти в документации вашего SSO провайдера

Настройка интеграции

• Для настройки интеграции необходимо добавить в файл conf.json следующий блок

    "init": {
    "scripts": [
      "auth/auth-sync-oidc.js",
      "auth/check-sync-oidc.js"
    ],
    "auth": "auth/auth-oidc.js"
  },
  "provider": "sso-provider-name",
  "sso-provider-name": {
    "serverUrl": "sso-server-url",
    "realm": "your-realm",
    "clientId": "your-client-id",
    "credentials": {
      "secret": "your-secret"
    ,
    "tokenUrl": "sso-server-get-token-url",
    "userInfoUrl": "sso-server-get-user-info-url",
    "publicKey": "your-public-key"
  },

Пример настройки для Keycloak

• В настройках клиента в keycloak нужно включить Client authentication и Service accounts roles
• В разделе "Credentials" в "Client Authenticator" следует выбрать "Client Id and Secret"
• publicKey можно найти в разделе "Realm settings" => "Keys". Необходимо взять ключ, имеющий тип RS256
• secret можно найти в настройках клиента в разделе "Clients" => "Client_name" => "Credentials" => поле "Client Secret"
• Для работы Keycloak необходимо выдать клиенту следующие дополнительные роли:
  • realm-management - query-users
  • realm-management - manage-users
  • realm-management - view-users
  • broker - read-token