Automatic License Acquisition Client

Overview

The Automatic License Acquisition Client is a component within the admin-api service responsible for automatically fetching a product license from the central platform. It is designed for deployments that have been registered with the platform but do not yet have a full license installed, such as those running on a temporary bootstrap license.

This client solves the problem of manual license installation by enabling a "zero operator steps" flow. Once a deployment is registered and a license is assigned to it on the platform, this client can automatically pull and install it without any user intervention.

The client is the outbound part of the license acquisition flow. It is invoked by a polling service (SpecariaLicenseAcquisitionService), which determines when to attempt a fetch. If the client successfully retrieves a license JWT, that JWT is then passed to a validator (LicenseValidator) for cryptographic verification and activation. The client itself does not persist the license.

This feature is enabled only when the deployment has a platform-assigned deployment ID and the platform's base URL is configured.

How it Works

The client's primary function, fetchIssuedLicense, orchestrates the process of retrieving a license. The entire process is designed to be "fail-open," meaning any error during the fetch operation will be logged, but will not throw an exception or crash the service. This ensures that a failure to acquire a new license does not disrupt the running deployment.

sequenceDiagram
    participant Poller as License Polling Service
    participant Client as License Acquisition Client
    participant Platform as Platform API

    Poller->>Client: Invoques fetchIssuedLicense()
    Client->>Client: Resolves Deployment ID
    Note right of Client: 1. Checks DB table s2r_specaria_deployment<br/>2. Falls back to S2R_SPECARIA_DEPLOYMENT_ID env var
    alt ID is missing or invalid
        Client-->>Poller: Returns empty (disabled)
    else ID is valid
        Client->>Platform: GET .../self-id-license<br/>(with mTLS client cert)
        Platform-->>Client: Responds with HTTP Status & Body
        alt 200 OK with valid JWT
            Client->>Client: Parses {"license_jwt": "..."}
            Client->>Client: Verifies license is bound to this deployment
            Note right of Client: Checks 'deployment_id' and 'aud' claims in JWT payload.
            Client-->>Poller: Returns Optional containing license JWT
        else Any other response (404, 409, error)
            Client->>Client: Logs status/error
            Client-->>Poller: Returns empty
        end
    end

The operational sequence is as follows:

1. Check Prerequisites: Before making any request, the client verifies that it is enabled. This requires both the platform API base URL to be configured and a valid deployment ID to be available.
2. Resolve Deployment ID: The client retrieves the deployment's unique identifier. The primary source of truth is the s2r_specaria_deployment database table. If the ID is not found in the database, it falls back to the S2R_SPECARIA_DEPLOYMENT_ID environment variable. If no ID can be resolved, the feature is considered disabled for this polling cycle.
3. Validate Deployment ID: The resolved ID is validated against the pattern for a canonical lowercase UUIDv4 (e.g., 123e4567-e89b-12d3-a456-426614174000). The platform rejects non-compliant IDs, so the client skips the request if the ID is malformed.
4. Construct API Request: The client builds a request to the platform's self-identification license endpoint:
   • Endpoint: GET <base_url>/v1/products/<product_id>/deployments/<deployment_id>/self-id-license
   • Authentication: Authentication is performed exclusively via a mutual TLS (mTLS) client certificate. No Authorization bearer token is sent.
   • Headers: The request includes a User-Agent and an Accept: application/json header.
5. Execute Request: The client sends the request with a configurable timeout (defaulting to 60 seconds).
6. Process Response:
   • On HTTP 200 (OK): The client parses the JSON response body to extract the license_jwt. It then performs a crucial pre-validation check to ensure the JWT is "bound" to the current deployment. It decodes the JWT payload and verifies that either the deployment_id claim or a specially formatted aud (audience) claim matches the deployment's own ID. If the binding is incorrect or the JWT is missing, the license is ignored.
   • On HTTP 409 (Conflict): This is a normal, expected response indicating that a license has not yet been assigned to the deployment on the platform. The client logs this and the poller will try again later.
   • On HTTP 404 (Not Found): Indicates the deployment is not registered with the platform.
   • On HTTP 403 (Forbidden) or 401 (Unauthorized): Indicates an authentication or authorization failure, such as a revoked deployment or an invalid mTLS certificate.
   • On Any Other Error: For any other non-200 status code, network error, or processing exception, the client logs a warning and returns an empty result.

Configuration

The license acquisition client is configured via environment variables and corresponding application properties.

API Reference

The client exposes a Java method for internal use by the SpecariaLicenseAcquisitionService. It also interacts with a specific re<customer>e platform API endpoint.

Public Method

Optional<String> fetchIssuedLicense()

Attempts to fetch this deployment's assigned license from the platform.

• Returns: An Optional<String> containing the raw license JWT if one is successfully fetched and passes the initial binding check. Returns an empty Optional if the feature is disabled, no license is available, or any error occurs during the process.
• Throws: This method is designed to never throw an exception. All failures are handled internally and result in an empty Optional.

Re<customer>e Endpoint

The client calls the following re<customer>e endpoint.

• Method: GET

• Path: /v1/products/<product_id>/deployments/<deployment_id>/self-id-license

• Authentication: Per-product mTLS client certificate.

• Successful Response (200 OK): A JSON object containing the license.

  {
    "license_jwt": "<base64-encoded-jwt>",
    "...": "..."
  }
  

• Key Status Codes:

  • 200 OK: A license is available. The response body should contain the license_jwt.
  • 401 Unauthorized: The provided mTLS client certificate was not accepted.
  • 403 Forbidden: The deployment is revoked or the client certificate does not have permission.
  • 404 Not Found: The specified deployment_id is not registered with the platform.
  • 409 Conflict: The deployment is registered, but a license has not yet been assigned to it. This is considered a normal pending state.

Troubleshooting

The client is designed for fail-open behavior, logging issues instead of throwing errors. Check the admin-api service logs for messages prefixed with S2R-LIC to diagnose problems.

See Also

• License Polling Service: The SpecariaLicenseAcquisitionService is the component that contains the polling logic and periodically calls this client to check for a new license.
• License Validator: After this client fetches a JWT, it is passed to the LicenseValidator component, which performs full cryptographic signature verification and activates the license.
• Platform Endpoint Configuration: The base URL and mTLS certificate settings for connecting to the central platform are configured globally for the application.

All SOAP-to-REST docs