GET Security Roles

The GET /Security/Roles method is used to return the list of security roles configured in Keyfactor Command. Query parameters enable filtering using defined criteria, control over pagination by specifying the page number and return limit, and customization of sorting based on specified fields and order. This method returns HTTP 200 OK on a success with the details of the security roles.

Tip:  The following permissions (see Security Roles and Claims) are required to use this feature:

/security/read/

This method has two available versions. Keyfactor strongly recommends using the newer method when possible; the v1 method has been deprecated since it supports Active Directory identities only. The v2 method has been redesigned to provide support for alternate identity providers and the newer claims-based authentication model that accompanies this. This version of the method supports both Active Directory and other identity providers. For more information about versioning, see Versioning.

Version 2 of the GET /Security/Roles method has been redesigned to provide support for alternate identity providers and the newer claims-based authentication model that accompanies this. All new development should use this version.

Table 747: GET Security Roles v2 Input Parameters

Name In Description
QueryString Query

A string containing a query to limit the results (e.g., field1 -eq value1 AND field2 -gt value2). The default is to return all records. Fields available for querying through the API for the most part match those that appear in the Keyfactor Command Management Portal search dropdowns for the same feature. For querying guidelines, refer to: Using the Security Role Search Feature. The query fields supported for this endpoint are:

  • Name
PageReturned Query An integer that specifies how many multiples of the returnLimit to skip and offset by before returning results, to enable paging. The default is 1.
ReturnLimit Query An integer that specifies how many results to return per page. The default is 50. Very large values can result in long processing time.
SortField Query

A string containing the property by which the results should be sorted. Fields available for sorting through the API include:

  • EmailAddress
  • Id
  • Immutable
  • Name
  • PermissionSetId

Available sort fields are affected by the query provided in QueryString. The default sort field is  Name.
SortAscending Query An integer that sets the sort order on the returned results. A value of 0 sorts results in ascending order while a value of 1 sorts results in descending order. The default is ascending.

Table 748: GET Security Roles v2 Response Data

Name

Description
Id

An integer containing the Keyfactor Command identifier for the security role.
Name A string containing the short reference name for the security role.
EmailAddress A string containing an email address for the role. This address can be used from workflows to direct email messages to the owner of certificates for uses such as certificate expiration alerts (assuming the certificate owner for the certificates, a security role, has been populated)
Immutable A Boolean indicating if the role is immutable or not. Only the built-in Administrators role is considered immutable. The value of this parameter cannot be changed.
Permission SetId

A string containing the Keyfactor Command reference GUID of the permission set to which the role is assigned (see Permission Sets).

Tip:  For details of the permissions associated with the role, use the GET /SecurityRoles/{id} method (see GET Security Roles ID) for the desired role. For details of the permissions associated withe the permission set to which the role belongs, use GET /PermissionSets/{id} method (see GET Permission Sets ID) using this permission set GUID. A role may be only granted a subset of the permissions available in a permission set.
Claims Count

An integer indicating the number of claims mapped to the role.

Tip:  For details of the claims associated with the role, use the GET /SecurityRoles/{id} method (see GET Security Roles ID) for the desired role.
Important:  This version has been deprecated since it supports Active Directory identities only. It is retained for backwards compatibility, but all new development should use methods that provide support for alternate identity providers and the newer claims-based authentication model that accompanies this. These newer methods support both Active Directory and other identity providers. See version 2 of this method.

Table 749: GET Security Roles v1 Input Parameters

Name In Description
Validate Query

A Boolean that specifies whether the optional parameter of validate is false, which allows the AuditXML validation to be skipped when loading records, or true (or not specified) in which case validation will occur. The default is true.
QueryString Query

A string containing a query to limit the results (e.g., field1 -eq value1 AND field2 -gt value2). The default is to return all records. Fields available for querying through the API for the most part match those that appear in the Keyfactor Command Management Portal search dropdowns for the same feature. For querying guidelines, refer to: Using the Security Role Search Feature. The query fields supported for this endpoint are:

  • Name
PageReturned Query An integer that specifies how many multiples of the returnLimit to skip and offset by before returning results, to enable paging. The default is 1.
ReturnLimit Query An integer that specifies how many results to return per page. The default is 50. Very large values can result in long processing time.
SortField Query

A string containing the property by which the results should be sorted. Fields available for sorting through the API include:

  • Description

  • EmailAddress

  • Immutable
  • Name
  • PermissionSetId

Available sort fields are affected by the query provided in QueryString. The default sort field is  Name.
SortAscending Query An integer that sets the sort order on the returned results. A value of 0 sorts results in ascending order while a value of 1 sorts results in descending order. The default is ascending.

Table 750: GET Security Roles v1 Response Data

Name

Description
Id

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.
EmailAddress A string containing an email address for the role. This address can be used from workflows to direct email messages to the owner of certificates for uses such as certificate expiration alerts (assuming the certificate owner for the certificates, a security role, has been populated).
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 (false) or not (true). 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.
Permission SetId A string indicating the Keyfactor Command reference GUID of the permission set associated with the role (see Permission Sets).
Identities

An array of objects containing information about the security identities assigned to the security role. ClosedShow identity details.
Permissions

An array of strings containing the permissions assigned to the role in a comma-separated list of Name:Value pairs. See Legacy Security Structure for an overview of the possible permissions.

For example:

Copy 
"Permissions": [
   "AdminPortal:Read",
   "Dashboard:Read"
],
Legacy Security Structure

The legacy security structure is documented in the tables below. It was completely replaced in Keyfactor Command version 11.0, but is retained for backwards compatibility for use with deprecated v1 security roles APIClosed An API is 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, only.

Table 751: Agent Management Security Role Permissions - Legacy

Portal Permission API Permission Description

Read

 AgentManagement: Read

Users can:

  • View orchestrators, including filtering the Orchestrator Management grid
  • View orchestrator jobs, including status, schedules, failures and warnings

Modify

 AgentManagement: Modify

Users can:

  • Manage orchestrators, including approving and disapproving them
  • Unschedule and reschedule orchestrator jobs

Table 752: Alerts Security Role Permissions - Legacy

Portal Permission API Permission Description

Read

 WorkflowManagement: Read

Users can view the pending, issued, and denied certificate request alerts.

Modify

 WorkflowManagement: Modify

Users can modify the pending, issued, and denied certificate request alerts, including the alert text, recipients, and event handlers. Users can also add new alerts, delete alerts, and configure the pending alert delivery schedule.
Test WorkflowManagement: Test

Users can test the pending certificate request alerts, including sending email to recipients. Users must also have Read permissions for Alerts.

Table 753: Application Settings Security Role Permissions - Legacy

Portal Permission API Permission Description

Read

 ApplicationSettings: Read

Users can view the application settings.

Modify

 ApplicationSettings: Modify

Users can modify the application settings.

Table 754: Auditing Security Role Permissions - Legacy

Portal Permission API Permission Description

Read

 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 dropdown menu will display the Audit Log option to users with the Auditing Read permission.

Table 755: Certificate Collections Security Role Permissions - Legacy

Portal Permission API Permission Description

Modify

 CertificateCollections: Modify

Users can add or edit Certificate Collections. See Certificate Collection Permissions for more information.

Table 756: Certificate Enrollment Security Role Permissions - Legacy

Portal Permission API Permission Description

Enroll PFX

 CertificateEnrollment: EnrollPFX

Users can use the PFX Enrollment page in the Management Portal and the equivalent API functions.

Enroll CSR

 CertificateEnrollment: EnrollCSR

Users can use the CSR Enrollment page in the Management Portal and the equivalent API functions.

CSR Generation

 CertificateEnrollment: CsrGeneration

Users can use the CSR Generation page in the Management Portal and the equivalent API functions.

Manage Pending CSRs

 CertificateEnrollment: PendingCsr

Users can use the Pending CSRs page in the Management Portal and the equivalent API functions.

Table 757: Certificate Metadata Types Security Role Permissions - Legacy

Portal Permission API Permission Description

Read

 CertificateMetadataTypes: Read

Users can read custom metadata attribute definitions on the Certificate Metadata page in the Management Portal and the equivalent API functions.

Modify

 CertificateMetadataTypes: Modify

Users can add, edit, and delete custom metadata attribute definitions on the Certificate Metadata page in the Management Portal and the equivalent API functions.

Table 758: Certificate Requests Security Role Permissions - Legacy

Portal Permission API Permission Description
Manage WorkflowManagement: Participate

Users can participate in the pending, issued, and denied alerts by approving or denying certificate requests from the Certificate Requests page, from the individual pages reached from links included in alerts, or using the Keyfactor API /Workflow/Certificates endpoints.

Note:  In previous versions of Keyfactor Command, this permission was Workflow Management: Participate.

Table 759: Certificate Store Management Security Role Permissions - Legacy

See Application Permissions, Certificate Operations, Certificate Store Types and Certificate Store Operations for more information.

UI Permission API Permission Description

Read

 CertificateStoreManagement: Read

Users can view the certificate stores and applications tabs on the Locations > Certificate Stores menu, and view certificate store types.

Schedule CertificateStoreManagement: Schedule

Users can add certificates to certificate stores, renew/reissue certificates, schedule and remove certificates from certificate stores.

Modify

 CertificateStoreManagement: Modify

Users can manage all operations regarding certificate stores—including the stores, applications, and discovery process—and certificate store types.

Table 760: Certificates Security Role Permissions - Legacy

Portal Permission API Permission Description

Read

 Certificates: Read

Users can view certificates, including certificate history, and can download certificates. Users who also have Read permissions for Certificate Store Management or certificate store application permissions can add certificates to certificate stores from Certificate Search and Certificate Collections.

The certificate operations possibly available to users with this permission are:

  • Add to Certificate Store (Also requires the Read and ScheduleCertificate Store Management permissions)
  • Edit
  • Download
  • Get CSV
  • Identity Audit (Also requires the ReadSecurity Settings permission)
  • Include Revoked checkbox
  • Include Expired checkbox
  • Renew (Also requires the Read and Schedule Certificate Store Management permissions)
  • Remove from Certificate Store (Also requires the Read and Schedule Certificate Store Management permissions)

This permission can be applied at either the global or certificate collect level (see Certificate Collection Permissions.

Users with global Read role permissions can browse to Certificate Search in the Management Portal and view all saved certificate collections. They can view any certificate in the Keyfactor Command database and are not limited to just those returned by select collections. Users with this permission can view the certificates returned by searches and open the details of the certificates.

Users with collection-level Read role permissions on a collection will see the collections to which they have been granted access appear on the Certificate Collections menu (if they have been configured to appear on the menu—see Certificate Collection Management). The users will be able to view all the certificates in the collections and open the details of the certificates.

Edit Metadata

 Certificates: EditMetadata

Users can modify certificate metadata for certificates in the Certificate Details dialog (only information on the metadata tab can be edited) and the equivalent API functions.

If the users have also been granted global Read permission on Certificates, they can modify the metadata of any certificates within the Keyfactor Command database. If the users have not been granted the global Read permission, they can only modify the certificates found in collections to which they have been granted collection-level Read access.

Note:  If you plan to edit metadata via the Keyfactor API, the user running the API needs only Edit Metadata permissions. Read permissions are not required.
Import Certificates: Import

Users can import certificates using the Management Portal Add Certificate page or the Keyfactor API POST /Certificates/Import method. Users who also have Read permissions for Certificate Store Management or application permissions can add certificates to certificate stores from Add Certificate.

Note:  This permission cannot be applied at the certificate collection level.

Download with Private Key

 Certificates: Recover

Users can download the certificates with their private key.
Revoke Certificates: Revoke

Users can revoke certificates through Keyfactor Command.

Users with this role can use the revoke certificate operation on any certificates to which they have been granted access. This includes certificates that have been issued by a Microsoft or EJBCA CA configured for synchronization or by a cloud-based certificate vendor that is managed via a Keyfactor certificate gateway.

Important:  In order to successfully revoke certificates, the service account under which the Keyfactor Command application pool is running must be granted Issue and Manage Certificates and Manage CA permissions to the CA database as per Create Groups to Control Access to Keyfactor Command Features, or, if delegation is configured for the CA, the user executing the revoke must have the Issue and Manage Certificate permissions while the application pool service account has the Manage CA permissions. If you are using explicit credentials to authenticate your CA (see DCOM CAs - Authentication Method Tab), it is the user specified on the CA configuration in Keyfactor Command who must have permissions on the CA.
Delete Certificates: Delete Users can delete certificates and, if applicable, the private keys of the certificates from the Keyfactor Command database.

Import Private Key

 Certificates: ImportPrivateKey

Users can save the private key for the certificate in the Keyfactor Command database.

Users with this role can add a certificate with an associated private key through the Add Certificate option under the Certificate Locations menu (see Add Certificate) and the private key will be stored in the Keyfactor Command database. Users must also be granted the Import role in order to be able to use the Add Certificate feature.

Note:  This permission cannot be applied at the certificate collection level.

Table 761: Dashboard Security Role Permissions - Legacy

Portal Permission API Permission Description

Read

 Dashboard: Read

Users can view the panels on their personalized dashboard and add and remove them.
Risk Header Dashboard: RiskHeader Users can view the risk header at the top of the dashboard.

Table 762: Event Handler Registration Security Role Permissions - Legacy

Portal Permission API Permission Description

Read

 EventHandlerRegistration: Read

Users can view the event handler registration settings.

Modify

 EventHandlerRegistration: Modify

Users can modify the event handler registration settings.

Table 763: Identity Providers Security Role Permissions - Legacy

Portal Permission API Permission Description

Read

 IdentityProviders: Read

Users can view the identity provider settings.

Modify

 IdentityProviders: Modify

Users can modify the identity provider settings.

Table 764: Management Portal Security Role Permissions - Legacy

Portal Permission API Permission Description

Read

 AdminPortal: Read

Users can access the Management Portal. This permission must be enabled for all roles that will access the Management Portal.

Table 765: Monitoring Security Role Permissions - Legacy

Portal Permission API Permission Description

Read

 Monitoring: Read

Users can view the expiration alerts in the Certificate Alerts in the Management Portal and the equivalent API functions, including the alert schedule.

Modify

 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.
Test Monitoring: Test

Users can test the expiration alerts, including sending email to recipients. Users must also have Read permissions for Monitoring to access this in the Management Portal.

Table 766: PKI Management Security Role Permissions - Legacy

Portal Permission API Permission Description

Read

 PkiManagement: Read

Users can view PKI management settings within:

  • Certificate Authorities
  • Certificate Templates
  • Revocation Monitoring

Modify

 PkiManagement: Modify

Users can modify PKI management settings to:

  • Import, add, edit, and delete certificate authorities
  • Import and edit certificate templates
  • Add, edit, delete, and test revocation monitoring endpoints
  • Configure revocation monitoring schedules
  • Configure revocation monitoring recipients

Table 767: Privileged Access Management Security Role Permissions - Legacy

Portal Permission API Permission Description

Read

 PrivilegedAccessManagement: Read

Users can view PAM providers.

Modify

 PrivilegedAccessManagement: Modify

Users can add, edit, and delete PAM providers.

Table 768: Reports Security Role Permissions - Legacy

Portal Permission API Permission Description

Read

 Reports: Read

Users can generate and view reports.

Modify

 Reports: Modify

Users can modify the delivery schedule for reports in Report Manager in the Management Portal and the equivalent API functions and add, edit, and delete custom reports.

Note:   Report scheduling is limited by collection 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.

Table 769: Scripts Security Role Permissions - Legacy

Portal Permission API Permission Description

Read

 Scripts: Read

Users can view scripts.

Modify

 Scripts: Modify

Users can add, edit, and delete scripts.

Table 770: Security Settings Security Role Permissions - Legacy

Portal Permission API Permission Description

Read

 SecuritySettings: Read

Users can view the settings for Security Roles and Security Claims. Users must also have the Read permission for System Settings to access this in the Management Portal.

Modify

 SecuritySettings: Modify

Users can modify the settings for Security Roles and Security Claims.

Table 771: SSH Security Role Permissions - Legacy

Portal Permission API Permission Description

User

 SSH: User

Users can generate their own SSH keys.

Server Admin

 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).
Enterprise Admin SSH: EnterpriseAdmin Users can use all SSH functions (see SSH Permissions).

Table 772: SSL Management Security Role Permissions - Legacy

Portal Permission API Permission Description

Read

 SslManagement: Read

Users can view the SSL Discovery pages in the Management Portal and the equivalent API functions, 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.

Modify

 SslManagement: Modify

Users can modify the SSL Discovery 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

Table 773: System Settings Security Role Permissions - Legacy

Portal Permission API Permission Description

Read

 SystemSettings: Read

Users can view the orchestrator auto-registration settings; users must also have Read permissions for Agent Management to access this in the Management Portal. Users can view the System Settings for:

  • SMTP Configuration for email delivery of reports and alerts
  • Installed components
  • Licensing
  • General Alerts and Warnings about the health of the Keyfactor Command system (not related to a specific area of the product)

Modify

 SystemSettings: Modify

Users can modify the System Settings for:

  • 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

Table 774: Workflow Definitions Security Role Permissions - Legacy

Portal Permission API Permission Description

Read

 WorkflowDefinitions: Read

Users can view the configured workflow definitions.

Modify

 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.

Table 775: Workflow Instances Security Role Permissions - Legacy

Portal Permission API Permission Description

ReadAll

 WorkflowInstances: ReadAll

Users can view all the workflow instances that have been initiated.

Read - Assigned To Me

 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 Read - Assigned To MeWorkflow Instances permission in order to provide the input.
Read - Started By Me WorkflowInstances: ReadMy

Users can view the workflow instances that have been initiated by them (e.g., because they enrolled for a certificate).
Manage WorkflowInstances: Manage

Users can manage initiated workflow instances, including stopping, restarting, and deleting them.
Tip:  See the Keyfactor API Reference and Utility which provides a utility through which the Keyfactor API endpoints can be called and results returned. It is intended to be used primarily for validation, testing and workflowClosed A workflow is a series of steps necessary to complete a process. In Keyfactor Command, it refers to the workflow builder, which allows you to automate event-driven tasks such as when a certificate is requested, revoked or found in a certificate store. development. It also serves secondarily as documentation for the API. The link to the Keyfactor API Reference and Utility is in the dropdown from the help icon () at the bottom of the Management Portal side menu.