Retrieves the service account password, available to security support providers (SSPs), such as Kerberos SSP.
NTSTATUS NTAPI GetServiceAccountPassword( _In_ PUNICODE_STRING AccountName, _In_opt_ PUNICODE_STRING DomainName, _In_ CRED_FETCH CredFetch, _Inout_opt_ FILETIME *FileTimeExpiry, _Out_ PUNICODE_STRING CurrentPassword, _Out_ PUNICODE_STRING PreviousPassword, _Out_opt_ FILETIME *FileTimeCurrPwdValidForOutbound );
- AccountName [in]
Null-terminated account name of the Group Managed Service Account (gMSA) account. The user name can be one of the following forms:
- SAM account name of the gMSA.
- User name in a fully qualified domain name (FQDN), such as DomainName\UserName or www.domain.com\name. The user name must be a SAM name only. The domain name can be a DNS name or a NetBIOS name.
- Implicit user principal name (UPN) for the gMSA account, for example, SomeName@Domain.com where, according to the definition of an implicit UPN, the Domain.com is the actual domain DNS name.
- DomainName [in, optional]
Optional null-terminated domain name. This is valid only if the AccountName parameter is a SAM account name. The domain name can only be a NetBIOS name or a fully qualified domain name (FQDN).
- CredFetch [in]
A value of the CRED_FETCH enumeration that specifies how to retrieve the credential.
- FileTimeExpiry [in, out, optional]
On input, if this value is nonnull and is not a zero FILETIME, FileTimeExpiry contains the expiry time of the service account credentials as known to the caller. If the FileTimeExpiry parameter is the same as one of the current credentials, this call fails. On output, the FileTimeExpiry parameter contains the expiry time of the credential being returned.
- CurrentPassword [out]
The current password of the gMSA.
- PreviousPassword [out]
The previous password of the gMSA.
- FileTimeCurrPwdValidForOutbound [out, optional]
Denotes the time after which the current password is valid for outbound requests. The caller should compare the current time with this value and use the current password returned only if the current time is greater than or equal to the value returned by this parameter. The use of this parameter is designed for callers that do not have retry in the outbound logic, for example, NTLM.
If the function succeeds, the return value is STATUS_SUCCESS.
If the function fails, the return value is an NTSTATUS code. For more information, see LSA Policy Function Return Values.
You can use the LsaNtStatusToWinError function to convert the NTSTATUS code to a Windows error code.
When you have finished using the buffers returned in the CurrentPassword and PreviousPassword parameters, free them by calling the FreeLsaHeap function.
The GetServiceAccountPassword function can be called in the following scenarios:
From the logon functions of Security Support Providers (SSP), the SSP should detect that the SERVICE_ACCOUNT_PASSWORD is being used to log on to the entity and should check that the caller has TCB privilege or is a network service. Then the SSP should allow the log on process to proceed by getting the latest credential by calling the GetServiceAccountPassword function with the CredFetchDefault value in the CRED_FETCH enumeration.
From SSPs in their InitializeSecurityContext and AcceptSecurityContext calls. SSPs should detect that the SERVICE_ACCOUNT_PASSWORD is being used for these calls, and if the call is for nonprimary credentials, then the SSP should ensure that the caller has either TCB privilege or is a network service. Then the SSP should call the GetServiceAccountPassword function with the CredFetchDefault value in the CRED_FETCH enumeration and proceed with the call. If the InitializeSecurityContext and AcceptSecurityContext calls fail, then the SSP should use the FileTimeExpiry retrieved from the previous call to GetServiceAccountPassword and use it as input to calling GetServiceAccountPassword again using the CredFetchForced value in the CRED_FETCH enumeration. If a new gMSA credential is available, the second call will succeed with new credentials, and the SSP should then retry with the new credentials.
Minimum supported client
|Windows 8 [desktop apps only]|
Minimum supported server
|Windows Server 2012 [desktop apps only]|