POST Authorize/Certificate

Obtains an authorization token from the Trust Protection Platform server using a client certificate that identifies the caller. To setup, see the Remote SDK section in Setting up certificate authentication for web console. After this call completes, place the access_token in the header of your REST call. Your client can reuse the same token until it expires. As necessary, your client should track the expiration time and use the refresh token to get a new one. On exit, your client can revoke the token.

For remote clients that use certificates to authenticate with the Web SDK, a bearer token is only returned by the VEDauth authentication server, when:

• A client certificate is present in the caller's computer.
• The client certificate was issued by an approved issuer.
• The user identity originates in the Certificate Name (CN), Email Subject Alternate Name (SAN), or User Principal Name (UPN) SAN of the certificate. The value depends on settings in the certificate authentication configuration settings.
• The mapped identity is authorized to use the Web SDK.

Prerequisites

Requirements

Permissions: The caller is not required to have any special permissions.

Headers

• Content type: Content-Type:application/json.

• No bearer access token is necessary for this API call.

Parameters

In the request URL, specify vedauth. For example, POST https://tpp.venafi.example/vedauth/authorize/certificate. All parameter names are case sensitive.

Input parameters

Name	Description
client_id	Case sensitive. The value must match the Client ID in the API integration. For more information, see Setting up token authentication.
scope	The set of scopes and restrictions for the client_id. The set must: Match some or all of the scope(s) that appear in the API integration. Match the scopes that your application actually uses when it makes API calls. Use the Scope map for tokens to verify requirements for endpoint. Otherwise, missing scopes may cause a failure at run time. Syntax When getting a token via an Authorize call, you can use the entire scope from the UI API integration OR a subset of the scopes. Check your syntax: [No scope]: An Authorize call is not necessary because future APIs that you are using do not require an access token. Single scope, no privilege restriction: Just the scope. For example, certificate. Single scope and privilege restrictions: Comma separate each privilege. For example, certificate:manage,discover. Multiple scopes, no privilege restrictions: Delimit each scope with a semicolon (;) to get read access. For example, configuration;certificate;ssh. Multiple scopes and privilege restrictions: Delimit each scope with a semicolon (;). If a scope requires a privilege, prepend a colon before the corresponding privilege. Comma separate privileges. For example, certificate:discover,manage,delete;configuration:manage.

Returns

Example 1: Use a local certificate to authorize, receive an access token for other API calls

In Postman, configure Settings that identify the Trust Protection Platform server and the location of certificate that identifies the caller. For more information, see https://learning.getpostman.com/docs/postman/sending_api_requests/certificates/.

Request for Example 1

POST https://tpp.venafi.example/vedauth/Authorize/Certificate
{
    "client_id": "MyApp",
    "scope": "Certificate:discover,manage,delete"
}

Response for Example 1

HTTP/1.1 200 OK
{
   "access_token":"zmbVaygOBFtFV8TlUW9lqg==",
   "refresh_token":"HKBOMauZqglTwy2odNKlCw==",
   "expires_in":7775999,
   "expires":1618855359,
   "token_type":"Bearer",
   "scope":"Certificate:discover,manage,delete",
   "identity":"local:{de3944a8-3479-4450-b412-0dacd642017d}",
   "refresh_until":1642615359
}

Example 2: Use a PowerShell script and a local certificate; receive an access token for other API calls

Request for Example 2

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12

#Define Connection Variables
$Server = 'https://tpp.venafi.example/vedauth'
$uri = $Server+'/authorize/certificate'

#Build up the request to send to the server, so add any values that you need to pass,
$client_id = 'client-certificate-auth'
$scope ='certificate:discover,manage,delete'

$cert_pfx = "C:\Temp\client.pfx"
$cert_pass = "newPassw0rd!"
$cert = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2 -ArgumentList @($cert_pfx,$cert_pass)
Write-Host Client Certificate: $cert

#Put object together and convert to JSON
$MyObject = @{ client_id = $client_id; scope = $scope }
$json = $MyObject | ConvertTo-Json

#When passing a JSON object, you need to pass it with -Body $variable
$result = Invoke-RestMethod -Method Post -Uri $uri -Body $json -ContentType 
  "application/json" -Certificate $cert

Write-Host Created token: $result

Response for Example 2

HTTP/1.1 200 OK
Client Certificate: [Subject]
  CN=client

[Issuer]
  CN=WIN140-CA

[Serial Number]
  740000008DF0E4A8354FFB1DA900000000008D

[Not Before]
  6/12/2019 1:29:18 PM

[Not After]
  6/12/2020 1:39:18 PM

[Thumbprint]
  CEC60F1BBBA4B907BB836DFDE19ED09599AFFA2D

Created token: @{access_token=DvklL3cHWmH1GaDOaEqZ5Q==;
 refresh_token=D3aACQ9NPhSN8ymM4cjSAA==; expires_in= 7775999;
 expires= 1619042507; token_type=Bearer; scope=certificate:discover, 
 manage,delete; identity=AD+Active Directory:77338c27877bd0418c62176f256abd4d; 
 refresh_until= 1642802507 }