1. Введение
В этой статье мы начнем с краткого обзора OAuth 2.0, OpenID и Keycloak. После этого мы узнаем об API-интерфейсах Keycloak REST и о том, как их вызывать в Postman.
2. ОАут 2.0
OAuth 2.0 — это структура авторизации, которая позволяет аутентифицированному пользователю предоставлять доступ третьим лицам с помощью токенов. Маркер обычно ограничен некоторыми областями с ограниченным временем жизни. Следовательно, это безопасная альтернатива учетным данным пользователя.
OAuth 2.0 состоит из четырех основных компонентов:
- Владелец ресурса — конечный пользователь или система, владеющая защищенным ресурсом или данными.
- Сервер ресурсов — служба предоставляет защищенный ресурс, как правило, через API на основе HTTP.
- Клиент — вызывает защищенный ресурс от имени владельца ресурса.
- Сервер авторизации — выдает токен OAuth 2.0 и доставляет его клиенту после аутентификации владельца ресурса.
OAuth 2.0 — это протокол с некоторыми стандартными потоками , но здесь нас особенно интересует компонент сервера авторизации.
3. Подключить OpenID
OpenID Connect 1.0 (OIDC) построен на основе OAuth 2.0, чтобы добавить в протокол уровень управления идентификацией. Следовательно, это позволяет клиентам проверять личность конечного пользователя и получать доступ к базовой информации профиля через стандартный поток OAuth 2.0. OAuth 2.0 представила несколько стандартных областей действия , таких как openid , профиль и электронная почта .
4. Keycloak как сервер авторизации
Компания JBoss разработала Keycloak как решение для управления идентификацией и доступом с открытым исходным кодом на основе Java. Помимо поддержки как OAuth 2.0, так и OIDC, он также предлагает такие функции, как посредничество в идентификации, объединение пользователей и единый вход.
Мы можем использовать Keycloak как автономный сервер с консолью администратора или встроить его в приложение Spring . Как только наш Keycloak заработает любым из этих способов, мы можем попробовать конечные точки.
5. Конечные точки Keycloak
Keycloak предоставляет множество конечных точек REST для потоков OAuth 2.0.
Чтобы использовать эти конечные точки с Postman , давайте начнем с создания среды под названием « Keycloak ». Затем мы добавляем несколько записей типа ключ/значение для URL-адреса сервера авторизации Keycloak, области, идентификатора клиента OAuth 2.0 и пароля клиента:
Затем давайте создадим коллекцию, в которой мы сможем организовать наши тесты Keycloak. Теперь мы готовы изучить доступные конечные точки.
5.1. Конечная точка конфигурации OpenID
Конечная точка конфигурации аналогична корневому каталогу. Он возвращает все другие доступные конечные точки, поддерживаемые области действия и утверждения, а также алгоритмы подписи .
Создадим запрос в Postman: {{server}} /auth/realms/ {{realm}} /.well-known/openid-configuration. Почтальон устанавливает значения {{server}} и {{realm}} из выбранной среды во время выполнения:
Затем мы выполняем запрос, и если все идет хорошо, мы получаем ответ:
{
"issuer": "http://localhost:8083/auth/realms/foreach",
"authorization_endpoint": "http://localhost:8083/auth/realms/foreach/protocol/openid-connect/auth",
"token_endpoint": "http://localhost:8083/auth/realms/foreach/protocol/openid-connect/token",
"token_introspection_endpoint": "http://localhost:8083/auth/realms/foreach/protocol/openid-connect/token/introspect",
"userinfo_endpoint": "http://localhost:8083/auth/realms/foreach/protocol/openid-connect/userinfo",
"end_session_endpoint": "http://localhost:8083/auth/realms/foreach/protocol/openid-connect/logout",
"jwks_uri": "http://localhost:8083/auth/realms/foreach/protocol/openid-connect/certs",
"check_session_iframe": "http://localhost:8083/auth/realms/foreach/protocol/openid-connect/login-status-iframe.html",
"grant_types_supported": [...],
...
"registration_endpoint": "http://localhost:8083/auth/realms/foreach/clients-registrations/openid-connect",
...
"introspection_endpoint": "http://localhost:8083/auth/realms/foreach/protocol/openid-connect/token/introspect"
}
Как упоминалось ранее, мы можем увидеть в ответе все доступные конечные точки — например, « authorization_endpoint », « token_endpoint » и так далее.
Кроме того, в ответе есть и другие полезные атрибуты. Например, мы можем определить все поддерживаемые типы грантов из « grant_types_supported » или все поддерживаемые области действия из « scopes_supported ».
5.2. Авторизовать конечную точку
Давайте продолжим наше путешествие с конечной точкой авторизации, отвечающей за поток кода авторизации OAuth 2.0 . Он доступен как «authorization_endpoint» в ответе конфигурации OpenID.
Конечная точка:
{{server}} /auth/realms/ {{realm}} /protocol/openid-connect/auth?response_type=code&client_id=jwtClient
Кроме того, эта конечная точка принимает область видимости и redirect_uri в качестве необязательных параметров.
Мы не собираемся использовать эту конечную точку в Postman. Вместо этого мы обычно инициируем поток кода авторизации через браузер. Затем Keycloak перенаправляет пользователя на страницу входа, если активный файл cookie для входа отсутствует. Наконец, код авторизации доставляется на URL-адрес перенаправления.
Давайте перейдем к следующему шагу, чтобы увидеть, как мы можем получить токен доступа.
5.3. Конечная точка токена
Конечная точка токена позволяет нам получить токен доступа, токен обновления или токен идентификатора. OAuth 2.0 поддерживает различные типы грантов, такие как author_code , refresh_token или пароль.
Конечная точка токена: {{server}} /auth/realms/ {{realm}} /protocol/openid-connect/token
Однако для каждого типа гранта требуются определенные параметры формы.
Давайте сначала проверим конечную точку нашего токена, чтобы получить токен доступа для нашего кода авторизации. Мы должны передать эти параметры формы в теле запроса: client_id , client_secret , grant_type , code и redirect_uri . Конечная точка маркера также принимает область действия в качестве необязательного параметра:
Более того, если мы хотим обойти поток кода авторизации, выбор типа предоставления пароля — это выбор . Здесь нам нужны учетные данные пользователя, поэтому мы можем использовать этот поток, когда у нас есть встроенная страница входа на наш веб-сайт или в приложение. ``
Давайте создадим запрос Postman и передадим в теле параметры формы client_id , client_secret , grant_type , username и password :
Перед выполнением этого запроса мы должны добавить переменные имени пользователя и пароля в пары ключ/значение среды Postman.
Еще один полезный тип гранта — refresh_token . Мы можем использовать это, когда у нас есть действительный токен обновления из предыдущего вызова конечной точки токена. Для потока токена обновления требуются параметры client_id , client_secret , grant_type и refresh_token .
Нам нужен ответ access_token для тестирования других конечных точек. Чтобы ускорить наше тестирование с помощью Postman, мы можем написать скрипт в разделе « Тесты » наших запросов к конечной точке токена:
var jsonData = JSON.parse(responseBody);
postman.setEnvironmentVariable("refresh_token", jsonData.refresh_token);
postman.setEnvironmentVariable("access_token", jsonData.access_token);
5.4. Конечная точка информации о пользователе
Мы можем получить данные профиля пользователя из конечной точки информации о пользователе, когда у нас есть действительный токен доступа.
Конечная точка информации о пользователе доступна по адресу: {{server}} /auth/realms/ {{realm}} /protocol/openid-connect/userinfo
Создадим для него запрос Postman и передадим токен доступа в заголовке Authorization :
Затем выполняем запрос. Вот успешный ответ:
{
"sub": "a5461470-33eb-4b2d-82d4-b0484e96ad7f",
"preferred_username": "john@test.com",
"DOB": "1984-07-01",
"organization": "foreach"
}
5.5. Токен Introspect Endpoint
Если ресурсному серверу необходимо убедиться, что токен доступа активен, или ему нужны дополнительные метаданные о нем, особенно для непрозрачных токенов доступа , то конечная точка самоанализа токена является ответом. В этом случае сервер ресурсов интегрирует процесс самоанализа с конфигурацией безопасности .
Мы вызываем конечную точку Keycloak для самоанализа: {{server}} /auth/realms/ {{realm}} /protocol/openid-connect/token/introspect
Давайте создадим запрос интроспекции в Postman, а затем передадим client_id , client_secret и токен в качестве параметров формы:
Если access_token действителен, у нас есть ответ:
{
"exp": 1601824811,
"iat": 1601824511,
"jti": "d5a4831d-7236-4686-a17b-784cd8b5805d",
"iss": "http://localhost:8083/auth/realms/foreach",
"sub": "a5461470-33eb-4b2d-82d4-b0484e96ad7f",
"typ": "Bearer",
"azp": "jwtClient",
"session_state": "96030af2-1e48-4243-ba0b-dd4980c6e8fd",
"preferred_username": "john@test.com",
"email_verified": false,
"acr": "1",
"scope": "profile email read",
"DOB": "1984-07-01",
"organization": "foreach",
"client_id": "jwtClient",
"username": "john@test.com",
"active": true
}
Однако, если мы используем недопустимый токен доступа, ответ будет таким:
{
"active": false
}
6. Заключение
В этой статье с работающим сервером Keycloak мы создали запросы Postman для авторизации, токена, информации о пользователе и конечных точек самоанализа.
Полные примеры запросов Postman, как всегда, доступны на GitHub .