Skip to content

Create a Custom API Integration service account

Custom API integtration service accounts leverage third-party issued tokens for authentication, utilizing workload identity federation.

What is workload identity federation?

Workload identity federation allows your applications to securely authenticate with Venafi Control Plane without having to manage and secure long-lived credentials (like passwords or API keys). Instead, it uses short-lived tokens obtained from a trusted Identity Provider (IdP). This means your application proves its identity to the IDP and receives a token, which it can then use to access Venafi Control Plane. Learn more

Before you begin

Before creating a Custom API Integration, you must complete the following tasks. Refer to your IdP's documentation to complete these tasks:

  1. Register your application with your IdP: To authenticate using a custom API integration service account, your application must be registered with your IdP. This registration process involves setting up your application within the IDP to recognize and authorize it as a legitimate entity. You'll also use the information from you JWT when creating your the service account in Venafi Control Plane (see item 3, "Gather JWT Information".)

  2. Configure your IdP to use Venafi's supported JWT signing algorithms: Ensure that the JWT (JSON Web Token) issued by your IdP are compatible with Venafi Control Plane. This involves configuring your IdP to use one of the supported JWT signing algorithms. You should be able to do this within your IdP’s management console or configuration API. This configuration is important for maintaining security integrity and ensuring smooth interoperability between your IdP and Venafi.

  3. Obtain a JWT token: During the registration process, your IdP will provide a JWT that your application will use to authenticate requests. This token contains critical information that the service account creation process will utilize.

  4. Gather JWT Information: Extract the necessary details from the JWT provided by your IdP, such as the issuer, subject, and audience. This information will be required when setting up your service account to ensure it is properly configured to authenticate using the token.

IMPORTANT!

  • Ensure that the JWT includes all required claims as specified by your service account setup. Missing information may prevent the service account from functioning correctly.
  • Verify that the JWT's lifespan aligns with your service account's usage pattern. Tokens with a very short lifespan might need to be refreshed often, depending on your application's needs.

By completing these prerequisites, you ensure that your service accounts are configured correctly and ready to handle authentication requests using modern security protocols.

To create a Custom API Integration service account

  1. Sign in to Venafi Control Plane.
  2. Click Settings > Service Accounts.
  3. Click New.
  4. Choose the desired use case from the Use case list, and click Continue. The use cases available for you to choose depend on which Venafi Control Plane components you have licenses for.
  5. Enter a Name for your new service account.

  6. Select an Owning Team. This team owns the machine you want to create the service account for.

  7. Select the desired Scope, making sure it matches the permissions and access requirements of your service account, and then click Continue. Learn more

  8. After selecting scope options, then click Continue.

  9. Fill in the credentials with the specific information required for authentication:

    • Issuer URL: Enter the URL provided by the third-party token service.

      • Example: https://<ISSUER-URL>/.githubusercontent.com

    • JWKS URI: Enter the URI where the JSON Web Key Set (JWKS) can be retrieved.

      • Example: https://www.example.com/.well-known/jwks.json

    • Subject Identifier: Enter the unique identifier for the subject within the issuing authority's namespace.

      • Example: repo:zarzusm/action-testing:environment:Development

    • Audience: Enter the intended audience for the token, which is usually the API or resource that the token is intended to access.

      • Example: api://AzureADTokenExchange

  10. After entering all the details, review the information to ensure it's correct and then click Finish to create the new service account.

After the JWT is used to request access, you'll receive an access token. You can then use that token to interact with supported APIs. You can review the workflow here.

Access tokens issued by a Venafi Control Plane token endpoint has a 15-minute expiry. So if an expired token is used, the request will be rejected (similar to expired API keys).

API Reference