Update Key Set Policy

This guide explains how to attach a policy template to specific keyset chains by deriving configurations from predefined templates. This process ensures that keyset policies are consistently applied across authentication keysets.

Prerequisites

• Access to the apishare_db_<tenantName> database with the appropriate permissions.

• Administrative privileges, specifically using a tenant Owner or serviceAccount ApiShare user.

Operational Steps

Initial Setup

Before executing SQL queries, connect to the database and set the correct schema context:

psql -U postgresadmin -d apishare_db_<tenant

Once connected, execute:

-- Set the search_path to the specified tenant schema
SET search_path TO "%tenant%"; -- Replace %tenant% with the actual tenant name (e.g., pre)

This ensures that all subsequent queries are executed in the correct schema.

Step 1: Create Keyset Policy Templates

Generate the policy template with the required specifications (e.g., rotation after X months, expiration after Y months) using the Admin Functionality. For further details, follow the guide on this page: Keyset management | managing authentication keys policies

Step 2: Retrieve Keyset Policy Template IDs

Retrieve the list of available keyset policy templates IDs (authentication_keyset_policy_template_id ) by executing the following query:

SELECT * FROM as_authentication_keyset_policy_template;

Step 3: Retrieve Target Keyset Chain IDs

Identify the keyset chains (authentication_keyset_chain_id)to which the policy should be applied. Run the following query:

SELECT * FROM as_authentication_keyset_chain;

Step 4: Upsert Keyset Chain Policy

To apply or update the policy for a keyset chain, use the following SQL statement. This operation inserts a new policy if it does not exist or updates it if already present.

⚠ Warning: Certain scenarios may introduce unexpected behaviors. Carefully review the impact before executing the update.

INSERT INTO as_authentication_keyset_policy (
    authentication_keyset_policy_id,
    authentication_keyset_chain_id,
    expiration_period,
    rotation_period,
    is_regeneration_enabled,
    secret_visibility_period,
    created,
    updated,
    name,
    description
)
SELECT
    gen_random_uuid(), -- Genera un nuovo ID casuale per la policy
    $1, -- authentication_keyset_chain_id passato in input
    t.expiration_period,
    t.rotation_period,
    t.is_regeneration_enabled,
    t.secret_visibility_period, 
    to_char(current_timestamp, 'Dy, DD Mon YYYY HH24:MI:SS +0000'), -- Data di creazione
    to_char(current_timestamp, 'Dy, DD Mon YYYY HH24:MI:SS +0000'), -- Data di aggiornamento
    t.name,
    t.description
FROM as_authentication_keyset_policy_template t
WHERE t.authentication_keyset_policy_template_id = $2
ON CONFLICT (authentication_keyset_chain_id) 
DO UPDATE SET
    expiration_period = EXCLUDED.expiration_period,
    rotation_period = EXCLUDED.rotation_period,
    is_regeneration_enabled = EXCLUDED.is_regeneration_enabled,
    secret_visibility_period = ECLUDED.secret_visibility_period,
    updated = to_char(current_timestamp, 'Dy, DD Mon YYYY HH24:MI:SS +0000'),
    name = EXCLUDED.name,
    description = EXCLUDED.description;

Step 5: Enforce Schedulation to Keyset

This step must be executed only if you want to maintain the current credentials without impacting those consuming the APIs authenticated by these keys. Alternatively, it is still possible to manually regenerate the key (as long as the policy assigned in the previous steps allows it).

This step should only be executed under the following conditions:

• The keyset marked as "latest" is NOT in a PENDING state.

• The keyset marked as "latest" is NOT in a final state (e.g., REVOKED, EXPIRED).

If the above conditions are met, the automatic policy evaluation and scheduling assignment process has already occurred, and it is therefore necessary to override the scheduled dates.

⚠ Warning: Certain scenarios may lead to unexpected behaviors. Carefully assess the impact before proceeding with the update. For example, the scheduled expiration date must be later than the expected rotation date. Scheduled dates should not be set in the past.

Date Format: Dy, DD Mon YYYY HH24:MI:SS +0000 (e.g. Thu, 20 Feb 2025 23:59:59 +0000)

-- Update rotation scheduled date
UPDATE as_authentication_keyset 
SET rotation_scheduled_date = $2
WHERE authentication_keyset_chain_id = $1
AND "sequence" = (
    SELECT MAX("sequence") 
    FROM as_authentication_keyset 
    WHERE authentication_keyset_chain_id = $1
);

-- Update expiration scheduled date
UPDATE as_authentication_keyset 
SET expiration_scheduled_date = $2
WHERE authentication_keyset_chain_id = $1
AND "sequence" = (
    SELECT MAX("sequence") 
    FROM as_authentication_keyset 
    WHERE authentication_keyset_chain_id = $1
);

Step 6: Refresh Keyset Elastic Index

Execute the elasticsearch-refresher

Verifications

1. Verify that the new policy has been successfully inserted or updated in the as_authentication_keyset_policy table.

2. Ensure that the policies have the expected expiration, rotation, and regeneration settings.

3. Login to ApiShare to confirm that the policies are enforced Keys Set Management | Viewing Key Set Details