Keycloak Integration – OAuth2 and OpenID with Swagger UI

1. Overview

In this tutorial, we’ll focus on how to test a REST service that is secured and uses Keycloak for authentication and authorization with Swagger UI.

2. The Challenge

Like other web resources, REST APIs are often secured. So, the service consumer (such as a Swagger UI) needs not only to handle the HTTP call itself but also needs to provide authentication information to the service provider.

Keycloak is an IAM server that allows authentication and authorization outside of the service provider implementation. It’s part of the architecture, as shown in the following diagram:

As we can see, both the service provider and the service consumer need to contact the Keycloak server. First, we’ll need to install a Keycloak server and integrate it into a Spring Boot application as a REST service provider. Then, we need to extend the Swagger UI.

3. Integrating Swagger UI

For the integration between spring-boot and swagger-ui, add the library to the list of your project dependencies (No additional configuration is needed):

<dependency>
     <groupId>org.springdoc</groupId>
     <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
     <version>2.1.0</version>
</dependency>

4. Using Standards

Extending the Swagger UI by vendor-specific code is only sensible for very special cases. So, we should prefer using vendor-independent standards. The following sections will describe how to implement this.

4.1. Existing Standards

First, we need to know which standards exist. For authentication and authorization, there’s a protocol like OAuth2. For SSO, we could use OpenID Connect (OIDC) as an extension to OAuth2.

The standard to describe a REST API is OpenAPI. This standard includes defining multiple security schemes, including OAuth2 and OIDC:

paths:
  /api/v1/products:
    get:
      ...
      security:
        - my_oAuth_security_schema:
          - read_access
...
securitySchemes:
  my_oAuth_security_schema:
    type: oauth2
    flows:
      implicit:
        authorizationUrl: https://api.example.com/oauth2/authorize
        scopes:
          read_access: read data
          write_access: modify data

4.2. Extend the Service Provider

In a code-first approach, the service provider can generate the OpenAPI documentation based on the code. So, the security schemes must also be provided this way. For example, with Spring Boot including SpringDoc, we could write such a configuration class:

@Configuration
public class OpenAPISecurityConfig {

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

    private static final String OAUTH_SCHEME_NAME = "my_oAuth_security_schema";

    @Bean
    public OpenAPI openAPI() {
        return new OpenAPI().components(new Components()
            .addSecuritySchemes(OAUTH_SCHEME_NAME, createOAuthScheme()))
            .addSecurityItem(new SecurityRequirement().addList(OAUTH_SCHEME_NAME))
            .info(new Info().title("Todos Management Service")
                .description("A service providing todos.")
                .version("1.0"));
    }

    private SecurityScheme createOAuthScheme() {
        OAuthFlows flows = createOAuthFlows();
        return new SecurityScheme().type(SecurityScheme.Type.OAUTH2)
            .flows(flows);
    }

    private OAuthFlows createOAuthFlows() {
        OAuthFlow flow = createAuthorizationCodeFlow();
        return new OAuthFlows().implicit(flow);
    }

    private OAuthFlow createAuthorizationCodeFlow() {
        return new OAuthFlow()
            .authorizationUrl(authServerUrl + "/realms/" + realm + "/protocol/openid-connect/auth")
            .scopes(new Scopes().addString("read_access", "read data")
                .addString("write_access", "modify data"));
    }

}

Using other technologies would lead to different implementations, of course. But we should always be aware of the OpenAPI that has to be generated.

4.3. Extend the Service Consumer

Swagger UI supports OpenAPI authentication schemes by default – no need to customize it. We’ll get a possibility to authenticate then:

Other clients would have different solutions. For example, there’s an NPM module for Angular applications that provides OAuth2 and OpenID Connect (OIDC) in a straightforward way.

5. Conclusion

In this article, we pointed out the possibilities to test REST services with Swagger UI in the case of using Keycloak as an IAM. The best solution is to use standards like OpenAPI, OAuth2, and OpenID Connect, which are all supported by the tools.

As always, all the code is available over on GitHub.