POST PKI/HashiCorp/Role

Creates a role in Trust Protection Platform. After role creation:

The HashiCorp Vault PKI application driver uses onboard validation to enforce the role policy. Daily onboard validation also compares the CA certificate in the Vault with the certificate of record in Trust Protection Platform.
The role is ready to provision to the vault. Because there is no automatic way to provision a role to the HashiCorp vault, you must call POST PKI/HashiCorp/CA/{guid}.

Prerequisites

In HashiCorp, create role permissions. For more information, see HashiCorp Vault permission requirements.

Requirements

Permissions: The caller must have Create permission and Manage Policy permission to the Policy folder where the role will be created.
Token scope: Certificate:Manage

Headers

Content type: Content-Type:application/json.
Token: The bearer access token that you received. For example, Authorization:Bearer 4MyGeneratedBearerTknz==. For more information, see Passing a bearer token in your API calls.

Parameters

For additional information, about HashiCorp roles, see https://www.vaultproject.io/api-docs/secret/pki/#createupdate-role [vaultproject.io].

When adding query parameters, use the /? syntax. If you are not passing any parameters, make sure the URL ends with a trailing slash. Otherwise, some environments, such as cURL and PowerShell, return a HTTP 307 Temporary Redirect message.

Input parameters
Name	Description
City	(Optional) The allowed City or Locality (L) that this role can use for CSRs.
Country	(Optional) The allowed Country (C) that this role can use for CSRs.
EnhancedKeyUsage	(Optional) The way to enforce the public key of a certificate: client_flag: This role can generate CSRs for client certificates. code_signing_flag: This role can generate CSRs for code signing certificates. email_protection_flag: This role can generate CSRs for email protection certificates. server_flag: This role can generate CSRs for server certificates.
FolderDn	The Policy folder that will hold the new role.
KeyAlgorithm	(Optional) Required when the HashiCorp Vault CA is responsible for generating the key pair and CSR. Use in conjunction with KeyBitSize. rsa: Default. RSA key. ec: ECC (Elliptic Curve Cryptography) key.
KeyBitSize	(Optional) Required when the HashiCorp Vault CA is responsible for generating the key pair and CSR. Use in conjunction with KeyAlgorithm: For rsa, specify 2048 or 4096 bits. For ec, specify 256, 384, or 521. Use the value that corresponds to National Institute of Standards and Technology (NIST): P256, P384, and P521.
Organization	(Optional) The allowed Organization (O) that this role can use for CSRs.
OrganizationalUnits	(Optional) An array of allowed department or divisions within the organization (OU) that this role can use for CSRs.
RoleName	The role name. The role only appears in Trust Protection Platform until you call POST PKI/HashiCorp/CA.
State	(Optional) The allowed State ( ST) that this role can use to generate CSRs.
WhitelistedDomains	(Optional) This role only allows the Common Name (CN) and Domain Name Server (DNS) SANs in CSRs to end with one of the domains from the array.

Returns

Response description
Name	Description
HTTP 400 on Error	For invalid requests, this method an Error: An error message for invalid parameters data, or syntax. [FolderDn] parameter is required. [RoleName] parameter is required. Can't read parent policy object. You do not have sufficient rights to the object. Failed to create role object. Invalid permissions. You do not have permission to create object. Invalid permissions. You do not have permission to manage policy object. Invalid value for [EnhancedKeyUsage]. Valid values are client_flag, server_flag, code_signing_flag, email_protection_flag. Invalid value for [KeyAlgorithm]. Valid values are ec, rsa. Role already exists. Guid [roleObject.GUID]. Role Id [policyGuid] does not exist or you do not have sufficient rights to the object.
HTTP 307	If the method is missing a slash (/) at the end of the URL or between the query parameters, this message appears: There is no operation listening for [Web SDK method], but there is an operation listening for [Web SDK method/], so you are being redirected there.
HTTP 200 on Success	For valid requests, this method returns a HTTP 200 message and the following message body: Error: Null. Guid: A GUID that uniquely identifies the new role.

Example: Create a role in Trust Protection Platform

Request for Example

POST https://test.venafi.example/vedsdk/PKI/HashiCorp/Role/ 
Authorization:Bearer 4MyGeneratedBearerTknz==
{
   "FolderDn":"\\VED\\Policy\\HashiCorp",
   "RoleName":"TestRole",
   "WhitelistedDomains":[
      "OKdomain.com"
   ],
   "AllowSubdomain":true,
   "OrganizationalUnits":[
      "Lab 71"
   ],
   "Organization":"Venafi",
   "City":"SLC",
   "State":"UT",
   "Country":"US",
   "KeyAlgorithm":"rsa",
   "KeyBitSize":"2048",
   "EnhancedKeyUsage":[
      "server_flag"
   ]
}

Response for Example

HTTP/1.1 200 OK
{
   "Error":null,
   "Guid":"{1951b602-ee26-4222-bd28-64f8b6f57db7}"
}