kcenon::pacs::web::auth::oauth2_middleware Class Reference

OAuth 2.0 middleware for DICOMweb endpoint authorization. More...

#include <oauth2_middleware.h>

Collaboration diagram for kcenon::pacs::web::auth::oauth2_middleware:

Public Member Functions
	oauth2_middleware (const oauth2_config &config)
	Construct middleware with OAuth 2.0 configuration.
void	set_jwks_provider (std::shared_ptr< jwks_provider > provider)
	Set the JWKS provider for signature verification.
void	set_access_control_manager (std::shared_ptr< security::access_control_manager > manager)
	Set the access control manager for RBAC integration.
std::optional< auth_result >	authenticate (const crow::request &req, crow::response &res) const
	Authenticate a request using OAuth 2.0 Bearer token.
bool	require_scope (const jwt_claims &claims, crow::response &res, std::string_view required_scope) const
	Check if the authenticated request has a required scope.
bool	require_any_scope (const jwt_claims &claims, crow::response &res, const std::vector< std::string > &required_scopes) const
	Check if the request has any of the required scopes.
bool	enabled () const noexcept
	Check if OAuth 2.0 is enabled.
const jwt_validator &	validator () const noexcept
	Get the underlying JWT validator.

Private Member Functions
std::optional< std::string_view >	extract_bearer_token (const crow::request &req) const
	Extract Bearer token from Authorization header.
bool	verify_signature (const jwt_token &token) const
	Verify token signature using JWKS keys.

Static Private Member Functions
static void	set_unauthorized (crow::response &res, std::string_view message)
	Set 401 Unauthorized response.
static void	set_forbidden (crow::response &res, std::string_view message)
	Set 403 Forbidden response.

Private Attributes
oauth2_config	config_
jwt_validator	validator_
std::shared_ptr< jwks_provider >	jwks_provider_
std::shared_ptr< security::access_control_manager >	security_manager_

Detailed Description

OAuth 2.0 middleware for DICOMweb endpoint authorization.

When OAuth 2.0 is enabled, the middleware:

1. Extracts the Bearer token from the Authorization header
2. Decodes and validates the JWT (issuer, audience, expiration)
3. Verifies the token signature using JWKS keys
4. Checks required scopes for the DICOMweb operation
5. Creates a user_context for the downstream endpoint

When OAuth 2.0 is disabled, the middleware is a no-op and the system falls back to the existing X-User-ID header-based authentication.

Example:

oauth2_config config;
config.enabled = true;
config.issuer = "https://auth.example.com";
 
oauth2_middleware middleware(config);
middleware.set_jwks_provider(jwks);
 
// In endpoint handler:
auto result = middleware.authenticate(req, res);
if (!result) return res;  // Error response already set
 
if (!middleware.require_scope(result->claims, res, dicomweb_scopes::read)) {
    return res;  // 403 Forbidden
}

Definition at line 111 of file oauth2_middleware.h.

Constructor & Destructor Documentation

oauth2_middleware()

kcenon::pacs::web::auth::oauth2_middleware::oauth2_middleware ( const oauth2_config & config )

explicit

Construct middleware with OAuth 2.0 configuration.

Parameters

config

The OAuth 2.0 configuration

Definition at line 32 of file oauth2_middleware.cpp.

    : config_(config), validator_(config) {}

Member Function Documentation

authenticate()

std::optional< auth_result > kcenon::pacs::web::auth::oauth2_middleware::authenticate ( const crow::request & req, crow::response & res ) const

nodiscard

Authenticate a request using OAuth 2.0 Bearer token.

Extracts the Bearer token, validates JWT claims, verifies the signature, and creates an auth_result containing both the user_context and validated claims. On failure, sets an appropriate error response (401 or 403).

Parameters

req	The HTTP request
res	The HTTP response (set on error)

Returns

auth_result on success, std::nullopt on failure

Definition at line 45 of file oauth2_middleware.cpp.

                                                     {
 
    // Extract Bearer token from Authorization header
    auto bearer = extract_bearer_token(req);
    if (!bearer) {
        set_unauthorized(res, "Missing or invalid Authorization header");
        return std::nullopt;
    }
 
    // Decode JWT
    auto [token, decode_err] = validator_.decode(*bearer);
    if (decode_err != jwt_error::none) {
        set_unauthorized(res, std::string(jwt_error_message(decode_err)));
        return std::nullopt;
    }
 
    // Validate claims (issuer, audience, expiration)
    auto claims_err = validator_.validate_claims(token.claims);
    if (claims_err != jwt_error::none) {
        set_unauthorized(res, std::string(jwt_error_message(claims_err)));
        return std::nullopt;
    }
 
    // Verify signature using JWKS
    if (!verify_signature(token)) {
        set_unauthorized(res, "Token signature verification failed");
        return std::nullopt;
    }
 
    // Create user_context from JWT subject
    // Try to find existing user in RBAC system, or create an OAuth-based context
    security::User user;
    user.id = token.claims.sub;
    user.username = token.claims.sub;
    user.active = true;
 
    // If we have an access control manager, try to look up the user
    if (security_manager_) {
        auto user_result = security_manager_->get_user(token.claims.sub);
        if (user_result.is_ok()) {
            user = user_result.unwrap();
        } else if (config_.allow_unknown_users) {
            // Backward compatibility: grant Viewer role to unknown OAuth users
            user.roles = {security::Role::Viewer};
        } else {
            set_unauthorized(res, "Unknown user: not registered in access control system");
            return std::nullopt;
        }
    } else if (config_.allow_unknown_users) {
        user.roles = {security::Role::Viewer};
    } else {
        set_unauthorized(res, "Unknown user: no access control manager configured");
        return std::nullopt;
    }
 
    auto ctx = security::user_context(std::move(user), token.claims.jti);
    ctx.set_source_ip(std::string(req.remote_ip_address));
    ctx.touch();
 
    return auth_result{std::move(ctx), std::move(token.claims)};
}

References kcenon::pacs::web::auth::oauth2_config::allow_unknown_users, config_, kcenon::pacs::web::auth::jwt_validator::decode(), extract_bearer_token(), kcenon::pacs::security::User::id, kcenon::pacs::web::auth::jwt_error_message(), kcenon::pacs::web::auth::none, security_manager_, set_unauthorized(), kcenon::pacs::web::auth::jwt_validator::validate_claims(), validator_, verify_signature(), and kcenon::pacs::security::Viewer.

Here is the call graph for this function:

enabled()

bool kcenon::pacs::web::auth::oauth2_middleware::enabled ( ) const

nodiscardnoexcept

Check if OAuth 2.0 is enabled.

Definition at line 138 of file oauth2_middleware.cpp.

                                               {
    return config_.enabled;
}

References config_, and kcenon::pacs::web::auth::oauth2_config::enabled.

extract_bearer_token()

std::optional< std::string_view > kcenon::pacs::web::auth::oauth2_middleware::extract_bearer_token ( const crow::request & req ) const

nodiscardprivate

Extract Bearer token from Authorization header.

Definition at line 150 of file oauth2_middleware.cpp.

                                  {
 
    auto auth_header = req.get_header_value("Authorization");
    if (auth_header.empty()) return std::nullopt;
 
    std::string_view header_view(auth_header);
 
    // Check for "Bearer " prefix (case-insensitive for "Bearer")
    constexpr std::string_view bearer_prefix = "Bearer ";
    if (header_view.size() <= bearer_prefix.size()) return std::nullopt;
 
    // Case-sensitive check per RFC 6750
    if (header_view.substr(0, bearer_prefix.size()) != bearer_prefix) {
        return std::nullopt;
    }
 
    auto token = header_view.substr(bearer_prefix.size());
    if (token.empty()) return std::nullopt;
 
    return token;
}

Referenced by authenticate().

Here is the caller graph for this function:

require_any_scope()

bool kcenon::pacs::web::auth::oauth2_middleware::require_any_scope ( const jwt_claims & claims, crow::response & res, const std::vector< std::string > & required_scopes ) const

nodiscard

Check if the request has any of the required scopes.

Parameters

claims	JWT claims from a previously validated token
res	The HTTP response (set on failure)
required_scopes	List of acceptable scopes

Returns

true if at least one scope is present

Definition at line 121 of file oauth2_middleware.cpp.

                                                       {
 
    if (!jwt_validator::has_any_scope(claims, required_scopes)) {
        std::string scope_list;
        for (size_t i = 0; i < required_scopes.size(); ++i) {
            if (i > 0) scope_list += " or ";
            scope_list += required_scopes[i];
        }
        set_forbidden(res, "Insufficient scope: requires " + scope_list);
        return false;
    }
    return true;
}

References kcenon::pacs::web::auth::jwt_validator::has_any_scope(), and set_forbidden().

Here is the call graph for this function:

require_scope()

bool kcenon::pacs::web::auth::oauth2_middleware::require_scope ( const jwt_claims & claims, crow::response & res, std::string_view required_scope ) const

nodiscard

Check if the authenticated request has a required scope.

Must be called after authenticate(). Returns false and sets 403 response if the required scope is missing.

Parameters

claims	JWT claims from a previously validated token
res	The HTTP response (set on failure)
required_scope	The required OAuth scope

Returns

true if the scope is present

Definition at line 108 of file oauth2_middleware.cpp.

                                         {
 
    if (!jwt_validator::has_scope(claims, required_scope)) {
        set_forbidden(res,
            "Insufficient scope: requires " + std::string(required_scope));
        return false;
    }
    return true;
}

References kcenon::pacs::web::auth::jwt_validator::has_scope(), and set_forbidden().

Here is the call graph for this function:

set_access_control_manager()

void kcenon::pacs::web::auth::oauth2_middleware::set_access_control_manager

(

std::shared_ptr< security::access_control_manager >

manager

)

Set the access control manager for RBAC integration.

Parameters

manager

Shared pointer to access control manager

Definition at line 40 of file oauth2_middleware.cpp.

                                                           {
    security_manager_ = std::move(manager);
}

References security_manager_.

set_forbidden()

void kcenon::pacs::web::auth::oauth2_middleware::set_forbidden ( crow::response & res, std::string_view message )

staticprivate

Set 403 Forbidden response.

Definition at line 207 of file oauth2_middleware.cpp.

                                                              {
    res.code = 403;
    res.add_header("Content-Type", "application/json");
    res.body = make_error_json("FORBIDDEN", message);
}

References kcenon::pacs::web::make_error_json().

Referenced by require_any_scope(), and require_scope().

Here is the call graph for this function:

Here is the caller graph for this function:

set_jwks_provider()

void kcenon::pacs::web::auth::oauth2_middleware::set_jwks_provider

(

std::shared_ptr< jwks_provider >

provider

)

Set the JWKS provider for signature verification.

Parameters

provider

Shared pointer to JWKS provider

Definition at line 35 of file oauth2_middleware.cpp.

                                           {
    jwks_provider_ = std::move(provider);
}

References jwks_provider_.

set_unauthorized()

void kcenon::pacs::web::auth::oauth2_middleware::set_unauthorized ( crow::response & res, std::string_view message )

staticprivate

Set 401 Unauthorized response.

Definition at line 199 of file oauth2_middleware.cpp.

                                                                 {
    res.code = 401;
    res.add_header("Content-Type", "application/json");
    res.add_header("WWW-Authenticate", "Bearer");
    res.body = make_error_json("UNAUTHORIZED", message);
}

References kcenon::pacs::web::make_error_json().

Referenced by authenticate().

Here is the call graph for this function:

Here is the caller graph for this function:

validator()

const jwt_validator & kcenon::pacs::web::auth::oauth2_middleware::validator ( ) const

nodiscardnoexcept

Get the underlying JWT validator.

Definition at line 142 of file oauth2_middleware.cpp.

                                                                 {
    return validator_;
}

References validator_.

verify_signature()

bool kcenon::pacs::web::auth::oauth2_middleware::verify_signature ( const jwt_token & token ) const

nodiscardprivate

Verify token signature using JWKS keys.

Definition at line 173 of file oauth2_middleware.cpp.

                                                                     {
    if (!jwks_provider_) return false;
 
    // Try to get key by kid from the token header
    std::optional<jwk_key> key;
    if (!token.header.kid.empty()) {
        key = jwks_provider_->get_key(token.header.kid);
    }
 
    // Fall back to algorithm-based lookup
    if (!key) {
        key = jwks_provider_->get_key_by_alg(token.header.alg);
    }
 
    if (!key) return false;
 
    // Verify based on algorithm
    if (token.header.alg == "RS256") {
        return validator_.verify_rs256(token, key->pem);
    } else if (token.header.alg == "ES256") {
        return validator_.verify_es256(token, key->pem);
    }
 
    return false;
}

References kcenon::pacs::web::auth::jwt_header::alg, kcenon::pacs::web::auth::jwt_token::header, jwks_provider_, kcenon::pacs::web::auth::jwt_header::kid, validator_, kcenon::pacs::web::auth::jwt_validator::verify_es256(), and kcenon::pacs::web::auth::jwt_validator::verify_rs256().

Referenced by authenticate().

Here is the call graph for this function:

Here is the caller graph for this function:

Member Data Documentation

config_

oauth2_config kcenon::pacs::web::auth::oauth2_middleware::config_

private

Definition at line 187 of file oauth2_middleware.h.

Referenced by authenticate(), and enabled().

jwks_provider_

std::shared_ptr<jwks_provider> kcenon::pacs::web::auth::oauth2_middleware::jwks_provider_

private

Definition at line 189 of file oauth2_middleware.h.

Referenced by set_jwks_provider(), and verify_signature().

security_manager_

std::shared_ptr<security::access_control_manager> kcenon::pacs::web::auth::oauth2_middleware::security_manager_

private

Definition at line 190 of file oauth2_middleware.h.

Referenced by authenticate(), and set_access_control_manager().

validator_

jwt_validator kcenon::pacs::web::auth::oauth2_middleware::validator_

private

Definition at line 188 of file oauth2_middleware.h.

Referenced by authenticate(), validator(), and verify_signature().

---

The documentation for this class was generated from the following files:

• include/kcenon/pacs/web/auth/oauth2_middleware.h
• src/web/auth/oauth2_middleware.cpp