POST Security Roles

Documentation Suite v10.3

POST Security Roles

The POST /Security/Roles method is used to create a new security role in Keyfactor Command. This method returns HTTP 200 OK on a success with the details of the security role.

Tip: The following permissions (see Security Overview) are required to use this feature:

SecuritySettings: Modify

Table 477: POST Security Roles Input Parameters

Name

Description

Name

Body

Required. A string containing the short reference name for the security role.

Description

Body

Required. A string containing the description for the security role.

Enabled

Body

A Boolean that indicates whether the security role is enabled (true) or not (false). Security roles that have been disabled cannot be assigned to security identities. The default is true.

This is considered deprecated and may be removed in a future release.

Private

Body

A Boolean that indicates whether the security role has been marked private (true) or not (false). The default is false.

This is considered deprecated and may be removed in a future release.

Permissions

Body

An object containing the permissions assigned to the role in a comma-separated list of Name:Value pairs. Show permission details.

Name	Value	Description
AdminPortal (a.k.a. Management Portal)	Read	Users can access the Management Portal. This permission must be enabled for all roles that will access the Management Portal.
AgentAutoRegistration	Read	Users can view the agent auto-registration settings; Users must also have Read permissions for Agent Management.
AgentAutoRegistration	Modify	Users can modify the agent auto-registration settings.
AgentManagement	Read	Users can access the Management Portal areas and 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. endpoints to: View orchestrators, including filtering the orchestrator Keyfactor orchestrators perform a variety of functions, including managing certificate stores and SSH key stores. management grid View orchestrator jobs, including status, schedules, failures and warnings
AgentManagement	Modify	Users can access the Management Portal areas and API endpoints to: Manage orchestrators, including approving and disapproving them Unschedule and reschedule orchestrator jobs
API	Read	Users can call the Classic (CMS) API endpoints.
ApplicationSettings	Read	Users can view the application settings.
ApplicationSettings	Modify	Users can modify the application settings.
Auditing	Read	Users can access the Audit Log page in the Management Portal, and will be able to make API requests to obtain data from the audit log (query, etc.). The System Settings drop-down menu will display the Audit Log option to users with the Auditing Read permission.
CertificateCollections	Modify	Users can add or edit certificate collections. See Certificate Permissions in the Keyfactor Command Reference Guide for more information.
CertificateEnrollment	EnrollPFX	Users can use the PFX A PFX file (personal information exchange format), also known as a PKCS#12 archive, is a single, password-protected certificate archive that contains both the public and matching private key and, optionally, the certificate chain. It is a common format for Windows servers. Enrollment Certificate enrollment refers to the process by which a user requests a digital certificate. The user must submit the request to a certificate authority (CA). page in the Management Portal and use the PFX enrollment related API endpoints.
CertificateEnrollment	EnrollCSR	Users can use the CSR A CSR or certificate signing request is a block of encoded text that is submitted to a CA when enrolling for a certificate. When you generate a CSR within Keyfactor Command, the matching private key for it is stored in Keyfactor Command in encrypted format and will be married with the certificate once returned from the CA. Enrollment page in the Management Portal and use the CSR enrollment related API endpoints.
CertificateEnrollment	CsrGeneration	Users can use the CSR Generation page in the Management Portal and use the CSR generation related API endpoints.
CertificateEnrollment	PendingCsr	Users can use manage pending CSRs.
CertificateMetadataTypes	Read	Users can read custom metadata Metadata provides information about a piece of data. It is used to summarize basic information about data, which can make working with the data easier. In the context of Keyfactor Command, the certificate metadata feature allows you to create custom metadata fields that allow you to tag certificates with tracking information about certificates. attribute definitions on the Certificate Metadata page in the Management Portal and with related API endpoints.
CertificateMetadataTypes	Modify	Users can add, edit, and delete custom metadata attribute definitions on the Certificate Metadata page in the Management Portal and with related API endpoints.
CertificateStoreManagement	Read	Users can view certificate stores—including the stores and containers but not discovery records—and certificate store types. Users who also have Read permissions for Certificates can view inventory for a certificate store. See Container Permissions in the Keyfactor Command Reference Guide for more information.
CertificateStoreManagement	Modify	Users can manage certificate stores—including the stores, containers, and discovery process—and certificate store types. Note that this permission does not control additions of certificates to certificate stores.
CertificateStoreManagement	Schedule	Users can add certificates to certificate stores, renew/reissue certificates, and remove certificates from certificate stores.
Certificates	Read	Users can view certificates in certificate search and certificate collections in the Management Portal and with related API endpoints, including certificate history, and can download certificates. Users who also have Read permissions for Certificate Store Management or container permissions can add certificates to certificate stores. See Certificate Permissions in the Keyfactor Command Reference Guide for more information.
Certificates	Import	Users can import certificates through Add Certificate in the Management Portal and with related API endpoints. Users who also have Read permissions for Certificate Store Management or container permissions can add certificates to certificate stores from Add Certificate.
Certificates	Recover	Users can download the certificates with their private key Private keys are used in cryptography (symmetric and asymmetric) to encrypt or sign content. In asymmetric cryptography, they are used together in a key pair with a public key. The private or secret key is retained by the key's creator, making it highly secure..
Certificates	Revoke	Users can revoke certificates through Certificate Search and Certificate Collections in the Management Portal and with related API endpoints.
Certificates	Delete	Users can delete certificates and, if applicable, the private keys of the certificates from the Keyfactor Command database.
Certificates	ImportPrivateKey	Users can save the private key for the certificate in the Keyfactor Command database.
Certificates	EditMetadata	Users can modify certificate metadata for certificates accessed through Certificate Search and Certificate Collections in the Management Portal and with related API endpoints.
Dashboard	Read	Users can view the panels on their personalized dashboard and add and remove them.
Dashboard	RiskHeader	Users can view the risk header at the top of the dashboard.
EventHandlerRegistration	Read	Users can view the event handler registration settings.
EventHandlerRegistration	Modify	Users can modify the event handler registration settings.
MacAutoEnrollManagement	Read	Users can view the Mac Auto-Enroll Management settings.
MacAutoEnrollManagement	Modify	Users can modify the Mac Auto-Enroll Management settings.
Monitoring	Read	Users can view the expiration alerts in the Certificate Alerts in the Management Portal and with related API endpoints, including the alert schedule.
Monitoring	Modify	Users can modify the expiration alerts, including the alert text, recipients and event handlers. Users can also add new alerts, delete alerts and configure the expiration alert delivery schedule.
Monitoring	Test	Users can test the expiration alerts, including sending email to recipients. Users must also have Read permissions for Monitoring.
PkiManagement	Read	Users can view the Keyfactor Command PKI A public key infrastructure (PKI) is a set of roles, policies, and procedures needed to create, manage, distribute, use, store and revoke digital certificates and manage public-key encryption. management settings within the following Management Portal areas and use related endpoints: Certificate Authorities Certificate Templates Revocation Monitoring
PkiManagement	Modify	Users can modify the Keyfactor Command PKI management settings: Import, add, edit, and delete certificate authorities Import certificate templates Add, edit, delete, and test revocation monitoring endpoints Configure revocation monitoring schedule Configure revocation monitoring recipients
PrivilegedAccessManagement	Read	Users can view PAM providers.
PrivilegedAccessManagement	Modify	Users can add, edit, and delete PAM providers.
Reports	Read	Users can generate and view reports.
Reports	Modify	Users can modify the delivery schedule for reports in Report Manager in the Management Portal and add, edit, and delete custom reports. Note: Report scheduling is limited by collection The certificate search function allows you to query the Keyfactor Command database for certificates from any available source based on any criteria of the certificates and save the results as a collection that will be availble in other places in the Management Portal (e.g. expiration alerts and certain reports). permissions. Users in roles that have Reports: Read and Modify permissions will also need to have Read collection permissions on individual collections to have the ability to add, edit and delete schedules associated with collections. The user will not have access to add, edit and delete schedules for any collections for which they do not have collection Read permissions in addition to Reports permissions.
SecuritySettings	Read	Users can view the settings for Security Roles and Security Identities. Users must also have the Read permission for System Settings.
SecuritySettings	Modify	Users can modify the settings for Security Roles and Security Identities in the Management Portal and with related API endpoints.
SSH The SSH (secure shell) protocol provides for secure connections between computers. It provides several options for authentication, including public key, and protects the communications with strong encryption.	User	Users can generate their own SSH keys.
SSH	ServerAdmin	Users can use all SSH functions, except creating server groups and assigning server group owners. Users have limited access to some functions based on server group ownership. See SSH Permissions in the Keyfactor Command Reference Guide for more information.
SSH	EnterpriseAdmin	Users can use all SSH functions. See SSH Permissions in the Keyfactor Command Reference Guide for more information.
SslManagement	Read	Users can view the SSL TLS (Transport Layer Security) and its predecessor SSL (Secure Sockets Layer) are protocols for establishing authenticated and encrypted links between networked computers. Network Discovery and Monitoring area in the Management Portal and with related API endpoints, including defined networks and the network ranges configured for them, agent pools, and scan results. Users can use the query tool on the Results tab to find discovered endpoints and then view the discovered endpoints, including the details for the endpoints.
SslManagement	Modify	Users can modify the SSL Network Discovery and Monitoring settings: Create, edit, and delete networks, including scan schedules and notification recipients Add, edit, and delete network ranges for networks Add, edit, and delete agent pools Add and remove discovered endpoints from monitoring
SystemSettings	Read	Users can view the System Settings for: Application Settings Event Handler Registration to view built-in or custom event handlers API Applications allowed to use the APIs for certificate lifecycle management SMTP Short for simple mail transfer protocol, SMTP is a protocol for sending email messages between servers. Configuration for email delivery of reports and alerts Installed components Licensing Alerts and Warnings about the health of the Keyfactor Command system
SystemSettings	Modify	Users can modify the System Settings for: Application Settings to configure many options for Keyfactor Command Event Handler Registration to add or remove built-in or custom event handlers Update SMTP Configuration for email delivery of reports and alerts Installed components, including removing servers from use Licensing, including the option to replace the existing license file
WorkflowDefinitions	Read	Users can view the configured 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. definitions.
WorkflowDefinitions	Modify	Users can modify both the built-in and any custom workflow definitions, including the name and description and the configuration for the steps. Users can also add new workflow definitions, delete workflow definitions, publish workflow definitions, and import and export workflow definitions.
WorkflowInstances	Manage	Users can manage initiated workflow instances, including stopping, restarting, and deleting them.
WorkflowInstances	ReadAssignedToMe	Users can view the workflow instances that have been initiated and are awaiting input from them. Tip: There is not a security permission at this level that controls whether users can provide input (a signal) to a workflow instance. This is controlled using the security roles configured on the specific workflow definition. Any user who holds one of the roles configured in the workflow step that requires a signal may provide the necessary input. The user does not need to hold the ReadAssignedToMe WorkflowInstances permission in order to provide the input.
WorkflowInstances	ReadAll	Users can view all the workflow instances that have been initiated.
WorkflowInstances	ReadMy	Users can view the workflow instances that have been initiated by them (e.g. because they enrolled for a certificate).
WorkflowManagement (a.k.a. Alerts)	Read	Users can view the pending, issued, and denied workflow alerts.
WorkflowManagement (a.k.a. Alerts)	Modify	Users can modify the pending, issued, and denied workflow alerts, including the alert text, recipients, and event handlers. Users can also add new alerts, delete alerts, and configure the pending alert delivery schedule.
WorkflowManagement (a.k.a. Alerts)	Test	Users can test the pending alerts, including sending email to recipients. Users must also have Read permissions for Workflow.
WorkflowManagement (a.k.a. Certificate Requests)	Participate	Users can participate in the pending, issued and denied workflow process by approving or denying certificate requests from the Certificate Requests page or from the individual pages reached from links included in alerts in the Management Portal and with related API endpoints.

For example:

"Permissions": [
   "AdminPortal:Read",
   "Dashboard:Read"
],

Identities

Body

An array containing one or more identifiers for each security identity to associate with the role. Show identifier information.

Name	Description
AccountName	Required^. A string containing the account name for the security identity. For Active Directory user and groups, this will be in the form DOMAIN\\user or group name. For example: KEYEXAMPLE\\PKI Administrators ^ One of AccountName or SID is required in order to specify an identity, but not both.
SID	Required^. A string containing the security identifier from the source identity store (e.g. Active Directory) for the security identity. ^ One of AccountName or SID is required in order to specify an identity, but not both.

For example:

"Identities": [
   {
      "Name": "KEYEXAMPLE\\jsmith"
   },
   {
      "Name": "KEYEXAMPLE\\mjones"
   }
]

Table 478: POST Security Roles Response Data

Name

Description

An integer containing the Keyfactor Command identifier for the security role.

Name

A string containing the short reference name for the security role.

Description

A string containing the description for the security role.

Enabled

A Boolean that indicates whether the security role is enabled (true) or not (false). Security roles that have been disabled cannot be assigned to security identities. The default is true.

This is considered deprecated and may be removed in a future release.

Immutable

A Boolean that indicates whether the security role has been marked as editable (true) or not (false). Internal Keyfactor Command roles are not editable. This setting is reserved for Keyfactor Command internal use.

Valid

A Boolean that indicates whether the security role's audit XML is valid (true) or not (false). A security role may become invalid if Keyfactor Command determines that it appears to have been tampered with. This setting is not end-user configurable.

Private

A Boolean that indicates whether the security role has been marked private (true) or not (false). The default is false.

This is considered deprecated and may be removed in a future release.

Identities

An array containing information about the security identities assigned to the security role. Show identity details.

Name	Description
Id	An integer containing the Keyfactor Command identifier for the security identity.
AccountName	A string containing the account name for the security identity. For Active Directory users and groups, this will be in the form DOMAIN\\user or group name. For example: KEYEXAMPLE\\PKI Administrators
IdentityType	A string indicating the type of identity—User or Group.
SID	A string containing the security identifier from the source identity store (e.g. Active Directory) for the security identity.

Permissions

An object containing the permissions assigned to the role in a comma-separated list of Name:Value pairs.

For example:

"Permissions": [
   "AdminPortal:Read",
   "Dashboard:Read"
],

Tip: For code examples, see the Keyfactor API Endpoint Utility. To find the embedded web copy of this utility, click the help icon (

) at the top of the Keyfactor Command Management Portal page next to the Log Out button.

POST Security Roles

Products

Solutions

Resources

Company