PowerShell CLI 1.1 - Use Cases - Credentials Management

Starting Situation

Credentials

• Credentials are objects that include the specification of a user account and password that can be used for authenticattion:
  • HTTP Authentication with a JobScheduler Master.
  • HTTP Authentication with a Proxy.
• Credentials objects can be created once and can be re-used:
  • Credentials can be created within a PowerShell session. The PowerShell built-in Get-Credential cmdlet can be used to specify credentials on the fly, e.g. prompting the user for input of the user account and password.
  • Credentials can be created outside of a PowerShell session and can be used in a PowerShell session. The Get-JobSchedulerSystemCredentials cmdlet can be used to retrieve an existing credentials object for authentification with the JobScheduler Master.

Windows Credential Management

• Windows remembers accounts and  passwords that a user has been prompted for. The operating system will store user credentials in an encrypted file scheme known as the Windows Vault. Such credentials are used to automatically log on to a server/site without first being prompted to provide an account and password.
• Windows provides the Credential Manager API that allows to create, read, update and delete credentials objects.

• A number of tools are available for credential management based on the Windows Credential Manager API:

  • Use of the Windows cmdkey command.
  • Use of the Windows Credential Manager GUI front end for the Windows Vault. Search for "Credentials" (German: "Anmeldungsinformationsverwaltung") in the Windows Search Settings page.

  • In addition a vast number of tools is available for credentials management.

• Credentials can be managed in a number of scopes, e.g. generic credentials for a local environment and enterprise credentials for use within a domain.

Use Cases

Using the Windows cmdkey command to manage credentials

The following example shows how to add and read credentials by use of the cmdkey command:

C:\> cmdkey /add:login_as_ap /user:ap /pass:ap
C:\> cmdkey /list:login_as_ap

Explanations

• Line 1 adds credentials for the account ap with password ap and specifies the target name login_as_ap.
• Line 2 reads the credentials that have been stored with the target name login_as_ap.
• The cmdkey command can only be used for generic credentials within a local scope.

Using the Get-JobSchedulerSystemCredentials cmdlet to retrieve credentials

Using the target name login_as_ap from the above example allows the user who owns this credential to retrieve the credentials object.

• The Get-JobSchedulerSystemCredentials cmdlet accepts the target name of a system credentials object that is owned by the current user. This cmdlet returns a system credentials object.
• The Set-JobSchedulerCredentials cmdlet expects a PowerShell credentials object, that is used for authentication when accessing the JobScheduler Master.
• A conversion of system and PowerShell objects is required that can be achieved e.g. like this:

Import-Module JobScheduler
$systemCredentials = Get-JobSchedulerSystemCredentials -TargetName 'login_as_ap'
$credentials = ( New-Object -typename System.Management.Automation.PSCredential -ArgumentList $systemCredentials.UserName, $systemCredentials.Password )
Set-JobSchedulerCredentials -Credentials $credentials

Explanations

• Line 1 imports the JobScheduler PowerShell Module
• Line 2 reads an existing system credentials object that has been stored with the target name login_as_ap.
• Line 3 copies the user account and password of the system credentials object to the PowerShell credentials object. The password is provided as a secure string, i.e. it is not visible and cannot be logged.
• Line 4 forwards the PowerShell credentials object to the JobScheduler CLI for authentification with the JobScheduler Master.

Specifying explicit credentials

Explicit credentials can be specified with the Set-JobSchedulerCredentials cmdlet like this:

Set-JobSchedulerCredentials -Credentials $credentials

Explanations

• A credentials object is forwarded to the JobScheduler Master should authentication be required.
• This operation can be carried out at any time and is valid starting from the next request that is sent to the JobScheduler Master.
• The credentials object that can be created e.g. by
  • $credentials = ( New-Object -typename System.Management.Automation.PSCredential -ArgumentList 'account', ( 'password' | ConvertTo-SecureString -AsPlainText -Force) )
  • Technically this allows to store the account and password in a script which is not recommended for compliance reasons.
• Set-JobSchedulerCredentials without parameters removes an existing credentials object from being forwarded for web requests.

Specifying credentials on-the-fly

Explicit credentials can be specified on-the-fly with the Set-JobSchedulerCredentials cmdlet like this:

Set-JobSchedulerCredentials -AskForCredentials

Explanations

• The cmdlet will prompt for input of the user account and password that are used for authentication with a proxy server.

Specifying credentials with the Web Service URL

Explicit credentials can be specified on-the-fly with the Use-JobSchedulerWebService cmdlet -Url parametewr like this:

Use-JobSchedulerWebService -Url http://root:root@localhost:4446 -Id scheduler111

Explanations

• The user account and password separated by a colon are preceeding the hostname and are separated by a @ character from the hostname. 
• Specifying credentials like this is considered insecure. 

Using the PowerShell profile to apply credentials

• Credentials can be added to the JobScheduler CLI by a PowerShell profile. Typically the profile is stored with a file Microsoft.PowerShell_profile.ps1.
  • A number of locations are available for profiles. 
  • Check the value of the $Profile built-in variable for locations of your profile.
• You can copy & paste the above example for use of the Get-JobSchedulerSystemCredentials cmdlet to your PowerShell profile. This allows to automatically use the specified credentials for the JobScheduler Master.