headless_lms_server/controllers/main_frontend/oauth/
introspect.rs

1use crate::domain::oauth::introspect_query::IntrospectQuery;
2use crate::domain::oauth::introspect_response::IntrospectResponse;
3use crate::domain::oauth::oauth_validated::OAuthValidated;
4use crate::prelude::*;
5use actix_web::{HttpResponse, web};
6use headless_lms_utils::ApplicationConfiguration;
7use models::{
8    library::oauth::token_digest_sha256,
9    oauth_access_token::{OAuthAccessToken, TokenType},
10    oauth_client::OAuthClient,
11};
12use sqlx::PgPool;
13
14/// Handles the `/introspect` endpoint for OAuth 2.0 token introspection (RFC 7662).
15///
16/// This endpoint allows resource servers to query the authorization server about
17/// the active state and metadata of an access token.
18///
19/// ### Security Features
20/// - Client authentication is required (client_id and client_secret for confidential clients)
21/// - Returns `active: false` for invalid/expired tokens or authentication failures
22///   to prevent token enumeration attacks
23/// - Always returns 200 OK, even for invalid tokens (per RFC 7662)
24///
25/// ### Request Parameters
26/// - `token` (required): The token to be introspected
27/// - `token_type_hint` (optional): Hint about token type ("access_token" or "refresh_token")
28/// - `client_id` (required): Client identifier
29/// - `client_secret` (required for confidential clients): Client secret
30///
31/// ### Response
32/// Returns a JSON object with:
33/// - `active` (bool, required): Whether the token is active
34/// - Additional fields only present if `active: true`:
35///   - `scope`: Space-separated list of scopes
36///   - `client_id`: Client identifier
37///   - `username`/`sub`: User identifier (if token has user)
38///   - `exp`: Expiration timestamp (Unix time)
39///   - `iat`: Issued at timestamp (Unix time)
40///   - `aud`: Audience
41///   - `iss`: Issuer
42///   - `jti`: JWT ID
43///   - `token_type`: "Bearer" or "DPoP"
44///
45/// Follows [RFC 7662 — OAuth 2.0 Token Introspection](https://datatracker.ietf.org/doc/html/rfc7662).
46///
47/// # Example
48/// ```http
49/// POST /api/v0/main-frontend/oauth/introspect HTTP/1.1
50/// Content-Type: application/x-www-form-urlencoded
51///
52/// token=ACCESS_TOKEN&client_id=test-client-id&client_secret=test-secret
53/// ```
54///
55/// Successful response:
56/// ```http
57/// HTTP/1.1 200 OK
58/// Content-Type: application/json
59/// Cache-Control: no-store
60///
61/// {
62///   "active": true,
63///   "scope": "openid profile email",
64///   "client_id": "test-client-id",
65///   "sub": "550e8400-e29b-41d4-a716-446655440000",
66///   "username": "550e8400-e29b-41d4-a716-446655440000",
67///   "exp": 1735689600,
68///   "iat": 1735686000,
69///   "iss": "https://example.com/api/v0/main-frontend/oauth",
70///   "jti": "123e4567-e89b-12d3-a456-426614174000",
71///   "token_type": "Bearer"
72/// }
73/// ```
74///
75/// Inactive token response:
76/// ```http
77/// HTTP/1.1 200 OK
78/// Content-Type: application/json
79/// Cache-Control: no-store
80///
81/// {
82///   "active": false
83/// }
84/// ```
85#[instrument(skip(pool, app_conf, form))]
86pub async fn introspect(
87    pool: web::Data<PgPool>,
88    OAuthValidated(form): OAuthValidated<IntrospectQuery>,
89    app_conf: web::Data<ApplicationConfiguration>,
90) -> ControllerResult<HttpResponse> {
91    let mut conn = pool.acquire().await?;
92    let server_token = skip_authorize();
93
94    // Authenticate client
95    // RFC 7662 §2.1: "The authorization server responds with HTTP status code 200
96    // and the introspection result, even if the client authentication failed or
97    // the token is invalid."
98    let client_result = OAuthClient::find_by_client_id(&mut conn, &form.client_id).await;
99
100    // Add non-secret fields to the span for observability
101    tracing::Span::current().record("client_id", &form.client_id);
102
103    // If client not found or secret invalid, return active: false per RFC 7662
104    let client = match client_result {
105        Ok(c) => c,
106        Err(_) => {
107            // Invalid client_id - return active: false per RFC 7662
108            return server_token.authorized_ok(
109                HttpResponse::Ok()
110                    .insert_header(("Cache-Control", "no-store"))
111                    .json(IntrospectResponse {
112                        active: false,
113                        scope: None,
114                        client_id: None,
115                        username: None,
116                        exp: None,
117                        iat: None,
118                        sub: None,
119                        aud: None,
120                        iss: None,
121                        jti: None,
122                        token_type: None,
123                    }),
124            );
125        }
126    };
127
128    // Validate client secret for confidential clients
129    let token_hmac_key = &app_conf.oauth_server_configuration.oauth_token_hmac_key;
130    let client_valid = if client.is_confidential() {
131        match &client.client_secret {
132            Some(secret) => {
133                let provided_secret_digest = token_digest_sha256(
134                    &form.client_secret.clone().unwrap_or_default(),
135                    token_hmac_key,
136                );
137                secret.constant_eq(&provided_secret_digest)
138            }
139            None => false,
140        }
141    } else {
142        true // Public clients don't need secret validation
143    };
144
145    // If client secret is invalid, return active: false per RFC 7662
146    if !client_valid {
147        return server_token.authorized_ok(
148            HttpResponse::Ok()
149                .insert_header(("Cache-Control", "no-store"))
150                .json(IntrospectResponse {
151                    active: false,
152                    scope: None,
153                    client_id: None,
154                    username: None,
155                    exp: None,
156                    iat: None,
157                    sub: None,
158                    aud: None,
159                    iss: None,
160                    jti: None,
161                    token_type: None,
162                }),
163        );
164    }
165
166    // Hash the provided token to get digest
167    let token_digest = token_digest_sha256(&form.token, token_hmac_key);
168
169    // Look up the access token (only access tokens are supported)
170    let access_token_result = OAuthAccessToken::find_valid(&mut conn, token_digest).await;
171
172    // If token not found or expired, return active: false
173    let access_token = match access_token_result {
174        Ok(token) => token,
175        Err(_) => {
176            return server_token.authorized_ok(
177                HttpResponse::Ok()
178                    .insert_header(("Cache-Control", "no-store"))
179                    .json(IntrospectResponse {
180                        active: false,
181                        scope: None,
182                        client_id: None,
183                        username: None,
184                        exp: None,
185                        iat: None,
186                        sub: None,
187                        aud: None,
188                        iss: None,
189                        jti: None,
190                        token_type: None,
191                    }),
192            );
193        }
194    };
195
196    // Add token type to span for observability
197    tracing::Span::current().record("token_type", format!("{:?}", access_token.token_type));
198    tracing::Span::current().record("token_active", "true");
199
200    // Fetch the client that originally issued the token (not the introspecting client)
201    let token_client = OAuthClient::find_by_id(&mut conn, access_token.client_id).await?;
202
203    // Build response with token metadata
204    let base_url = app_conf.base_url.trim_end_matches('/');
205    let issuer = format!("{}/api/v0/main-frontend/oauth", base_url);
206
207    let response = IntrospectResponse {
208        active: true,
209        scope: Some(access_token.scopes.join(" ")),
210        client_id: Some(token_client.client_id.clone()),
211        username: access_token.user_id.map(|id| id.to_string()),
212        exp: Some(access_token.expires_at.timestamp()),
213        iat: Some(access_token.created_at.timestamp()),
214        sub: access_token.user_id.map(|id| id.to_string()),
215        aud: access_token.audience.clone(),
216        iss: Some(issuer),
217        jti: Some(access_token.jti.to_string()),
218        token_type: Some(match access_token.token_type {
219            TokenType::Bearer => "Bearer".to_string(),
220            TokenType::DPoP => "DPoP".to_string(),
221        }),
222    };
223
224    server_token.authorized_ok(
225        HttpResponse::Ok()
226            .insert_header(("Cache-Control", "no-store"))
227            .json(response),
228    )
229}
230
231pub fn _add_routes(cfg: &mut web::ServiceConfig) {
232    cfg.route("/introspect", web::post().to(introspect));
233}
headless_lms_server/controllers/main_frontend/oauth/introspect.rs

headless_lms_server/controllers/main_frontend/oauth/
introspect.rs
