TOC

Краткое руководство по использованию Keycloak с Spring Boot

Краткое руководство по использованию Keycloak с Spring Boot

1. обзор

В этой статье мы рассмотрим основы настройки сервера Keycloak, как подключить к немуconnect a Spring Boot application и как использовать его с Spring Security.

2. Что такое Keycloak?

Keycloak - это решение с открытым исходным кодом для управления идентификацией и доступом, ориентированное на современные приложения и услуги.

Keycloak предлагает такие функции, как единый вход (SSO), брокерская идентификация и социальный вход в систему, федерация пользователей, клиентские адаптеры, консоль администратора и консоль управления учетными записями. Чтобы узнать больше о Keycloak, посетитеofficial page.

В нашем руководстве мы будем использовать консоль администратора Keycloak для настройки и последующего подключения к Spring Boot с помощью клиентского адаптера Keycloak.

3. Настройка сервера Keycloak

3.1. Скачивание и установка Keycloak

На выбор есть несколько дистрибутивов.

Однако в этом руководстве мы будем использовать автономную версию.

ЗагрузитеKeycloak-3.3.0.Final Standalone server distribution из официального источника.

После того, как мы скачали дистрибутив Standalone server, мы можем распаковать и запустить Keycloak из терминала: 

unzip keycloak-3.3.0.Final.zip
cd keycloak-3.3.0.Final/bin
./standalone.sh -Djboss.socket.binding.port-offset=100

После запуска./standalone.sh Keycloak запустит свои службы. Как только мы увидим строку, содержащуюKeycloak 3.3.0.Final (WildFly Core 3.0.1.Final) start, мы будем знать, что ее запуск завершен.

Откройте браузер и зайдите наhttp://localhost:8180.. Мы будем перенаправлены наhttp://localhost:8180/auth, чтобы создать административный вход:

image

Давайте создадим пользователя с именем «initial1» с паролем «zaq1!QAZ».

Теперь мы видим «Welcome to Keycloak”:

image

Теперь мы можем перейти к административной консоли.

3.2. Создание Царства

Наведите указатель мыши на верхний левый верхний угол и найдите кнопку“Create a Realm”:

image

Назовем его «SpringBootKeycloak»:

image

3.3. Создание клиента

Теперь мы перейдем на страницу клиентов. Как видно на изображении ниже,Keycloak comes with Clients that are already built in:

image

Но нам нужно добавить клиента в наше приложение, поэтому мы нажимаем «Создать». Мы назовем нового Клиента «login-app«:.

image

На следующем экране этого руководства мы оставим все значения по умолчанию, кроме поля «Допустимые URI перенаправления». Мы будем перенаправлены на порт8081:

image

3.4. Создание роли и пользователя

Keycloak использует доступ на основе ролей. Следовательно, у каждого пользователя должна быть роль.

Нам нужно перейти на страницу «Роль»:

image

Затем мы добавляем роль «user»:

image

Теперь у нас есть роль, которую можно назначать пользователям, но пользователей пока нет. Итак, перейдем на страницу "Пользователи" и добавим ее:

image

Добавляем пользователя“user1”:

image

Как только пользователь будет создан, нам будет показана эта страница:

image

Теперь мы можем перейти на вкладку «Учетные данные». Мы будем устанавливать пароль «[email protected]”:

image

Перейдем на вкладку «Сопоставление ролей». Мы назначим пользователю роль:

image

3.5. Создание пользовательской страницы входа

Keycloak предоставляет REST API для генерации и обновления токенов доступа. Мы можем легко использовать этот API для создания собственной страницы входа.

Во-первых, нам нужно получить токен доступа от Keycloak, отправив запрос POST на этот URL: 

http://localhost:8180/auth/realms/master/protocol/openid-connect/token

Запрос должен иметь это тело JSON: 

{
    'client_id': 'your_client_id',
    'username': 'your_username',
    'password': 'your_password',
    'grant_type': 'password'
}

В ответ мы получимaccess_token иrefresh_token.

Маркер доступа следует использовать в каждом запросе к ресурсу, защищенному Keycloak, просто поместив его в заголовокAuthorization: 

headers: {
    'Authorization': 'Bearer' + access_token
}

После истечения срока действия токена доступа мы можем обновить его, отправив запрос POST по тому же URL-адресу, что и выше, но вместо имени пользователя и пароля содержит токен обновления: 

{
    'client_id': 'your_client_id',
    'refresh_token': refresh_token_from_previous_request,
    'grant_type': 'refresh_token'
}

Это ответит новымиaccess_token иrefresh_token.

4. Создание приложения Spring Boot

4.1. зависимости

Последние зависимости Spring Boot Keycloak Starter можно найти вon Maven Central.

The Keycloak Spring Boot adaptercapitalizes on Spring Boot’s auto-configuration, поэтому все, что нам нужно сделать, это добавить стартер Keycloak Spring Boot в наш проект.

В элементе XML зависимостей нам нужно следующее для запуска Keycloak с Spring Boot: 


    org.keycloak
    keycloak-spring-boot-starter

После XML-элемента зависимостей нам нужно указатьdependencyManagement для Keycloak: 


    
        
            org.keycloak.bom
            keycloak-adapter-bom
            3.3.0.Final
            pom
            import

Следующие встроенные контейнеры теперь поддерживаются и не требуют дополнительных зависимостей при использовании Spring Boot Keycloak Starter:

  • Кот

  • отлив прибоя

  • пристань

4.2. Веб-страницы Тимелеафа

Мы используем Thymeleaf для наших веб-страниц.

У нас есть три страницы:

  • external.html – внешняя веб-страница для общественности

  • customers.html - внутренняя страница, доступ к которой будет ограничен только аутентифицированными пользователями с ролью «пользователь».

  • layout.html - простой макет, состоящий из двух фрагментов, который используется как для внешней страницы, так и для внутренней.

Код для шаблонов Thymeleaf -available on Github.

4.3. контроллер

Веб-контроллер сопоставляет внутренние и внешние URL-адреса с соответствующими шаблонами Thymeleaf: 

@GetMapping(path = "/")
public String index() {
    return "external";
}

@GetMapping(path = "/customers")
public String customers(Model model) {
    addCustomers();
    model.addAttribute("customers", customerDAO.findAll());
    return "customers";
}

Для пути/customers мы получаем всех клиентов из репозитория и добавляем результат как атрибут вModel. Позже мы повторим результаты в Thymeleaf.

4.4. Конфигурация Keycloak

Вот основная обязательная конфигурация: 

keycloak.auth-server-url=http://localhost:8180/auth
keycloak.realm=SpringBootKeycloak
keycloak.resource=login-app
keycloak.public-client=true

Как мы помним, мы запустили Keycloak на порту8180, следовательно, путь указан вkeycloak.auth-server-url. Мы вводим имя области, которую создали в консоли администратора Keycloak.

Значение, которое мы указываем вkeycloak.resource, соответствует клиенту, который мы назвали в консоли администратора.

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

keycloak.security-constraints[0].authRoles[0]=user
keycloak.security-constraints[0].securityCollections[0].patterns[0]=/customers/*

Вышеупомянутое состояние ограничений безопасности гарантирует, что каждый запрос к/customers/* будет авторизован только в том случае, если тот, который его запрашивает, является аутентифицированным пользователем с ролью «пользователь».

4.5. демонстрация

Теперь мы готовы протестировать наше приложение. Чтобы запустить приложение Spring Boot, мы можем легко запустить его через IDE, такую ​​как Spring Tool Suite (STS), или запустить эту команду в терминале: 

mvn clean spring-boot:run

Мы посещаемlocalhost:8081:

image

Теперь мы нажимаем «customers», чтобы войти в интрасеть, где хранится конфиденциальная информация.

Мы видим, что мы были перенаправлены на аутентификацию через Keycloak, чтобы узнать, авторизованы ли мы для просмотра этого контента:

image

После аутентификации и проверки нашей авторизации Keycloak мы перенаправляемся на страницу клиентов с ограниченным доступом:

image

На этом мы закончили настройку подключения Spring Boot к Keycloak и продемонстрировали, как это работает.

Теперь мы рассмотрим, как использовать Spring Security вместе с нашим существующим приложением.

5. Spring Security

Есть адаптер безопасности Keycloak Spring, и этоalready included in our Spring Boot Keycloak Starter dependency. Теперь посмотрим, как интегрировать Spring Security с Keycloak.

5.1. зависимость

Чтобы использовать Spring Security с Spring Boot, мы должны добавить эту зависимость: 


    org.springframework.boot
    spring-boot-starter-security
    1.5.3

Последнюю версию Spring Boot Starter Security можно найтиon Maven Central.

5.2. Класс конфигурации

Keycloak предоставляетKeycloakWebSecurityConfigurerAdapter в качестве удобного базового класса для создания экземпляраWebSecurityConfigurer, что удобно, потому что класс конфигурации, расширяющийWebSecurityConfigurerAdapter, необходим для любого приложения, защищенного Spring Security: 

@Configuration
@EnableWebSecurity
@ComponentScan(basePackageClasses = KeycloakSecurityComponents.class)
class SecurityConfig extends KeycloakWebSecurityConfigurerAdapter {

    @Autowired
    public void configureGlobal(
      AuthenticationManagerBuilder auth) throws Exception {

        KeycloakAuthenticationProvider keycloakAuthenticationProvider
         = keycloakAuthenticationProvider();
        keycloakAuthenticationProvider.setGrantedAuthoritiesMapper(
          new SimpleAuthorityMapper());
        auth.authenticationProvider(keycloakAuthenticationProvider);
    }

    @Bean
    public KeycloakSpringBootConfigResolver KeycloakConfigResolver() {
        return new KeycloakSpringBootConfigResolver();
    }

    @Bean
    @Override
    protected SessionAuthenticationStrategy sessionAuthenticationStrategy() {
        return new RegisterSessionAuthenticationStrategy(
          new SessionRegistryImpl());
    }

    @Override
    protected void configure(HttpSecurity http) throws Exception {
        super.configure(http);
        http.authorizeRequests()
          .antMatchers("/customers*")
          .hasRole("user")
          .anyRequest()
          .permitAll();
    }
}

Пожалуйста, обратите внимание на код выше:

  • configureGlobal: поручаетSimpleAuthorityMapper убедиться, что роли не имеют префиксаROLE_

  • keycloakConfigResolver: это определяет, что мы хотим использовать поддержку файла свойств Spring Boot вместо значения по умолчаниюkeycloak.json

5.3. application.propertiesс

Поскольку мы установили ограничения безопасности с помощью Spring Security, мы можем удалить предыдущие ограничения безопасности, которые мы поместили вapplication.properties.

Теперь добавим это к нашемуapplication.properties: 

keycloak.principal-attribute=preferred_username

5.4. контроллер

Чтобы использовать имя пользователя, мы обновляем наш контроллер, добавляяPrincipal: 

@GetMapping(path = "/customers")
public String customers(Principal principal, Model model){
    addCustomers();
    model.addAttribute("customers", customerDAO.findAll());
    model.addAttribute("username", principal.getName());
    return "customers";
}

5.5. Thymeleaf

Под контейнером div мы добавим одну строку для приветствия пользователя: 

Hello, --name--.

5.6. Demo

Теперь, после аутентификации и перехода на страницу внутренних клиентов, мы увидим:

image

6. Заключение

В этом руководстве мы настроили сервер Keycloak и использовали его с приложением Spring Boot.

Мы также увидели, как настроить Spring Security и использовать его вместе с Keycloak. Доступна рабочая версия кода, показанного в этой статьеover on Github.

Related