NAME

Win32::IntAuth - Perl extension for implementing basic Windows Integrated Authentication

SYNOPSIS

  # at client:
  use Win32::IntAuth;
  my $auth  = Win32::IntAuth->new();

  # create a user token intended for the user the server process is running as
  my $token = $auth->create_token('my_service_user@my_domain.org')
    or die "couldn't create auth token, ", $auth->last_err_txt();
  # now transfer the token to the server process


  # at server:
  # receive the token from client, then:

  use Win32::IntAuth;
  my $auth  = Win32::IntAuth->new();

  # the service user will need the user rights
  # SeAssignPrimaryTokenPrivilege and SeImpersonatePrivilege
  # and needs to be trusted for delegation in ActiveDirectory

  # impersonate the user that created the token
  $auth->impersonate($token)
      or die "couldn't impersonate user, ", $auth->last_err_txt();

  print 'Hooray user ', $auth->get_username(), " authenticated!\n";

  # now do something as the impersonated user

  # revert back to standard server context
  $auth->revert()

DESCRIPTION

This module encapsulates (with Win32::API) the SSPI-API functions that are necessary to authenticate and impersonate remote users from an already existing session without additional specification of username and password.

The module does not handle transport of the created user token to the server process or service nor does it provise routines for further evaluation of user rights or group memberships.

The outline provided in the synopsis should be enough to get you started. For details please look at the SSPI docs.

Link to SSPI docs (as of 5/2008)

EXPORT

None by default. Only for calling the SSPI functions directly via _sspi_call() the constants can be imported with:

  use Win32::IntAuth qw/:constants/;

But to do that you will have to look at the implementation. May the source be with you :-).

CONSTRUCTOR

new

  my $auth  = Win32::IntAuth->new([debug => 1]);

Creates a new Win32::IntAuth object. By setting the debug parameter, you'll get a bit of debugging information on STDERR.

METHODS

All methods return undef on error. Call last_err() or last_err_txt() to get the error code respectively a short description.

last_err

Returns the last error code from a method call.

last_err_txt

Returns the last error text from a method call.

create_token($spn [, $mechanism [, $token]])

Create and returns a token for the current process user ready to be sent to the server service that should authenticate/impersonate the client.

The mechanism defaults to "Negotiate".

$spn has to be the UPN (User Principal Name) of the user the service is running as (or a dedicated Service Principal Name SPN).

$token is only used in a second call to create_token in case of a continue request. It must contain the token sent back by the server.

get_token_upn($token [, $spn])

Combines impersonate($token [, $spn]), get_username() and revert() for simple authentication without acting on behalf of the user.

Returns the fully qualified user name (UPN) of the token user.

impersonate($token [, $spn])

Impersonates the user that has created the token in the client session.

The client user has to have the appropriate rights. (At least network logon rights on the server the service is running at).

The service user has to have at least the user rights SeAssignPrimaryTokenPrivilege and SeImpersonatePrivilege and needs to be trusted for delegation in ActiveDirectory.

If the client creates the token for an ServicePrincipalName the server must call impersonate with the same SPN in $spn. Otherwise the UPN of the user the service is running as has to be used.

You will have to check continue_needed() after a call to impersonate(). If it is needed, impersonate will have returned a token to be sent back to the client. The client then has to make a second call to create_token with the server token as second parameter.

Proceed with the second client token as before.

continue_needed()

Will return 1 if the last call to impersonate() returned a request to ask the client for a second token.

revert()

Ends impersonation and reverts back to the original server context.

get_username()

Returns the fully qualified user name (UPN) of the current user. If called after impersonate it will return the impersonated user's UPN.

AUTHOR

Thomas Kratz <tomk@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2011 by Thomas Kratz

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available.

cpanm Win32::IntAuth

perl -MCPAN -e shell
install Win32::IntAuth