Описание запросов

0. Конфигурация OIDC (.well-known)

Формат запроса

Для клиентов, которые поддерживают конфигурацию SSO по стандарту OpenID Connect через `.well-known` адрес, данный способ является приоритетным.

GET https://id.itmo.ru/auth/realms/itmo/.well-known/openid-configuration

1. Получение кода авторизации

Формат запроса

GET https://id.itmo.ru/auth/realms/itmo/protocol/openid-connect/auth

Параметры запроса

Параметр	Значение	Описание
client_id*	${client_id}	Идентификатор клиента
response_type*	code	Запрашиваемый тип ответа
redirect_uri*	${redirect_uri}	URL, на который будет переадресован пользователь в случае успешной авторизации. Должен соответствовать указанному на сервере регулярному выражению для данного клиента
scope	"openid profile email"	Список разрешений, которые требуются Клиенту для работы, такие как доступ к данным или выполнение определенных действий.

* – обязательные поля

В случае, если вам в дальнейшем необходимо получение данных каких-либо данных пользователя, передача scope `openid` обязательна

Опционально возможно передать дополнительные параметры, необходимые вашему приложению. Данные параметры вернутся в качестве параметров запроса при переадресации.

Ответ

После авторизации пользователь будет переадресован на страницу, указанную в {redirect_uri}. Если при авторизации указывались дополнительные параметры (например, state), они будут переданы вместе с кодом авторизации

${redirect_uri}?code=${code}

2. Получение Access Token

Формат запроса

POST https://id.itmo.ru/auth/realms/itmo/protocol/openid-connect/token

Параметры запроса

Параметры передаются в виде application/x-www-form-urlencoded

Параметр	Значение	Описание
client_id*	${client_id}	Идентификатор клиента
client_secret	${client_secret}	Секретный идентификатор клиента (используется в зависимости от настроек клиента)
grant_type*	authorization_code	Запрашиваемый тип ответа
redirect_uri*	${redirect_uri}	URL, который указывался при получении кода авторизации
code*	${code}	Код авторизации, полученный в запросе 1

* – обязательные поля

Ответ

Ответ на запрос представляет собой объект JSON, содержащий следующие параметры

Поле	Описание
access_token	Токен пользователя
expires_in	Время жизни Access Token в секундах
refresh_token	Токен для обновления Access Token
refresh_expires_in	Время жизни Refresh Token в секундах
id_token*	Токен, содержащий в себе информацию о пользователе (см. получение информации о пользователе из id_token)
token_type	Тип полученного Access Token
session_state	Идентификатор сессии SSO
scope	Выданные разрешения для клиента
not-before-policy	Метка времени, обозначающая, что если токен выписан раньше этого времени, он считается скомпрометированным

* id_token возвращается только в случае, если при авторизации (запрос 1) был передан scope "openid"

Пример ответа

{
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJwT1JJTXJmdXBiZllqdlVOcmNDSHJrOGVkeDd0aWhrTjF3ODJlWjFnLXNzIn0.eyJleHAiOjE2MjU4NTc2NjQsImlhdCI6MTYyNTg1NzYwNCwianRpIjoiN2I2NjE1YTQtOGZlMi00OGVjLTliMzktMDllNWE0ZTJlYjg3IiwiaXNzIjoiaHR0cHM6Ly9sb2dpbi5pdG1vLnN1L2F1dGgvcmVhbG1zL21hc3RlciIsImF1ZCI6bOvgekT710jMFOJQ5NdyMvXx3ECHDsvtm97_4fqJbyLABtHLbOJnATdhLFrbP8pWymgHgvNpJFIPh_MEnI_MFZGA-EJ31Z9U4U0gtovxUEeugMvvfC_oazmR0oVbnbl0MpgqfUuiVmewtIZp8fzGHaJgXeHwlf0iZsOE8rq9F3WPJSkMVwIB0nXjkppLGVSfGPotyvLcgIjG7Y36Rf15m0rkzwmNdVFoKfwf_glbPbZvCXz5Pq8p9_Dg",
    "expires_in": 60,
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJmNWNiN2Y4My1hNTc1LTRmMzQtYjg0ZC04NWViNjU3MDE0YmMifQ.eyJleHAiOjE2MjU4NTk0MDQsImlhdCI6MTYyNTg1NzYwNCwianRpIjoiZWU4YjRmNDQtZmMb2xlIiwic2Vzc2lvbl9zdGF0ZSI6IjkyOTAyZmUyLWU3M2YtNDNkZC04MzAzLTE4ZGU3NzdkNWFkNyIsInNjb3BlIjoiZW1haWwgcHJvZmlsZSJ9.mT0XtQJnHSqWsi0En-8JY_TInH1JqEeP6pMyYG9QlDs",
    "refresh_expires_in": 1800,
    "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICIwSVliSmNVLW1wbEdBdzhFMzNSNkNKTUdWa3hZdUQ2eUItdWt3RlBJOXV3In0.eyJleHAiOjE2NDIwNzYyNTAsImlhdCI6MTY0MjA3NDQ1MCwiYXV0aF90aW1lIjowLCJqdGkiOiJiODZjNmFlNJRCIsImF2JlNjczNzZlY2M0OTU4MmUvIn0.a18AVlXsueggk17oju0iO9g-QNdtVANdP8y_C4PQlV8_bGHQ3lwU1SokeXj0Qr_Zm7Z9dJ3v5GHKDFm3iS3ujlPvpdWuQSZhct9tayhUPw6IXMA_l0U5usnB5FgNKU-v9gkkY9gBfowcyNpCx4S8fg8Sp00nunKoC3hxAGep81eYFp1AUsBRI3j82tJs5SrwlkDfno3phNEVbjS8H8jp6QSxa6WbpbB3teQlttOOqdo5oFNY__dm3QQCf4rnmuZst_rBdRN1_iYFepjEeXj7Ynw_5FOxddQTgO_CTm5kH-WpwLWRjCit2idQFyJjo9JrkZL31tdQ1DCP0yNq2Dn_zQ",
    "token_type": "Bearer",
    "session_state": "92902fe2-e73f-43dd-8303-18de777d5ad7",
    "scope": "email profile",
    "not-before-policy": 0
}

Примечание

В случае, если при авторизации был передан scope "profile", в теле Access Token будет содержаться поле isu.

3a. Получение информации о пользователе по эндпоинту

Формат запроса

GET https://id.itmo.ru/auth/realms/itmo/protocol/openid-connect/userinfo
Header: Authorization=Bearer ${access_token}

Ответ

Ответ на запрос представляет собой объект JSON, который по умолчанию содержит параметры, соответствующие указанным при авторизации scope. В случае, если у пользователя нет значения определенного параметра, поле в объекте json может отсутствовать.

Пример ответа

{
  "sub": "3eae6b67-bc18-4f96-98e8-aea3425ff901",
  "zoneinfo": "Europe/Moscow",
  "gender": "male",
  "name": "Иван Иванов",
  "isu": 123456,
  "preferred_username": "exampleuser",
  "locale": "ru",
  "given_name": "Иван",
  "middle_name": "Иванович",
  "family_name": "Иванов",
  "picture": "https://example.com/photo",
  "email": "email@example.com",
  "email_verified": true,
  "corp_email": "example@itmo.ru"
}

3b. Получение информации о пользователе из ID Token

данный метод требует проверки подписи токенов

ID Token представляет собой JWT-токен, содержащий в себе информацию о пользователе. Данный способ позволяет получать информацию о пользователе в момент авторизации без дополнительных запросов по API.

Описание полей токена

Ответ на запрос представляет собой объект JSON, который по умолчанию содержит следующие параметры. В случае, если у пользователя нет значения определенного параметра, параметр может отсутствовать.

Пример

{
  "sub": "3eae6b67-bc18-4f96-98e8-aea3425f901",
  "zoneinfo": "Europe/Moscow",
  "gender": "male",
  "name": "Иван Иванов",
  "isu": 123456,
  "preferred_username": "exampleuser",
  "locale": "ru",
  "given_name": "Иван",
  "middle_name": "Иванович",
  "family_name": "Иванов",
  "picture": "https://example.com/photo",
  "email": "email@example.com",
  "email_verified": true,
  "corp_email": "example@itmo.ru"
}

4. Выход из SSO

Формат запроса

GET https://id.itmo.ru/auth/realms/itmo/protocol/openid-connect/logout

Параметры запроса

Параметр	Значение	Описание
client_id	${client_id}	Идентификатор клиента
post_logout_redirect_uri*	${post_logout_redirect_uri}	URL, на который будет переадресован пользователь после выхода из системы

* – обязательные поля

Ответ

После выхода из системы пользователь будет переадресован на страницу, указанную в ${post_logout_redirect_uri}.

5. Получение публичных ключей

Формат запроса

GET https://id.itmo.ru/auth/realms/itmo/protocol/openid-connect/certs

Ответ

Ответ на запрос представляет собой объект JSON, содержащий следующие параметры

Поле	Описание
keys	Массив активных ключей
keys.kid	Идентификатор ключа
keys.kty	Тип ключа (семейство алгоритмов шифрования ключа)
keys.alg	Алгоритм, который используется данным ключом
keys.use	Область применения ключа (`sig` – подпись, `enc` – шифрование)

Пример ответа

{
  "keys": [
    {
      "kid": "BZJy3x3RRGRwRW0WSRcipPOLCxFDvOTTmlgj1zW9ucQ",
      "kty": "RSA",
      "alg": "RS256",
      "use": "sig",
      "n": "74L9vMaiOha0ivyVHfHNUJG-RANNcAIUrIUCOXOSp9fN8kfKr1rACsnsHClpRpA3ZYBHkYSK7b-TxnUZHGfdD59WqFI4XuU33YrZ5Nj3omBBxXk3hpBFKh0mBbCvful0TCbjHxPH0yYPs89qqzkn6aM2sN1I31XRVMmy14BWybLG6MB1gIrCuQrygVXmZM6_IPWAHylHnE6nM5nJ5FUpVOvLQgzpZnCVCmCOBZhcL1Uqw8OxkKJda9jq5vPov41lHNXw1riLXwvNRihH0c36LjD96dyri_s5vdv44qzMsUOvklo3UWs-eezM0okwkyMq1L2wAvdTifmtYHUcK28NSQ",
      "e": "AQAB",
      "x5c": [
    "MIIClzCCAX8CBgF3HENMJDANBgkqhkiG9w0BAQsFADAPMQ0wCwYDVQQDDARpdG1vMB4XDTIxMDExOTIwMDY0OFoXDTMxMDExOTIwMDgyOFowDzENMAsGA1UEAwwEaXRtbzCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAO+C/bzGojoWtIr8lR3xzVCRvkQDTXACFKyFAjlzkqfXzfJHyq9awArJ7BwpaUaQN2WAR5GEiu2/k8Z1GRxn3Q+fVqhSOF7lN92K2eTY96JgQcV5N4aQRSodJgWwr37pdEwm4x8Tx9MmD7PPaqs5J+mjNrDdSN9V0VTJsteAVsmyxujAdYCKwrkK8oFV5mTOvyD1gB8pR5xOpzOZyeRVKVTry0IM6WZwlQpgjgWYXC9VKsPDsZCiXWvY6ubz6L+NZRzV8Na4i18LzUYoR9HN+i4w/encq4v7Ob3b+OKszLFDr5JaN1FrPnnszNKJMJMjKtS9sAL3U4n5rWB1HCtvDUkCAwEAATANBgkqhkiG9w0BAQsFAAOCAQEAjjzSQnK1gaDOoiDEDh1/pVsYWvQCD9I/hKNgKoIuvWNzdAE7u/AJxhVZgus7sGJiHpEls51NKlDi0Vu7EJNxRC1cZq1c5X/7rFZbSYC8siH8QOgli2DBvoiq8oHXS/Qw9U9CKEm6W3dShRM5BcBJtDk4rIH5VapAttCxlP29P4V+t5UzFJXgbRFBm/jdt3c5WQNpfbCONZtdW1bz0QTPldrJHjOVNziaQ+3Rkk6C/7nHfM8eYlZefRlnaCzZdlImU5PKFCVBGp4lbsIPZz/Ne+FP4VTNe5EMX5BIGmydoMcuju+OnZqJ5hL4U59slqZISY0cWNvuE+dwGE4PcenBCg=="
      ],
      "x5t": "bwP0J5CaPkhzf_sptc4jMSSQXHU",
      "x5t#S256": "jHjSvbOsmLzHeN70cD946e6__ks2YpU3PSUukPRadwQ"
    }
  ]
}