Интеграция Keycloak в Swagger

У меня есть защищенный бэкэнд Keycloak, к которому я хотел бы получить доступ через swagger-ui. Keycloak обеспечивает неявный поток кода oauth2 и доступ к нему, но я не смог заставить его работать. В настоящее время отсутствует документация Keycloak относительно того, какой URL следует использовать для authorizationUrl и tokenUrl в swagger.json.

Каждая область в Keycloak предлагает огромный список URL-адресов конфигурации, открывая http://keycloak.local/auth/realms/REALM/.well-known/openid-configuration

Кроме того, я попытался напрямую интегрировать js-клиент keycloak в swagger-ui index.html, добавив следующие строки:

<script src="keycloak/keycloak.js"></script>
<script>
  var keycloak = Keycloak('keycloak.json');
    keycloak.init({ onLoad: 'login-required' })
      .success(function (authenticated) {
        console.log('Login Successful');
        window.authorizations.add("oauth2", new ApiKeyAuthorization("Authorization", "Bearer " + keycloak.token, "header"));
      }).error(function () {
        console.error('Login Failed');
        window.location.reload();
      }
    );
 </script>

Я также попробовал что-то подобное после "Вход успешен"

swaggerUi.api.clientAuthorizations.add("key", new SwaggerClient.ApiKeyAuthorization("Authorization", "Bearer " + keycloak.token, "header"));

Но это также не работает.

Любые предложения, как я могу интегрировать аутентификацию Keycloak в Swagger?

ОТВЕТЫ

Ответ 1

Swagger-ui может интегрироваться с keycloak, используя implicit режим аутентификации. Вы можете настроить oauth2 на swagger-ui, чтобы он попросил вас аутентифицироваться вместо того, чтобы напрямую передавать токен доступа.

1-ое, ваше чванство должно ссылаться на определение безопасности, например:

"securityDefinitions": {
    "oauth2": {
        "type":"oauth2",
        "authorizationUrl":"http://172.17.0.2:8080/auth/realms/master/protocol/openid-connect/auth",
        "flow":"implicit",
        "scopes": {
            "openid":"openid",
            "profile":"profile"
        }
    }
}

Затем вам нужно указать другой параметр: с чистым js вы можете использовать в index.html

const ui = SwaggerUIBundle({ ...} );

ui.initOAuth({
    clientId: "test-uid",
    realm: "Master",
    appName: "swagger-ui",
    scopeSeparator: " ",
    additionalQueryStringParams: {"nonce": "132456"}
})

В этом коде,

  • authorizationUrl - это конечная точка авторизации в вашей области keyclloak
  • Области - это то, что вы можете настроить на свои нужды
  • clientId - клиент, параметризованный с implicit режимом в области keyclloak
  • дополнительный параметр nonce должен быть случайным, но swagger-ui еще не использует его.

Я добавлю здесь пример, если вы хотите сделать все это в Spring-boot:

На этой основе вы в основном будете использовать swagger и swagger-ui web-jar от Springfox. Это делается путем добавления зависимостей:

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.8.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.8.0</version>
</dependency>

Swagger разрешен путем добавления аннотации swagger2 в вашем основном классе:

@SpringBootApplication
@EnableSwagger2
public class TestSpringApplication {
    ...

то вы можете настроить класс Configuration следующим образом:

@Configuration
public class SwaggerConfigurer {

    @Bean
    public SecurityConfiguration securityConfiguration() {

        Map<String, Object> additionalQueryStringParams=new HashMap<>();
        additionalQueryStringParams.put("nonce","123456");

        return SecurityConfigurationBuilder.builder()
            .clientId("test-uid").realm("Master").appName("swagger-ui")
            .additionalQueryStringParams(additionalQueryStringParams)
            .build();
    }

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.example.testspring"))
            .paths(PathSelectors.any())
            .build().securitySchemes(buildSecurityScheme()).securityContexts(buildSecurityContext());
    }

    private List<SecurityContext> buildSecurityContext() {
        List<SecurityReference> securityReferences = new ArrayList<>();

        securityReferences.add(SecurityReference.builder().reference("oauth2").scopes(scopes().toArray(new AuthorizationScope[]{})).build());

        SecurityContext context = SecurityContext.builder().forPaths(Predicates.alwaysTrue()).securityReferences(securityReferences).build();

        List<SecurityContext> ret = new ArrayList<>();
        ret.add(context);
        return ret;
    }

    private List<? extends SecurityScheme> buildSecurityScheme() {
        List<SecurityScheme> lst = new ArrayList<>();
        // lst.add(new ApiKey("api_key", "X-API-KEY", "header"));

        LoginEndpoint login = new LoginEndpointBuilder().url("http://172.17.0.2:8080/auth/realms/master/protocol/openid-connect/auth").build();

        List<GrantType> gTypes = new ArrayList<>();
        gTypes.add(new ImplicitGrant(login, "acces_token"));

        lst.add(new OAuth("oauth2", scopes(), gTypes));
        return lst;
    }

    private List<AuthorizationScope> scopes() {
        List<AuthorizationScope> scopes = new ArrayList<>();
        for (String scopeItem : new String[]{"openid=openid", "profile=profile"}) {
            String scope[] = scopeItem.split("=");
            if (scope.length == 2) {
                scopes.add(new AuthorizationScopeBuilder().scope(scope[0]).description(scope[1]).build());
            } else {
                log.warn("Scope '{}' is not valid (format is scope=description)", scopeItem);
            }
        }

        return scopes;
    }
}

В этом коде есть много вещей, которые вы можете обновить. Это в основном то же самое, что и раньше:

  • nonce который должен быть случайным (swagger-ui еще не использует его)
  • clientId который вам нужно настроить соответствующим клиенту, который вы устанавливаете в keycloak
  • basePackage: вам нужно установить пакет, в котором весь ваш контроллер
  • Если вам нужен api-ключ, вы можете включить его и добавить в список схем безопасности
  • LoginEndpoint: это должна быть конечная точка авторизации для вас.
  • scopeItems: области, которые вы хотите для этой аутентификации.

Он будет генерировать то же самое, что и раньше: обновляя swagger, чтобы добавить securityDefinition, и сделайте swagger-UI, возьмите параметр для clientId, nonce,...

Ответ 2

Борьба с этой установкой в течение последних 2 дней. Наконец получил рабочее решение для тех, кто не может решить.

pom.xml

    ...
    <dependency>
        <groupId>org.keycloak</groupId>
        <artifactId>keycloak-spring-security-adapter</artifactId>
    </dependency>
    <dependency>
        <groupId>org.keycloak</groupId>
        <artifactId>keycloak-spring-boot-starter</artifactId>
    </dependency>
    ...

Включить Swagger на основной класс

...    
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@SpringBootApplication
@EnableSwagger2
@EnableAsync
@EnableCaching
public class MainApplication {
  public static void main(String[] args) {
    SpringApplication app = new SpringApplication(MainApplication.class);
    app.run(args);
  }
}

SwaggerConfig.java

package com.XXX.XXXXXXXX.app.config;

import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.AuthorizationCodeGrantBuilder;
import springfox.documentation.builders.OAuthBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.service.*;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.contexts.SecurityContext;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger.web.SecurityConfiguration;
import springfox.documentation.swagger.web.SecurityConfigurationBuilder;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.Arrays;

import static springfox.documentation.builders.PathSelectors.regex;

/*
 * Setting up Swagger for spring boot
 * https://www.baeldung.com/swagger-2-documentation-for-spring-rest-api
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {

 @Value("${keycloak.auth-server-url}")
 private String AUTH_SERVER;

 @Value("${keycloak.credentials.secret}")
 private String CLIENT_SECRET;

 @Value("${keycloak.resource}")
 private String CLIENT_ID;

 @Value("${keycloak.realm}")
 private String REALM;

 private static final String OAUTH_NAME = "spring_oauth";
 private static final String ALLOWED_PATHS = "/directory_to_controllers/.*";
 private static final String GROUP_NAME = "XXXXXXX-api";
 private static final String TITLE = "API Documentation for XXXXXXX Application";
 private static final String DESCRIPTION = "Description here";
 private static final String VERSION = "1.0";

 @Bean
 public Docket taskApi() {
   return new Docket(DocumentationType.SWAGGER_2)
    .groupName(GROUP_NAME)
    .useDefaultResponseMessages(true)
    .apiInfo(apiInfo())
    .select()
    .paths(regex(ALLOWED_PATHS))
    .build()
    .securitySchemes(Arrays.asList(securityScheme()))
    .securityContexts(Arrays.asList(securityContext()));
 }

 private ApiInfo apiInfo() {
   return new 
     ApiInfoBuilder().title(TITLE).description(DESCRIPTION).version(VERSION).build();
 }

 @Bean
 public SecurityConfiguration security() {
   return SecurityConfigurationBuilder.builder()
    .realm(REALM)
    .clientId(CLIENT_ID)
    .clientSecret(CLIENT_SECRET)
    .appName(GROUP_NAME)
    .scopeSeparator(" ")
    .build();
 }

 private SecurityScheme securityScheme() {
   GrantType grantType =
    new AuthorizationCodeGrantBuilder()
        .tokenEndpoint(new TokenEndpoint(AUTH_SERVER + "/realms/" + REALM + "/protocol/openid-connect/token", GROUP_NAME))
        .tokenRequestEndpoint(
            new TokenRequestEndpoint(AUTH_SERVER + "/realms/" + REALM + "/protocol/openid-connect/auth", CLIENT_ID, CLIENT_SECRET))
        .build();

SecurityScheme oauth =
    new OAuthBuilder()
        .name(OAUTH_NAME)
        .grantTypes(Arrays.asList(grantType))
        .scopes(Arrays.asList(scopes()))
        .build();
return oauth;
 }

 private AuthorizationScope[] scopes() {
AuthorizationScope[] scopes = {
  new AuthorizationScope("user", "for CRUD operations"),
  new AuthorizationScope("read", "for read operations"),
  new AuthorizationScope("write", "for write operations")
};
return scopes;
}

private SecurityContext securityContext() {
return SecurityContext.builder()
    .securityReferences(Arrays.asList(new SecurityReference(OAUTH_NAME, scopes())))
    .forPaths(PathSelectors.regex(ALLOWED_PATHS))
    .build();
 }
}

С терминала запустите "mvnw spring-boot: run"

Откройте браузер и нажмите http://localhost: [port]/[app_name]/swagger-ui.html.

Нажмите кнопку Авторизация: кнопка авторизации Swagger

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

Нажмите кнопку "Авторизация" еще раз. Вы должны быть перенаправлены на экран входа в систему.

Когда учетные данные будут введены и подтверждены, вы будете перенаправлены обратно в Swagger-UI полностью аутентифицированным.

Ответ 3

Swagger-ui + Keycloak (или любой другой поставщик OAuth2), использующий неявный поток, шаблон OpenAPI 3.0:

components:
  ...
   securitySchemes:
    my_auth_whatever:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: https://MY-KEYCLOAK-HOST/auth/realms/MY-REALM-ID/protocol/openid-connect/auth
          scopes: {}
  ...
security:
  - my_auth_whatever: []

Убедитесь, что неявный поток включен в настройках Keycloak для клиента, который вы используете.

Недостатком является то, что пользователь по-прежнему запрашивает client_id в модальном режиме, когда нажимает кнопку "Авторизовать" в Swagger UI. Значение, которое вводит пользователь, может быть перезаписано добавлением параметра запроса ?client_id=YOUR-CLIENT-ID в authorizationUrl, но это своего рода грязный хак, и модал все еще показывается пользователю. При запуске swagger-ui в docker - контейнер OAUTH_CLIENT_ID env может быть предоставлен контейнеру, чтобы установить значение client_id по умолчанию для модального окна. Для развертывания без докера обратитесь к подходу @wargre с изменением index.html (не уверен, есть ли лучший способ).

Для примера SwaggerAPI (OpenAPI 2.0) см. Первый фрагмент кода в ответе @wargre и этот документ: https://swagger.io/docs/specification/2-0/authentication/