Authenticating to the Keyfactor API

When you make a connection to Keyfactor Command using the Keyfactor API A set of functions to allow creation of applications. Keyfactor offers the Keyfactor API, which allows third-party software to integrate with the advanced certificate enrollment and management features of Keyfactor Command., you need to provide authentication. If you’re using Active Directory as an identity provider, you have the choice to authenticate to Keyfactor Command using Basic authentication or Windows integrated authentication. Any users who have already authenticated to Keyfactor Command before opening the Keyfactor API Reference and Utility in the same browser session will be seamlessly authenticated to Keyfactor Command automatically, and will not need to re-authenticate. The need to intentionally provide authentication for the Keyfactor API comes into play in situations such as:

• You are developing or running an application or script that leverages the Keyfactor API.
• You are running a workflow A workflow is a series of steps necessary to complete a process. In the context of Keyfactor Command, it refers to the workflow builder, which allows you automate event-driven tasks when a certificate is requested or revoked. step of type Invoke REST Request with Active Directory Basic or Windows authentication.
• You are running a workflow step of type Invoke REST Request with OAuth with an identity provider other than Active Directory and token authentication.
• You are using the Keyfactor API Reference and Utility and using an identity provider other than Active Directory (see Acquire a Token to Authenticate to the Keyfactor API).
• You are using the Keyfactor API Reference and Utility, using Active Directory as an identity provider, and have not authenticated to Keyfactor Command within the same browser session.

In many of these cases, you will probably want to make the API requests not as an individual user, but as a service account. The service account you use depends on the identity provider you’re using:

• If you’re using Active Directory as an identity provider, a standard Active Directory service account in the primary Keyfactor Command server forest An Active Directory forest (AD forest) is the top most logical container in an Active Directory configuration that contains domains, and objects such as users and computers. can be used.

• If you’re using an identity provider other than Active Directory, a client (not user) in your identity provider is used. The client should be configured with a secret and have Client authentication and Service account roles enabled (see Service Accounts). The user who will make use of the API will need the client ID and secret as well as the bearer token URL. This is the URL of the token endpoint An endpoint is a URL that enables the API to gain access to resources on a server. for your identity provider instance. For example:

  https://my-keyidp-server.keyexample.com/realms/Keyfactor/protocol/openid-connect/token

  For Keyfactor Identity Provider, this is included among the information that can be found on the OpenID Endpoint Configuration page, a link to which can be found on the Realm Settings page (see Configuring Keyfactor Identity Provider and Collecting Data for the Keyfactor Command Installation).

  

  Figure 430: Client Secret for Keyfactor API in Keyfactor Identity Provider

This service account needs to be granted appropriate permissions in Keyfactor Command to complete the API requests that will be run as this service account.

Acquire a Token to Authenticate to the Keyfactor API

If you’re using the Keyfactor API Reference and Utility (Swagger) and using an identity provider other than Active Directory, you will need to acquire a token from your identity provider in order to authenticate to the Keyfactor API Reference and Utility. There are a number of approaches to doing this. Here we provide a couple of examples.

First, be sure that you have created a client in your identity provider (see Service Accounts) and that you know this information about the client:

• Client ID

• Client Secret

• Bearer Token URL

To acquire a token to authenticate to the Keyfactor API either via the Keyfactor API Reference and Utility or directly, from a Linux server execute a curl command similar to the following, referencing appropriate values for your client ID, client secret, and bearer token URL:

curl --request POST --url https://appsrvr18.keyexample.com:1443/realms/Keyfactor/protocol/openid-connect/token --header 'Content-Type: application/x-www-form-urlencoded' --data client_secret=o2mwI5LjZEAmcbC9dnhHq589BOf2OqD4 --data client_id=Keyfactor-API-Workflow-User --data grant_type=client_credentials

To acquire a token to authenticate to the Keyfactor API either via the Keyfactor API Reference and Utility or directly, in PowerShell execute a script similar to the following, referencing appropriate values for your client ID, client secret, and bearer token URL:

$Body = @{
   grant_type = "client_credentials"
   client_id = "Keyfactor-API-Workflow-User"
   client_secret = "o2mwI5LjZEAmcbC9dnhHq589BOf2OqD4"
}

$Headers = @{
   'Content-Type' = 'application/x-www-form-urlencoded'
}

$TokenResults = Invoke-RestMethod -Method Post -Uri https://appsrvr18.keyexample.com:1443/realms/Keyfactor/protocol/openid-connect/token -Headers $Headers -Body $Body

# Output the token string to a file to avoid CR/LFs
$MyToken = $TokenResults.access_token
Set-Content -Value $MyToken -Path C:\Stuff\MyTokenOutFile.txt

In both cases, the results will include an access_token value in addition to other data, as shown in Figure 431: Access Token for the Keyfactor API Reference and Utility. In the PowerShell case, this is output to a file to avoid introducing spaces or line wraps into the token value. You can open the output file, display the token without line wrapping, and copy the token value for pasting into the Keyfactor API Reference and Utility. Any line wraps that display on the screen in either the PowerShell window or text editor window will be interpreted by copy/paste as CR/LF, which will cause API commands to fail when the resulting token is submitted. Be sure to use a text editor to open the output file that can display the entire length of the token string as a single line. The built-in Windows Notepad application will display a maximum of 1024 characters on a line before wrapping even if word wrap is disabled. A tool such as the third-party Notepad++ is much less limited.

To use the token in the Keyfactor API Reference and Utility:

1. Copy the access token value only with no spaces or CR/LFs. For example:

   eyJhbGciOi JSUzI1NiIsI nR5cCIgOiAiS ldUIiwia2lkI iA6ICJmYU04Nj Q5UHAzREl1NWN BWkk4a3NYSV [portion removed for display ] KmIoPWfTu_APh MltlbXnnO8NCic2T faF_IrVjlc95EK4b6I aEbWcbCIg_896f5bOxrXed ouGP12dbRHOqB2jffD1glDveTB2XL 4WnbTVuSbgc2NsI SoNzGZB-HGXIW llo4l-PXK42nY5Y Ur7k0lf2W39HSojk yJRuwrpBjeV UmeDVQ_njCQ1ru fxrDK1ZkAnbw3r YiJKGzsVJzAl NwTFiM6-9pHPz6 8Nc1rPwviPyAmQ

2. In the Keyfactor API Reference and Utility click either the Authorize button at the top or one of the padlock authorization icons on each endpoint to open the authorization dialog.

   

   

   Figure 432: Keyfactor API Reference and Utility Authorize Options

3. In the Available authorizations dialog, paste in your access token value and click Authorize.

   

   Figure 433: Enter Access Token in the Keyfactor API Reference and Utility

4. If authorization is successful, the Authorize button will change to Logout, and the padlocks will change to locked.

   

   Figure 434: Successful Authorization in the Keyfactor API Reference and Utility

# Build the headers for the API request
$headers = @{
   "Authorization"="Bearer " + $TokenValue.access_token
   "Accept"="application/json"
   "x-keyfactor-requested-with"="APIClient"
}