DEV Community: Yuan Ji

How to Build an Elm Land Project for Production

Yuan Ji — Sun, 13 Oct 2024 05:40:20 +0000

After completing my demo project on Keycloak OAuth2 Token Exchange, I decided to expand the idea and created a new demo project called my-ai-doctor. Unlike the previous demo, which focused on backend integration, this project uses Elm for the UI and Docker Compose to run all six servers locally: the Keycloak server, API server, and the SPA web servers for both MyDoctor and MyHealth.

Fixing the Elm Compiler for Linux ARM 64

The first challenge was building the Elm Land project and deploying it to Docker containers. Initially, I used a standard Dockerfile to build my Elm UI project, but soon hit a roadblock:

 > [build 8/9] RUN npm install:                                                                                                                             
8.709 npm error code 1                                                                                                                                     
8.709 npm error path /app/node_modules/elm                                                                                                                 
8.709 npm error command failed                                                                                                                             
8.709 npm error command sh -c node install.js                                                                                                              
8.709 npm error -- ERROR -----------------------------------------------------------------------
8.709 npm error
8.709 npm error I am detecting that your computer (linux_arm64) may not be compatible with any
8.709 npm error of the official pre-built binaries.
8.709 npm error
8.709 npm error I recommend against using the npm installer for your situation. Check out the
8.709 npm error alternative installers at https://github.com/elm/compiler/releases/tag/0.19.1
8.709 npm error to see if there is something that will work better for you.
8.709 npm error
8.709 npm error From there I recommend asking for guidance on Slack or Discourse to find someone
8.709 npm error who can help with your specific situation.
8.709 npm error
8.709 npm error --------------------------------------------------------------------------------

After some investigation, I found that the latest Elm compiler (version 0.19.1) does not support linux_arm64. This meant I could build and run Elm projects on my Apple Mac Mini Pro natively, but not inside Docker. Fortunately, Simon Lydell and Mario Rogic created a new version of the elm npm package, which supports Linux ARM 64. Based on this discussion, the solution was to override the elm package in my package.json file by adding these lines:

"overrides": {
  "elm": "npm:@lydell/elm"
}

This replaces the Elm npm module in the locally downloaded node_modules directory with the @lydell/elm module, allowing the unofficial Elm compiler to work correctly on the Linux ARM64 platform.

Passing Environment Variables to UI Code

When developing the AI Doctor system locally, the UI SPA connects to the backend API at http://api.mydoctor:8081/api/v1/records. However, when running the entire demo inside Docker, the API is accessible via port 80 with the help of an Nginx reverse proxy: http://api.mydoctor/api/v1/records. The challenge was how to dynamically change the backend API URL in the Elm code.

The Elm Land documentation briefly mentions environment variables, but without detailed examples. I found a helpful blog, Deploying an Elm Frontend to Cloudflare Pages, which provided some hints on how to pass environment variables to an Elm Land app. After studying the Elm Land documentation again (here and here), I realized it was quite straightforward to pass different values as environment variables to Elm code.

In the interop.js file, we can pick environment variables and pass them to Elm code as Flags. For example:

export const flags = ({ env }) => {
  return {
    apiBaseUrl: env.API_BASE_URL
  };
};

Here, we pass the backend API base URL as a field in flags, which is then saved into Shared.Model.

First, I needed to customize the Shared module:

elm-land customize shared

This command will move three files from .elm-land into src folder: Shared.elm, Shared/Model.elm and Shared/Msg.elm.

Next, I added the field apiBaseUrl to Shared.Model.Model. Here is the code for Shared/Model.elm:

module Shared.Model exposing (Model)

type alias Model =
  { apiBaseUrl : String
  }

In Shared.elm, I decoded the flags and passed apiBaseUrl to Shared.Model.Model:

-- FLAGS

type alias Flags =
  { apiBaseUrl : String
  }

decoder : Json.Decode.Decoder Flags
decoder =
  Json.Decode.map Flags
    (Json.Decode.field "apiBaseUrl" Json.Decode.string)

-- INIT
type alias Model =
  Shared.Model.Model

init : Result Json.Decode.Error Flags -> Route () -> ( Model, Effect Msg )
init flagsResult route =
  ( { apiBaseUrl =
        case flagsResult of
          Ok flags -> flags.apiBaseUrl
          Err _ -> ""
    }
  , Effect.none
  )

The Shared.Model.Model (or Shared.Model) is then passed to each page, so the apiBaseUrl can be accessed whenever we need to call the backend API. See example code at Pages/Test.elm

Setting Environment Variables

To set environment variables like API_BASE_URL, you first need to declare them in the elm-land.json file under app.env, as:

{
  "app": {
    "env": [ "API_BASE_URL" ]
  }
}

For security reasons, all environment variables are hidden from your Elm Land application by default.
When you want to share an environment variable with your app, the app.env field is the one spot check

See my elm-land.json file, and I also declared AUTH_SERVER_URL for Keycloak server address and WS_BASE_URL for backend chatbot WebSocket address.

Then, you can pass API_BASE_URL in the command line when developing locally:

API_BASE_URL=http://api.mydoctor:8081/api/v1 elm-land server

For production builds, use the ENV directive in the Dockerfile like this:

ENV API_BASE_URL="http://api.mydoctor/api/v1"

See my Dockerfile for mydoctor-ui app.

You can find all source code at https://github.com/jiwhiz/my-ai-doctor. This is still a work in progress. Please let me know if you find this blog is helpful.

Using ChatGPT o1 to write UI code with Elm

Yuan Ji — Tue, 17 Sep 2024 03:37:25 +0000

After I finished my Oauth 2 Token Exchange demo project, I suddenly had a desire to write the front end UI with Elm language. Elm is my favorite front end language: elegant, functional, strongly typed.

But I haven't touched Elm for over a year, so it would take a while to remember how to start. Fortunately, or coincidentally, ChatGPT o1 just came out, and I wanted to see if it is as good as people say.

So I wrote a detailed prompt and asked ChatGPT o1 to give me a simple web application using the Elm language and the elm-land framework, also using keycloak to do login with port. I love the Elm Land framework, and it is still well maintained today.

It gave me step-by-step instructions on how to setup the mydoctor-elm project, exactly the same as what Elm Land document says, but using my project name instead. Excellent job!

Then it gave me Main.elm code with port implementation to connect with keycloak.js. I copied to VS Code, and, to my surprise, it passed Elm compiler's type check!

Unfortunately the javascript portion of the code was not correct; it resembled interop examples from the official Elm documentation or online examples. The issue is that, as a framework, Elm Land has its own way to handle port with Javascript; the structure of the JS code is quite different. I think it is because there isn't enough training data (meaning not many open-source projects using Elm Land with ports) for ChatGPT to figure out how to write Javascript code within Elm Land constraints. Besides, its code also didn't handle keycloak login well.

So I read the Elm Land documentation again and wrote my own code. I have to say Elm Land documentation is really good! I quickly finished interop.js and got it working. During the coding process, I asked ChatGPT serval questions about how to handle promise, how to use 'check-sso' for silent authentication, and it gave me correct answers, because those are very common questions.

I posted my interop.js code here so next time when someone ask ChatGPT how to connect keycloak.js with port in Elm Land project, they can get some code that works:

import Keycloak from 'keycloak-js';

var keycloak = new Keycloak({
    url: 'http://auth.mydoctor:8080',
    realm: 'mydoctor-demo',
    clientId: 'mydoctor-elm',
});


// This is called BEFORE your Elm app starts up
// 
// The value returned here will be passed as flags 
// into your `Shared.init` function.
export const flags = ({ env }) => {
}

// This is called AFTER your Elm app starts up
//
// Here you can work with `app.ports` to send messages
// to your Elm application, or subscribe to incoming
// messages from Elm
export const onReady = ({ app, env }) => {

    // Initialize Keycloak
    keycloak
    .init({
        onLoad: 'check-sso',
        silentCheckSsoRedirectUri:
            window.location.origin + '/assets/silent-check-sso.html'
    })
    .then(function (result) {
        if (keycloak.authenticated) {
            app.ports.onLoginSuccess.send(keycloak.token);
        }
    });

    if (app.ports && app.ports.login && app.ports.logout) {

        app.ports.login.subscribe( () => {
            keycloak
            .login()
            .then(function () {
                if (keycloak.authenticated) {
                    app.ports.onLoginSuccess.send(keycloak.token);
                }
            })
            .catch(function () {
                console.error('Failed to login Keycloak');
            });
        })

        app.ports.logout.subscribe( () => {
            console.log("Call logout()");
            keycloak
            .logout()
            .then(function () {
                console.log("After logout: " + keycloak.authenticated);
            })
            .catch(function (err) {
                console.error('Failed to logout Keycloak');
                console.error(err);
            });
        })
    }
}

The full mydoctor-elm project can be found at GitHub.

Overall, after this simple experiment, I was very impressed that its Elm code passed type checking on the first try. However, for situations where answers are not easily found online, it still generates incorrect code, so developers can not fully trust it. For simple tasks, I don't need to search online and read many pages to find the answer, just ask ChatGPT, and the results are pretty good. So ChatGPT o1 is a better coding assistant, my productivity improved a lot. What is your experience with ChatGPT o1 as a developer?

OAuth 2 Token Exchange with Spring Security and Keycloak

Yuan Ji — Sat, 14 Sep 2024 07:07:45 +0000

Introduction

In today's interconnected digital landscape, companies often collaborate to provide seamless services to their users. In this post, we’ll explore a scenario involving two hypothetical companies: MyDoctor and MyHealth. We’ll demonstrate how MyHealth users can log in to MyDoctor using their MyHealth credentials, and how MyDoctor's backend can securely call MyHealth's APIs on behalf of the user. To achieve this, we’ll leverage OAuth 2 Token Exchange (RFC8693) with Spring Security and Keycloak.

All the code can be found in my GitHub project here.

Business Scenario

Let’s start by outlining the scenario:

MyHealth: A service where users can view their health records.
MyDoctor: A service where users can register, log in, and talk to AI doctors to get medical advice.

Now, imagine MyHealth users want to access MyDoctor without creating a new account. Additionally, for MyDoctor's AI bot to give better advice, the backend needs to securely access MyHealth's APIs to retrieve user health records or other user-specific data.

In the past, this could have been done using API key, where MyHealth would assign a unique secret key to MyDoctor for accessing MyHealth API. However, this approach only authenticates the application, meaning MyDoctor would have full access to all of MyHealth’s data, which raises trust and security concerns.

To avoid this, MyHealth needs to authenticate the actual user and apply proper access controls. So, how can MyDoctor impersonate the current logged-in user and access MyHealth’s APIs? We can use OAuth 2’s Token Exchange extension, which allows one token (e.g., from MyDoctor) to be exchanged for another token (e.g., from MyHealth) that has the correct permissions for that user.

Understanding OAuth 2 Token Exchange

Token Exchange RFC 8693 is an extension to the standard OAuth 2.0 that allows a client to exchange an existing token for another token. This is particularly useful in scenarios where:

A client needs to access resources on behalf of the user from multiple APIs.
There is a need to exchange one token (e.g., an ID token or access token) for another token (e.g., an access token with specific permissions or scope).

In this scenario:

A MyHealth user logs into MyDoctor via Keycloak’s identity provider linking.
The MyDoctor backend exchanges the received token for one that allows it to access MyHealth's APIs.

Keycloak Setup and Linking Identity Providers

To enable MyHealth users to log in to MyDoctor via their MyHealth account, we need to configure Keycloak to act as the identity provider (IdP). Since Token Exchange is a preview feature, you have to start the Keycloak server with --features=preview.

Setting up Keycloak for MyHealth

Create a new realm myhealth-demo for the MyHealth keycloak server.
Under the myhealth-demo realm, create a new client myhealth-ui for MyHealth's frontend. Add the client role view-health-record. Since it is a SPA web application, disable Client authentication.
Add a user John Doe, login id john, password john with client role view-health-record.
Create a new client mydoctor-api-server for the MyDoctor backend API server to access MyHealth API endpoints.
Create another client mydoctor-auth for MyDoctor keycloak server to link MyHealth keycloak server as an identity provider.

Setting up Keycloak for MyDoctor

Create a new realm mydoctor-demo for the MyDoctor keycloak server.
Under the mydoctor-demo realm, create a new client mydoctor-ui for MyDoctor's frontend. Add client role edit-appointment and view-appointment. Disable Client authentication.
Add a user doctor with the client role edit-appointment.
Add another client mydoctor-api for the backend API server to do token exchange requests.
In Realm settings, select User registration tab, click button Assign role to add role view-appointment, so any new user will automatically have this role.

Adding MyHealth as an Identity Provider:

In the MyDoctor keycloak server under mydoctor-demo realm, navigate to Identity Providers and select OpenID Connect.
Enter the details of the MyHealth Keycloak server, using the well-known OpenID configuration URL http://auth.myhealth:8090/realms/myhealth-demo/.well-known/openid-configuration.
Enter client ID and secret of mydoctor-auth client from MyHealth keycloak server.
Turn on Store tokens.
Follow the Keycloak documentation 7.3. Internal token to external token exchange, to enable permissions for token exchange, and create a client policy.

It is very tedious to setup Keycloak servers correctly, however, you can find the step-by-step instructions in my Github project to start two Keycloak servers with docker and take a look at all the settings. Just login to Keycloak servers using admin as username and password at http://mydoctor:8080 and http://myhealth:8090.

Implementing OAuth 2 Token Exchange in Spring Security

Token Exchange has been supported in Spring Security since version 6.3. Below, we will demonstrate how MyDoctor’s backend can use this feature to retrieve the health records of a logged-in MyHealth user.

Configure MyHealth API Server App:

The MyHealth backend API myhealth-api is an OAuth 2 resource server. Add the following dependency in build.gradle:



    implementation 'org.springframework.boot:spring-boot-starter-oauth2-resource-server'

Config spring security in ProjectConfig:



@Configuration
@EnableWebSecurity
@EnableMethodSecurity(securedEnabled = true)
public class ProjectConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        // @formatter:off
        http
            .csrf(AbstractHttpConfigurer::disable)
            .cors((cors) -> cors.configurationSource(request -> {
                var corsConfig = new CorsConfiguration();
                corsConfig.setAllowedOrigins(List.of("http://myhealth:4210"));
                corsConfig.setAllowedMethods(
                    List.of("GET", "POST", "OPTIONS", "PUT", "DELETE")
                );
                corsConfig.setAllowedHeaders(List.of("*"));
                corsConfig.setAllowCredentials(true);
                return corsConfig;
            }))
            .authorizeHttpRequests(authorize -> authorize
                .requestMatchers(HttpMethod.OPTIONS, "/**").permitAll()
                .requestMatchers("/api/records").hasAuthority("ROLE_view_health_record")
                .anyRequest().authenticated()
            )
            .oauth2ResourceServer(oauth2ResourceServer -> oauth2ResourceServer
                .jwt( jwt -> jwt.jwtAuthenticationConverter(new KeycloakJwtAuthenticationConverter(List.of("myhealth-ui", "mydoctor-api-server"))))
            )
            ;
        // @formatter:on
        return http.build();
    }

    @Bean
    public JwtDecoder jwtDecoder(OAuth2ResourceServerProperties oAuth2ResourceServerProperties) {
        NimbusJwtDecoder jwtDecoder = NimbusJwtDecoder.withJwkSetUri(oAuth2ResourceServerProperties.getJwt().getJwkSetUri()).build();
        jwtDecoder.setJwtValidator(JwtValidators.createDefaultWithIssuer(oAuth2ResourceServerProperties.getJwt().getIssuerUri()));
        return jwtDecoder;
    }
}

The KeycloakJwtAuthenticationConverter is the Spring Converter to translate OAuth 2 access token claims of resource_access to Spring Security GrantedAuthority. I copied the code from StackOverflow discussion How configure the JwtAuthenticationConverter for a specific claim structure?

And here is the config for resource server in application.yml:



spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: http://auth.myhealth:8090/realms/myhealth-demo
          jwk-set-uri: http://auth.myhealth:8090/realms/myhealth-demo/protocol/openid-connect/certs

Configure MyDoctor API Server App:

MyDoctor API backend needs to call MyHealth API, so it acts as both an OAuth 2 Resource Server and an OAuth 2 Client. Add these dependencies inbuild.gradle:



    implementation 'org.springframework.boot:spring-boot-starter-oauth2-resource-server'
    implementation 'org.springframework.boot:spring-boot-starter-oauth2-client'

In application.yml, configure the two clients myhealth-client and mydoctor-client:



spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: http://auth.mydoctor:8080/realms/mydoctor-demo
          jwk-set-uri: http://auth.mydoctor:8080/realms/mydoctor-demo/protocol/openid-connect/certs
      client:
        registration:
          myhealth-client:
            client-id: mydoctor-api-server
            authorization-grant-type: urn:ietf:params:oauth:grant-type:jwt-bearer
            provider: health-auth-provider
          mydoctor-client:
            client-id: mydoctor-api
            client-secret: nvYxjQFYGdNI8zj5Nb3Jz25ezWgN1cE8
            client-authentication-method: client_secret_basic
            authorization-grant-type: urn:ietf:params:oauth:grant-type:token-exchange
            provider: doctor-auth-provider
        provider:
          doctor-auth-provider:
            token-uri: http://auth.mydoctor:8080/realms/mydoctor-demo/protocol/openid-connect/token
          health-auth-provider:
            token-uri: http://auth.myhealth:8090/realms/myhealth-demo/protocol/openid-connect/token

You can see those two clients have two different providers.

When MyDoctor UI calls backend API endpoint of http://api.mydoctor:8081/api/records, backend API server actually calls MyHealth API endpoint http://api.myhealth:8082/api/record using WebClient:



@RestController
@RequestMapping("/api")
@RequiredArgsConstructor
@Slf4j
public class RecordController {

    private final WebClient webClient;

    @GetMapping("/records")
    public List<Message> getHealthRecords(
        @RegisteredOAuth2AuthorizedClient("mydoctor-client")
        OAuth2AuthorizedClient doctorAuthClient
    ) {
        String token = doctorAuthClient.getAccessToken().getTokenValue();
        log.debug("Exchanged access token is:\n {}\n", token);

        var result = webClient.get()
            .uri("http://api.myhealth:8082/api/records")
            .headers((headers) -> headers.setBearerAuth(token))
            .retrieve()
            .bodyToMono(new ParameterizedTypeReference<List<Message>>() {})
            .block()
            ;
        log.debug("Return result from MyHealth API Server: {}", result);
        return result;
    }
}

We have to impersonate current user as MyHealth user, so we add bearer token to WebClient http request header. The token is coming from injected doctorAuthClient, which is resolved by OAuth2AuthorizedClientArgumentResolver using client registration ID mydoctor-client. This client will call MyDoctor keycloak server to do Token Exchange, passing current login user access token from MyDoctor keycloak, and get a new access token from MyHealth keycloak server.

All the tricky parts are in Spring Security configuration:



    OAuth2AuthorizedClientProvider tokenExchange(
        ClientRegistrationRepository clientRegistrationRepository,
        OAuth2AuthorizedClientRepository authorizedClientRepository
    ) {
        Function<OAuth2AuthorizationContext, OAuth2Token> subjectResolver = (context) -> {
            if (context.getPrincipal() instanceof JwtAuthenticationToken jwtAuthenticationToken) {
                Jwt jwt = jwtAuthenticationToken.getToken();
                OAuth2AccessToken token = new OAuth2AccessToken(TokenType.BEARER, jwt.getTokenValue(), jwt.getIssuedAt(), jwt.getExpiresAt());
                log.debug("Get Access Token for current user from JwtAuthenticationToken: {}", token.getTokenValue());
                return token;
            }

            throw new RuntimeException("Cannot resolve subject token with context principal " + context.getPrincipal() );
        };

        Converter<TokenExchangeGrantRequest, RequestEntity<?>> requestEntityConverter = new TokenExchangeGrantRequestEntityConverter() {
            @Override
            protected MultiValueMap<String, String> createParameters(TokenExchangeGrantRequest grantRequest) {
                MultiValueMap<String, String> parameters = super.createParameters(grantRequest);
                parameters.add("requested_issuer", "myhealth-keycloak-oidc");
                return parameters;
            }
        };
        DefaultTokenExchangeTokenResponseClient accessTokenResponseClient = new DefaultTokenExchangeTokenResponseClient();
        accessTokenResponseClient.setRequestEntityConverter(requestEntityConverter);

        TokenExchangeOAuth2AuthorizedClientProvider authorizedClientProvider =
                new TokenExchangeOAuth2AuthorizedClientProvider();
        authorizedClientProvider.setSubjectTokenResolver(subjectResolver);
        authorizedClientProvider.setAccessTokenResponseClient(accessTokenResponseClient);

        return authorizedClientProvider;
    }

    @Bean
    public OAuth2AuthorizedClientManager authorizedClientManager(
        ClientRegistrationRepository clientRegistrationRepository,
        OAuth2AuthorizedClientService clientService,
        OAuth2AuthorizedClientRepository authorizedClientRepository
    ) {
        OAuth2AuthorizedClientProvider authorizedClientProvider =
                OAuth2AuthorizedClientProviderBuilder.builder()
                        .refreshToken()
                        .clientCredentials()
                        .provider(tokenExchange(clientRegistrationRepository, authorizedClientRepository))
                        .build();

        AuthorizedClientServiceOAuth2AuthorizedClientManager authorizedClientManager =
                new AuthorizedClientServiceOAuth2AuthorizedClientManager(clientRegistrationRepository, clientService);

        authorizedClientManager.setAuthorizedClientProvider(authorizedClientProvider);

        return authorizedClientManager;
    }

    @Bean
    WebClient webClient(OAuth2AuthorizedClientManager authorizedClientManager) {
        ServletOAuth2AuthorizedClientExchangeFilterFunction oauth2Client =
                new ServletOAuth2AuthorizedClientExchangeFilterFunction(authorizedClientManager);
        oauth2Client.setDefaultClientRegistrationId("myhealth-client");

        return WebClient.builder()
                .apply(oauth2Client.oauth2Configuration())
                .build();
    }

It took me several days to get it working! I got the idea from Spring Security project issue discussion, and Keycloak documentation.

First, using subjectResolver to get JWT token from current security context, because we are using KeycloakJwtAuthenticationConverter to store JwtAuthenticationToken object as Principal. Pass it to TokenExchangeOAuth2AuthorizedClientProvider, so this client provider can call MyDoctor keycloak server with current login user’s access token.

Second, Keycloak server implements RFC8693 Token Exchange a little differently:

Token exchange in Keycloak is a very loose implementation of the OAuth Token Exchange specification at the IETF. We have extended it a little, ignored some of it, and loosely interpreted other parts of the specification.

The Keycloak token exchange request parameters include requested_issuer, which is the alias of the ID provider in MyDoctor configuration, the MyHealth Keycloak, and its alias is myhealth-keycloak-oidc. Since requested_issuer is not the standard RFC8693 request parameters, Spring Security doesn’t support it as well. Fortunately I can hack TokenExchangeOAuth2AuthorizedClientProvider with a customized OAuth2AccessTokenResponseClient to set requested_issuer parameter inside TokenExchangeGrantRequestEntityConverter. See above code in tokenExchange().

Third, config OAuth2AuthorizedClientManager with OAuth2AuthorizedClientProvider from tokenExchange(), so our doctorAuthClient above can call MyDoctor Keycloak server to do token exchange as client ID mydoctor-api!

Last, build WebClient with ServletOAuth2AuthorizedClientExchangeFilterFunction, passing client registration ID myhealth-client, so this WebClient will be able to call MyHealth API as client ID mydoctor-api-server, but we use the access token exchanged from MyDoctor Keycloak server as bearer token.

You can open MyDoctor UI at http://mydoctor:4200,

and click Login button, to redirect to MyDoctor Keycloak Login Page:

Then click MyHealth Keycloak button to login with MyHealth Keycloak server:

You can see the host changed from auth.mydoctor:8080 to auth.myhealth:8090.

Login with MyHealth user John Doe (username and password as john), you can see in MyDoctor Keycloak server admin console, under mydoctor-demo realm, a new user john was added, and this user has links to another identity provider Myhealth-keycloak-oidc.

In MyDoctor UI, after login, you can click button call http://api.mydoctor:8081/api/records, so UI will call MyDoctor backend, and backend server actually will first call MyDoctor Keycloak server to do Token Exchange, then call MyHealth API server to get user health records.

From mydoctor-api server log, we can find out the access token used by MyDoctor UI is



{
  "exp": 1726293365,
  "iat": 1726293065,
  "auth_time": 1726293065,
  "jti": "c01fc98f-f959-42ba-a25b-7e8e1a29dc12",
  "iss": "http://auth.mydoctor:8080/realms/mydoctor-demo",
  "aud": [
    "broker",
    "account"
  ],
  "sub": "5adba68d-c9cc-487d-a9e2-62bfae549483",
  "typ": "Bearer",
  "azp": "mydoctor-ui",
  "sid": "40cd230f-a5af-4308-84dc-e5f856bc0a0e",
  "acr": "1",
  "allowed-origins": [
    "http://mydoctor:4200"
  ],
  "realm_access": {
    "roles": [
      "default-roles-mydoctor-demo",
      "offline_access",
      "uma_authorization"
    ]
  },
  "resource_access": {
    "mydoctor-ui": {
      "roles": [
        "view-appointment"
      ]
    },
    "broker": {
      "roles": [
        "read-token"
      ]
    },
    "account": {
      "roles": [
        "manage-account",
        "manage-account-links",
        "view-profile"
      ]
    }
  },
  "scope": "openid email profile",
  "email_verified": false,
  "name": "John Doe",
  "preferred_username": "john",
  "given_name": "John",
  "family_name": "Doe",
  "email": "john.doe@demo.com"
}

And after token exchange, the access token used by MyDoctor API server:



{
  "exp": 1726293365,
  "iat": 1726293065,
  "auth_time": 1726293065,
  "jti": "6c221b25-9b49-45e1-975a-88448104050d",
  "iss": "http://auth.myhealth:8090/realms/myhealth-demo",
  "aud": [
    "myhealth-ui",
    "account"
  ],
  "sub": "1b0d98b6-ea18-4dbd-9d6e-a83e621c07c2",
  "typ": "Bearer",
  "azp": "mydoctor-auth",
  "sid": "531b04de-1ac5-4b04-8125-4c8ca10872bf",
  "acr": "1",
  "allowed-origins": [
    "http://auth.mydoctor:8080/*"
  ],
  "realm_access": {
    "roles": [
      "default-roles-myhealth-demo",
      "offline_access",
      "uma_authorization"
    ]
  },
  "resource_access": {
    "myhealth-ui": {
      "roles": [
        "view-health-record"
      ]
    },
    "account": {
      "roles": [
        "manage-account",
        "manage-account-links",
        "view-profile"
      ]
    }
  },
  "scope": "openid profile email",
  "email_verified": true,
  "name": "John Doe",
  "preferred_username": "john",
  "given_name": "John",
  "family_name": "Doe",
  "email": "john.doe@demo.com"
}

Before exchange, the access token has the role of view-appointment for mydoctor-ui, and after exchange, it has the role of view-health-record for myhealth-ui. Quite amazing!

Conclusion

Recently, I designed and implemented an integration allowing users to log in to Company A using Company B’s account and access Company B’s APIs on the user’s behalf. By combining Keycloak’s identity provider linking and the OAuth 2 Token Exchange protocol, we can provide a seamless experience while maintaining secure API calls between different systems.

However, as of September 2024, Token Exchange is still a preview feature in Keycloak, and Spring Security has only recently added support for it. I hope this guide helps others attempting to implement this functionality in their projects.