From dfb35bad628b750b94b30ea7946ee19c11e5c85d Mon Sep 17 00:00:00 2001 From: Mauro Mugnaini Date: Mon, 6 May 2024 18:09:40 +0200 Subject: [PATCH] Added javadoc for token exchange methods and exchage for an offline token now raises an IllegalArgumetException if the original token not contains `offline_access` within its scopes, required by the `v24.0.2` version of the Keycloak --- .../gcube/common/keycloak/KeycloakClient.java | 88 +++++++++++++++++-- 1 file changed, 79 insertions(+), 9 deletions(-) diff --git a/src/main/java/org/gcube/common/keycloak/KeycloakClient.java b/src/main/java/org/gcube/common/keycloak/KeycloakClient.java index 28ccf74..27d9e12 100644 --- a/src/main/java/org/gcube/common/keycloak/KeycloakClient.java +++ b/src/main/java/org/gcube/common/keycloak/KeycloakClient.java @@ -634,24 +634,94 @@ public interface KeycloakClient { */ TokenResponse refreshToken(URL tokenURL, String clientId, String clientSecret, String refreshTokenJWTString) throws KeycloakClientException; - - TokenResponse exchangeTokenForAccessToken(URL tokenURL, String oidcAccessToken, String clientId, - String clientSecret, String audience) throws KeycloakClientException; - + + /** + * Exchanges a token for another access token for a specific client and a specific audience + * + * @param context the context where the Keycloak's is needed (e.g. /gcube for DEV) + * @param oidcAccessToken the original access token to exchange + * @param clientId the authorized client's id + * @param clientSecret the authorized client's secret + * @param audience the requested token audience + * @return the exchanged token response + * @throws KeycloakClientException if an error occurs during the exchange + */ TokenResponse exchangeTokenForAccessToken(String context, String oidcAccessToken, String clientId, String clientSecret, String audience) throws KeycloakClientException; - TokenResponse exchangeTokenForRefreshToken(URL tokenURL, String oidcAccessToken, String clientId, + /** + * Exchanges a token for another access token for a specific client and a specific audience + * + * @param tokenURL the token endpoint URL + * @param oidcAccessToken the original access token to exchange + * @param clientId the authorized client's id + * @param clientSecret the authorized client's secret + * @param audience the requested token audience + * @return the exchanged token response + * @throws KeycloakClientException if an error occurs during the exchange + */ + TokenResponse exchangeTokenForAccessToken(URL tokenURL, String oidcAccessToken, String clientId, String clientSecret, String audience) throws KeycloakClientException; + /** + * Exchanges a token for another access and a refresh tokens for a specific client and a specific audience + * + * @param context the context where the Keycloak's is needed (e.g. /gcube for DEV) + * @param oidcAccessToken the original access token to exchange + * @param clientId the authorized client's id + * @param clientSecret the authorized client's secret + * @param audience the requested token audience + * @return the exchanged token response + * @throws KeycloakClientException if an error occurs during the exchange + */ TokenResponse exchangeTokenForRefreshToken(String context, String oidcAccessToken, String clientId, String clientSecret, String audience) throws KeycloakClientException; -// TokenResponse exchangeTokenForOfflineToken(URL tokenURL, String oidcAccessToken, String clientId, -// String clientSecret, String audience) throws IllegalArgumentException, KeycloakClientException; + /** + * Exchanges a token for another access and a refresh tokens for a specific client and a specific audience + * + * @param tokenURL the token endpoint URL + * @param oidcAccessToken the original access token to exchange + * @param clientId the authorized client's id + * @param clientSecret the authorized client's secret + * @param audience the requested token audience + * @return the exchanged token response + * @throws KeycloakClientException if an error occurs during the exchange + */ + TokenResponse exchangeTokenForRefreshToken(URL tokenURL, String oidcAccessToken, String clientId, + String clientSecret, String audience) throws KeycloakClientException; -// TokenResponse exchangeTokenForOfflineToken(String context, String oidcAccessToken, String clientId, -// String clientSecret, String audience) throws IllegalArgumentException, KeycloakClientException; + /** + * Exchanges a token for another access and an offline refresh tokens for a specific client and a specific audience + * The refresh token will be of the offline type only if the original token has the offline_access within its scopes + * + * @param tokenURL the token endpoint URL + * @param oidcAccessToken the original access token to exchange + * @param clientId the authorized client's id + * @param clientSecret the authorized client's secret + * @param audience the requested token audience + * @return the exchanged token response + * @throws IllegalArgumentException if the original token does'nt contains the offline_access scope within its scopes or if is impossible to parse the access token as JSON + * @throws KeycloakClientException if an error occurs during the exchange + */ + TokenResponse exchangeTokenForOfflineToken(String context, String oidcAccessToken, String clientId, + String clientSecret, String audience) throws IllegalArgumentException, KeycloakClientException; + + /** + * Exchanges a token for another access and an offline refresh tokens for a specific client and a specific audience + * The refresh token will be of the offline type only if the original token has the scope offline_access within its scopes + * + * @param tokenURL the token endpoint URL + * @param oidcAccessToken the original access token to exchange + * @param clientId the authorized client's id + * @param clientSecret the authorized client's secret + * @param audience the requested token audience + * @return the exchanged token response + * @throws IllegalArgumentException if the original token does'nt contains the offline_access scope within its scopes or if is impossible to parse the access token as JSON + * @throws KeycloakClientException if an error occurs during the exchange + */ + TokenResponse exchangeTokenForOfflineToken(URL tokenURL, String oidcAccessToken, String clientId, + String clientSecret, String audience) throws IllegalArgumentException, KeycloakClientException; /** * Introspects an access token against the Keycloak server.