Page History

Scope

• The Universal Agent for Windows is frequently running in the system account or a service account and will execute jobs within the context and permission of this account.
• Running a job as a different user includes to login as that user, optionally load the user profile and execute commands in this context.
• User switching applies to
  • All job types (standalone jobs and job chain jobs)
  • Shell Jobs
  • API jobs in any of the supported languages
  • Pre-processing and post-processing Monitors
• This article applies to the Universal Agent for Windows only. For Unix environments there is no need for scheduler based user switching as the built-in sudo and su capabilities provide this functionality.

Introduction

• Display feature availability
  StartingFromRelease 1.11.4

  , see 

  Jira
  server SOS JIRA columns key,summary,type,created,updated,due,assignee,reporter,priority,status,resolution serverId 6dc67751-9d67-34cd-985b-194a8cdc9602 key JS-861

Introduction

• For user switching the Agent has to be operated for a user account or service account, not for the system account.
• The credentials of the target user for which a job should be executed are not stored with JobScheduler configuration data. Instead the
• For user switching the Agent has to be operated for a user account or service account, not for the system account.
• The credentials of the target user for which a job should be executed are not stored with JobScheduler configuration data. Instead the user account that runs the JobScheduler Windows Service stores credentials with the Windows Credential Manager. When a job should be executed then the JobScheduler Agent reads the credentials from the Windows Credential Manager. Reading credentials that have previously been stored using the same account works without the need to specify a password. Therefore the solution is free from the use of passwords.
• A login is performed with the target user credentials and the user's environment is active when executing the job.

...

Setting the Agent User Account

The Windows Credential Manager is accessible via its

• Graphical User Interface  
• Command Line Interface: cmdkey
• API: the API is used by the JobScheduler Agent

Manage credentials with the Graphical User Interface

...

• English: Control Panel -> Credential Manager
• German: Systemsteuerung -> Anmeldeinformationsverwaltung

...

user account that is used by a Universal Agent can be set during the installation of the Agent. If an account is not specified here the Agent will run under the system account.

The Windows Services (German: Dienste) application shows the account an Agent is running under in the Log On As (German: Anmelden als) column.

To change the account right-click the Agent in the Windows Services application and select Properties. (German: Eigenschaften). Then select the Log On (German: Anmelden) tab and This Account (German: Dieses Konto) and then enter the account name and password.

Credential Manager

There are three possibilities for accessing the Windows Credential Manager:

• Graphical User Interface  
• Command Line Interface: cmdkey
• API: the API is used by the JobScheduler Agent

Manage credentials with the Graphical User Interface

• Log onto the operating system with the Agent account.
• Open the Credential Manager GUI:
  • English: Control Panel -> Credential Manager
  • German: Systemsteuerung -> Anmeldeinformationsverwaltung
• Select the Credential Type Windows Authentication -> Generic
  
  • Add a generic credential information for a target user with the following input fields: 
    • Intenet or network address
      • For use with JobScheduler this field holds the "target name" of the credentials. 
      • You are free to use any characters to specify a unique identifier for the credentials.
    • User name
      • The account for the target user can be specified by Unicode characters and digits including space, comma,  _, - and @
      • For domain users specify the  user principal name  (UPN) in the format username@DOMAIN
        • The format DOMAIN\username is not supported
    • Password
  • Your input screen should look like this:
    
    Image Added

Manage credentials with the Command Line Interface

• Open a Windows console window (cmd.exe) for the JobScheduler Agent account.
• Use the following commands to add credentials for a target user:

 # Add credentials for a local user 
cmdkey /generic:run_as_jobuser /user:JOBUSER /pass:PASSWORD 
 
# Add credentials for a domain user 
cmdkey /generic:run_as_jobuser /user:JOBUSER@DOMAIN /pass:PASSWORD 
 
# Show a list of all credentials 
cmdkey /list

Permissions

Permissions are required for the JobScheduler Agent account and for the target user of a job.

• To manage permissions switch to 
  • English: Control panel -> Administrative Tools -> Local Security Policy -> Local Policies -> User Rights Assignment
  • German: Systemsteuerung -> Verwaltung -> Lokale Sicherheitsrichlinie -> Lokale Richtlinien -> Zuweisen von Benutzerrechten
• Just in case you want to dig into the details, the following references describe the constants that are used for privileges:
  • Privilege Constants
  • Account Rights Constants
  • User Rights Assignment

Permissions for the Agent Account

Hint

To add a permission, right-click the permission and use the Properties -> Add user or group action in the User Rights Assignment (German: Zuweisen von Benutzerrechten) application opened above.

Apply the following permissions for the account that the Agent is to use:

• Permission: SE_ASSIGNPRIMARYTOKEN_NAME (SeAssignPrimaryTokenPrivilege)
  
  • English: Replace a process-level token
  • German: Ersetzen eines Tokens auf Prozessebene
  • French: Remplacer un jeton de niveau processus
  • Japanese: プロセス レベル トークンを置き換え
• Permission: SE_INCREASE_QUOTA_NAME (SeIncreaseQuotaPrivilege)
  
  • English: Adjust memory quotas for a process
  • German: Anpassen von Speicherkontingenten für einen Prozess
  • French: Ajuster les quotas de mémoire pour un processus
  • Japanese: プロセスのメモリ クォータの増加

Load target user profile

If the profile of the target user should be loaded then the Agent account requires the Administrator role, see LoadUserProfile, and the following permissions:

• Permission: SE_BACKUP_NAME (SeBackupPrivilege)
  
  • English: Back up files and directories 
  • German: Sichern von Dateien und Verzeichnissen
  • French: Sauvegarder des fichiers et des répertoires
  • Japanese: ファイルとディレクトリのバックアップ
• Permission: SE_RESTORE_NAME (SeRestorePrivilege)
  
  • English: Restore files and directories
  • German: Wiederherstellen von Dateien und Verzeichnissen
  • French: Restaurer des fichiers et des répertoires
  • Japanese: ファイルとディレクトリの復元

Hint

Right-click the permission and use the Properties -> Add user or group action to add the respective Agent account as explained above.

Important

Restart the JobScheduler Agent Windows Service in order to apply changes to roles and permissions.

Permissions for the Target User

Assign the following permissions for the target user of the job:

• Permission: SE_BATCH_LOGON_NAME (SeBatchLogonRight)
  
  • English: Log on as a batch job

  • German: Anmelden als Stapelverarbeitungsauftrag
  • French: Ouvrir une session en tant que tâche
  • Japanese: バッチ ジョブとしてログオン

Hint

Right-click the permission and use the Properties -> Add user or group action to add the respective target user as explained above.

Job Configuration

Jobs that should be executed for a target user have to be assigned the credentials key that has previously been stored with the Credential Manager for the Agent account. A resulting job could look like this: 

<job  order="yes" stop_on_error="no" credentials_key="run_as_jobuser" process_class="/agent">
    <script  language="shell">
        <![CDATA[
@echo username %USERNAME%
@echo userprofile %USERPROFILE%
        ]]>
    </script>
    <run_time />
</job>

<job  order="yes" stop_on_error="no" credentials_key="run_as_jobuser" load_user_profile="true" process_class="/agent">
    <script  language="shell">
        <![CDATA[
@echo username %USERNAME%
@echo userprofile %USERPROFILE%
        ]]>
    </script>
    <run_time />
</job>

When using the JOE job editor the settings for the credentials key and loading of user profile are available in the "Options" tab.

Error Messages

This section is intended to explain common error messages and pitfalls. Find a complete reference from System Error Codes.

Errors when using credentials

Error Code: WINDOWS-1168 (CredRead)

Windows Credential Manager does not return an entry named 'MyCredentialsKey': WINDOWS-1168 (CredRead) Element not found.

Windows Credential Manager does not return an entry named 'MyCredentialsKey': WINDOWS-1168 (CredRead) Element nicht gefunden.

COM-80020009 java.lang.IllegalArgumentException: requirement failed: Unsupported character in Windows user name: 'MYDOMAIN\JOBUSER'

Errors when setting file permissions

Error Code: COM-80020009 (icacls.exe)

COM-80020009 java.lang.RuntimeException: Windows command failed: C:\Windows\System32\icacls.exe => JOBUSER: No mapping between account names and security IDs was done.

COM-80020009 java.lang.RuntimeException: Windows command failed: C:\Windows\System32\icacls.exe => JOBUSER: Zuordnungen von Kontennamen und Sicherheitskennungen wurden nicht durchgeführt.

Errors when performing a logon for a target user

Error Code: WINDOWS-1326 (LogonUser)

WINDOWS-1326 (LogonUser) Logon failure: The user name or password is incorrect.

WINDOWS-1326 (LogonUser) Anmeldung fehlgeschlagen: unbekannter Benutzername oder falsches Kennwort.

Wrong credentials have been used for the target user. The problem is related to the credentials that have peviously been stored with the Credential Manager.

Frequently a wrong password has been used. This is suggested from the fact that in the preceding step the call to Icalcs to set permissions for log files did work for that target user, otherwise an exception would have been raised.

Check the Credential Manager for use of a valid user  name and password.

Error Code: WINDOWS-1385 (LogonUser)

WINDOWS-1385 (LogonUser) Logon failure: the user has not been granted the requested logon type at this computer.

WINDOWS-1385 (LogonUser) Anmeldung fehlgeschlagen: Der Benutzer besitzt nicht den benötigten Anmeldetyp auf diesem Computer.

Errors when creating user environment

Error Code: WINDOWS-5 (CreateEnvironmentBlock)

WINDOWS-5 (CreateEnvironmentBlock) Access is denied

WINDOWS-5 (CreateEnvironmentBlock) Zugriff verweigert

• Such problems can occur if at the time of process start for the target user that user is logged in on the same machine that the Agent is operated for, The user could be logged in for an interactive session or as a Windows service.
• This problem does not occur when a number of parallel jobs for the target user are executed by an Agent.

Errors when loading a user profile

Error Code: WINDOWS-1314 (LoadUserProfile)

...

• For use with JobScheduler this field holds the "target name" of the credentials. 
• You are free to use any characters to specify a unique identifier for the credentials.

...

Manage credentials with the Command Line Interface

• Open a Windows console window (cmd.exe) for the JobScheduler Agent account.

Permissions are required for the JobScheduler Agent account and for the target user of a job.

• To manage permissions switch to 
  • English: Control panel -> Administrative Tools -> Local Security Policy -> Local Policies -> User Rights Assignment
  • German: Systemsteuerung -> Verwaltung -> Lokale Sicherheitsrichlinie -> Lokale Richtlinien -> Zuweisen von Benutzerrechten
• Then right-click the permission and use the Properties -> Add user or group action to add the respective Agent account or target user as explained for the below permissions.
• Just in case that you want to dig into details find references about the constants that are used for privileges from the following links:
  • Privilege Constants
  • Account Rights Constants

Permissions for the Agent Account

Apply the following permissions for the account that the Agent is running for:

• Permission: SE_ASSIGNPRIMARYTOKEN_NAME
  
  • English: Replace a process-level token
  • German: Ersetzen eines Tokens auf Prozessebene
• Permission: SE_INCREASE_QUOTA_NAME
  
  • English: Adjust memory quotas for a process 
  • German: Anpassen von Speicherkontingenten für einen Prozess

Load target user profile

If the profile of the target user should be loaded then the Agent account requires the Administrator role, see LoadUserProfile, and the following permissions:

• Permission: SE_BACKUP_NAME
  
  • English: Back up files and directories 
  • German: Sichern von Dateien und Verzeichnissen
• Permission: SE_RESTORE_NAME
  
  • English: Restore files and directories
  • German: Wiederherstellen von Dateien und Verzeichnissen

Hints

Restart the JobScheduler Agent Windows Service in order to apply changes to roles and permissions.

Permissions for Target User

Assign the following permissions for the target user of the job:

• Permission: SE_BATCH_LOGON_NAME
  
  • English: Log on as a batch job 
  • German: Anmelden als Stapelverarbeitungsauftrag

Error Messages

This chapter is intended to explain common error messages and pitfalls.

• Find a complete reference from System Error Codes

Credential Manager

Error Code: WINDOWS-1168

Windows Credential Manager does not return an entry named 'MyCredentialsKey': WINDOWS-1168 (CredRead) Element not found.

Windows Credential Manager does not return an entry named 'MyCredentialsKey': WINDOWS-1168 (CredRead) Element nicht gefunden.

Icacls

Error Code: COM-80020009

COM-80020009 java.lang.RuntimeException: Windows command failed: C:\Windows\System32\icacls.exe => JOBUSER: No mapping between account names and security IDs was done.

COM-80020009 java.lang.RuntimeException: Windows command failed: C:\Windows\System32\icacls.exe => JOBUSER: Zuordnungen von Kontennamen und Sicherheitskennungen wurden nicht durchgeführt.

LogonUser

Error Code: WINDOWS-1326

WINDOWS-1326 (LogonUser) Logon failure: The user name or password is incorrect.

WINDOWS-1326 (LogonUser) Anmeldung fehlgeschlagen: unbekannter Benutzername oder falsches Kennwort.

WINDOWS-1385 (LogonUser) Logon failure: the user has not been granted the requested logon type at this computer.

WINDOWS-1385 (LogonUser) Anmeldung fehlgeschlagen: Der Benutzer besitzt nicht den benötigten Anmeldetyp auf diesem Computer.

LoadUserProfile

...

Code Block
language java title English: WINDOWS-1314
WINDOWS-1314 (LoadUserProfile) A required privilege is not held by the client.

Code Block
collapse language java title German: WINDOWS-1314 true
WINDOWS-1314 (LoadUserProfile) Dem Client fehlt ein erforderliches Recht.

...

The Agent account

are

is not assigned one or more of the following permissions: 

• Permission: SE_BACKUP_NAME

  • English: Back up files and directories
  • German: Sichern von Dateien und Verzeichnissen

• Permission: SE_RESTORE_NAME

  • English: Restore files and directories
  • German: Wiederherstellen von Dateien und Verzeichnissen

Error Code: WINDOWS-5 (LoadUserProfile)

Code Block
language java title English: WINDOWS-5
WINDOWS-5 (LoadUserProfile) Access is denied

Code Block
language java title German: WINDOWS-5 collapse true
WINDOWS-5 (LoadUserProfile) Zugriff verweigert

Common causes for this error include:

• The job  is configured to load the target user profile but the Agent account is not assigned the Administrator role. 

• This role is required for the Agent acount if the target user profile should be loaded.

API-Job stderr

...

Errors related to logs

Error Message: Access is denied

[info]   SCHEDULER-726  Task runs on remote scheduler http://localhost:5445<port>
[info]   SCHEDULER-918  state=starting (at=2017-08-02 15:00:47.803+0200)
[info]   [stderr] log4j:ERROR setFile(null,true) call failed.
[info]   [stderr] java.io.FileNotFoundException: <agent_data>\logs\jobscheduler_agent_<port>.log (Access is denied)
[info]   [stderr]     at java.io.FileOutputStream.open0(Native Method)
[info]   [stderr]     at java.io.FileOutputStream.open(Unknown Source)
[info]   [stderr]     at java.io.FileOutputStream.<init>(Unknown Source)
[info]   [stderr]     at java.io.FileOutputStream.<init>(Unknown Source)
[info]   [stderr]     at org.apache.log4j.FileAppender.setFile(FileAppender.java:294)
[info]   [stderr]     at org.apache.log4j.FileAppender.activateOptions(FileAppender.java:165)
[info]   [stderr]     at org.apache.log4j.DailyRollingFileAppender.activateOptions(DailyRollingFileAppender.java:223)
[info]   [stderr]     at org.apache.log4j.config.PropertySetter.activate(PropertySetter.java:307)
[info]   [stderr]     at org.apache.log4j.xml.DOMConfigurator.parseAppender(DOMConfigurator.java:295)
[info]   [stderr]     at org.apache.log4j.xml.DOMConfigurator.findAppenderByName(DOMConfigurator.java:176)
[info]   [stderr]     at org.apache.log4j.xml.DOMConfigurator.findAppenderByReference(DOMConfigurator.java:191)
[info]   [stderr]     at org.apache.log4j.xml.DOMConfigurator.parseChildrenOfLoggerElement(DOMConfigurator.java:523)
[info]   [stderr]     at org.apache.log4j.xml.DOMConfigurator.parseCategory(DOMConfigurator.java:436)
[info]   [stderr]     at org.apache.log4j.xml.DOMConfigurator.parse(DOMConfigurator.java:1004)
[info]   [stderr]     at org.apache.log4j.xml.DOMConfigurator.doConfigure(DOMConfigurator.java:872)
[info]   [stderr]     at org.apache.log4j.xml.DOMConfigurator.doConfigure(DOMConfigurator.java:778)
[info]   [stderr]     at org.apache.log4j.helpers.OptionConverter.selectAndConfigure(OptionConverter.java:483)
[info]   [stderr]     at org.apache.log4j.LogManager.<clinit>(LogManager.java:127)
[info]   [stderr]     at org.slf4j.impl.Log4jLoggerFactory.getLogger(Log4jLoggerFactory.java:64)
[info]   [stderr]     at org.slf4j.LoggerFactory.getLogger(LoggerFactory.java:285)
[info]   [stderr]     at com.sos.scheduler.engine.common.scalautil.Logger$.apply(Logger.scala:104)
[info]   [stderr]     at com.sos.scheduler.engine.taskserver.TaskServerMain$.<init>(TaskServerMain.scala:22)
[info]   [stderr]     at com.sos.scheduler.engine.taskserver.TaskServerMain$.<clinit>(TaskServerMain.scala)
[info]   [stderr]     at com.sos.scheduler.engine.taskserver.TaskServerMain.main(TaskServerMain.scala)
[info]   [stderr] log4j:ERROR Either File or DatePattern options are not set for appender [file].

Common causes for this error include that the Agent account is not assigned read/write permissions for the file jobscheduler_agent_<port>.log

...

.

This problem might occur after switching the account of the Agent Windows Service. To remedy this situation add read/write permissions to the Agent account and target user.

...