Documentation Suite v11.1

GET SSH Users

The GET /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./Users method is used to retrieve one or more SSH users defined in Keyfactor Command. The method returns both users and service accounts. See SSH in the Keyfactor Command Reference Guide for more information on the difference between users and service accounts. Results can be limited to selected users using filtering, and URL parameters can be used to specify paging and the level of information detail. This method returns HTTP 200 OK on a success with details for the requested SSH users and their public keys. To return the SSH 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., use the GET /SSH/Keys/MyKey method (see GET SSH Keys My Key) for user accounts and the GET /SSH/ServiceAccounts/Key/{id} method (see GET SSH Service Accounts Key ID) for service accounts.

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

/ssh/server_admin/

/ssh/enterprise_admin/

SSH actions are affected by ownership on the server group with which user to logon mappings are associated and limited for users with only the Server Admin (/ssh/server_admin/) role. For more information, see SSH Permissions.

This method has two available versions. Keyfactor recommends using the newer method when possible. For more information about versioning, see Versioning.

Version 2

Version 1

Version 2 of the GET /SSH/Users method redesigns how logon information for the user is returned, providing a greater level of detail in the returned data.

Table 721: GET SSH Users v2 Input Parameters

Name	In	Description
showOwnedAccess	Query	A Boolean that specifies whether to return only users that have logons on servers that the requesting user owns (true) or not (false). The default is false. This option applies only to requesting users with SSH User or SSH Server Admin permissions; users with SSH Enterprise Admin permissions will see all users regardless of the configuration of this setting. Use the GET /SSH/Servers method (see GET SSH Servers) or the GET /SSH/ServerGroups method (see GET SSH Server Groups) to determine ownership of a server or server group. Example: Example Scenario One Server A is owned by Gina and server B is owned by John. Gina is an SSH Server Admin but not an SSH Enterprise Admin. Dave has a logon on server B but not on server A. Gina does a GET /SSH/Users with showOwnedAccess=false and looks at the results for Dave's user record. She sees Dave's user record, but sees no specific logon information for Dave (other than the LogonCount), because all Dave's logons are on servers that Gina does not own. Gina does a GET /SSH/Users with showOwnedAccess=true and looks at the results for Dave's user record. Dave's user record does not appear. The presence or absence of Dave's user record is controlled by showOwnedAccess. The presence or absence of logon information associated with Dave's user record is controlled by Gina's level of SSH permissions—with SSH Server Admin permissions, Gina will always see only logons for servers that she owns. Example: Example Scenario Two Server A is owned by Gina and server B is owned by John. Gina is an SSH Server Admin but not an SSH Enterprise Admin. Dave has a logon on server B and a logon on server A. Gina does a GET /SSH/Users with showOwnedAccess=false and looks at the results for Dave's user record. She sees Dave's user record and she sees logon information for server A, but no logon information for server B. Because Gina does not own server B, logon information for that server is not visible to her. Gina does a GET /SSH/Users with showOwnedAccess=true and looks at the results for Dave's user record. She sees Dave's user record and she sees logon information for server A, but no logon information for server B. Because Gina does not own server B, logon information for that server is not visible to her. Notice there is no difference here in the results whether you choose true or false because at least one logon for Dave is present on a server owned by Gina. The showOwnedAccess option only comes into play when a user has no logons on a server owned by the requesting user. The presence or absence of logon information associated with Dave's user record is controlled by Gina's level of SSH permissions—with SSH Server Admin permissions, Gina will always see only logons for servers that she owns.
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 SSH Server Search. The query fields supported for this endpoint are: Email Fingerprint IsServiceAccount KeyLength KeyType LogonCount LogonServerGroupId LogonServerId ServiceAccountId StaleDate Username
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.
SortField	Query	A string containing the property by which the results should be sorted. Fields available for sorting through the API for the most part match those that appear as sortable columns in the Keyfactor Command Management Portal. The default sort field is Username.
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 722: GET SSH Users v2 Response Data

Name

Description

An integer indicating the Keyfactor Command reference ID of the SSH user.

Key

An object containing information about the key for the user. Show key details.

Name	Description
Id	An integer indicating the Keyfactor Command reference ID of the SSH user's key.
Fingerprint	A string indicating the fingerprint of the public key. Each SSH public key has a single cryptographic fingerprint that can be used to uniquely identify the key.
PublicKey	A string indicating the public key of the key pair for the SSH user.
KeyType	A string indicating the cryptographic algorithm used to generate the SSH key. Possible values are: RSA ECDSA Ed25519
KeyLength	An integer indicating the key length for the SSH key. The key length supported depends on the key type selected. Keyfactor Command supports 256 bits for Ed25519 and ECDSA and 2048 or 4096 bits for RSA.
CreationDate	A string containing the date, in UTC, on which the SSH key pair was created.
StaleDate	A string containing the date, in UTC, after which the SSH key pair is considered to be out of date based on the key lifetime defined by the Key Lifetime (days) application setting. See Application Settings: SSH Tab in the Keyfactor Command Reference Guide for more information.
Email	A string containing the email address of the user, for user accounts, or administrator or group of administrators responsible for managing the key, for service accounts. This email address is used to alert the user or administrator when the key pair is approaching the end of its lifetime.
Comments	An array of strings containing one or more strings with the user-defined descriptive comments, if any, on the key. Although entry of an email address in the comment field of an SSH key is traditional, this is not a required format. The comment may can contain any characters supported for string fields, including spaces and most punctuation marks. Keys created through the Keyfactor Command Management Portal or with the POST /SSH/Keys/MyKey or POST /SSH/ServiceAccounts method will contain only one string in the array.
LogonCount	An integer indicating the number of Linux logons associated with the SSH key pair.

Username

A string indicating the full username of the user or service account. For a user account, the username appears in DOMAIN\\username format (e.g. KEYEXAMPLE\\jsmith). For a service account, the username is made up of the user name and ClientHostname entered when the service account is created (e.g. myapp@appsrvr75).

Access

An object containing information about the Linux logons mapped to the user.

Show Linux logon mapping details.

IsGroup

A Boolean indicating whether the user is an Active Directory group (true) or not (false).

Version 1 of the GET /SSH/Users method includes the same capabilities as version 2, but offers more limited information on returned logons for the user.

Table 723: GET SSH Users v1 Input Parameters

Name	In	Description
showOwnedAccess	Query	A Boolean that specifies whether to return only users that have logons on servers that the requesting user owns (true) or not (false). The default is false. This option applies only to requesting users with SSH User or SSH Server Admin permissions; users with SSH Enterprise Admin permissions will see all users regardless of the configuration of this setting. Use the GET /SSH/Servers method (see GET SSH Servers) or the GET /SSH/ServerGroups method (see GET SSH Server Groups) to determine ownership of a server or server group. Example: Example Scenario One Server A is owned by Gina and server B is owned by John. Gina is an SSH Server Admin but not an SSH Enterprise Admin. Dave has a logon on server B but not on server A. Gina does a GET /SSH/Users with showOwnedAccess=false and looks at the results for Dave's user record. She sees Dave's user record, but sees no specific logon information for Dave (other than the LogonCount), because all Dave's logons are on servers that Gina does not own. Gina does a GET /SSH/Users with showOwnedAccess=true and looks at the results for Dave's user record. Dave's user record does not appear. The presence or absence of Dave's user record is controlled by showOwnedAccess. The presence or absence of logon information associated with Dave's user record is controlled by Gina's level of SSH permissions—with SSH Server Admin permissions, Gina will always see only logons for servers that she owns. Example: Example Scenario Two Server A is owned by Gina and server B is owned by John. Gina is an SSH Server Admin but not an SSH Enterprise Admin. Dave has a logon on server B and a logon on server A. Gina does a GET /SSH/Users with showOwnedAccess=false and looks at the results for Dave's user record. She sees Dave's user record and she sees logon information for server A, but no logon information for server B. Because Gina does not own server B, logon information for that server is not visible to her. Gina does a GET /SSH/Users with showOwnedAccess=true and looks at the results for Dave's user record. She sees Dave's user record and she sees logon information for server A, but no logon information for server B. Because Gina does not own server B, logon information for that server is not visible to her. Notice there is no difference here in the results whether you choose true or false because at least one logon for Dave is present on a server owned by Gina. The showOwnedAccess option only comes into play when a user has no logons on a server owned by the requesting user. The presence or absence of logon information associated with Dave's user record is controlled by Gina's level of SSH permissions—with SSH Server Admin permissions, Gina will always see only logons for servers that she owns.
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 SSH Server Search. The query fields supported for this endpoint are: Email Fingerprint IsServiceAccount KeyLength KeyType LogonCount LogonServerGroupId LogonServerId ServiceAccountId StaleDate Username
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.
sortField	Query	A string containing the property by which the results should be sorted. Fields available for sorting through the API for the most part match those that appear as sortable columns in the Keyfactor Command Management Portal. The default sort field is Username.
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 724: GET SSH Users v1 Response Data

Name

Description

An integer indicating the Keyfactor Command reference ID of the SSH user.

Key

An object containing information about the key for the user. Show key details.

Name	Description
Id	An integer indicating the Keyfactor Command reference ID of the SSH user's key.
Fingerprint	A string indicating the fingerprint of the public key. Each SSH public key has a single cryptographic fingerprint that can be used to uniquely identify the key.
PublicKey	A string indicating the public key of the key pair for the SSH user.
KeyType	A string indicating the cryptographic algorithm used to generate the SSH key. Possible values are: RSA ECDSA Ed25519
KeyLength	An integer indicating the key length for the SSH key. The key length supported depends on the key type selected. Keyfactor Command supports 256 bits for Ed25519 and ECDSA and 2048 or 4096 bits for RSA.
CreationDate	A string containing the date, in UTC, on which the SSH key pair was created.
StaleDate	A string containing the date, in UTC, after which the SSH key pair is considered to be out of date based on the key lifetime defined by the Key Lifetime (days) application setting. See Application Settings: SSH Tab in the Keyfactor Command Reference Guide for more information.
Email	A string containing the email address of the user, for user accounts, or administrator or group of administrators responsible for managing the key, for service accounts. This email address is used to alert the user or administrator when the key pair is approaching the end of its lifetime.
Comments	An array of strings containing one or more strings with the user-defined descriptive comments, if any, on the key. Although entry of an email address in the comment field of an SSH key is traditional, this is not a required format. The comment may can contain any characters supported for string fields, including spaces and most punctuation marks. Keys created through the Keyfactor Command Management Portal or with the POST /SSH/Keys/MyKey or POST /SSH/ServiceAccounts method will contain only one string in the array.
LogonCount	An integer indicating the number of Linux logons associated with the SSH key pair.

Username

LogonIds

An array of integers indicating the Keyfactor Command reference IDs for the Linux logons mapped to the user to cause the user's SSH public key to be published out to the Linux servers on which those logons reside.

Tip: See the Keyfactor API Reference and Utility which provides a utility through which the Keyfactor 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 can be called and results returned. It is intended to be used primarily for validation, testing and 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. 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 top of the Management Portal page next to the Log Out button.

Version 11.1

On this page: