Azure / azure-sdk-for-java

This repository is for active development of the Azure SDK for Java. For consumers of the SDK we recommend visiting our public developer docs at https://docs.microsoft.com/java/azure/ or our versioned developer docs at https://azure.github.io/azure-sdk-for-java.
MIT License
2.35k stars 1.99k forks source link

[Key Vault] Add support for Key Rotation #22993

Closed maorleger closed 3 years ago

maorleger commented 3 years ago

To support KeyVault Key Rotation, implement the following changes (modeled from JS, but use whatever API is idiomatic for your language):

ARM Template changes

When creating a keyvault, add rotate to the keys' accessPolicies so that your test application has permissions to rotate and set the rotation policy.

Key Client API

getKeyRotationPolicy(name: string, options?: GetKeyRotationPolicyOptions): Promise<KeyRotationPolicy | undefined>; // see (1) below
rotateKey(name: string, options?: RotateKeyOptions): Promise<KeyVaultKey>;
updateKeyRotationPolicy(name: string, policy: KeyRotationPolicyProperties, options?: UpdateKeyRotationPolicyOptions): Promise<KeyRotationPolicy>;

Note that policy behavior is against the latest version of a key.

New models

// @public
export interface KeyRotationLifetimeAction {
    action: KeyRotationPolicyAction;
    timeAfterCreate?: string; // see (2) below
    timeBeforeExpiry?: string;  // see (2) below
}

// @public
export interface KeyRotationPolicy extends KeyRotationPolicyProperties {
    readonly createdOn: Date;
    readonly id: string;
    readonly updatedOn?: Date;
}

// @public
export type KeyRotationPolicyAction = "Rotate" | "Notify";

// @public
export interface KeyRotationPolicyProperties { // see (3) below
    expiresIn?: string;  // see (2) below
    lifetimeActions?: KeyRotationLifetimeAction[];
}

Swagger inconsistencies to be mindful of

The swagger defines the possible values for LifetimeActionsType as an enum consisting of rotate and notify but in reality it returns Rotate and Notify - the service accepts both casing, is case-insensitive, but in order to model the correct values here we went with the following swagger transformation:

directive:
  - from: swagger-document
    where: $.definitions.LifetimeActionsType.properties["type"]["x-ms-enum"]
    transform: >
      $.values[0].value = "Rotate";
      $.values[1].value = "Notify";

Notes

  1. Calling GET /keys/{name}/rotationpolicy will return an object with all properties set to null. We're discussing having that endpoint 404, but until then I am return undefined if the id doesn't exist
  2. We're still discussing whether the swagger should model this as an ISO8601 duration. In JS, the architects prefer a string, but model this duration in whatever way is idiomatic (TimeSpan, etc). If the swagger changes, I'll update the feature crew
  3. In order to properly model input / output values I separated out the KeyRotationPolicy and the KeyRotationPolicyProperties . The former extends the latter and adds the server-side attributes (timestamps and ID).
maorleger commented 3 years ago

FYI here are the JS PRs for your reference: