feat(dgw): add jet_cred_id KDC claim (#1786)

Introduces the `jet_cred_id` KDC claim and a typed `KdcDestination`
wrapper at the token-claims layer, plumbed through the Gateway,
`tokengen` and the `Devolutions.Gateway.Utils` NuGet package.

A KDC session token now has two mutually exclusive shapes:

* `{ krb_realm, krb_kdc }` — forward traffic to a real upstream KDC
(existing behavior, no wire change).
* `{ jet_cred_id }` — serve KDC traffic locally using the credentials
provisioned at session establishment, identified by the JTI of the
access token that carries them.

Co-authored-by: irving ou <jou@devolutions.net>

Author: CBenoit

devolutions-gateway/src/api/kdc_proxy.rs

@@ -13,7 +13,7 @@ use tokio::net::{TcpStream, UdpSocket};
 use crate::DgwState;
 use crate::http::{HttpError, HttpErrorBuilder};
 use crate::target_addr::TargetAddr;
-use crate::token::AccessTokenClaims;
+use crate::token::{AccessTokenClaims, KdcDestination};
 
 pub fn make_router<S>(state: DgwState) -> Router<S> {
     Router::new().route("/{token}", post(kdc_proxy)).with_state(state)
@@ -66,15 +66,24 @@ async fn kdc_proxy(
 
     debug!("Request is for realm (target_domain): {realm}");
 
-    if !claims.krb_realm.eq_ignore_ascii_case(&realm) {
+    let (claims_realm, claims_kdc) = match &claims.destination {
+        KdcDestination::Real { krb_realm, krb_kdc } => (krb_realm, krb_kdc),
+        KdcDestination::Inject { .. } => {
+            // TODO(DGW-378): dispatch credential-injection KDC requests to the in-process
+            // sspi-rs server backed by the credentials provisioned at session establishment.
+            return Err(HttpError::internal().msg("credential injection KDC dispatch is not implemented yet"));
+        }
+    };
+
+    if !claims_realm.eq_ignore_ascii_case(&realm) {
         if conf.debug.disable_token_validation {
             warn!(
-                token_realm = %claims.krb_realm,
+                token_realm = %claims_realm,
                 request_realm = %realm,
                 "**DEBUG OPTION** Allowed a KDC request towards a KDC whose Kerberos realm differs from what's inside the KDC token"
             );
         } else {
-            let error_message = format!("expected: {}, got: {}", claims.krb_realm, realm);
+            let error_message = format!("expected: {}, got: {}", claims_realm, realm);
 
             return Err(HttpError::bad_request()
                 .with_msg("requested domain is not allowed")
@@ -102,7 +111,7 @@ async fn kdc_proxy(
         warn!("**DEBUG OPTION** KDC address has been overridden with {kdc_addr}");
         kdc_addr
     } else {
-        &claims.krb_kdc
+        claims_kdc
     };
 
     let kdc_reply_message = send_krb_message(kdc_addr, &kdc_proxy_message.kerb_message.0.0).await?;

devolutions-gateway/src/api/webapp.rs

@@ -386,8 +386,10 @@ pub(crate) async fn sign_session_token(
 
         SessionTokenContentType::Kdc { krb_realm, krb_kdc } => (
             KdcTokenClaims {
-                krb_realm: krb_realm.into(),
-                krb_kdc: krb_kdc.clone(),
+                destination: crate::token::KdcDestination::Real {
+                    krb_realm: krb_realm.into(),
+                    krb_kdc: krb_kdc.clone(),
+                },
             }
             .pipe(serde_json::to_value)
             .map(|mut claims| {

devolutions-gateway/src/token.rs

@@ -604,18 +604,36 @@ pub struct JrecTokenClaims {
 
 #[derive(Clone)]
 pub struct KdcTokenClaims {
-    /// Kerberos realm.
-    ///
-    /// E.g.: `ad.it-help.ninja`
-    /// Should be lowercased (actual validation is case-insensitive though).
-    pub krb_realm: SmolStr,
+    /// Where the KDC traffic for this session is routed.
+    pub destination: KdcDestination,
+}
 
-    /// Kerberos KDC address.
+/// Destination for a KDC session token.
+///
+/// Either a real upstream KDC (the typical case, with `krb_realm` + `krb_kdc` on the wire) or
+/// a credential-injection placeholder pointing at the JTI of the access token whose credentials
+/// must be used to forge Kerberos tickets locally (the `jet_cred_id` claim on the wire).
+#[derive(Clone)]
+pub enum KdcDestination {
+    /// Forward to an upstream KDC.
+    Real {
+        /// Kerberos realm.
+        ///
+        /// E.g.: `ad.it-help.ninja`
+        /// Should be lowercased (actual validation is case-insensitive though).
+        krb_realm: SmolStr,
+
+        /// Kerberos KDC address.
+        ///
+        /// E.g.: `tcp://IT-HELP-DC.ad.it-help.ninja:88`
+        /// Default scheme is `tcp`.
+        /// Default port is `88`.
+        krb_kdc: TargetAddr,
+    },
+    /// Serve the request locally using credentials injected at session establishment.
     ///
-    /// E.g.: `tcp://IT-HELP-DC.ad.it-help.ninja:88`
-    /// Default scheme is `tcp`.
-    /// Default port is `88`.
-    pub krb_kdc: TargetAddr,
+    /// `jti` is the JTI of the access token that provisioned the credentials to use.
+    Inject { jti: Uuid },
 }
 
 // ----- jrl claims ----- //
@@ -1389,8 +1407,12 @@ mod serde_impl {
 
     #[derive(Serialize, Deserialize)]
     struct KdcClaimsHelper {
-        krb_realm: SmolStr,
-        krb_kdc: SmolStr,
+        #[serde(default, skip_serializing_if = "Option::is_none")]
+        krb_realm: Option<SmolStr>,
+        #[serde(default, skip_serializing_if = "Option::is_none")]
+        krb_kdc: Option<SmolStr>,
+        #[serde(default, skip_serializing_if = "Option::is_none")]
+        jet_cred_id: Option<Uuid>,
     }
 
     impl ser::Serialize for SessionTtl {
@@ -1637,11 +1659,20 @@ mod serde_impl {
         where
             S: serde::Serializer,
         {
-            KdcClaimsHelper {
-                krb_realm: self.krb_realm.clone(),
-                krb_kdc: SmolStr::new(self.krb_kdc.as_str()),
-            }
-            .serialize(serializer)
+            let helper = match &self.destination {
+                KdcDestination::Real { krb_realm, krb_kdc } => KdcClaimsHelper {
+                    krb_realm: Some(krb_realm.clone()),
+                    krb_kdc: Some(SmolStr::new(krb_kdc.as_str())),
+                    jet_cred_id: None,
+                },
+                KdcDestination::Inject { jti } => KdcClaimsHelper {
+                    krb_realm: None,
+                    krb_kdc: None,
+                    jet_cred_id: Some(*jti),
+                },
+            };
+
+            helper.serialize(serializer)
         }
     }
 
@@ -1654,28 +1685,42 @@ mod serde_impl {
 
             let claims = KdcClaimsHelper::deserialize(deserializer)?;
 
-            // Validate krb_realm value
+            let destination = match (claims.krb_realm, claims.krb_kdc, claims.jet_cred_id) {
+                (Some(krb_realm), Some(krb_kdc), None) => {
+                    // Validate krb_realm value
 
-            if claims.krb_realm.chars().any(char::is_uppercase) {
-                return Err(de::Error::custom("krb_realm field contains uppercases"));
-            }
+                    if krb_realm.chars().any(char::is_uppercase) {
+                        return Err(de::Error::custom("krb_realm field contains uppercases"));
+                    }
+
+                    // Validate krb_kdc field
 
-            // Validate krb_kdc field
+                    let krb_kdc = TargetAddr::parse(&krb_kdc, DEFAULT_KDC_PORT).map_err(de::Error::custom)?;
+                    match krb_kdc.scheme() {
+                        "tcp" | "udp" => { /* supported! */ }
+                        unsupported_scheme => {
+                            return Err(de::Error::custom(format!(
+                                "unsupported protocol for KDC proxy: {unsupported_scheme}"
+                            )));
+                        }
+                    }
 
-            let krb_kdc = TargetAddr::parse(&claims.krb_kdc, DEFAULT_KDC_PORT).map_err(de::Error::custom)?;
-            match krb_kdc.scheme() {
-                "tcp" | "udp" => { /* supported! */ }
-                unsupported_scheme => {
-                    return Err(de::Error::custom(format!(
-                        "unsupported protocol for KDC proxy: {unsupported_scheme}"
-                    )));
+                    KdcDestination::Real { krb_realm, krb_kdc }
                 }
-            }
+                (None, None, Some(jti)) => KdcDestination::Inject { jti },
+                (None, None, None) => {
+                    return Err(de::Error::custom(
+                        "missing KDC destination: expected `krb_realm`+`krb_kdc` or `jet_cred_id`",
+                    ));
+                }
+                _ => {
+                    return Err(de::Error::custom(
+                        "conflicting KDC destination fields: `jet_cred_id` is mutually exclusive with `krb_realm`+`krb_kdc`",
+                    ));
+                }
+            };
 
-            Ok(Self {
-                krb_realm: claims.krb_realm,
-                krb_kdc,
-            })
+            Ok(Self { destination })
         }
     }
 }

tools/tokengen/src/lib.rs

@@ -99,8 +99,12 @@ pub struct JrecClaims {
 
 #[derive(Clone, Serialize)]
 pub struct KdcClaims<'a> {
-    pub krb_realm: &'a str,
-    pub krb_kdc: &'a str,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub krb_realm: Option<&'a str>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub krb_kdc: Option<&'a str>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub jet_cred_id: Option<Uuid>,
     #[serde(skip_serializing_if = "Option::is_none")]
     pub jet_gw_id: Option<Uuid>,
     pub exp: i64,
@@ -257,8 +261,9 @@ pub enum SubCommandArgs {
         jet_reuse: Option<u32>,
     },
     Kdc {
-        krb_realm: String,
-        krb_kdc: String,
+        krb_realm: Option<String>,
+        krb_kdc: Option<String>,
+        jet_cred_id: Option<Uuid>,
     },
     Jrl {
         revoked_jti_list: Vec<Uuid>,
@@ -452,14 +457,36 @@ pub fn generate_token(
             };
             ("JREC", serde_json::to_value(claims)?)
         }
-        SubCommandArgs::Kdc { krb_realm, krb_kdc } => {
-            let claims = KdcClaims {
-                exp,
-                nbf,
-                krb_realm: &krb_realm,
-                krb_kdc: &krb_kdc,
-                jet_gw_id,
-                jti,
+        SubCommandArgs::Kdc {
+            krb_realm,
+            krb_kdc,
+            jet_cred_id,
+        } => {
+            let claims = match (krb_realm.as_deref(), krb_kdc.as_deref(), jet_cred_id) {
+                (Some(krb_realm), Some(krb_kdc), None) => KdcClaims {
+                    exp,
+                    nbf,
+                    krb_realm: Some(krb_realm),
+                    krb_kdc: Some(krb_kdc),
+                    jet_cred_id: None,
+                    jet_gw_id,
+                    jti,
+                },
+                (None, None, Some(jet_cred_id)) => KdcClaims {
+                    exp,
+                    nbf,
+                    krb_realm: None,
+                    krb_kdc: None,
+                    jet_cred_id: Some(jet_cred_id),
+                    jet_gw_id,
+                    jti,
+                },
+                _ => {
+                    return Err(
+                        "KDC subcommand requires either both --krb-realm and --krb-kdc, or only --jet-cred-id (mutually exclusive)"
+                            .into(),
+                    );
+                }
             };
             ("KDC", serde_json::to_value(claims)?)
         }

tools/tokengen/src/main.rs

@@ -122,7 +122,15 @@ fn sign(
             jet_aid,
             jet_reuse,
         },
-        SignSubCommand::Kdc { krb_realm, krb_kdc } => SubCommandArgs::Kdc { krb_realm, krb_kdc },
+        SignSubCommand::Kdc {
+            krb_realm,
+            krb_kdc,
+            jet_cred_id,
+        } => SubCommandArgs::Kdc {
+            krb_realm,
+            krb_kdc,
+            jet_cred_id,
+        },
         SignSubCommand::Jrl { jti } => SubCommandArgs::Jrl { revoked_jti_list: jti },
         SignSubCommand::NetScan {} => SubCommandArgs::NetScan {},
     };
@@ -255,9 +263,11 @@ enum SignSubCommand {
     },
     Kdc {
         #[clap(long)]
-        krb_realm: String,
+        krb_realm: Option<String>,
+        #[clap(long)]
+        krb_kdc: Option<String>,
         #[clap(long)]
-        krb_kdc: String,
+        jet_cred_id: Option<Uuid>,
     },
     Jrl {
         #[clap(long)]

tools/tokengen/src/server/server_impl.rs

@@ -212,6 +212,7 @@ pub(crate) async fn kdc_handler(
         SubCommandArgs::Kdc {
             krb_realm: request.krb_realm,
             krb_kdc: request.krb_kdc,
+            jet_cred_id: request.jet_cred_id,
         },
     )
     .await
@@ -339,8 +340,12 @@ pub(crate) struct JrecRequest {
 pub(crate) struct KdcRequest {
     #[serde(flatten)]
     common: CommonRequest,
-    krb_realm: String,
-    krb_kdc: String,
+    #[serde(default)]
+    krb_realm: Option<String>,
+    #[serde(default)]
+    krb_kdc: Option<String>,
+    #[serde(default)]
+    jet_cred_id: Option<Uuid>,
 }
 
 #[derive(Deserialize)]

utils/dotnet/Devolutions.Gateway.Utils.Tests/JsonSerializationTests.cs

@@ -17,6 +17,16 @@ public void KdcClaims()
         Assert.Equal(EXPECTED, result);
     }
 
+    [Fact]
+    public void KdcClaimsForCredentialInjection()
+    {
+        const string EXPECTED = """{"jet_cred_id":"2dd6fb87-5340-4a85-9e96-d383ebef8a41","jet_gw_id":"ccbaad3f-4627-4666-8bb5-cb6a1a7db815"}""";
+
+        var claims = Devolutions.Gateway.Utils.KdcClaims.ForCredentialInjection(gatewayId, Guid.Parse("2dd6fb87-5340-4a85-9e96-d383ebef8a41"));
+        string result = JsonSerializer.Serialize(claims);
+        Assert.Equal(EXPECTED, result);
+    }
+
     [Fact]
     public void JmuxClaims()
     {

utils/dotnet/Devolutions.Gateway.Utils/src/KdcClaims.cs

@@ -5,9 +5,17 @@ namespace Devolutions.Gateway.Utils;
 public class KdcClaims : IGatewayClaims
 {
     [JsonPropertyName("krb_kdc")]
-    public TargetAddr KrbKdc { get; set; }
+    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+    public TargetAddr? KrbKdc { get; set; }
+
     [JsonPropertyName("krb_realm")]
-    public string KrbRealm { get; set; }
+    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+    public string? KrbRealm { get; set; }
+
+    [JsonPropertyName("jet_cred_id")]
+    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+    public Guid? JetCredId { get; set; }
+
     [JsonPropertyName("jet_gw_id")]
     public Guid ScopeGatewayId { get; set; }
 
@@ -18,6 +26,23 @@ public KdcClaims(Guid scopeGatewayId, TargetAddr krbKdc, string krbRealm)
         this.ScopeGatewayId = scopeGatewayId;
     }
 
+    private KdcClaims(Guid scopeGatewayId, Guid jetCredId)
+    {
+        this.JetCredId = jetCredId;
+        this.ScopeGatewayId = scopeGatewayId;
+    }
+
+    /// <summary>
+    /// Build a KDC claims set whose KDC traffic is served locally using credentials provisioned
+    /// at session establishment, rather than forwarded to an upstream KDC.
+    /// </summary>
+    /// <param name="scopeGatewayId">Target Gateway identifier.</param>
+    /// <param name="jetCredId">JTI of the access token whose credentials must be used.</param>
+    public static KdcClaims ForCredentialInjection(Guid scopeGatewayId, Guid jetCredId)
+    {
+        return new KdcClaims(scopeGatewayId, jetCredId);
+    }
+
     public string GetContentType()
     {
         return "KDC";