Skip to main content

JsonWebTokenHeader Class

Abblix.Jwt​

Abblix.Jwt​

JsonWebTokenHeader Class​

Represents the header part of a JSON Web Token (JWT), containing metadata about the token such as the type and the algorithm used for signing.

public class JsonWebTokenHeader

Inheritance System.Object → JsonWebTokenHeader

Remarks​

The JWT header typically specifies the cryptographic operations applied to the JWT and can also include additional properties defined or required by the application.

Constructors​

JsonWebTokenHeader(JsonObject) Constructor​

Represents the header part of a JSON Web Token (JWT), containing metadata about the token such as the type and the algorithm used for signing.

public JsonWebTokenHeader(System.Text.Json.Nodes.JsonObject json);

Parameters​

json System.Text.Json.Nodes.JsonObject​

Remarks​

The JWT header typically specifies the cryptographic operations applied to the JWT and can also include additional properties defined or required by the application.

Properties​

JsonWebTokenHeader.Algorithm Property​

The algorithm used to sign the JWT, indicating how the token is secured.

public string? Algorithm { get; set; }

Property Value​

System.String

Remarks​

The 'alg' parameter identifies the cryptographic algorithm used to secure the JWT. Common algorithms include HS256, RS256, and ES256. It is crucial for verifying the JWT integrity. Per RFC 7515 Section 4.1.1, this parameter is REQUIRED.

JsonWebTokenHeader.Certificates Property​

The 'x5c' (X.509 Certificate Chain) header parameter (RFC 7515 §4.1.6): an X.509 certificate chain as a JSON array of base64-encoded DER certificates, the first being the leaf. Returns the raw base64 strings; consumers are responsible for decoding to X509Certificate2 and validating the chain per RFC 5280.

public System.Collections.Generic.IReadOnlyList<string>? Certificates { get; set; }

Property Value​

System.Collections.Generic.IReadOnlyList<System.String>

Exceptions​

System.Text.Json.JsonException
Thrown when 'x5c' is present but is not a JSON array of strings.

JsonWebTokenHeader.CertificateSha1Thumbprint Property​

The 'x5t' (X.509 SHA-1 Thumbprint) header parameter (RFC 7515 §4.1.7): base64url-encoded SHA-1 digest of the DER-encoded leaf certificate. Per RFC 7515 §10.11, SHA-1 is discouraged because of cryptographic weaknesses — prefer CertificateSha256Thumbprint for new deployments. The library exposes 'x5t' for inspection of legacy producers.

public string? CertificateSha1Thumbprint { get; set; }

Property Value​

System.String

JsonWebTokenHeader.CertificateSha256Thumbprint Property​

The 'x5t#S256' (X.509 SHA-256 Thumbprint) header parameter (RFC 7515 §4.1.8): base64url-encoded SHA-256 digest of the DER-encoded leaf certificate. The C# member name strips the '#' character (illegal in identifiers); the JSON literal stays 'x5t#S256' as defined by the spec.

public string? CertificateSha256Thumbprint { get; set; }

Property Value​

System.String

JsonWebTokenHeader.CertificatesUrl Property​

The 'x5u' (X.509 URL) header parameter (RFC 7515 §4.1.5): a URI referring to an X.509 public-key certificate or certificate chain corresponding to the key used for the JWS signature. Same caveat as JwkSetUrl — the library does not fetch.

public System.Uri? CertificatesUrl { get; set; }

Property Value​

System.Uri

JsonWebTokenHeader.Critical Property​

The 'crit' (Critical) header parameter (RFC 7515 §4.1.11): names of JOSE header parameters that the recipient MUST understand and process. Returns null when 'crit' is absent.

public System.Collections.Generic.IReadOnlyList<string>? Critical { get; set; }

Property Value​

System.Collections.Generic.IReadOnlyList<System.String>

Exceptions​

System.Text.Json.JsonException
Thrown when 'crit' is present but is not a JSON array of strings.

JsonWebTokenHeader.EncryptionAlgorithm Property​

The content encryption algorithm used for JWE (JSON Web Encryption).

public string? EncryptionAlgorithm { get; set; }

Property Value​

System.String

Remarks​

The 'enc' parameter identifies the content encryption algorithm used to encrypt the plaintext to produce the JWE ciphertext and authentication tag. Common algorithms include A128CBC-HS256, A192CBC-HS384, A256CBC-HS512, A128GCM, A192GCM, and A256GCM.

JsonWebTokenHeader.Json Property​

The underlying mutable JSON object backing the strongly-typed accessors on this header. Use this when reading or writing custom header parameters that are not modeled as properties.

public System.Text.Json.Nodes.JsonObject Json { get; }

Property Value​

System.Text.Json.Nodes.JsonObject

JsonWebTokenHeader.JwkSetUrl Property​

The 'jku' (JWK Set URL) header parameter (RFC 7515 §4.1.2): a URI referring to a JSON Web Key Set whose keys the issuer claims are candidates for verifying the JWS. The library only exposes the URI; it does not fetch the URL — the host is responsible for trust and transport per RFC 7515 §8 (TLS with server identity validation per RFC 6125).

public System.Uri? JwkSetUrl { get; set; }

Property Value​

System.Uri

JsonWebTokenHeader.KeyId Property​

The key ID that indicates which key was used to secure the JWT.

public string? KeyId { get; set; }

Property Value​

System.String

Remarks​

The 'kid' parameter is a hint indicating which specific key from a JWKS was used to sign the JWT. This is particularly useful when the issuer has multiple keys and the verifier needs to identify the correct key for signature verification.

JsonWebTokenHeader.KeyWrapAuthenticationTag Property​

The 'tag' header parameter (RFC 7518 §4.7.1.2): base64url-encoded 128-bit GCM authentication tag produced when the CEK is wrapped with AES-GCM key wrapping (A128GCMKW/A192GCMKW/A256GCMKW).

public string? KeyWrapAuthenticationTag { get; set; }

Property Value​

System.String

JsonWebTokenHeader.KeyWrapInitializationVector Property​

The 'iv' header parameter (RFC 7518 §4.7.1.1): base64url-encoded 96-bit Initialization Vector used when the CEK is wrapped with AES-GCM key wrapping (A128GCMKW/A192GCMKW/A256GCMKW).

public string? KeyWrapInitializationVector { get; set; }

Property Value​

System.String

JsonWebTokenHeader.Type Property​

The type of the JWT, typically "JWT" or a similar identifier. This field is optional and used to declare the media type of the JWT.

public string? Type { get; set; }

Property Value​

System.String

Remarks​

The 'typ' parameter is recommended when the JWT is embedded in places not inherently carrying this information, helping recipients process the JWT type accordingly.

JsonWebTokenHeader.VerificationKey Property​

The 'jwk' (JSON Web Key) header parameter (RFC 7515 §4.1.3): the public key used to verify the JWS, embedded directly in the JOSE header as a JWK. Returns null when 'jwk' is absent. Trust is the consumer's responsibility — for example, DPoP (RFC 9449) binds this key to the request via a separate confirmation claim.

public Abblix.Jwt.JsonWebKey? VerificationKey { get; set; }

Property Value​

JsonWebKey

Exceptions​

System.Text.Json.JsonException
Thrown when 'jwk' is present but is not a valid JWK (e.g. unknown 'kty').