Единый вход через OpenID Connect

CityScreen Deals может выступать провайдером идентификации для ваших других веб-приложений. Сотрудник, который открывает вики, дашборд или другое приложение с поддержкой OpenID Connect, входит с учётной записью CityScreen Deals, в том числе с двухэтапной проверкой, если она включена для учётной записи. Приложение получает данные сотрудника и, если запрашивает, группы, в которые он входит. Когда сотрудник выходит из CityScreen Deals, приложения, которые зарегистрировали адрес выхода, получают уведомление.

Эта функция лицензируется. Если лицензия вашей организации её не включает, обратитесь в CityScreen.

Подключение приложения

Клиент OpenID Connect — это OAuth-приложение с типом авторизации «код авторизации» и областью доступа openid. Форма регистрации и процесс описаны в разделе OAuth-приложения.

Откройте Сотрудники > OAuth-приложения и нажмите Копировать URL обнаружения. Адрес выглядит как https://deals.example.com/.well-known/openid-configuration.
Нажмите Создать приложение и зарегистрируйте приложение: выберите тип авторизации Код авторизации, введите адрес возврата, который другое приложение показывает в разделе Адреса возврата (redirect URI), и оставьте отмеченными Разрешённые области доступа (scopes) openid, profile, email и groups. Оставьте api неотмеченной, если приложению не нужно также вызывать REST API.
Скопируйте идентификатор клиента и секрет клиента из диалога «OAuth-приложение создано». Секрет показывается только один раз. Веб-приложение, которое работает на сервере, сохраняет значение по умолчанию и остаётся конфиденциальным клиентом. Отмечайте Публичный клиент (без секрета клиента) только для приложения, которое не может хранить секрет.
В другом приложении введите адрес обнаружения, идентификатор клиента и секрет клиента и запросите области доступа openid profile email groups.
При необходимости введите Адрес уведомления о выходе (back-channel logout URI) и Адреса возврата после выхода (post-logout redirect URI), см. Выход во всех приложениях.

Обнаружение

GET /.well-known/openid-configuration возвращает описание, которое читают клиентские библиотеки. GET /.well-known/oauth-authorization-server возвращает его часть, относящуюся к OAuth. Оба адреса публичные. Они отвечают 404 без лицензии и 503, если адрес вашей организации не является адресом https.

Член Значение

Член	Значение
`issuer`	Адрес вашей организации без завершающей косой черты.
`authorization_endpoint`, `token_endpoint`, `userinfo_endpoint`, `jwks_uri`, `end_session_endpoint`	`/oauth/authorize`, `/oauth/token`, `/oauth/userinfo`, `/oauth/jwks` и `/oauth/end-session` на этом адресе.
`registration_endpoint`, `revocation_endpoint`	`/oauth/register` и `/oauth/revoke`, см. OAuth-приложения.
`response_types_supported`	Только `code`.
`response_modes_supported`	Только `query`.
`authorization_response_iss_parameter_supported`	`true`: перенаправление содержит `iss`.
`grant_types_supported`	`authorization_code`, `refresh_token` и `client_credentials`.
`code_challenge_methods_supported`	`S256`.
`token_endpoint_auth_methods_supported`	`client_secret_basic`, `client_secret_post` и `none`.
`subject_types_supported`	`public`.
`id_token_signing_alg_values_supported`	`RS256`.
`scopes_supported`	`openid`, `profile`, `email`, `groups` и `api`.
`claims_supported`	`sub`, `iss`, `aud`, `azp`, `exp`, `iat`, `auth_time`, `nonce`, `at_hash`, `name`, `preferred_username`, `locale`, `email`, `groups` и `group_names`.
`backchannel_logout_supported`	`true`.

issuer

Адрес вашей организации без завершающей косой черты.

authorization_endpoint, token_endpoint, userinfo_endpoint, jwks_uri, end_session_endpoint

/oauth/authorize, /oauth/token, /oauth/userinfo, /oauth/jwks и /oauth/end-session на этом адресе.

registration_endpoint, revocation_endpoint

/oauth/register и /oauth/revoke, см. OAuth-приложения.

response_types_supported

Только code.

response_modes_supported

Только query.

authorization_response_iss_parameter_supported

true: перенаправление содержит iss.

grant_types_supported

authorization_code, refresh_token и client_credentials.

code_challenge_methods_supported

S256.

token_endpoint_auth_methods_supported

client_secret_basic, client_secret_post и none.

subject_types_supported

public.

id_token_signing_alg_values_supported

RS256.

scopes_supported

openid, profile, email, groups и api.

claims_supported

sub, iss, aud, azp, exp, iat, auth_time, nonce, at_hash, name, preferred_username, locale, email, groups и group_names.

backchannel_logout_supported

true.

Claims

Области доступа в запросе авторизации определяют, какие claims содержат ID-токен и UserInfo.

Область доступа Claims

Область доступа	Claims
всегда	`sub` — идентификатор сотрудника в CityScreen Deals. Он не меняется.
`profile`	`name`, `preferred_username` (имя пользователя сотрудника) и `locale`, если оно есть у учётной записи.
`email`	`email` — адрес электронной почты учётной записи.
`groups`	`groups` и `group_names`, см. ниже.

всегда

sub — идентификатор сотрудника в CityScreen Deals. Он не меняется.

profile

name, preferred_username (имя пользователя сотрудника) и locale, если оно есть у учётной записи.

email

email — адрес электронной почты учётной записи.

groups

groups и group_names, см. ниже.

С областью доступа groups claim groups перечисляет машинные имена групп сотрудника, а claim group_names — их названия в том же порядке. Группы отсортированы по машинному имени, и каждая группа встречается один раз. Сотрудник без групп получает два пустых списка. Claims перечисляют группы, в которые сотрудник входит напрямую. Claims читаются в момент выдачи токена, поэтому при обновлении токена подхватываются изменения названия, адреса электронной почты и групп.

Сопоставляйте группы с ролями в другом приложении по машинному имени, потому что машинное имя после создания группы никогда не меняется. Название группы можно изменить в любое время. См. Группы сотрудников.

ID-токен

ID-токен — это JWT, подписанный RS256, который содержит claims из OpenID Connect Core 1.0, раздел 2, а ключ указан в заголовке, в поле kid. sub — идентификатор сотрудника, а aud и azp — идентификатор клиента. Claims по областям доступа перечислены в разделе Claims.

ID-токен живёт столько же, сколько выданный вместе с ним токен доступа, см. OAuth-приложения. nonce и auth_time попадают в ID-токен только при обмене кода, а при обновлении токена их нет.

Приложение проверяет ID-токен так, как описывает раздел 3.1.3.7 стандарта, с ключами из jwks_uri.

UserInfo

GET или POST /oauth/userinfo с Authorization: Bearer <access token> возвращает те же claims, что и ID-токен, для областей доступа токена. Токен должен быть получен по схеме с кодом авторизации и содержать область доступа openid. Любой другой запрос, в том числе с персональным токеном доступа, токеном учётных данных клиента (client credentials), неизвестным или просроченным токеном, получает 401 invalid_token.

Ключи подписи

GET /oauth/jwks публикует открытые ключи, которыми проверяют ID-токены и токены выхода. Ответ можно кэшировать на один час, поэтому приложение запрашивает набор ключей заново, когда встречает неизвестный kid.

Администратор с правом «Смена ключа подписи» нажимает Сменить ключ подписи в Сотрудники > OAuth-приложения. С этого момента токены подписывает новый ключ, а предыдущий ключ остаётся опубликованным 24 часа, чтобы токены, подписанные им, по-прежнему проверялись. Ключ меняется только тогда, когда его меняет администратор.

Выход во всех приложениях

Уведомление о выходе (back-channel logout)

Приложение, которое зарегистрировало Адрес уведомления о выходе (back-channel logout URI), получает уведомление, когда сотрудник вышел из CityScreen Deals, и может завершить свою собственную сессию этого сотрудника. Адрес должен быть адресом https на публичном хосте. Для адреса внутри вашей сети обратитесь в CityScreen.

CityScreen Deals отправляет POST с полем формы logout_token — JWT, подписанным RS256:

в заголовке typ равен logout+jwt и указан kid ключа подписи;
claims — iss, sub (идентификатор сотрудника, как в ID-токене), aud (идентификатор клиента), iat, jti, events и exp, который наступает через 120 секунд после iat;
sid нет: приложение завершает все свои сессии сотрудника, названного в sub.

Ответ 2xx сообщает CityScreen Deals, что сообщение дошло.

CityScreen Deals отправляет сообщение о выходе каждому приложению, у которого есть адрес выхода и токен сотрудника, когда:

сотрудник выходит или завершает сессию;
администратор завершает сессии сотрудника;
пароль сотрудника сброшен или истёк и сессии завершаются;
смена пароля завершает сессии;
учётную запись деактивируют или удаляют;
сотрудник отзывает авторизацию приложения в разделе Аккаунт > Авторизации.

Сессия, которая просто истекла, сообщения не отправляет.

Доставка выполняется в фоне, чтобы недоступное приложение никогда не задерживало выход. Приложение отвечает в течение 5 секунд статусом 2xx, что считается доставкой. Перенаправление, по которому сервер не переходит, и ответ 4xx, кроме 408 и 429, прекращают доставку. Любой другой сбой повторяется в течение нескольких часов.

Результат показан в форме редактирования приложения в поле Последнее уведомление о выходе.

Выход по запросу приложения

Приложение может направить браузер сотрудника на GET или POST /oauth/end-session с такими параметрами:

Параметр Значение

Параметр	Значение
`id_token_hint`	ID-токен, выданный CityScreen Deals. Он мог истечь.
`client_id`	Идентификатор клиента. Он должен совпадать с аудиторией подсказки.
`post_logout_redirect_uri`	Один из Адресов возврата после выхода (post-logout redirect URI) приложения, символ в символ.
`state`	До 500 символов. Он добавляется к адресу перенаправления.

id_token_hint

ID-токен, выданный CityScreen Deals. Он мог истечь.

client_id

Идентификатор клиента. Он должен совпадать с аудиторией подсказки.

post_logout_redirect_uri

Один из Адресов возврата после выхода (post-logout redirect URI) приложения, символ в символ.

state

До 500 символов. Он добавляется к адресу перенаправления.

Для перенаправления обратно в приложение нужны client_id или id_token_hint, который указывает клиента, и зарегистрированный post_logout_redirect_uri.

Сначала сотрудник подтверждает выход. CityScreen Deals показывает страницу «{{application}} просит вас выйти из CityScreen Deals» с кнопками Выйти и Остаться в системе. Выйти завершает только сессию этого браузера и возвращает на адрес перенаправления, если в запросе он был. Другие приложения получают уведомление так же, как при любом другом выходе. Страница описана в разделе Вход и выход.

Запрос, которому нельзя доверять, никогда не возвращается в приложение. Сотрудник видит «Не удалось выполнить запрос на выход», а адрес этой страницы содержит один из кодов invalid_request, invalid_id_token_hint, client_mismatch или invalid_post_logout_redirect_uri.

Выход и токены приложений

Выход из CityScreen Deals завершает текущую сессию сотрудника, см. Вход и выход. Токены, которые сотрудник выдал приложениям, остаются действительными. Они заканчиваются, когда сотрудника деактивируют или когда он нажимает Отозвать в разделе Аккаунт > Авторизации.

Длительность сессии задаётся в Настройки > Общие, см. Политика паролей и защита входа.

Что видят администраторы

На странице сотрудника блок Сессии перечисляет Подключённые приложения: приложения, у которых есть токен сотрудника. Для каждого показаны «Последнее использование», «Уведомляется о выходе» и «Последнее уведомление». Подтверждение Завершить все сессии перечисляет приложения, которые получат уведомление. Для списка нужны право просматривать сотрудника и право «OAuth-приложения» Просмотр в области организации.

Пример: подключение универсального клиента OpenID Connect

Получите документ обнаружения, чтобы проверить адреса:

curl -s https://deals.example.com/.well-known/openid-configuration

Ответ начинается так (сокращённо):

{
  "issuer": "https://deals.example.com",
  "authorization_endpoint": "https://deals.example.com/oauth/authorize",
  "token_endpoint": "https://deals.example.com/oauth/token",
  "userinfo_endpoint": "https://deals.example.com/oauth/userinfo",
  "jwks_uri": "https://deals.example.com/oauth/jwks",
  "end_session_endpoint": "https://deals.example.com/oauth/end-session",
  "scopes_supported": ["openid", "profile", "email", "groups", "api"],
  "code_challenge_methods_supported": ["S256"]
}

Зарегистрируйте приложение в Сотрудники > OAuth-приложения с типом авторизации Код авторизации, адресом возврата https://wiki.example.com/callback и разрешёнными областями доступа openid, profile, email и groups. В диалоге показаны идентификатор клиента app_43 и секрет клиента. Затем введите эти значения в любом приложении с поддержкой OpenID Connect:

Параметр Значение

Параметр	Значение
Издатель или адрес обнаружения	`https://deals.example.com` или `https://deals.example.com/.well-known/openid-configuration`
Идентификатор клиента	`app_43`
Секрет клиента	Секрет из диалога.
Процесс	Код авторизации. Добавьте PKCE с `S256`, если приложение его поддерживает.
Аутентификация клиента	`client_secret_basic` или `client_secret_post`.
Адрес возврата	`https://wiki.example.com/callback`, записанный точно так, как зарегистрирован.
Области доступа	`openid profile email groups`
Claim имени пользователя	`preferred_username`
Claim электронной почты	`email`
Claim групп	`groups`. Сопоставьте машинные имена, например `sales-managers`, с ролями приложения.

Издатель или адрес обнаружения

https://deals.example.com или https://deals.example.com/.well-known/openid-configuration

Идентификатор клиента

app_43

Секрет клиента

Секрет из диалога.

Процесс

Код авторизации. Добавьте PKCE с S256, если приложение его поддерживает.

Аутентификация клиента

client_secret_basic или client_secret_post.

Адрес возврата

https://wiki.example.com/callback, записанный точно так, как зарегистрирован.

Области доступа

openid profile email groups

Claim имени пользователя

preferred_username

Claim электронной почты

email

Claim групп

groups. Сопоставьте машинные имена, например sales-managers, с ролями приложения.

Введите необязательный Адрес уведомления о выходе (back-channel logout URI), если приложение может завершить свою сессию по запросу.

Связанные страницы

OAuth-приложения — регистрация приложений, процессы, области доступа и срок действия токенов
Группы сотрудников — машинное имя, которое определяет группу в claim groups
Вход и выход — что делает выход и какую страницу выхода могут запросить приложения
Политика паролей и защита входа — длительность сессии и защита входа
Интеграции — все подключения к другим системам