GET Security Roles

The GET /Security/Roles operation returns the list of security roles configured in Keyfactor Command. Query parameters support 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. On success, the operation returns HTTP 200 OK 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 operation has two available versions. Keyfactor strongly recommends using the newer operation when possible. The v1 operation has been deprecated since it supports Active Directory identities only. The v2 operation has been redesigned to provide support for alternate identity providers and the newer claims-based authentication model that accompanies this. This version of the operation supports both Active Directory and other identity providers. For more information, see Endpoint Definition Versioning.

Version 2 of GET /Security/Roles 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 785: GET Security Roles v2 Input Parameters

Name In Description
QueryString Query

A string containing a query to limit the results (for example, 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: Searching Security Roles. The query fields supported for this operation 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 786: 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 Security Roles ID operation for the desired role. For details of the permissions associated withe the permission set to which the role belongs, use the GET Permission Sets ID operation with this permission set GUID. A role may be only granted a subset of the permissions available in a permission set.
Enable Cert Ownership A Boolean indicating if the role can be assigned as a certificate owner (True or False). If this security role is expected to be an owner of any certificate, this flag must be True. If this value is set to False, this role will not appear when trying to assign an owner to a certificate.
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 Security Roles ID operation for the desired role.

Version 1 of GET /Security/Roles includes the same capabilities as version 2, but offers support for managing only legacy formatted Active Directory identities.

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 operations that provide support for alternate identity providers and the newer claims-based authentication model that accompanies this. These newer operations support both Active Directory and other identity providers. See version 2 of this operation.

Table 787: 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 (for example, 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: Searching Security Roles. The query fields supported for this operation 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 788: 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 active (True or False). Security roles that have been deactivated 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 (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 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 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. operations, only.

Table 789: 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 790: 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 791: 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 792: 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 793: 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 794: 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 795: 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 796: 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 operations.

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

Table 797: Certificate Store Management Security Role Permissions - Legacy

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

Portal 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, set schedules, 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 798: 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 Schedule Certificate Store Management permissions)
  • Edit
  • Download
  • Get CSV
  • Identity Audit (Also requires the Read Security 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 operation. 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.
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 to be able to use the Add Certificate feature.

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

Table 799: 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 800: 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 801: 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 802: Management Portal Security Role Permissions: Legacy

Portal Permission API Permission Description

Read

 AdminPortal: Read

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

Table 803: 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 804: 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 805: 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 806: 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 to which they do not have both collection Read and Reports permissions.

Table 807: 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 808: 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 809: 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 810: 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 811: 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 812: 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 813: 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 Me Workflow Instances permission to provide the input.
Read - Started By Me WorkflowInstances: ReadMy

Users can view the workflow instances that have been initiated by them (for example, 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 allows you to call API operations and view results. It is primarily intended 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, and also serves as an interactive supplement to this API documentation. You can access it from the help menu () in the Management Portal.