Session Credentials

Operations invoked by the REST API run as the Windows System account, which cannot decrypt credentials that are not shared with it. To facilitate this ability, you must provide session credentials for the specified user. Session credentials are an explicit local login with a local API server Window Session. This provides a local token that is used to initialize access to the Security Controls credential store. These credentials define the exact user account that will be used by the system account when performing patch scan and patch deployment operations remotely using the REST API.

For information about creating, locating, sharing, and deleting credentials, see Credentials.

Some important notes about session credentials:

  • The session credential password must be the same as that of the Windows user account that is used to authenticate to the REST API.
  • There is no session credential timeout.
  • It is safe to initialize the session credential multiple times. If it already exists, the REST API will respond with a 409 Conflict response status code. This can safely be ignored.
  • To reset the session credential you must delete it and then add it back.

Base URL

        https://<consoleFQDN:port>/st/console/api/v1.0/sessioncredentials

Supported Requests

Method URL Input Return

DELETE

https://<consoleFQDN:port>/st/console/api/v1.0/sessioncredentials

 

Success code

POST

https://<consoleFQDN:port>/st/console/api/v1.0/sessioncredentials

Session Body

 

Input Models

Name Description

cipherText

Sets the encrypted password. The type of encryption is determined by ProtectionMode and SessionKey. Mutually exclusive with ClearText.

clearText

Sets the unencrypted password. Mutually exclusive with CipherText.

protectionMode

The type of data protection applied to the password for at-rest security. The valid options are:

  • None: This is the default
  • Local DPApi: Will not work remotely
  • SessionKey: Protected with an RSA-encrypted session key

sessionKey

Defines an encrypted session key used to protect the password in transit and at rest. It contains the following fields:

  • algorithmIdentifier: Required. The algorithm URI identifier. Valid values vary based on platform, FIPS compliance and the availability of crypto providers. The best practice is AES.
  • encryptedKey: Required. The base64-encoded, RSA-encrypted session key.
  • iv: The base64-encoded, unencrypted initialization vector used with the session key. It is used to seed the security algorithm.

Request Examples

This follows the security best practices by encrypting the password while it is in memory. Passwords sent over the network are encrypted using TLS and are always encrypted in storage.

POST Request

Copy 
https://<consoleFQDN:port>/st/console/api/v1.0/sessioncredentials 

    {
        "cipherText": $cipherText; "protectionMode": "SessionKey"; "sessionKey": "AES"
    }

For more information, see function Add-Credential in the Start-to-Finish Example.

This example shows how to create and set a session credential. For more information about the credentials function, see Credentials.

#SetSessionCredentials
$securePassword = ConvertTo-SecureString "secretPassword" -AsPlainText -Force
					
$global:ExampleRestApiCredential = New-Object System.Management.Automation.PSCredential ("domain\user", $securePassword)
					
#CreatePSCredential
$pw = @{ClearText = (New-Object PSCredential "user", $global:ExampleRestApiCredential.Password).GetNetworkCredential().Password} | ConvertTo-Json -Depth 20
					
Invoke-RestMethod -Credential $global:ExampleRestApiCredential https://<consoleFQDN:port>/st/console/api/v1.0/sessioncredentials -body $pw -Method Post -ContentType "application/json"

For a fuller understanding of how to create and use credentials, see PowerShell Example: Create and Install an Agent.

The following PowerShell script shows how to use the session credential to initiate a patch scan against a remote endpoint using the API. It makes some simplifying assumptions, including sending a password in plain text, which we do not recommend.

Copy 

param
(
    # The DNS name of the Ivanti Security Controls REST API Server.
    [Parameter(Mandatory = $true)]
    [String]$ISecServerDnsName,


    # The remote endpoint system to patch scan.
    # Note: this script makes the simplyfing assumption that you already have a machine credential defined for this endpoint or the session credential as admin rights to the endpoint.
    [Parameter(Mandatory = $true)]
    [String]$RemoteEndpointMachineName
)

###########################################################################
# Interactively capture a credential to authenticate to the API Server.
$apiContextCredential = Get-Credential


###########################################################################
# Forward the credential to the service over the Secure TLS channel to allow the server to log in directly.
# The purpose of the Session credential is to prevent the need for delegation to remote Scan/Deploy targets from the ISeC Server.
# This also enables a local cryptographic context and the ability to decrypt credentials that are owned/assigned to the API user.

# The Session Credential IS the SAME credential as the Integrated Windows authentication challenge response user.
#  - The REST API authentication is the Windows Kerberos or NTLM challenge response. 
#  - The session credential is a explicit remote Logon on the ISEC server. 

#  - Note additional protection modes are available for the password to support long-lived sessions without defining the password as a string in memory.
#  - See: https://help.ivanti.com/iv/help/en_US/isec/API/Topics/Credentials.htm#Session
# 

$sessionPasswordRequest =  @{ClearText = $apiContextCredential.GetNetworkCredential().Password; ProtectionMode = "None" }
$body = $sessionPasswordRequest | ConvertTo-Json

# Note: if prior sessions fail to complete or cleanup - you'll get a 409 - statement conflict resposne, in this case you should DETELE the session credential and post a new one.
$sessionCredentialresponse = Invoke-RestMethod -Uri "https://$($ISecServerDnsName)`:3121/st/console/api/v1.0/sessioncredentials" -Method Post -Body $body -ContentType "application/json" -Credential $apiContextCredential -Verbose



###########################################################################
# Scan the Remote Endpoint For Patches. 
# - Use the default Security Patch scan template.
# - Simplifing Assumption:
#    - this script makes the simplyfing assumption that you already have a machine credential defined for this endpoint 
#    - or - the session credential admin rights to the remote endpoint.


$scanRequestBody = @{ EndpointNames = @( $RemoteEndpointMachineName  ); Name = "API Session Cred Demo"; TemplateId = "4c7069eb-6e1c-4352-91fc-04d4d8abc07b"; UseMachineCredential = $True } | ConvertTo-Json -Depth 99
Write-Host "Starting scan"
$scanOperationResult = Invoke-WebRequest -Uri "https://$($ISecServerDnsName)`:3121/st/console/api/v1.0/patch/scans" -Method Post -Body $scanRequestBody -Credential $apiContextCredential -Verbose -ContentType 'application/json' -UseBasicParsing
$operationLocation = $scanOperationResult.headers['Operation-Location']

#### wait a few minutes for the patch scan to complete
$operationResult = Invoke-RestMethod -Uri $operationLocation -Method Get -Credential $apiContextCredential -Verbose
$startTime = [DateTime]::Now;
while ($operationResult.Status -eq 'Running')
{
    if ([DateTime]::Now -gt $startTime.AddMinutes(5))
    {
        Write-Host "Patch Scan wait timed out after 5 minutes"
        break;
    }

    # Poll every 15 seconds or so to check the status.
    Start-Sleep 10
    $operationResult = Invoke-RestMethod -Uri $operationLocation -Method Get -Credential $apiContextCredential -Verbose
}

Write-Host "Patch Scan wait completed with status: $($operationResult.Status)"

###########################################################################
# Finally remove your Session credential. 
Invoke-RestMethod -Uri "https://$($ISecServerDnsName)`:3121/st/console/api/v1.0/sessioncredentials" -Method DELETE -Credential $apiContextCredential -Verbose

Output Model

Name Type Description

created

Boolean

Status success indicator.