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. Customizing Swagger UI

We could directly extend the Swagger UI by including a script like this one into the 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>

The script is available as an NPM package, so it would be possible to fork the Swagger UI Source Code Repository and extend the project by the corresponding 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 SpringFox, we could write such a configuration class:

@Configuration
public class OpenAPISecurityConfig {

    @Autowired
    void addSecurity(Docket docket) {
        docket
          .securitySchemes(of(authenticationScheme()))
          .securityContexts(of(securityContext()));
    }

    private SecurityScheme authenticationScheme() {
        return new OAuth2SchemeBuilder("implicit")
          .name("my_oAuth_security_schema")
          .authorizationUrl("https://api.example.com/oauth2/authorize")
          .scopes(authorizationScopes())
          .build();
    }

    private List<AuthorizationScope> authorizationScopes() {
        return Arrays.asList(
          new AuthorizationScope("read_access", "read data"),
          new AuthorizationScope("write_access", "modify data")
        );
    }

    private SecurityContext securityContext() {
        return SecurityContext.builder()
          .securityReferences(readAccessAuth())
          .operationSelector(operationContext ->
            HttpMethod.GET.equals(operationContext.httpMethod())
          )
          .build();
    }

    private List<SecurityReference> readAccessAuth() {
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[] { authorizationScopes().get(0) };
        return of(new SecurityReference("my_oAuth_security_schema", authorizationScopes));
    }

}

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.

4.4. Swagger UI Restrictions

Swagger UI supports OpenID Connect Discovery since version 3.38.0 (Swagger Editor since version 3.14.8). Unfortunately, SpringFox in the current version 3.0.0 packages a Swagger UI 3.26.2. Therefore, if we want to include a Swagger UI of a newer version, we need to include it directly within our application using the same directory structure as SpringFox does to overshadow the SpringFox-packaged files:

SpringDoc 1.6.1 instead does not package a Swagger UI but declares a transitive dependency to the Swagger UI 4.1.3, so we won't have any troubles with SpringDoc.

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.

res – Security (video) (cat=Security/Spring Security)

Learn the basics of securing a REST API with Spring

Get access to the video lesson