You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 6 Next »

This guide outlines the steps to implement the Group Representative Information Exchange specification using the general JWS JSON Serialization syntax. This specification defines a standardized mechanism for extracting a URL from the SAML extension GroupRepresentative element within SAML metadata, enhancing the interoperability of entities within a federation. Here's how to implement it:

Prerequisites

Before you begin, ensure that you have the following prerequisites in place:

  • Knowledge of SAML and its concepts.
  • Access to SAML metadata for entities involved in the federation.
  • Familiarity with JSON Web Signature (JWS) and JSON Schema.

Base64 vs. Base64url Encoding

Before proceeding, it's crucial to understand the difference between Base64 and Base64url encoding. The Group Representative Information Exchange specification uses Base64url encoding for various components, including the JWS header, payload, and signature. The key distinction is that Base64url encoding is URL-safe and does not include characters that are problematic in URLs, such as '+' and '/' in Base64. Instead, it uses '-' and '_' to replace these characters.

For example, in Base64 encoding, the character '+' is used, while in Base64url encoding, it's replaced with '-'. Similarly, '/' in Base64 is replaced with '_'. Be sure to use Base64url encoding when working with JWS components.

Implementation Steps

Create SAML Metadata

Ensure that the SAML metadata includes the GroupRepresentative element. This element must contain a URL pointing to a JSON Web Signature (JWS) conforming to the specification, and it must also include the certificate used for the JWS signature validation.


Example GroupRepresentative element in SAML metadata:

SAML metadata
<?xml version="1.0" encoding="UTF-8"?>
<EntityDescriptor xmlns="urn:oasis:names:tc:SAML:2.0:metadata" entityID="http://idp1.example.com">
  <IDPSSODescriptor>
    <Extensions>
      <grie:GroupRepresentative xmlns:grie="http://saml-schema.swefed.se/schema/grie" location="https://www.example.com/mdie.jws">
        <md:KeyDescriptor use="signing">
          <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
            <ds:X509Data>
              <ds:X509Certificate>(Your certificate content here)</ds:X509Certificate>
            </ds:X509Data>
          </ds:KeyInfo>
        </md:KeyDescriptor>
      </grie:GroupRepresentative>
    </Extensions>
  </IDPSSODescriptor>
</EntityDescriptor>

Create the JSON Web Signature (JWS)

Generate the JSON Web Signature (JWS) according to the specified format and content. Ensure that it includes the necessary claims, such as iss, exp, iat, version, cache_ttl, and entities, as defined in the specification.

Understanding the cache_ttl Claim

The cache_ttl claim is a critical component of the JWS. It defines the time-to-live duration in seconds for caching the data within the JWS. This duration governs how long the metadata can be cached before it needs to be refreshed by fetching updated data.

It is essential to understand the importance of the cache_ttl claim. It ensures that the information contained within the JWS remains fresh and accurate. Therefore, the metadata should be retrieved and updated within this specified cache TTL period.

Understanding the exp Claim

In addition to the cache_ttl claim, it's vital to understand the significance of the exp claim, short for "Expiration Time." The exp claim specifies the timestamp after which the data contained within the JWS is no longer considered valid. Beyond this timestamp, the data should not be considered reliable or usable.

The exp claim is particularly important when it's not possible to fetch updated data within the cache_ttl period. It safeguards against using outdated or potentially inaccurate information.


Here's an example JWS structure in JSON:

{
  "iss": "https://my-domain.example.com",
  "exp": 1693056343,
  "iat": 1692192343,
  "version": "1.0.0",
  "cache_ttl": 3600,
  "entities": [
    {
      "entity_id": "https://idp1.example.com",
      "constituents": [
        {
          "organization_id": "1122334455",
          "organization_name": "Example Org One"
        },
        {
          "organization_id": "6677889900",
          "organization_name": "Example Org Two"
        }
      ]
    }
  ]
}

Sign the Metadata with JWS

Sign the JWS using the recommended algorithm, ECDSA with P-256 and SHA-256 ("ES256"). Ensure that you include the required headers in the JWS, such as alg and x5t#S256, as specified in the specification.

Understanding the x5t#S256 Header Claim

In the process of creating the JWS, it's essential to include the x5t#S256 header claim. This claim plays a crucial role in preserving the accuracy and security of the metadata. x5t#S256 stands for "X.509 Certificate SHA-256 Thumbprint," and it serves as a fingerprint for the certificate used for signing within the SAML metadata.

Here's how to work with the x5t#S256 claim:

  • Retrieve the Certificate: Before generating the JWS, obtain the X.509 certificate that will be used for signing the metadata. This certificate should be the same one specified in the SAML metadata.

  • Calculate the SHA-256 Fingerprint: Calculate the SHA-256 fingerprint of the certificate. This involves hashing the certificate data using the SHA-256 algorithm to produce a unique fingerprint.

  • Include in the JWS Header: When creating the JWS, include the x5t#S256 claim in the JWS header. This claim's value should be the calculated SHA-256 fingerprint of the certificate. This step ensures that the JWS references the same certificate found in the SAML metadata.

By including the x5t#S256 claim with the correct certificate fingerprint, you establish a secure link between the JWS and the certificate used for signing, enhancing trust and authenticity in the metadata exchange process. This validation mechanism helps confirm that the metadata hasn't been tampered with and comes from the expected source.


Here's an example JWS header:

JWS Header
{
  "alg": "ES256",
  "x5t#S256": "f7d2Euxs1UGh0p4-7Lga5sNWNhx25fxDr2WP87bovJU"
}

Publish the Metadata

Publish the JWS, at the URL specified in the GroupRepresentative element within the SAML metadata. Make sure this URL is accessible to entities within the federation.

Validate and Interpret Metadata

Entities within the federation can retrieve and validate the Group Representative Information Exchange metadata by accessing the URL specified in the GroupRepresentative element.

After receiving the JWS-signed metadata, it's crucial to perform validation and interpretation to ensure the integrity and authenticity of the data.

Verify the Digital Signature

  1. Check the exp Claim: First, verify the exp (Expiration Time) claim in the JWS payload. Ensure that the current timestamp is before the specified expiration time. If the data is past its expiration time, it should not be considered valid.

  2. Validate the Digital Signature: To verify the authenticity of the metadata, use the alg (Algorithm) and x5t#S256 header claims in the JWS header.

    • alg Claim: Ensure that the algorithm specified in the alg claim matches the one used for signing (e.g., "ES256" for ECDSA with P-256 and SHA-256).

    • x5t#S256 Claim: This claim specifies the SHA-256 fingerprint of the signing key used for the JWS. It should correspond to the fingerprint of the certificate used for signing in the SAML metadata.

      • Retrieve the certificate from the SAML metadata, and calculate its SHA-256 fingerprint.

      • Compare the calculated fingerprint with the x5t#S256 claim in the JWS header. If they do not match, it indicates a potential security issue, and the metadata should not be trusted.

  3. Check the Issuer (iss) Claim: Verify that the iss (Issuer) claim in the JWS payload matches the expected issuer URI. This ensures that the metadata is coming from a trusted source.

  4. Validate the iat Claim: Ensure that the iat (Issued At) claim is a valid NumericDate representing the time when the data was issued.

Validate Against JSON Schema

To ensure the metadata's structure and data types conform to the specification, you should validate it against the provided JSON Schema. The JSON Schema defines the expected format and structure of the metadata.

  • Retrieve the JSON Schema associated with the Group Representative Information Exchange specification.

  • Validate the received metadata against the JSON Schema to ensure it adheres to the defined structure and data constraints.

Interpret the Metadata

Once the metadata is validated:

  • Extract and use the information as needed.
  • Pay special attention to the cache_ttl and exp claims. The cache_ttl specifies the cache duration, while exp defines the expiration time of the data. Refresh the metadata before the cache_ttl expires or if exp is reached to maintain data accuracy.

By following these validation steps and interpreting the metadata correctly, you can trust the information provided within the JWS-signed metadata, enhancing the security and reliability of the federation.

Example Code for JWS Creation and Validation

To facilitate the creation and validation of JWS in compliance with the Group Representative Information Exchange specification, you can leverage example code available on GitHub. This code provides a practical reference for implementing the JWS generation and validation process.

Example Code Repository: GitHub Example Code

The provided example code offers a step-by-step guide, including the following functionalities:

  • Creating JWS: The code demonstrates how to construct a JWS according to the specification's requirements, including the necessary claims and Base64url encoding.
  • Signing JWS: It shows how to sign the JWS using the recommended algorithm (ECDSA with P-256 and SHA-256, "ES256") and include the required headers.
  • Serializing JWS: The code illustrates how to serialize the JWS using the general JWS JSON Serialization syntax, ensuring Base64url encoding for various components.
  • Validating JWS: It demonstrates how to validate the JWS signature, ensuring the integrity and authenticity of the metadata.

By utilizing this example code as a reference, you can streamline the implementation of the Group Representative Information Exchange specification within a SAML-based federation. It provides practical guidance on handling JWS creation and validation, helping you ensure compliance with the specification's encoding and security requirements.

Conclusion

By following these steps, you can successfully implement the Group Representative Information Exchange specification in the SAML-based federation using the general JWS JSON Serialization syntax. This mechanism allows for standardized representation of group representatives and their associated entities, enhancing interoperability and security within the federation.


  • No labels