RpcGetAuthorizationContextForClient, fonction (rpcasync.h)

Article
03/01/2024

La fonction RpcGetAuthorizationContextForClient retourne le contexte Authz d’un client RPC qui peut être utilisé avec les fonctions Authz pour l’authentification hautes performances. Pris en charge pour les séquences de protocole ncalrpc et ncacn_* uniquement.

Syntaxe

RPC_STATUS RpcGetAuthorizationContextForClient(
  [in, optional] RPC_BINDING_HANDLE ClientBinding,
  [in]           BOOL               ImpersonateOnReturn,
  [in]           PVOID              Reserved1,
  [in, optional] PLARGE_INTEGER     pExpirationTime,
  [in]           LUID               Reserved2,
  [in]           DWORD              Reserved3,
  [in]           PVOID              Reserved4,
  [out]          PVOID              *pAuthzClientContext
);

Paramètres

[in, optional] ClientBinding

Handle de liaison sur le serveur qui représente une liaison à un client. Le serveur emprunte l’identité du client indiqué par ce handle. Si la valeur zéro est spécifiée, le serveur emprunte l’identité du client pris en charge par ce thread de serveur.

[in] ImpersonateOnReturn

Indique à la fonction d’emprunter l’identité du client au retour, puis de retourner une structure AUTHZ_CLIENT_CONTEXT_HANDLE . Définissez ce paramètre sur un paramètre différent de zéro pour emprunter l’identité du client. Consultez la section Notes.

[in] Reserved1

Réservé. Doit être NULL.

[in, optional] pExpirationTime

Pointeur vers la date et l’heure d’expiration du jeton. Si aucune valeur n’est passée, le jeton n’expire jamais. Le délai d’expiration n’est actuellement pas appliqué.

[in] Reserved2

Réservé. Doit être une structure LUID avec chaque membre défini sur zéro.

[in] Reserved3

Réservé. Doit être zéro.

[in] Reserved4

Réservé. Doit être NULL.

[out] pAuthzClientContext

Pointeur vers une structure AUTHZ_CLIENT_CONTEXT_HANDLE qui peut être passée directement aux fonctions Authz. Si la fonction échoue, le contenu de ce paramètre n’est pas défini.

Valeur retournée

Valeur	Signification
RPC_S_OK	L’appel a réussi.
RERROR_INVALID_PARAMETER	Un paramètre réservé est différent de sa valeur prescrite.
RPC_S_NO_CONTEXT_AVAILABLE	Le client RPC n’a pas été authentifié avec succès.

L’échec retourne un code d’erreur RPC_S_* ou un code d’erreur Windows. Les informations d’erreur étendues sont disponibles via les mécanismes de récupération de code d’erreur RPC ou Windows standard. Pour obtenir la liste des codes d’erreur valides, consultez Valeurs de retour RPC.

Remarques

La fonction RpcGetAuthorizationContextForClient peut être appelée dans le même contexte que la fonction RpcImpersonateClient . Toutes les fonctions qui empruntent l’identité case activée pour déterminer si l’appelant dispose du privilège SeImpersonatePrivilege. Si l’appelant a le SeImpersonatePrivilege, ou si l’identité authentifiée est identique à l’appelant, l’emprunt d’identité demandé est autorisé. Sinon, l’emprunt d’identité réussit au niveau De l’identification uniquement.

Note Le privilège SeImpersonatePrivilege n’est pas pris en charge tant que Windows XP avec Service Pack 2 (SP2).

La fonction RpcGetAuthorizationContextForClient est prise en charge uniquement pour les séquences de protocole ncalrpc et ncacn_* et n’est pas prise en charge sur les canaux nommés qui implémentent uniquement la sécurité de transport.

La fonction RpcGetAuthorizationContextForClient est thread-safe et peut être appelée à partir de plusieurs threads. Le contexte retourné dans pAuthzClientContext est indépendant de l’appel de fonction et peut être utilisé après son achèvement. L’appelant est chargé de libérer le contexte avec un appel à la fonction RpcFreeAuthorizationContext .

L’amélioration des performances observée à l’aide de la fonction RpcGetAuthorizationContextForClient, par rapport aux méthodes précédentes d’emprunt d’identité ou d’accès case activée ou de retour à soi, dépend des facteurs suivants :

Nombre de fois que la fonction est appelée pour une identité cliente donnée.
Suivi de la séquence de protocole et des identités en vigueur pour l’appel de fonction.

Les appels ultérieurs à la fonction RpcGetAuthorizationContextForClient pour la même identité client ont un coût extrêmement faible. Cette efficacité est obtenue grâce aux résultats des requêtes précédentes mises en cache et aux réponses retournées à partir du cache dans la mesure du possible.

Les appels sur ncalrpc avec le suivi des identités statiques exécutent la fonction RpcGetAuthorizationContextForClient plus rapidement que les appels sur ncalrpc avec le suivi dynamique des identités. Les appels sur ncacn_* s’exécutent avec approximativement la même vitesse pour une séquence de protocole donnée, que le suivi des identités soit statique ou dynamique.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows XP [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2003 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	rpcasync.h (inclure Rpc.h)
Bibliothèque	Rpcrt4.lib
DLL	Rpcrt4.dll