Keycloak und Spring Security Teil 3: Kommunikation via KeycloakRestTemplate

In den vorangegangenen Teilen haben wir eine durch Keycloak geschützte Applikation bestehend aus Frontendservice und Backendservice erstellt und dabei Keycloak in Spring Security integriert.
Nun möchten wir abschließend noch einen weiteren Service hinzufügen, der mit dem Backendservice via role-based authentication vor unbefugtem Zugriff geschützt kommuniziert. Glücklicherweise stellt Keycloak uns hierfür das KeycloakRestTemplate zur Verfügung, das dies sehr einfach ermöglicht.

Disclaimer: Um das Beispiel nicht zu verkomplizieren gehe ich hier davon aus, dass der User, der einen Eintrag hinzufügt und der User, dem es erlaubt ist, Mails zu verschicken, ein und derselbe ist.
Andere Implementierungen, z.B. via Confidential-Flow und REST API/ dem Java-Client von Keycloak, die eine Unterscheidung zwischen Frontenduser und Mailuser ermöglichen würden, wären hier ebenso passend.
Weiter setze ich wie gehabt Grundkenntnisse mit Spring Boot und Spring Security sowie eine lauffähige Keycloak-Instanz voraus.

Der Mailservice

Unser Mailservice verschickt schlicht Mails über einen externen SMTP-Server an eine in den application.properties gesetzte Adresse.

Bild 1: Projektstruktur des Mailservices – Diesmal ganz einfach gehalten.

Damit andere Services mit dem Mailservice kommunizieren können, stellt dieser einen mit Keycloak geschützten POST-Endpunkt /mail bereit, den die anderen Services ansprechen. Außerdem wollen wir unserem Testnutzer noch eine dedizierte Rolle „mail“ zuweisen, welche wir erst im Adminbereich anlegen und dem Nutzer zuweisen. Da wir diesen Vorgang schon in Teil 1 abgehandelt haben, soll hier ein Bild der fertigen Zuweisung reichen:

Bild 2: Rollenzuweisung der mail-Rolle (Ein Klick vergrößert das Bild)

Damit unser Mailservice auch Emails verschicken kann, nutzen wir als Maven-Dependencies neben den Startern für Spring Boot Web, Security und Keycloak(!) noch den Spring Boot Mail-Starter, der für unsere Zwecke völlig ausreicht. An dieser Stelle sei mir der obligatorische Hinweis auf das GitHub-Repository gestattet, in dem sich das vollständige Codebeispiel zum Mailservice findet.

Entsprechend erstellen wir unsere application.properties:

1server.port=8082
2 
3#Spring Mail-Properties
4spring.mail.host=smtp.yourhost.com
5spring.mail.port=xxx
6spring.mail.username=[yourmailsenderaccount]
7spring.mail.password=[yourpassword]
8spring.mail.properties.mail.smtp.auth=true
9spring.mail.properties.mail.smtp.ssl.enable = true
10 
11#keycloak
12keycloak.auth-server-url=http://localhost:8080/auth
13keycloak.realm=springboot-example
14keycloak.bearer-only=true
15keycloak.resource=guestbook-mail-app
16keycloak.principal-attribute=preferred_username
17keycloak.cors=true
18 
19#Custom Mail properties
20mail.from=${mail_from:Guestbook <yourmailsenderaccount>}
21mail.to=${mail_to:yourmailreceiveraccount}

Unser Mailservice läuft also auf Port 8082, kann Emails über einen festzulegenden Anbieter versenden und ist, wie schon in Teil 2 besprochen, für die Kommunikation mit Keycloak konfiguriert.

Die SecurityConfig unseres Mailservices entspricht vom Aufbau der Config des Backendservices, die wir im Detail in Teil 2 besprochen und implementiert haben. Nur in der Security Filter Chain ändern wir unseren Endpunkt und die Rolle entsprechend ab:

1@Override
2protected void configure(HttpSecurity http) throws Exception
3{
4    super.configure(http);
5    http.cors()
6            .and()
7            .csrf()
8            .disable()
9            .sessionManagement().sessionCreationPolicy(SessionCreationPolicy.STATELESS)
10            .sessionAuthenticationStrategy(sessionAuthenticationStrategy())
11            .and()
12            .authorizeRequests()
13            .antMatchers("/mail*").hasRole("mail")
14            .anyRequest().permitAll();
15}

Der Einfachheit halber lassen wir unseren Controller jetzt die ganze Arbeit übernehmen und implementieren ihn wie folgt:

1@RestController
2@CrossOrigin(origins = "*", methods = {RequestMethod.GET, RequestMethod.POST, RequestMethod.OPTIONS, RequestMethod.PUT})
3public class GuestbookMailController {
4 
5    private final MailSender sender;
6 
7    @Value("${mail.from}")
8    private String from;
9 
10    @Value("${mail.to}")
11    private String to;
12 
13    @Autowired
14    public GuestbookMailController(MailSender sender) {
15        this.sender = sender;
16    }
17 
18    @PostMapping(value = "/mail",
19            consumes=MediaType.APPLICATION_JSON_VALUE)
20    public ResponseEntity<Boolean> sendMail(@RequestBody GuestbookEntry entry, Principal p) {
21        Boolean isSent = false;
22        SimpleMailMessage msg = new SimpleMailMessage();
23        msg.setFrom(from);
24        msg.setTo(to);
25        msg.setSubject("[Guestbook Entry] " + entry.getTitle());
26        msg.setText(entry.getCommenter() + " schrieb:\r\n\r\n" + entry.getComment());
27 
28        sender.send(msg);
29        try {
30            Thread.sleep(1500);
31            isSent = true;
32        } catch (InterruptedException e) {
33            e.printStackTrace();
34        }
35 
36        return ResponseEntity.ok().body(isSent);
37    }
38}

Die Methode sendMail verschickt unsere erzeugte Mail mit den Inhalten des neuen Eintrags. Das war es auch schon zur Implementierung des Mailservices.

Da das KeycloakRestTemplate als ein Decorator mit den benötigten Headern um das normale Spring RestTemplate fungiert, benötigen wir hier nicht mehr als die Einbindung des Starters und die Spring Security-Integration via SecurityConfig, um es zu verarbeiten. Wird nun ein Request eines Nutzers ohne mail-Rolle abgeschickt, erhält dieser einen 403-Status zurück.

Aufruf und Konfiguration im Backendservice

Für die Konfiguration des aufrufenden Backend-Services ändern wir unsere Security-Konfiguration so ab, dass sie in der Lage ist, auch asynchrone Requests vernünftig zu authentifizieren.
Dazu müssen wir die Strategie ändern, mit der der SecurityContextHolder in Spring diesen Context gegenüber Threads vorhält – standardmäßig passiert dies via ThreadLocal, welcher leider dafür sorgt, dass neu gespawnte Threads (@Async) die Authentication verlieren.
Das manifestiert sich als Fehler im KeycloakRestTemplate, da dieses intern über die KeycloakClientRequestfactory die Authentication wie folgt abruft:

1...
2SecurityContextHolder.getContext().getAuthentication();
3...

Ist diese null, wird eine IllegalStateException ausgelöst, da das Template keine Möglichkeit hat, auf die sicherheitsrelevanten Daten zuzugreifen.

Lange Rede, kurze Lösung: Wir ändern die Strategy im Konstruktor unserer SecurityConfig, sodass für den SecurityContext statt eines ThreadLocal ein InheritableThreadLocal genutzt wird, der diese Informationen beim Spawnen von Childthreads weitergibt. Dann klappt’s auch mit dem @Async.

1public SecurityConfig(KeycloakClientRequestFactory keycloakClientRequestFactory) {
2        this.keycloakClientRequestFactory = keycloakClientRequestFactory;
3 
4        //to use principal and authentication together with @async
5        SecurityContextHolder.setStrategyName(SecurityContextHolder.MODE_INHERITABLETHREADLOCAL);
6 
7    }

Daneben müssen wir das KeycloakRestTemplate noch als @Bean deklarieren. Hier nutzt der Keycloak-Adapter und dessen Doku leider noch nicht die aktuellen Spring-Boot-Best Practices > Version 1.4. Eine entsprechende Änderung sollte aber a) relativ einfach sein, und wird b) mit einer der nächsten Versionen kommen – wir halten uns in diesem Fall erst einmal an die Dokumentation:

1@Bean
2@Scope(ConfigurableBeanFactory.SCOPE_PROTOTYPE)
3public KeycloakRestTemplate keycloakRestTemplate() {
4    return new KeycloakRestTemplate(keycloakClientRequestFactory);
5}

Im Codebeispiel sehen wir außerdem, dass das Bean den Scope Prototype besitzt. Nun gebe ich gern zu, dass ich mir nicht sicher bin, warum dies so sein muss. Die Dokumentation sagt an dieser Stelle nur:

Note that it must be scoped as a prototype to function correctly.

Soweit ich es sehen kann, haben RestTemplates in Spring den üblichen Singleton-Scope und sind thread-safe, mit der Einschränkung, dass durch Nutzung von eigenen MessageConvertern die thread-safety nicht mehr garantiert werden kann. Das KeycloakRestTemplate setzt aber nur den Authorization-Header, keine eigenen Converter.
Einige Kommentare sagen weiter, dass eine mehrfache Instanziierung durchaus Performanceprobleme auslösen kann.

Was ich bisher sicher sagen kann ist, dass es auch ohne den Prototype-Scope bestens funktioniert. Meine Nachfrage bei Sébastien Blanc von Red Hat hat weiter ergeben, dass der Spring Security Adapter in Version 3.3.0 auf den aktuellen Best Practice refaktorisiert wird und dort dann auch der Singleton-Scope genutzt wird. Bis dahin sei es euch überlassen, den Scope zu ändern oder auch nicht. 🙂

Damit sind wir jedenfalls auch schon fertig mit der Konfiguration – kommen wir also jetzt zum Aufruf des Mailservices aus dem Backendservice:

1package de.codecentric.demo.guestbook.infrastructure.thirdParty;
2 
3@Component
4public class SpringMailClient implements GuestbookMailClient {
5 
6    private final KeycloakRestTemplate template;
7 
8    public SpringMailClient(KeycloakRestTemplate template) {
9        this.template = template;
10    }
11 
12    @Override
13    public void sendMail(GuestbookEntry entry) {
14        String endpoint = "http://localhost:8082/mail";
15        Boolean result = template.postForObject(endpoint, entry, Boolean.class);
16        System.out.println("Mail sent: " + result.toString());
17    }
18}

Diesen registrieren wir als @Component und injizieren unser soeben konfiguriertes KeycloakRestTemplate. Dann rufen wir in altbekannter RestTemplate-Manier den Endpunkt via postForObject auf. Dabei übernimmt das KeycloakResttemplate für uns das komplette Handling des bearer-tokens.
Starten wir jetzt unsere 3 Services, melden uns an und entfernen die mail-Rolle des Testnutzers, so kann dieser beim nächsten Request zwar noch einen Eintrag erstellen, allerdings würde keine Mail mehr versandt werden, und unser Backendservice erhielte einen 403-Statuscode. Der Endpunkt ist also geschützt 🙂

Fazit:

Im Laufe dieser Artikelreihe haben wir gesehen, wie einfach es mit Spring Boot, Spring Security und Red Hats SSO-Lösung Keycloak ist, seine Systeme und APIs vor unbefugtem Zugriff zu schützen. Dabei haben wir in diesem Teil einen geschützten Endpunkt mittels KeycloakRestTemplate in wenigen Schritten einrichten und aufrufen können.

Dies soll zur Darstellung der Grundintegration von Keycloak in Spring Security erst einmal ausreichen, auch wenn die Themenvielfalt noch um einiges größer ist. Sehr spannend ist zum Beispiel auch die Anbindung bestehender Identity Provider, wie z.B. Active Directory, oder das Hinzufügen von Custom-Attributen zu einem User/Token.

Ich freue mich sehr über alle Leser und Leserinnen, die bis hierhin durchgehalten haben. Schreibt gern in die Kommentare, was euch gefallen hat, was ich besser machen oder erklären könnte und wo vielleicht noch Schwierigkeiten beim Verständnis vorhanden sind. Ich versuche, jeden Kommentar zeitnah zu beantworten.

Code: GitHub
Weitere Artikel dieser Serie: Teil 1 | Teil 2