Overview
This document outlines the steps necessary to integrate the platform with OTPKI, so that certificates can be issued, renewed, revoked, and registered in OTPKI through the platform.
OTPKI (OmniTrust PKI) is a cloud-native PKI service for operating certification authorities and managing the certificate lifecycle through an API-first interface.
OTPKI Connector
The OTPKI Connector is the Connector that the platform uses to talk to OTPKI. It implements the Authority Provider v3 interface and supports the following operations:
| Operation | Description |
|---|---|
| Issue | Creates an end entity in OTPKI, enrolls it, and returns the issued certificate |
| Renew | Enrolls a new certificate request for an end entity that already exists in OTPKI |
| Revoke | Revokes an issued certificate with the selected revocation reason |
| Register | Pre-registers an identity in OTPKI before a certificate request exists |
| Identify | Matches an existing certificate against OTPKI by its serial number |
| CA certificates | Downloads the certificate chain of the selected certification authority |
The connector does not provide CRLs; the platform downloads them from the CRL distribution point in each certificate.
The connector authenticates to OTPKI with an OAuth 2.0 access token obtained through the client credentials grant. OTPKI validates that token against the identity provider that issued it, and resolves it to an OTPKI user whose roles determine what the connector is allowed to do.
Prerequisites
Before you start, make sure that:
- OTPKI is installed, running, and reachable from the OTPKI Connector. Installing and operating OTPKI is out of scope of this document, refer to the OTPKI documentation.
- The deployed OTPKI is a 1.0.x release. The connector does not work with earlier releases, so upgrade OTPKI and the connector together. If certificates carry otherName subject alternative names, such as a user principal name, use 1.0.1 or a later 1.0.x: OTPKI 1.0.0 encodes them incorrectly, and the platform then stores the certificate without subject alternative names.
- An OIDC identity provider is registered in OTPKI and can issue client credentials tokens. See Identity Providers.
- The platform is release 2.19.0 or later. The connector fills the
RA Profileform through Attributes v2 callbacks, which earlier releases do not provide. - The OTPKI Connector is deployed and registered in the platform as a v2 connector. The Helm chart of the platform deploys and registers it with
otpkiConnector.enabled: true; with the Kubernetes Operator, aConnectorresource withspec.registrationdoes. Both registrations wait for approval in the platform. A connector deployed otherwise is registered as Register Connector shows. - On a new deployment, the connector has
OTPKI_LOGIN_PASSWORD_KEYset before the first certificate is issued or registered. An existing deployment keeps its current setting: setting, changing or removing the key makes renewal fail for every end entity created under the previous setting. See Password configuration. - A
Vault Profileis available in the platform to store the OAuth client credentials.
Integration
Configuration in OTPKI
The following steps are required in OTPKI before the integration can be configured in the platform:
| # | Reference | Short description |
|---|---|---|
| 1 | Create Role and Permissions | Create the role for the connector and grant it the permissions it needs |
| 2 | Create OAuth Client | Create the OAuth client the connector authenticates with |
| 3 | Configure CA and Profiles | Prepare the certification authority and the profiles used for issuance |
Configuration in the platform
The following steps are required in the platform to connect the prepared OTPKI:
| # | Reference | Short description |
|---|---|---|
| 4 | Create Authority | Store the OAuth client credentials and connect OTPKI as an Authority |
| 5 | Create RA Profile | Select the OTPKI profiles and configure how end entities are named |
When both sides are configured, Test Integration confirms that the certificate lifecycle works end to end. Troubleshooting lists the problems most commonly seen during the setup.