Skip to content

Moving from the Admin SDK

The Admin SDK (co.ankatech:ankasecure-admin-sdk) and the Admin CLI (co.ankatech:ankasecure-cli-admin) end at 3.3.0. From 3.4.0, automation that manages one tenant's keys uses the Key Management SDK (co.ankatech:ankasecure-key-management-sdk) or the Key Management CLI (ankasecure-km). Everything else the Admin SDK did is done by people in the Admin Console.

The published Admin SDK versions stay on Maven Central, but an Admin SDK client is not supported against a 3.4.0 server: operations it calls were removed or moved to the Admin Console.

What changes for an integration

  • Sign-in. The Key Management SDK signs in only as an administrative workload of one tenant: AnkaSecureKeyManagementSdk.authenticateWorkload(WorkloadCredential), with a registered private key or a federated token, every request DPoP-bound. There is no person sign-in, no device or browser flow and no refresh token.
  • Tenant. The token names the tenant. No method takes a tenant id, and there is no tenant setting.
  • Request and response bodies. They are the generated models of the Key Management contract, so every member an operation accepts can be set.
  • Approvals. A destruction request always waits for a person's approval. An operation the tenant's quorum policy gates throws QuorumApprovalPendingException with the pending request. Approval and rejection are made in the Admin Console; the SDK can list, read and cancel the workload's own requests.

Call map

Admin SDK 3.3.0 From 3.4.0
createKey, getKeyMetadata, listKeys, suspendKey, revokeKey keys().create, keys().get, keys().list, keys().suspend, keys().revoke
rotateKey rotation().rotate
revokeKeyMaterialVersion materials().revoke
— New: keys().update, archive, reactivate, export, importKey, importKeystore, analyzeKeystore; rotation().schedule, replaceSchedule, listExecutions; destruction()
createExchangeContext, suspendExchangeContext exchangeContexts().create, suspend (plus get, list, update, resume, close)
createExchange, validateExchange, activateExchange, suspendExchange, revokeExchange exchanges().create, validate, activate, suspend, revoke
provisionUseCase, getUseCase, listUseCases, suspendUseCase, resumeUseCase, revokeUseCase internalCryptoUseCases().create, get, list, suspend, resume, delete
listActors, getActor, listApplications directory().listActors, getActor, listApplications (read-only)
createActor, assignActorRoles, createApplication Admin Console
createRuntimeIdentity, rotateRuntimeCredential Admin Console, or internalCryptoUseCases().create when the identity serves an internal cryptographic use case
createUser, listUsers, assignUserRoles, suspendUser, reactivateUser, removeUser Admin Console
provisionTenant, listTenants, activateTenant, suspendTenant, platform identities Admin Console
Algorithm and rotation policies, policy templates, the tenant override switch Admin Console
Key-protection backends (deployment, managed tier, tenant BYOK) Admin Console
Quorum approve, reject, policy changes, scheduled recovery Admin Console
Quorum getRequest, listRequests, cancel quorumRequests().get, list, cancel (the workload's own requests)
exportAudit Admin Console audit screens, or the Audit API

Configuration map

The Key Management SDK and CLI read only their own names. The Admin SDK's adminsdk.* properties and the Admin CLI's configuration location are not read, so a configuration that still carries only the old names is incomplete and is refused as such (kmsdk.host is required).

Admin SDK / Admin CLI 3.3.0 Key Management SDK / CLI
adminsdk.scheme kmsdk.scheme — required
adminsdk.host kmsdk.host — required
adminsdk.port kmsdk.port — defaults to the scheme's own port (443 for https, 80 for http)
adminsdk.connectTimeoutMs, adminsdk.readTimeoutMs, adminsdk.writeTimeoutMs kmsdk.connectTimeoutMs, kmsdk.readTimeoutMs, kmsdk.writeTimeoutMs
adminsdk.tls.insecure kmsdk.tls.insecure
adminsdk.auth.issuer kmsdk.auth.issuer
adminsdk.workloadId, adminsdk.workloadPrivateKeyFile, adminsdk.workloadFederatedFile No property: the WorkloadCredential passed to authenticateWorkload
adminsdk.tenantId No property: the token names the tenant
CLI directory ~/.ankasecure-admin ~/.ankasecure-km
CLI environment variable ANKASECURE_ADMIN_CONFIG ANKASECURE_KM_CONFIG
CLI system property ankasecure.admin.config.dir ankasecure.km.config.dir

The Admin CLI's configuration files are not read, copied or changed: create the Key Management CLI's configuration with ankasecure-km init (Installation). Every key and its default is listed in Prerequisites § Configuration.

Tenant and actor provisioning

Provisioning tenants, users, roles, actors and their credentials is no longer offered by any SDK or CLI. It is done in the Admin Console by the platform's or the tenant's administrators. An integration that created its own tenant or actors with the Admin SDK now receives them from those administrators, together with the administrative workload it signs in as.

Steps

  1. Ask the tenant administrator to register an administrative workload for the integration, with the key-management scopes it needs, and to register its public key or federated subject.
  2. Replace the dependency co.ankatech:ankasecure-admin-sdk with co.ankatech:ankasecure-key-management-sdk.
  3. Rename the configuration as the configuration map shows, setting kmsdk.scheme and kmsdk.host.
  4. Replace the sign-in with authenticateWorkload, and remove every tenant argument and setting.
  5. Move each call as the call map shows. Calls that map to the Admin Console leave the integration.
  6. Handle QuorumApprovalPendingException and destruction receipts where the tenant uses approvals.