Skip to main content

Troubleshooting

Connection and authentication​

SymptomCauseResolution
The connection check fails before OTPKI is reachedThe base URL or the token endpoint is wrong, or the network does not allow the connectionVerify both addresses and the network access described in Create OAuth Client
The connection check fails with a TLS errorOTPKI or the identity provider is served by a private certification authorityAdd the issuing CA certificates to the TLS trust attribute of the Authority
The token is obtained, but OTPKI rejects itNo identity provider registered in OTPKI can introspect the token, so the client belongs to a provider OTPKI does not knowRegister the provider in OTPKI, or create the client in a provider that is already registered
The integration worked and later fails with permission errorsThe access token carries no roles claim, so OTPKI cleared the roles of the connector userInclude the role name in the roles claim, and check it is present in the introspection response
The connector has no permissions from the startThe role name in the roles claim does not exist in OTPKI, and unknown names are ignored silentlyCheck the name against the role created in Create Role and Permissions
An operation fails with a message that no handler at the configured baseUrl answered (HTTP 404)The Base URL points at a different service, or the deployed OTPKI release does not provide the API the connector calls. A version mismatch can pass the connection check and fill the RA Profile dropdowns, and fail only at issuanceCheck the Base URL of the Authority, then check the OTPKI release against the prerequisites and upgrade whichever is behind. Every connection check records the OTPKI version as otpki_version on the OTPKI connection check line of the connector log

Attributes of the RA Profile​

SymptomCauseResolution
The End Entity Profile list is emptyOTPKI cannot be reached, the role lacks Read on end entity profiles, or every profile has an approval profile attachedRun the connection check, review Create Role and Permissions, then check the approval settings in Configure CA and Profiles
The Certificate Profile or Certificate Authority list is empty, or an expected entry is missingThe selected end entity profile has nothing bound to it, the role lacks Read on them, or the missing entry has an approval profile attached and is therefore hiddenComplete the binding and review the approval settings, both in Configure CA and Profiles

Certificate issuance​

SymptomCauseResolution
The end entity already existsThe derived login ID is already used by another end entity in OTPKI, which happens on every issuance after the first when the login ID is not unique per certificateUse Random login ID, see Create RA Profile
The end entity data is rejected as invalidThe certificate profile does not allow the selected certification authority, the login ID does not match the format the end entity profile requires, or the password does not meet the minimum strengthReview the profile configuration in Configure CA and Profiles
The subject of the certificate request lacks the attribute the login ID is derived fromThe certificate request has no CN, or not the configured DN attributeCorrect the certificate request, or change the login ID strategy
The derived login ID is outside the allowed lengthThe username prefix, the derived value, and the username postfix together are shorter than 3 or longer than 64 bytesAdjust the prefix, the postfix, or the strategy so that the result stays within the range
A subject alternative name is reported as requiredThe end entity profile requires a subject alternative name attribute that has no default value, and the connector supplies noneMake the attribute optional or give it a default, see Configure CA and Profiles
The issued certificate has no subject alternative namesThe certificate profile does not take extensions from the certificate requestAllow the certificate profile to override extensions from the request
A CRMF request is refusedThe login ID strategy derives the value from the subject, which a CRMF request does not exposeSet the RA Profile to Random login ID, or to Custom login ID for a single certificate
Issuance fails with a permission error, although the connection check succeedsThe role lacks a permission that issuance needs, such as Update on End Entity, which every enrollment requiresGrant every permission listed in Create Role and Permissions
Issuance or renewal fails with a message that OTPKI paused the enrollment for approvalAn approval profile applies to the end entity profile, the certificate profile, or the certification authorityUse profiles without approvals, see Approval settings
The end entity in OTPKI has an unexpected login IDThe end entity profile auto-generates the login ID and replaced the one the connector suppliedTurn auto-generation off on the end entity profile

Certificate renewal and revocation​

SymptomCauseResolution
Renewal is refused without a certificate requestRenewal with the existing key is not supportedRenew with a new certificate request
Renewal of a certificate that was issued outside of the platform failsMatching by serial number does not resolve the end entity that renewal enrolls againstRenew the certificate in OTPKI, or issue a new one through the RA Profile
Revocation reports that the certificate is unknownThe certificate was not issued through this Authority and was never associated with itAssociate the certificate first, see Test Integration
An operation cannot be cancelledOTPKI has no cancel operation, so an issuance or a revocation runs to its conclusionWait for the operation to finish, then revoke the certificate if needed