Managing Secrets

Rotation functions included the following four steps:

1. VERIFY_CONNECTION: Verifies the connection to the target system using the existing credentials stored in the secret.
2. CREATE_PENDING_VERSION: Creates a new pending secret version in the secret.
3. UPDATE_TARGET_SYSTEM: Updates the target system with the credentials stored in the pending secret version created in the second step.
4. PROMOTE_PENDING_VERSION: Updates the state of the secret from pending to current.

Function handler:

The function handler must contain the logic to call the appropriate rotation step based on the step parameter. This can be achieved either by using IF ELSE conditional statements or switch case. The function handler generates an error if an invalid step parameter is provided.

Input:

The function handler expects single parameter: SecretRotationInput. The secretRotationInput is a POJO (Plain-old java object) containing the parameters required for rotation, including the secretId(String), step(String) and currentVersionNo(Long).

• secretId: The secret identifier or OCID
• step: The rotation step (Must be one of VERIFY_CONNECTION, CREATE_PENDING_VERSION, UPDATE_TARGET_SYSTEM or PROMOTE_PENDING_VERSION)
• currentVersionNo: The number of the CURRENT secret version

SecretRotationInput POJO

@Getter
@Setter
@ToString(callSuper = true)
@JsonInclude(JsonInclude.Include.NON_NULL)
@AllArgsConstructor
@Builder(toBuilder = true)
public static class SecretRotationInput {
    private String step;
    private Long versionNo;
    private String secretId;
}                

Sample function handler code:

public static class SecretRotationOutput {
    int responseCode;
    Long currentVersionNo;
    String returnMessage;
}
 
 
public SecretRotationOutput handleRequest(SecretRotationInput input) {
    switch(input.getStep()) {
        case "VERIFY_CONNECTION":
            return verifyConnection(input.getSecretId());
        case "CREATE_PENDING_VERSION":
            return createNewPendingVersion(input.getSecretId());
        case "UPDATE_TARGET_SYSTEM":
            return updateTargetSystem(input.getSecretId(), input.getVersionNo());
        case "PROMOTE_PENDING_VERSION":
            return promotePendingVersion(input.getSecretId(), input.getVersionNo());
        default:
            log.error("Secret Rotation: invalid rotation step");
            return SecretRotationOutput.builder()
                    .responseCode(400)
                    .currentVersionNo(null)
                    .returnMessage("INVALID STEP")
                    .build();
    }
}

Step 1: VERIFY_CONNECTION

This step verifies connection to the target system.

• Input: This method expects only the parameter SecretId.
• Output: This method outputs the SecretRotationOutput.
• Logic: The function first tries to fetch the PENDING version and verify the connection with it. This handles the failure scenario where previous retry failed to promote the PENDING version, but the version has been successfully applied to the system. If it succeeds, return the success response. If it fails, fetch the current version and check the connection. If that succeeds, return the success response code along with the current version number. If it doesn't succeed, return the error.

Pseudo code for VERIFY_CONNECTION

pseudo code for verifyConnection:
    Check if "PENDING" secret version exists
        If it exist, verify connection
            If succeeds, then return success.
    Fetch the "CURRENT" secret version
    Verify connection with "CURRENT" secret version
       If succeeds, return success and the current version number in the response.
        If not, return SecretRotationOutput with appropriate error code and message.

Step 2: CREATE_PENDING_VERSION

Generates a new pending secret version.

• Input: This method also accepts the secretId parameter.
• Output: This method outputs the SecretRotationOutput.

• Logic: This method first checks for the existence of a secret version in PENDING state. If one doesn't exist, it generates a new PENDING secret version. However, if one already exists, the step returns the success response. You can also use the secret metadata field to store extra details about the secret structure and can use the same structure when creating a new secret version. You can also use the Secret service's auto-generation feature to auto-generate the secret content. Auto-generation lets you to write more generic functions.

Pseudo code for CREATE_PENDING_VERSION

pseudo code for createPendingVersion:
    Try to get the pending version
        If it succeeds, return success
        Else create a new secret version in "PENDING" state and then return success

Sample code:

// Constructor
public void constructorClass() {
     secretsDpClient = SecretsClient.builder()
                    .region(region)
                    .configuration(configuration)
                    .build(auth_provider);
     secretsCpClient = VaultsClient.builder()
                    .region(region)
                    .configuration(configuration)
                    .build(auth_provider);
}
 
private String createNewPassword() {
    // This method must contains the logic to generate the new secret content
}
  
private SecretRotationOutput createNewPendingVersion(SecretRotationInput input) {
    // Make sure the given secret exist
    Secret secret = secretsCpClient.getSecret(GetSecretRequest.builder()
                    .secretId(input.getSecretId())
            .build()).getSecret();
  
    // Now try to get the pending secret version, if that fails, create a new one
    try {
        GetSecretBundleRequest getSecretBundleRequest = GetSecretBundleRequest.builder()
                .secretId(input.getSecretId())
                .stage(GetSecretBundleRequest.Stage.Pending)
                .build();
        secretsDpClient.getSecretBundle(getSecretBundleRequest);
        return SecretRotationOutput.builder()
                .responseCode(200)
                .returnMessage("Successfully retrieved the pending secret version")
                .build();
    } catch (BmcException bmc) {
        // Create a new pending version
        UpdateSecretDetails updateSecretDetails = secret.getIsAutoGenerationEnabled() ? UpdateSecretDetails.builder()
                .secretContent(Base64SecretContentDetails.builder()
                        .stage(SecretContentDetails.Stage.Pending)
                        .build())
                .build() : UpdateSecretDetails.builder()
                .secretContent(Base64SecretContentDetails.builder()
                        .content(createNewPassword())
                        .stage(SecretContentDetails.Stage.Pending)
                        .build())
                .build();
        secretsCpClient.updateSecret(UpdateSecretRequest.builder()
                .secretId(input.getSecretId())
                .updateSecretDetails(updateSecretDetails)
                .build()).getSecret();
        log.info("Successfully added a new version with 'PENDING' stage for secretId {}", input.getSecretId());
        return SecretRotationOutput.builder()
                .responseCode(200)
                .returnMessage("Pending version created successfully")
                .currentVersionNo(input.getVersionNo())
                .build();
    }
}

Step 3: UPDATE_TARGET_SYSTEM

Sets the pending secret in the target system.

• Input: This method accepts the currentVersionNo and secretId.
• Output: This method also outputs the SecretRotationOutput.
• Logic: This method first tries to login to the target system with the PENDING secret version and returns on success. This also handles the failure scenario where previous retry failed to promote the pending version but the version has been successfully applied to the system. If that fails, it tries to login with the CURRENT secret version. If the current secret version succeeds, it sets the PENDING password as the user password in the target system.

Pseudo code for UPDATE_TARGET_SYSTEM

Pseudo code for updateTargetSystem:
    Fetch the "PENDING" secret version
    Check the connection with Pending version
        It it works return success and the pending version number in the response
    Fetch the "CURRENT" secret version
    Check the connection with it
        If it works
            Update the target system with "PENDING" version
            Verify that target system is updated.
               if yes then return success and the pending version number in the response 
            else return the appropriate error code and the error message
        If not, return SecretRotationOutput with appropriate error code and message.

Sample code:

private SecretRotationOutput updateTargetSystem(String secretId, Long currentVersionNo) {
    // Get the pending secret version
    SecretBundle pendingSecretBundle = secretsDpClient.getSecretBundle(GetSecretBundleRequest.builder()
                    .secretId(secretId)
                    .stage(GetSecretBundleRequest.Stage.Pending)
            .build()).getSecretBundle();
  
    // First try to login with the pending secret, if it succeeds, return
    Connection conn = getConnection(pendingSecretBundle);
    if(conn) {
        log.info("Updated the target system with pending version");
        return SecretRotationOutput.builder()
                    .responseCode(200)
                    .returnMessage("Successfully update target service")
                    .currentVersionNo(pendingSecretBundle.getVersionNumber())
                    .build();
    }
  
    SecretBundle currentSecretBundle = secretsDpClient.getSecretBundle(GetSecretBundleRequest.builder()
                    .versionNumber(currentVersionNo)
                    .secretId(secretId)
            .build()).getSecretBundle();
  
    conn = getConnection(currentSecretBundle);
    if(conn) {
        // Write logic to update the target system and check the connection with the updated password
    } else {
        log.error("Unable to log into system using the current version");
        return SecretRotationOutput.builder()
                .returnMessage("Unable to log into system using the current version")
                .responseCode(400)
                .build();
    }
}

Step 4: PROMOTE_PENDING_VERSION

Finish the rotation by marking the pending secret as current.

• Input: This method accepts the currentVersionNo and secretId.
• Output: This method also outputs the SecretRotationOutput.
• Logic: Call the Secret service to promote the PENDING version to CURRENT. UpdateRequest must specify which version need be promoted to CURRENT.

Pseudo code for PROMOTE_PENDING_VERSION

pseudo code for promotePendingVersion:
    Make updateSecret Api call to promote the specified version to "CURRENT"

Sample code:

private SecretRotationOutput promotePendingVersion(String secretId, Long versionNo) {
    try {
        Secret secret = secretsCpClient.updateSecret(UpdateSecretRequest.builder()
                .secretId(secretId)
                .updateSecretDetails(UpdateSecretDetails.builder()
                        .currentVersionNumber(versionNo)
                        .build())
                .opcRequestId(UUID.randomUUID().toString())
                .build()).getSecret();
        log.info("Successfully promoted the version number {} to 'CURRENT'", versionNo);
        return SecretRotationOutput.builder()
                .responseCode(200)
                .currentVersionNo(secret.getCurrentVersionNumber())
                .returnMessage("Successfully promoted the pending version")
                .build();
    } catch (BmcException bmc) {
        log.error("Fail to promote the pending version. SecretId: {}, pendingVersionNo: {}. {}", secretId, versionNo, bmc.getMessage());
        return SecretRotationOutput.builder()
                .returnMessage(bmc.getMessage())
                .responseCode(bmc.getStatusCode())
                .build();
    }
}