Macro

Summary

Executes code while impersonating the user.

Package

win32

Signature

impersonating-user (user-name password &key domain logon-type fail-form) &body body

Arguments

user-name

A string, or t.

password

A string.

domain

A string or nil.

logon-type

nil or one of the keywords :interactive, :batch, :network, :network-cleartext, :service and :new-credentials.

fail-form

A Lisp form.

body

Lisp forms.

Description

The macro impersonating-user executes the code of body while impersonating a specified user.

user-name and password specify login credentials. In general, these are strings but the symbol t as user-name is treated specially to mean the user that is currently interacting with the console of the computer (password is ignored in this case).

domain, if non-nil, must be a string specifying the domain or server where the account database to find the user is held. It can be "." meaning the local database. domain nil means use the default domain or server, as defined by Windows.

The logon-type keywords are mapped to the LOGON32_LOGON_* constants which are documented in the MSDN entry for LogonUser. The default value nil of logon-type is treated as an alias for :interactive.

body is evaluated only if the impersonation is successful. If the impersonation is not successful for any reason, body is not executed, and instead fail-form is evaluated.

On success, impersonating-user returns the result of the last form of body. On failure, it returns the result of fail-form.

Notes

Impersonation means that, in operations where the user identity makes a difference, the user identity is the impersonated user rather than the user running the process. For example, when opening a file the system uses the credentials of the impersonated user to check the access control list of the file. When creating a file, the impersonated user is also used as the owner and creator of the file.

The process that tries to impersonate must have special privilege to do that. Processes do not normally have these privileges. The processes that do are those that run with system credentials, for example services. Impersonation is used by these processes to perform specific operations with the credentials of some user rather than the system user.

Impersonation can also be used when a service process wants to start a process to interact with the user. In that situation, the new process must run as the user. To do that, you start process inside the scope of impersonating-user, for example by calling call-system or open-pipe. Normally you will want to run as the user that is currently logged on the console (see the special user-name value t above).

See also

impersonating-named-pipe-client