proto: pass the scope parameter as returned from the token endpoint

in the OIDC_scope header/environment variable and make it available for
`Require claim scope:` purposes if not available as a claim returned in
the id_token or userinfo endpoint

Signed-off-by: Hans Zandbelt <[email protected]>

Author: zandbelt

ChangeLog

@@ -1,3 +1,8 @@
+04/08/2025
+- proto: pass the scope parameter as returned from the token endpoint in the OIDC_scope
+  header/environment variable and make it available for `Require claim scope:` purposes
+  if not available as a claim returned in the id_token or userinfo endpoint
+
 04/07/2025
 - allow for regular Apache processing (e.g. setting response/security headers)
   by deferring HTML/HTTP output generation to the content handler (instead of user id check handler)

src/cache/shm.c

@@ -302,7 +302,7 @@ static apr_byte_t oidc_cache_shm_set(request_rec *r, const char *section, const
 	if (value != NULL) {
 
 		/* fill out the entry with the provided data */
-		_oidc_strncpy(t->section_key, section_key, OIDC_CACHE_SHM_KEY_MAX-1);
+		_oidc_strncpy(t->section_key, section_key, OIDC_CACHE_SHM_KEY_MAX - 1);
 		_oidc_strcpy(t->value, value);
 		t->expires = expiry;
 		t->access = current_time;

src/handle/authz.c

@@ -384,7 +384,8 @@ static void oidc_authz_error_add(request_rec *r, const char *msg) {
 /*
  * get the claims and id_token from request state
  */
-static void oidc_authz_get_claims_and_idtoken(request_rec *r, json_t **claims, json_t **id_token) {
+static void oidc_authz_get_claims_idtoken_scope(request_rec *r, json_t **claims, json_t **id_token,
+						const char **scope) {
 
 	const char *s_claims = oidc_request_state_get(r, OIDC_REQUEST_STATE_KEY_CLAIMS);
 	if (s_claims != NULL)
@@ -393,6 +394,8 @@ static void oidc_authz_get_claims_and_idtoken(request_rec *r, json_t **claims, j
 	const char *s_id_token = oidc_request_state_get(r, OIDC_REQUEST_STATE_KEY_IDTOKEN);
 	if (s_id_token != NULL)
 		oidc_util_decode_json_object(r, s_id_token, id_token);
+
+	*scope = oidc_request_state_get(r, OIDC_REQUEST_STATE_KEY_SCOPE);
 }
 
 #if HAVE_APACHE_24
@@ -537,6 +540,38 @@ static authz_status oidc_authz_24_unauthorized_user(request_rec *r) {
 	return AUTHZ_DENIED;
 }
 
+/*
+ * merge the claims from the userinfo endpoint, the claims from the id_token, and the scope returned
+ * from the userinfo endpoint into a single set of claims that can be used to authorize on
+ */
+static json_t *oidc_authz_merge_claims(request_rec *r) {
+	json_t *claims = NULL, *id_token = NULL;
+	const char *scope = NULL;
+
+	/* get the set of claims from the request state as they have been set in the authentication part earlier */
+	oidc_authz_get_claims_idtoken_scope(r, &claims, &id_token, &scope);
+
+	json_t *result = json_object();
+
+	/* if scope was returned from the token endpoint, include it in the set of authorization claims */
+	if (scope)
+		json_object_set_new(result, OIDC_CLAIM_SCOPE, json_string(scope));
+
+	/* merge userinfo claims into the authorization claims (take precedence over scope) */
+	if (claims)
+		oidc_util_json_merge(r, claims, result);
+
+	/* merge id_token claims (e.g. "iss") into the authorization claims (take precedence over userinfo claims and
+	 * scope) */
+	oidc_util_json_merge(r, id_token, result);
+
+	if (id_token)
+		json_decref(id_token);
+	if (claims)
+		json_decref(claims);
+
+	return result;
+}
 /*
  * generic Apache >=2.4 authorization hook for this module
  * handles both OpenID Connect or OAuth 2.0 in the same way, based on the claims stored in the session
@@ -557,22 +592,14 @@ authz_status oidc_authz_24_checker(request_rec *r, const char *require_args, con
 	}
 
 	/* get the set of claims from the request state (they've been set in the authentication part earlier */
-	json_t *claims = NULL, *id_token = NULL;
-	oidc_authz_get_claims_and_idtoken(r, &claims, &id_token);
-
-	/* merge id_token claims (e.g. "iss") in to claims json object */
-	if (claims)
-		oidc_util_json_merge(r, id_token, claims);
+	json_t *claims = oidc_authz_merge_claims(r);
 
 	/* dispatch to the >=2.4 specific authz routine */
-	authz_status rc =
-	    oidc_authz_24_worker(r, claims ? claims : id_token, require_args, parsed_require_args, match_claim_fn);
+	authz_status rc = oidc_authz_24_worker(r, claims, require_args, parsed_require_args, match_claim_fn);
 
 	/* cleanup */
 	if (claims)
 		json_decref(claims);
-	if (id_token)
-		json_decref(id_token);
 
 	if ((rc == AUTHZ_DENIED) && ap_auth_type(r))
 		rc = oidc_authz_24_unauthorized_user(r);
@@ -753,8 +780,7 @@ int oidc_authz_22_checker(request_rec *r) {
 	}
 
 	/* get the set of claims from the request state (they've been set in the authentication part earlier */
-	json_t *claims = NULL, *id_token = NULL;
-	oidc_authz_get_claims_and_idtoken(r, &claims, &id_token);
+	json_t *claims = oidc_authz_merge_claims(r);
 
 	/* get the Require statements */
 	const apr_array_header_t *const reqs_arr = ap_requires(r);
@@ -766,18 +792,12 @@ int oidc_authz_22_checker(request_rec *r) {
 		return DECLINED;
 	}
 
-	/* merge id_token claims (e.g. "iss") in to claims json object */
-	if (claims)
-		oidc_util_json_merge(r, id_token, claims);
-
 	/* dispatch to the <2.4 specific authz routine */
 	int rc = oidc_authz_22_worker(r, claims ? claims : id_token, reqs, reqs_arr->nelts);
 
 	/* cleanup */
 	if (claims)
 		json_decref(claims);
-	if (id_token)
-		json_decref(id_token);
 
 	if ((rc == HTTP_UNAUTHORIZED) && ap_auth_type(r))
 		rc = oidc_authz_22_unauthorized_user(r);

src/handle/handle.h

@@ -116,12 +116,6 @@ apr_byte_t oidc_response_post_preserve_javascript(request_rec *r, const char *lo
 char *oidc_response_make_sid_iss_unique(request_rec *r, const char *sid, const char *issuer);
 int oidc_response_authorization_redirect(request_rec *r, oidc_cfg_t *c, oidc_session_t *session);
 int oidc_response_authorization_post(request_rec *r, oidc_cfg_t *c, oidc_session_t *session);
-apr_byte_t oidc_response_save_in_session(request_rec *r, oidc_cfg_t *c, oidc_session_t *session,
-					 oidc_provider_t *provider, const char *remoteUser, const char *id_token,
-					 oidc_jwt_t *id_token_jwt, const char *claims, const char *access_token,
-					 const char *access_token_type, const int expires_in, const char *refresh_token,
-					 const char *session_state, const char *state, const char *original_url,
-					 const char *userinfo_jwt);
 
 // revoke.c
 int oidc_revoke_session(request_rec *r, oidc_cfg_t *c);

src/handle/refresh.c

@@ -202,6 +202,7 @@ apr_byte_t oidc_refresh_token_grant(request_rec *r, oidc_cfg_t *c, oidc_session_
 	char *s_token_type = NULL;
 	char *s_access_token = NULL;
 	char *s_refresh_token = NULL;
+	char *s_scope = NULL;
 	oidc_jwt_t *id_token_jwt = NULL;
 	oidc_jose_error_t err;
 	const char *refresh_token = NULL;
@@ -227,7 +228,7 @@ apr_byte_t oidc_refresh_token_grant(request_rec *r, oidc_cfg_t *c, oidc_session_
 
 	/* refresh the tokens by calling the token endpoint */
 	if (oidc_proto_token_refresh_request(r, c, provider, refresh_token, &s_id_token, &s_access_token, &s_token_type,
-					     &expires_in, &s_refresh_token) == FALSE) {
+					     &expires_in, &s_refresh_token, &s_scope) == FALSE) {
 		OIDC_METRICS_COUNTER_INC(r, c, OM_PROVIDER_REFRESH_ERROR);
 		oidc_error(r, "access_token could not be refreshed with refresh_token: %s", refresh_token);
 		goto end;
@@ -259,6 +260,10 @@ apr_byte_t oidc_refresh_token_grant(request_rec *r, oidc_cfg_t *c, oidc_session_
 	if (s_refresh_token != NULL)
 		oidc_session_set_refresh_token(r, session, s_refresh_token);
 
+	/* see if a new scope was returned from the token endpoint */
+	if (s_scope != NULL)
+		oidc_session_set_scope(r, session, s_scope);
+
 	/* if we have a new id_token, store it in the session and update the session max lifetime if required */
 	if (s_id_token != NULL) {
 

src/handle/response.c

@@ -219,12 +219,12 @@ char *oidc_response_make_sid_iss_unique(request_rec *r, const char *sid, const c
 /*
  * store resolved information in the session
  */
-apr_byte_t oidc_response_save_in_session(request_rec *r, oidc_cfg_t *c, oidc_session_t *session,
-					 oidc_provider_t *provider, const char *remoteUser, const char *id_token,
-					 oidc_jwt_t *id_token_jwt, const char *claims, const char *access_token,
-					 const char *access_token_type, const int expires_in, const char *refresh_token,
-					 const char *session_state, const char *state, const char *original_url,
-					 const char *userinfo_jwt) {
+static apr_byte_t oidc_response_save_in_session(request_rec *r, oidc_cfg_t *c, oidc_session_t *session,
+						oidc_provider_t *provider, const char *remoteUser, const char *id_token,
+						oidc_jwt_t *id_token_jwt, const char *claims, const char *access_token,
+						const char *access_token_type, const int expires_in,
+						const char *refresh_token, const char *scope, const char *session_state,
+						const char *state, const char *original_url, const char *userinfo_jwt) {
 
 	/* store the user in the session */
 	session->remote_user = apr_pstrdup(r->pool, remoteUser);
@@ -290,6 +290,12 @@ apr_byte_t oidc_response_save_in_session(request_rec *r, oidc_cfg_t *c, oidc_ses
 		oidc_session_set_refresh_token(r, session, refresh_token);
 	}
 
+	/* see if a scope was returned from the token endpoint */
+	if (scope != NULL) {
+		/* store the scope in the session context */
+		oidc_session_set_scope(r, session, scope);
+	}
+
 	/* store max session duration in the session as a hard cut-off expiry timestamp */
 	apr_time_t session_expires =
 	    (oidc_cfg_provider_session_max_duration_get(provider) == 0)
@@ -637,8 +643,8 @@ static int oidc_response_process(request_rec *r, oidc_cfg_t *c, oidc_session_t *
 			r, c, session, provider, r->user, apr_table_get(params, OIDC_PROTO_ID_TOKEN), jwt, claims,
 			apr_table_get(params, OIDC_PROTO_ACCESS_TOKEN), apr_table_get(params, OIDC_PROTO_TOKEN_TYPE),
 			expires_in, apr_table_get(params, OIDC_PROTO_REFRESH_TOKEN),
-			apr_table_get(params, OIDC_PROTO_SESSION_STATE), apr_table_get(params, OIDC_PROTO_STATE),
-			original_url, userinfo_jwt) == FALSE) {
+			apr_table_get(params, OIDC_PROTO_SCOPE), apr_table_get(params, OIDC_PROTO_SESSION_STATE),
+			apr_table_get(params, OIDC_PROTO_STATE), original_url, userinfo_jwt) == FALSE) {
 			oidc_proto_state_destroy(proto_state);
 			oidc_jwt_destroy(jwt);
 			return HTTP_INTERNAL_SERVER_ERROR;

src/mod_auth_openidc.c

@@ -580,6 +580,7 @@ static void oidc_copy_tokens_to_request_state(request_rec *r, oidc_session_t *se
 
 	const char *id_token = oidc_session_get_idtoken_claims(r, session);
 	const char *claims = oidc_session_get_userinfo_claims(r, session);
+	const char *scope = oidc_session_get_scope(r, session);
 
 	oidc_debug(r, "id_token=%s claims=%s", id_token, claims);
 
@@ -594,6 +595,9 @@ static void oidc_copy_tokens_to_request_state(request_rec *r, oidc_session_t *se
 		if (s_claims != NULL)
 			*s_claims = claims;
 	}
+
+	if (scope != NULL)
+		oidc_request_state_set(r, OIDC_REQUEST_STATE_KEY_SCOPE, scope);
 }
 
 /*
@@ -637,6 +641,13 @@ apr_byte_t oidc_session_pass_tokens(request_rec *r, oidc_cfg_t *cfg, oidc_sessio
 				       OIDC_DEFAULT_HEADER_PREFIX, pass_in, encoding);
 	}
 
+	/* set the scope in the app headers/variables alongside of the access token, if enabled */
+	const char *scope = oidc_session_get_scope(r, session);
+	if ((oidc_cfg_dir_pass_access_token_get(r) != 0) && scope != NULL) {
+		/* pass it to the app in a header or environment variable */
+		oidc_util_set_app_info(r, OIDC_APP_INFO_SCOPE, scope, OIDC_DEFAULT_HEADER_PREFIX, pass_in, encoding);
+	}
+
 	if (extend_session) {
 		/*
 		 * reset the session inactivity timer

src/mod_auth_openidc.h

@@ -59,6 +59,7 @@
 #define OIDC_REQUEST_STATE_KEY_HTTP "hp"
 #define OIDC_REQUEST_STATE_KEY_HTML "hl"
 #define OIDC_REQUEST_STATE_KEY_IDTOKEN "i"
+#define OIDC_REQUEST_STATE_KEY_SCOPE "sc"
 #define OIDC_REQUEST_STATE_KEY_AUTHN_PRESERVE "p"
 #define OIDC_REQUEST_STATE_KEY_SAVE "s"
 #define OIDC_REQUEST_STATE_TRACE_ID "t"
@@ -124,8 +125,10 @@
 #define OIDC_CLAIM_HTM "htm"
 #define OIDC_CLAIM_HTU "htu"
 #define OIDC_CLAIM_ATH "ath"
+#define OIDC_CLAIM_SCOPE "scope"
 
 #define OIDC_APP_INFO_REFRESH_TOKEN "refresh_token"
+#define OIDC_APP_INFO_SCOPE "scope"
 #define OIDC_APP_INFO_ACCESS_TOKEN "access_token"
 #define OIDC_APP_INFO_ACCESS_TOKEN_TYPE "access_token_type"
 #define OIDC_APP_INFO_ACCESS_TOKEN_EXP "access_token_expires"

src/proto/proto.h

@@ -254,10 +254,10 @@ void oidc_proto_state_set_timestamp_now(oidc_proto_state_t *proto_state);
 // token.c
 apr_byte_t oidc_proto_token_endpoint_request(request_rec *r, oidc_cfg_t *cfg, oidc_provider_t *provider,
 					     apr_table_t *params, char **id_token, char **access_token,
-					     char **token_type, int *expires_in, char **refresh_token);
+					     char **token_type, int *expires_in, char **refresh_token, char **scope);
 apr_byte_t oidc_proto_token_refresh_request(request_rec *r, oidc_cfg_t *cfg, oidc_provider_t *provider,
 					    const char *rtoken, char **id_token, char **access_token, char **token_type,
-					    int *expires_in, char **refresh_token);
+					    int *expires_in, char **refresh_token, char **scope);
 
 // userinfo.c
 apr_byte_t oidc_proto_userinfo_request(request_rec *r, oidc_cfg_t *cfg, oidc_provider_t *provider,

src/proto/response.c

@@ -292,7 +292,8 @@ static apr_byte_t oidc_proto_parse_idtoken_and_validate_code(request_rec *r, oid
  */
 static apr_byte_t oidc_proto_resolve_code(request_rec *r, oidc_cfg_t *cfg, oidc_provider_t *provider, const char *code,
 					  const char *code_verifier, char **id_token, char **access_token,
-					  char **token_type, int *expires_in, char **refresh_token, const char *state) {
+					  char **token_type, int *expires_in, char **refresh_token, char **scope,
+					  const char *state) {
 
 	oidc_debug(r, "enter");
 
@@ -310,7 +311,7 @@ static apr_byte_t oidc_proto_resolve_code(request_rec *r, oidc_cfg_t *cfg, oidc_
 		apr_table_setn(params, OIDC_PROTO_STATE, state);
 
 	return oidc_proto_token_endpoint_request(r, cfg, provider, params, id_token, access_token, token_type,
-						 expires_in, refresh_token);
+						 expires_in, refresh_token, scope);
 }
 
 /*
@@ -326,6 +327,7 @@ static apr_byte_t oidc_proto_resolve_code_and_validate_response(request_rec *r,
 	int expires_in = -1;
 	char *refresh_token = NULL;
 	char *code_verifier = NULL;
+	char *scope = NULL;
 
 	if (oidc_proto_profile_pkce_get(provider) != &oidc_pkce_none)
 		oidc_proto_profile_pkce_get(provider)->verifier(r, oidc_proto_state_get_pkce_state(proto_state),
@@ -334,7 +336,7 @@ static apr_byte_t oidc_proto_resolve_code_and_validate_response(request_rec *r,
 	const char *state = oidc_proto_state_get_state(proto_state);
 
 	if (oidc_proto_resolve_code(r, c, provider, apr_table_get(params, OIDC_PROTO_CODE), code_verifier, &id_token,
-				    &access_token, &token_type, &expires_in, &refresh_token, state) == FALSE) {
+				    &access_token, &token_type, &expires_in, &refresh_token, &scope, state) == FALSE) {
 		oidc_error(r, "failed to resolve the code");
 		OIDC_METRICS_COUNTER_INC(r, c, OM_PROVIDER_TOKEN_ERROR);
 		return FALSE;
@@ -364,6 +366,10 @@ static apr_byte_t oidc_proto_resolve_code_and_validate_response(request_rec *r,
 		apr_table_set(params, OIDC_PROTO_REFRESH_TOKEN, refresh_token);
 	}
 
+	if (scope != NULL) {
+		apr_table_set(params, OIDC_PROTO_SCOPE, scope);
+	}
+
 	return TRUE;
 }
 
@@ -393,6 +399,7 @@ apr_byte_t oidc_proto_response_code_idtoken(request_rec *r, oidc_cfg_t *c, oidc_
 	apr_table_unset(params, OIDC_PROTO_TOKEN_TYPE);
 	apr_table_unset(params, OIDC_PROTO_EXPIRES_IN);
 	apr_table_unset(params, OIDC_PROTO_REFRESH_TOKEN);
+	apr_table_unset(params, OIDC_PROTO_SCOPE);
 
 	if (oidc_proto_resolve_code_and_validate_response(r, c, provider, response_type, params, proto_state) == FALSE)
 		return FALSE;
@@ -420,6 +427,7 @@ apr_byte_t oidc_proto_response_code_token(request_rec *r, oidc_cfg_t *c, oidc_pr
 	/* clear parameters that should only be set from the token endpoint */
 	apr_table_unset(params, OIDC_PROTO_ID_TOKEN);
 	apr_table_unset(params, OIDC_PROTO_REFRESH_TOKEN);
+	apr_table_unset(params, OIDC_PROTO_SCOPE);
 
 	if (oidc_proto_resolve_code_and_validate_response(r, c, provider, response_type, params, proto_state) == FALSE)
 		return FALSE;
@@ -454,6 +462,7 @@ apr_byte_t oidc_proto_response_code(request_rec *r, oidc_cfg_t *c, oidc_proto_st
 	apr_table_unset(params, OIDC_PROTO_EXPIRES_IN);
 	apr_table_unset(params, OIDC_PROTO_ID_TOKEN);
 	apr_table_unset(params, OIDC_PROTO_REFRESH_TOKEN);
+	apr_table_unset(params, OIDC_PROTO_SCOPE);
 
 	if (oidc_proto_resolve_code_and_validate_response(r, c, provider, response_type, params, proto_state) == FALSE)
 		return FALSE;
@@ -520,6 +529,7 @@ apr_byte_t oidc_proto_response_code_idtoken_token(request_rec *r, oidc_cfg_t *c,
 
 	/* clear parameters that should only be set from the token endpoint */
 	apr_table_unset(params, OIDC_PROTO_REFRESH_TOKEN);
+	apr_table_unset(params, OIDC_PROTO_SCOPE);
 
 	if (oidc_proto_resolve_code_and_validate_response(r, c, provider, response_type, params, proto_state) == FALSE)
 		return FALSE;