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.
DID YOU KNOW? This call, which is managed by the VEDauth service, replaces a Web SDK call by the same name.
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.
CAUTION Secure your bearer tokens. Do not share tokens with other integrations. When processing completes, your integration can manage the grant by calling GET Revoke/Token.
Prerequisites
Register an API Integration and give the caller access. Use the scope and other information from the integration. For more information, see Setting up access token authentication.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.
Name | Description |
---|---|
client_id | Case sensitive. The value must match the Client ID in the API integration. For more information, see Setting up access token authentication. |
scope | The set of scopes and restrictions for the client_id. The set must:
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:
|
Returns
Name | Description |
---|---|
HTTP 200 | For valid requests, Authorize/Certificate returns a HTTP 200 message; and the following data:
|
HTTP 400 | If the response is HTTP 400, a generic error appears with a customized description for this particular endpoint.
|
HTTP 401 | If there are authentication errors, this API call returns a HTTP 401; it includes one of the following:
|
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 }