Spring Cloud Gateway and Apereo CAS Integration

Deniz G
5 min readDec 18, 2020

There are 2 components in CAS Terminology. The first one is CAS server whose main responsibility is to provide single sign-on service. The other is CAS client which are applications that delegate authentication to CAS server.

The cas-client library must exist in the programming language used in order to integrate CAS clients with the CAS server. Today, you can connect your Spring application to CAS because the cas client library made for Spring
available. However, you cannot integrate Spring Cloud Gateway with Cas server using this cas client library. Why?


Traditional Spring applications are based on a Servlet/MVC stack and provide blocking operation. However, applications developed with the reactive approach are based on WebFlux, which in contrast provides non-blocking operation. So, libraries that depend on Servlet/MVC cannot run on reactive libraries.

The cas client library developed for Spring is based on Servlet/MVC. Spring Cloud Gateway is a reactive library built on WebFlux. So if the cas client is added to the Spring Cloud Gateway and the Spring Cloud Gateway is requested to be the cas client, this will not work.

So is there a reactive cas client for spring right now? No. Then, we will either write our own reactive cas client library or wait for someone to write it.




Use OpenID Connect (OIDC). This is simply authentication using the OAuth2 protocol. Spring Cloud Gateway supports OAuth2 client, and Apereo CAS supports to be used as Authorization Server. Bingo!! Then we can integrate each other with OpenID connect.

Let’s start from Apereo CAS. (https://apereo.github.io/2019/02/19/cas61-as-oauth-authz-server/)

Firstly, add OAuth dependency to build.gradle

compile "org.apereo.cas:cas-server-support-oauth-webflow:${casServerVersion}"

Then, add OAuth credentials to your service registry.

"@class" : "org.apereo.cas.support.oauth.services.OAuthRegisteredService",
"bypassApprovalPrompt": true,
"clientId": "abc",
"clientSecret": "123",
"supportedGrantTypes": [ "java.util.HashSet", [ "authorization_code" ] ],
"supportedResponseTypes": [ "java.util.HashSet", [ "code" ] ]

After these settings, Apereo CAS will provide endpoints for use in the OpenID Connect process. (https://apereo.github.io/cas/6.2.x/installation/OAuth-OpenId-Authentication.html#endpoints)

  • /oauth2.0/accessToken
  • /oauth2.0/authorize
  • /oauth2.0/profile
  • /oauth2.0/instrospect

Apereo CAS is now complete. Turn at Spring Cloud Gateway.

Add OAuth2 client dependency.


Then, configure security.

public class WebSecurityConfig {
public SecurityWebFilterChain securityWebFilterChain(ServerHttpSecurity http) { http.authorizeExchange().anyExchange().authenticated().and().oauth2Login();
return http.build();

Then, provide Authorization Server endpoints and credentials.

provider: uaa
client-id: abc
client-secret: 123
authorization-grant-type: authorization_code
redirect-uri: "{baseUrl}/login/oauth2/code/{registrationId}"
scope: custom_mod
authorization-uri: ${cas-address}/oauth2.0/authorize
token-uri: ${cas-address}/oauth2.0/accessToken
user-info-uri: ${cas-address}/oauth2.0/profile
user-name-attribute: id
user-info-authentication-method: form

Last but not least. Add TokenRelay filter to your route to pass access token during downstream. In OAuth2 Terminology, your microservices behind gateway are resource server. So, Spring Cloud Gateway sends access tokens to resource servers, and they are required to validate this tokens.

- id: test_route
- Path=/test/**
- TokenRelay=
uri: http://test

So how will the flow work with these settings?

  • When you request to Spring Cloud Gateway, it will redirects to Apereo CAS to get authorization code (or access code). (/oauth2.0/authorize)
  • When you are redirect to Apereo CAS to authorization code, you will login if you are not yet logged into CAS.
  • After sucessful login, Apereo CAS will redirect back to Spring Cloud Gateway with autohorization code.
  • When the request with authorization code comes back Spring Cloud Gateway, it will use this code and sends access token request to Apereo CAS. (/oauth2.0/accessToken)
  • Apereo CAS will validate authorization code and provide access token to Spring Cloud Gateway.
  • After get access token, Spring Cloud Gateway will send profile request to Apereo CAS. Because, it needs to create principal/authentication object within itself. (/oauth2.0/profile)

Authentication is completed now.

Let’s authorize access token passed to resource server.

First, add security and resource server dependencies to your microservices.


Then, configure security.

public class WebSecurityConfig extends WebSecurityConfigurerAdapter{

protected void configure(HttpSecurity http) throws Exception {

Then, provide Authorization server endpoint and credentials.


Done! If you open debug log level for RestTemplate object, you will see validation request to Apereo CAS.


Access Token Types

There are 2 types of access token. First one is called opaque token (or reference token). It is non-sense and random string value (like AT-5-l5-uexxsnSAs5uFSWwIF91XW8a9jOrE1). This token is only known by the authorization server that assigned it.

So, when the resource server receives this token, it should send a request to the authorization server to make sense and verify access token.

Apereo CAS provides opaque token as access token by default in the examples I have given above. So, for every request coming to the resource server, I have to request the authorization server again to verify this. It is network round-trip cost.

The other access token type is called self-contained token (or JWT). This token contains all the necessary information and we don’t need anything else to understand what is it. So, for every request coming to the resource server, there is no need to request the authorization server verify this.

Let’s change opaque token to JWT.

Add this to your service registry at Apereo CAS.

“jwtAccessToken”: true

JWT is also divided into 3.

  • JWT: Json Web Token (unsigned JWT. signature part is empty.)
  • JWS: Json Web Signature (signed JWT. there is a signature part.)
  • JWE: Json Web Encrpytion (signed and encrypted. there is a signature part, and also payload part is encrpyted.)

When Apereo CAS starts, you will see encrpytion and signing keys at logs (it means that it creates JWE) if you don’t configure these keys. Set it up to avoid creating new keys over and over at every startup. I prefer to JWS to prevent overwork on encrpytion. So, I disable encrpytion and want only signing.


There is no need to change in Spring Cloud Gateway. Let’s continue from resource server.

Change token type from opaque to jwt.

public class WebSecurityConfig extends WebSecurityConfigurerAdapter{

protected void configure(HttpSecurity http) throws Exception {
public JwtDecoder jwtDecoder() {
String signKey = "abBkYP2TGd1qobBQnW0mraR1jJ5_uBT65LlnpP8xe_sy3IiNQ_6SnNUxagwcPxHUudOdsf_hEPRRUHxaAsTzcd";
SecretKey secretKey = new SecretKeySpec(signKey.getBytes(), "HMACSHA512");
return NimbusJwtDecoder

That is it. No longer need to go to the authorization server to verify the access token every time a request comes up. If you break/disrupt your key at resource server, it will respond HTTP 401 Unauthorized.