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.
Course – LSS (cat=Security/Spring Security)
I just announced the new Learn Spring Security course, including the full material focused on the new OAuth2 stack in Spring Security 5:
>> CHECK OUT THE COURSE
res – Security (video) (cat=Security/Spring Security)