Internet Authentication Service

Purpose

The Internet Authentication Service (IAS) API enables software developers to write their own extensions to IAS. IAS also allows developers to implement session control and accounting plug-ins, add authorizations, and use network authentication methods for remote access. IAS supports the Remote Authentication Dial-In User Service (RADIUS) protocol.

Where Applicable

IAS is applicable in any computing environment where it would improve efficiency to authenticate dial-in users through a remote server. This technology is especially useful for Internet Service Providers (ISPs).

Developer Audience

The IAS API is designed for use by C/C++ programmers. Programmers should also be familiar with networking concepts, and with the RADIUS protocol. RADIUS is documented in RFC 2865 and Draft Radius Accounting v2 05.

Run-Time Requirements

IAS is supported on Microsoft® Windows® 2000. It is also supported on Microsoft® Windows NT® Server version 4.0 with the installation of the Windows NT Option Pack or Microsoft Commercial Internet Service (MCIS).

See Also

Extensible Authentication Protocol (EAP)

Overview

General information about programming for Internet Authentication Service.

Reference

Documentation for functions, structures, and enumerated types for programming with Internet Authentication Service.

Samples

Sample code that extends the functionality of Internet Authentication Service.

Feedback

Make error reports and feature requests directly to Microsoft.

Microsoft Platform SDK, February 2001 Edition.
This content last built on Thursday, February 01, 2001.


About Internet Authentication Service

Internet Authentication Service (IAS) is a feature of Microsoft® Windows® NT version 4.0 and later that extends networking capabilities. You can use IAS to implement session control and accounting plug-ins, to add your own authorizations, and to use your own network authentication methods.

IAS is incorporated into Microsoft® Windows® 2000. IAS can also be installed into Microsoft® Windows NT 4.0 SP5 and higher from the Windows NT® Option Pack or Microsoft® Commercial Internet Service (MCIS).

The Windows 2000 version of IAS is more fully extensible than the Windows NT 4.0 version. Windows 2000 supports an additional function, RadiusExtensionProcessEx, and also supports authorization DLLs. These features are not available in the Windows NT 4.0 version of IAS.

Note Since the Windows 2000 version of IAS is based on the Option Pack version, Windows 2000 IAS does not support RADIUS Proxy.

This documentation describes the following topics:

  • Scope
  • Authentication and Accounting
  • Implementing DLLs to Extend IAS
  • RADIUS Accounting Packets
  • Working with a State Server


Scope

You can use extensions to Internet Authentication Service (IAS) to implement the following capabilities:

  • Control the number of end-user network sessions, using a state server.
  • Extend the remote access authorizations currently provided by IAS (on Windows® 2000 and later versions only).
  • Connect to Windows NT® Domain authentication databases and the Windows 2000 Active Directory.
  • Create custom authentication methods for Windows NT 4.0 SP5, and for Windows 2000.


Authentication and Accounting

Internet Authentication Service (IAS) fully supports the Remote Authentication Dial-In User Service (RADIUS) protocol. The RADIUS protocol is the de facto standard for remote user authentication.

The following paragraphs describe the roles played by the various elements of a RADIUS authentication solution.

A Network Access Server (NAS) operates as a client of the server that supports the RADIUS protocol. The server that supports the RADIUS protocol is generally referred to as the RADIUS server. The RADIUS client, that is, the NAS, passes user information to designated RADIUS servers, and then acts on the response that the servers return. The request sent by the client to the server in order to authenticate the user is generally called an "authentication request."

The NAS also sends information to designated RADIUS servers when the user logs on and logs off. The requests sent by the client to the server to record logon/logoff and usage information are generally called "accounting requests." The RADIUS Interim Accounting Draft published by the Internet Engineering Task Force (IETF) also allows the NAS to send usage information on a periodic basis while the session is in progress.

RADIUS servers receive connection requests from remote users. For each user, the RADIUS server authenticates the user, and returns configuration information to the NAS so that it can provide network service to the user. This configuration information is composed of "authorizations". The RADIUS server also collects a variety of information sent by the NAS that can be used for accounting and for reporting on network activity.

A RADIUS server can act as a proxy client to other RADIUS servers. In these cases, the RADIUS server contacted by the NAS passes the authentication request to another RADIUS server that actually performs the authentication.

While the RADIUS server is processing the authentication request, it can perform authorization functions such as verifying the user's telephone number and checking whether the user already has a session in progress. The RADIUS server can determine whether the user already has a session in progress by contacting a state server.


Implementing DLLs to Extend IAS

This section describes how to implement DLLs to extend the Internet Authentication Service (IAS). It describes the interaction between IAS and the DLLs, and presents some design considerations regarding the DLLs.

IAS provides two "plug-in" points, one for authentication and the other for authorization. Authentication refers to verifying the identity of the user. Authorization refers to determining what services the network should provide to the user. The two plug-in points correspond to Extension DLLs and Authorization DLLs. (Authorization DLLs are supported only on Windows 2000 and later systems.) Each plug-in point can support multiple DLLs.

IAS provides both authentication and authorization services. Extension DLLs are called by IAS prior to the built-in IAS authentication and authorization. Authorization DLLs are called after IAS authentication and authorization.


Setting Up the Extension and Authorization DLLs

At startup, IAS checks the registry for a list of third-party DLLs to call.

To set up an Extension or Authorization DLL on an IAS server, list the paths to the DLLs in values below the following registry key:

HKLM\System\CurrentControlSet\Services\AuthSrv\Parameters\

If the AuthSrv and Parameters keys do not exist, create them.

The value in which to list the Extension DLLs is:

ExtensionDLLs

The value in which to list the Authorization DLLs is:

AuthorizationDLLs

Both the ExtensionDLLs and AuthorizationDLLs values must be of type REG_MULTI_SZ. This type allows you to list multiple DLLs.


Authentication and Authorization Process

Both Extension DLLs and Authorization DLLs must export the function, RadiusExtensionProcess. The prototype for this function is in the Authif.h header file. IAS calls this function for each valid authentication or accounting packet that it receives from the Network Access Server (NAS). IAS calls RadiusExtensionProcess in each of the DLLs listed below the preceding registry key. The DLLs are called in the order in which they are listed.

On Windows 2000 and later systems, the DLLs may export RadiusExtensionProcessEx instead of RadiusExtensionProcess. RadiusExtensionProcessEx enables the DLL to append additional authorization attributes to the authentication response. The DLL cannot, however, modify or remove any of the attributes that are already present.

If a scenario arises in which the DLL might need to modify or remove attributes, the only option is to use the IAS user interface to ensure that the attributes are not present. By default, no authorization attributes will be present. Any that are present must have been added through the user interface.

In other respects, the semantics of RadiusExtensionProcessEx are the same as RadiusExtensionProcess. The following discussion of RadiusExtensionProcess is applicable to both functions.

The RadiusExtensionProcess function has access to all the attributes received in the authentication or accounting request. Using these attributes, the function can perform additional validations, validate the user's authorizations, or send accounting records to a central state server.

IAS will take various actions depending on the return value of RadiusExtensionProcess, and the value returned in the pfAction parameter of RadiusExtensionProcess:

pfAction | Extension DLL | Authorization DLL
Accept | Bypasses any further Extension DLLs and also bypasses the IAS authentication mechanism. | Accept not allowed.
Reject | Bypasses any further Extension DLLs and also bypasses the IAS authentication mechanism. Access-Reject packet is sent. | Bypasses any further Authorization DLLs.
Continue | The packet is sent to the next Extension DLL or to the IAS authentication mechanism if no more Extension DLLs are listed in the registry. | The packet is sent to the next Authorization DLL or to the IAS accounting log if no more Authorization DLLs are listed in the registry.

In the case of both Extension and Authorization DLLs, if RadiusExtensionProcess(Ex) returns an error, the packet is discarded. Packets that are discarded because of an error are not processed by the IAS accounting log.

If an error occurs, IAS posts a generic error event to the Event Log. It is recommended that the Extension or Authorization DLL provide additional error logging.

RadiusExtensionProcess(Ex) should return an error if it cannot reach a decision regarding the acceptance or rejection of the packet. Such a situation might arise if a network problem prevents RadiusExtensionProcess(Ex) from communicating with its user authentication database.

DLLs that process accounting packets should return either an error, or a pfAction of Continue.

Note After receiving an accept, IAS does not call the remaining RadiusExtensionProcess DLLs in the sequence. Some authentication functions may also implement authorizations within them; skipping such authentication functions may cause authorizations to be omitted. For example, Windows NT 4.0 Domain Authentication also checks authorizations. If RadiusExtensionProcess returns an accept, it is important not to make any assumptions about the authorizations retrieved.

If a continue or accept is returned, the profile corresponding to the realm will be sent back in the Access-Accept packet.

Extension DLLs should be designed to coexist with the built-in IAS authentication providers and with other Extension DLLs. If an extension is only applicable to a certain user database (for example Windows NT 4.0 Domain Authentication or Windows 2000 Active Directory), then it should check the ratProvider attribute passed in through the pAttrs parameter, before processing the request. The ratProvider attribute would be one of a list of attributes pointed to by the pAttrs parameter.

Extension and Authorization DLLs should generally not reject requests simply because needed attributes are missing. For example, if an authentication extension requires the User-Password attribute, ratUserPassword, and the attribute is not present, the extension should return an action of raContinue to give other extensions and providers a chance to process the request.

IAS calls the RadiusExtensionProcess function after the decision to use a particular authentication database is made, but before the user is authenticated. Therefore, information about which authentication database to use is available to the function, so that the function can check for the user's authorizations in the appropriate authentication database. IAS supports various authentication databases including: Windows NT 4.0 Domain Authentication, and the Windows 2000 Active Directory.

If the DLL exports both RadiusExtensionProcess and RadiusExtensionProcessEx, IAS will call RadiusExtensionProcess Windows NT 4.0 and RadiusExtensionProcessEx on Windows 2000.

The DLL may also export RadiusExtensionInit and RadiusExtensionTerm functions. IAS will call these functions if they are present.

The declarations for RadiusExtensionProcess and other functions supported for RADIUS Extension DLLs can be found in the header file Authif.h.


User Identification Attributes

The identity of the user requesting authentication is supplied to the Extension and Authorization DLLs in a number of different attributes:

  • ratUserName
  • ratStrippedUserName
  • ratFQUserName

Each attribute provides the user identity in a different format. In general, developers should use ratStrippedUserName. The uses of the ratUserName and ratFQUserName attributes are more specialized.

ratUserName

The ratUserName attribute contains the name that was actually sent "over the wire." IAS has not, in any way, processed or validated the contents of this attribute. This attribute may not be available at all because the user may have been identified through a means such as caller ID. If this attribute is available, it is available only at the Extension DLL plug-in point. It is not available at the Authorization DLL plug-in point because Authorization DLLs see only the "outbound" attributes.

ratStrippedUserName

The ratStrippedUserName is the user's identity after "realm stripping." This attribute will always be present at both the Extension DLL plug-in point and the Authorization DLL plug-in point. The format of the contents of this attribute may differ between Windows NT 4.0 and Windows 2000. On Windows 2000, this attribute is guaranteed to have the format:

Domain\UserName

Where "Domain" is the NetBios domain name. On Windows NT 4.0, this attribute generally has the above format, but IAS does not guarantee it.

ratFQUserName

The ratFQUserName attribute is the "fully-qualified" user name. This name is available at both the Extension DLL plug-in point and the Authorization DLL plug-in point. However, the format of the name may differ between the two plug-in points. At the Extension DLL plug-in point, the user name will always be of the form:

Domain\UserName

The format of the name at the Authorization DLL plug-in point depends on whether the user is an Active Directory user. If the user is a local user, or a Windows NT 4.0 user, ratFQUserName will have the same format at the Authorization DLL plug-in point. If the user is an Active Directory user, ratFQUserName will contain the user's name in "canonical" format. Canonical format is the format used by the Active Directory to identify the user. It is the path from the root of the Active Directory tree, and includes the user's Organizational Unit (OU). The IAS server must be running Windows 2000 in order for ratFQUserName to be in canonical format.


RADIUS Accounting Packets

This section describes only the most important aspects of the RADIUS accounting packets. The RADIUS Accounting internet draft (Draft Radius Accounting v2 05) provides detailed information on these packets.

RADIUS accounting packets can be divided into:

  1. Accounting-Start packet contains userid, nas-identifier/ipaddress, plus other information received from the NAS.
  2. Accounting-Stop record contains userid, nas-identifier/ipaddress, plus other information received from the NAS.
  3. Accounting-On record contains nas-identifier/ipaddress record and indicates that a particular NAS has restarted.
  4. Accounting-Off record contains nas-identifier/ipaddress record and indicates that a particular NAS has been shutdown.
  5. Accounting-Interim record is an accounting record that could be received from the NAS. This record is sent periodically by the NAS for each user that is logged on at the NAS. This feature is generally supported in newer versions of NASs.

The following issues are important to consider when collecting accounting information made available through RADIUS: In rare cases, records could be lost during transmission and may never reach the RADIUS server.

  1. The RADIUS server is not notified if the NAS aborts.
  2. If the authentication and accounting requests are received from a RADIUS Proxy, then the other ISP may not forward accounting-on, off records.
  3. ISDN supports multiple sessions and each session generates an accounting start/stop pair of records. There is an accounting attribute called multi-session identifier that clearly identifies such multi-session records. Check for the multi-session identifier in addition to the session identifier to calculate the number of sessions.


Working With a State Server

Internet Authentication Service (IAS) performs authentications using a database that is configured at the IAS server site. This authentication database could be the user database for a Microsoft® Windows NT®/Windows® 2000 Domain or it could draw upon the user information obtained from the Windows 2000 Active DirectoryThe following diagram illustrates a typical configuration that shows how IAS interacts with authentication databases such as a Windows Domain user database or Active Directory. The diagram also shows how IAS could interact with a state server that is provided by a third party. The primary purpose of a state server is to limit the number of simultaneous logon sessions a single user can run.

There are two points of interaction between IAS and the state server. One interaction takes place when IAS receives an authentication request from the NAS. The state server provides information from its database to determine whether to accept or deny the request. The other interaction takes place when IAS receives accounting records from the NAS. The state server uses these accounting records to update its database.


State Server Design Considerations

Depending on your design, you may need a server to track the users that are currently logged onto the network. The main challenge with the state server is keeping the information in the state server database in-sync with who is actually logged on. If the information in the state server is out of sync, users may succeed in having multiple sessions when they aren't authorized to do so. Also, users who do not have multiple sessions could be inadvertently penalized. The following should be taken into consideration in implementing the state server:

  1. The state server must make the decision online in a few seconds. For this reason the state server requires a scalable infrastructure that can support many updates and queries per second. Relational databases are not appropriate for such large queries with simultaneous updates. Relational databases are primarily built to keep data consistent and to provide a consistent view of the data to all consumers. They are not built for quick updates.
  2. Transactional consistency on updates between multiple objects is not important. This is because the state server can tolerate a small window of opportunity. However, transactional consistency of a single update is important to reduce the chances of leaving the state server in an inconsistent state if one of the RADIUS servers is shut down in the middle of the update.
  3. Persistence (saving the state of the network to persistent storage) is not important because the persistent information will quickly fall out of sync with the actual state of the network.
  4. If ISDN or other forms of multilink are supported on the network, the state server should be able to handle scenarios that use these features.

One possible design is to implement both an Extension DLL and an Authorization DLL. Each of these DLLs can communicate over the network with a database. The Authorization DLL can update the database with information about who is currently logged onto the network. The Extension DLL can query the database for this information to decide whether to accept or reject a particular user's authentication request; if the user is already logged on, the request is rejected.

The advantage of having the Authorization DLL update the state-server database is that the Authorization DLL has access to more information about the authenticated user. The Authorization DLL has access to all of the authorization attributes from the IAS Authorization mechanism. For example, some users may have authorizations that allow them to have multiple sessions. The state server should treat such users as a special case.


Using Internet Authentication Service

The following sample code implements the functions for a RADIUS extension DLL that checks the dial-in bit for the user.

///////////////////////////////////////////////////////////////////////////////
//
// Copyright (c) 1998, Microsoft Corp. All rights reserved.
//
// FILE
//
//    dialin.cpp
//
// SYNOPSIS
//
//    Implements the DLL exports for a RADIUS extension that checks the
//    dial-in bit.
//
// MODIFICATION HISTORY
//
//    09/29/1998    Original version.
//
///////////////////////////////////////////////////////////////////////////////

#include <windows.h>
#include <malloc.h>
#include <authif.h>
#include <rassapi.h>
#include <lmerr.h>

//////////
// The UNC name of the localhost.
//////////
WCHAR theLocalServer[UNCLEN + 1];

//////////
// Finds an attribute of the desired type.
//////////
CONST RADIUS_ATTRIBUTE*
WINAPI
FindAttribute(
    IN CONST RADIUS_ATTRIBUTE *pAttrs,
    IN DWORD dwAttrType
    ) throw ()
{
   for ( ; pAttrs->dwAttrType != ratMinimum; ++pAttrs)
   {
      if (pAttrs->dwAttrType == dwAttrType) { return pAttrs; }
   }

   return NULL;
}

//////////
// Initialize the extension.
//////////
extern "C"
DWORD
WINAPI
RadiusExtensionInit( VOID )
{
   // theLocalServer must be in UNC format.
   wcscpy(theLocalServer, L"\\\\");

   // Append the computer name.
   DWORD cbData = UNCLEN - 1;
   if (!GetComputerNameW(theLocalServer + 2, &cbData))
   { return GetLastError(); }

   return NO_ERROR;
}

//////////
// Process a request.
//////////
extern "C"
DWORD
WINAPI
RadiusExtensionProcess(
    IN CONST RADIUS_ATTRIBUTE *pAttrs,
    OUT OPTIONAL PRADIUS_ACTION pfAction
    )
{
   // If we can't abort the request, we're not interested.
   if (pfAction == NULL) { return NO_ERROR; }

   // If it's not destined for the Windows NT provider, we're not interested.
   CONST RADIUS_ATTRIBUTE* p = FindAttribute(pAttrs, ratProvider);
   if (p == NULL || p->dwValue != rapWindowsNT) { return NO_ERROR; }

   // Find the Stripped-User-Name attribute.
   p = FindAttribute(pAttrs, ratStrippedUserName);

   // Make sure we found an attribute and it's the right data type.
   if (p == NULL || p->fDataType != rdtString) { return ERROR_INVALID_DATA; }

   // Allocate a buffer for the UNICODE string.
   PWSTR domain = (PWSTR)_alloca((p->cbDataLength + 1) * sizeof(WCHAR));

   // Convert to UNICODE.
   int nChar = MultiByteToWideChar(
                   CP_ACP,
                   0,
                   p->lpValue,
                   p->cbDataLength,
                   domain,
                   p->cbDataLength + 1
                   );
   if (nChar == 0) { return GetLastError(); }
   domain[nChar] = L'\0';

   // Look for the delimiter in "domain\username".
   PWSTR username = wcschr(domain, L'\\');

   DWORD error;
   WCHAR buffer[UNCLEN + 1], *accountServer = theLocalServer;

   if (username)
   {
      // We found a delimiter, so null it out and advance.
      *username++ = L'\0';

      // Is this the local computer?
      if (_wcsicmp(domain, theLocalServer + 2))
      {
         // No, so we have to find a DC.
         error = RasAdminGetUserAccountServer(
                     domain,
                     NULL,
                     buffer
                     );
         if (error != NO_ERROR) { return error; }

         accountServer = buffer;
      }
   }
   else
   {
      // No delimiter, so the whole thing is the user name.
      username = domain;
   }

   // Retrieve the dial-in information for this user.
   RAS_USER_0 ru0;
   error = RasAdminUserGetInfo(
               accountServer,
               username,
               &ru0
               );

   // If the user doesn't exist, it's not an error, but we always reject.
   if (error == NERR_UserNotFound)
   {
      *pfAction = raReject;
      return NO_ERROR;
   }

   // Any other error and we bail.
   if (error != NO_ERROR) { return error; }

   // Is the dial-in bit set?
   if ((ru0.bfPrivilege & RASPRIV_DialinPrivilege) == 0)
   {
      *pfAction = raReject;
   }

   return NO_ERROR;
}


Internet Authentication Service Reference

The following documentation describes the functions, structures, and enumeration types to use when implementing RADIUS Extension DLLs for Internet Authentication Service (IAS).

  • Internet Authentication Service Functions
  • Internet Authentication Service Structures
  • Internet Authentication Service Enumerated Types


Internet Authentication Service Functions

An architecture for RADIUS Extension DLLs supports the following exported functions:

RadiusExtensionFreeAttributes

RadiusExtensionInit

RadiusExtensionTerm

RadiusExtensionProcess

RadiusExtensionProcessEx

The RadiusExtensionInit and RadiusExtensionTerm functions are optional. However, the Extension DLL must export either RadiusExtensionProcess or RadiusExtensionProcessEx.


RadiusExtensionFreeAttributes

The RadiusExtensionFreeAttributes function is called by IAS to free the memory occupied by attributes returned by RadiusExtensionProcessEx.

typedef VOID (WINAPI * RadiusExtensionFreeAttributes)(
    PRADIUS_ATTRIBUTE pAttrs
    );

Paramters

pAttrs
Pointer to an array of attributes. The RadiusExtensionFreeAttributes function should deallocate the memory occupied by these attributes.

These attributes were returned in the pOutAttrs parameter in a previous call to the RadiusExtensionProcessEx function.

Remarks

If you implement RadiusExtensionProcessEx, you must also implement RadiusExtensionFreeAttributes.

See Also

RadiusExtensionProcessEx


RadiusExtensionInit

The RadiusExtensionInit function is called by IAS while the service is starting up. Use RadiusExtensionInit to perform any initialization operations for the Extension DLL.

typedef DWORD ( WINAPI * RadiusExtensionInit )( VOID );

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value should be an appropriate error code from Winerror.h.

Remarks

A return value other then NO_ERROR will cause IAS to fail to start.

RadiusExtensionInit is an optional function. The RADIUS Extension DLL need not implement RadiusExtensionInit.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later. Available as a redistributable for Windows NT 4.0.
Header: Declared in AuthIf.h.

See Also

About Internet Authentication Service Overview, Internet Authentication Service Functions, RadiusExtensionTerm


RadiusExtensionTerm

The RadiusExtensionTerm function is called by IAS prior to unloading the Extension DLL. Use RadiusExtensionTerm to perform any clean-up operations for the Extension DLL.

typedef VOID ( WINAPI * RadiusExtensionTerm )( VOID );

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value should be an appropriate error code from Winerror.h.

Remarks

RadiusExtensionTerm is an optional function. The RADIUS Extension DLL need not implement RadiusExtensionTerm.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later. Available as a redistributable for Windows NT 4.0.
Header: Declared in AuthIf.h.

See Also

About Internet Authentication Service Overview, Internet Authentication Service Functions, RadiusExtensionInit


RadiusExtensionProcess

The RadiusExtensionProcess function is called by IAS for each authentication or accounting packet that IAS receives from the NAS.

typedef DWORD (WINAPI * RadiusExtensionProcess )(
  RADIUS_ATTRIBUTE * pAttrs,    // pointer to array of attributes
  PRADIUS_ACTION pfAction   // action that IAS should take
  );

Parameters

pAttrs
[in] Pointer to an array of attributes from the request. The array is terminated by an attribute with dwAttrType set to ratMinimum. These attributes should be treated as read-only; they should not be modified by RadiusExtensionProcess. Also, these attributes should not be referenced in any way after RadiusExtensionProcess returns.
pfAction
[out] Pointer to a value of type RADIUS_ACTION. This parameter specifies the action that IAS should take in response to an Access-Request. If the request is not an access request, RadiusExtensionProcess should return NULL for this parameter.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value should be an appropriate error code from Winerror.h.

Remarks

If the return value is anything other than NO_ERROR, IAS discards the request.

IAS supports multiple Extension DLLs. IAS calls RadiusExtensionProcess for each of the DLLs listed in the registry.

On Windows 2000, the Extension DLL may export RadiusExtensionProcessEx instead of RadiusExtensionProcess.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later. Available as a redistributable for Windows NT 4.0.
Header: Declared in AuthIf.h.

See Also

About Internet Authentication Service Overview, Internet Authentication Service Functions, RADIUS_ACTION, RADIUS_ATTRIBUTE, RADIUS_ATTRIBUTE_TYPE, RadiusExtensionProcessEx


RadiusExtensionProcessEx

The RadiusExtensionProcessEx function is called by IAS for each authentication or accounting packet that IAS receives from the NAS. This function is similar to RadiusExtensionProcess. However, RadiusExtensionProcessEx enables the Extension DLL to append attributes to the authentication response.

typedef DWORD (WINAPI * RadiusExtensionProcessEx )(
  CONST RADIUS_ATTRIBUTE * pInAttrs,    // pointer to array of input attributes
  RADIUS_ATTRIBUTE * pOutAttrs,   // pointer to array of output attributes
  PRADIUS_ACTION pfAction     // action that IAS should take
  );

Parameters

pInAttrs
[in] Pointer to an array of attributes from the request. The array is terminated by an attribute with dwAttrType set to ratMinimum. These attributes should be treated as read-only; they should not be modified by RadiusExtensionProcessEx. Also, these attributes should not be referenced in any way after RadiusExtensionProcessEx returns.
pOutAttrs
[out] Pointer to an array of attributes from the request. The array is terminated by an attribute with dwAttrType set to ratMinimum. Internet Authentication Service adds these attributes to the authentication response.
pfAction
[out] Pointer to a value of type RADIUS_ACTION. This parameter specifies the action that IAS should take in response to an Access-Request. If the request is not an access request, RadiusExtensionProcessEx should return NULL for this parameter.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value should be an appropriate error code from Winerror.h.

Remarks

If the return value is anything other than NO_ERROR, IAS discards the request.

IAS supports multiple Extension DLLs. IAS calls RadiusExtensionProcessEx for each of the DLLs listed in the registry.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in AuthIf.h.

See Also

About Internet Authentication Service Overview, Internet Authentication Service Functions, RADIUS_ACTION, RADIUS_ATTRIBUTE, RADIUS_ATTRIBUTE_TYPE, RadiusExtensionProcess


Internet Authentication Service Structures

Use the RADIUS_ATTRIBUTE structure to represent a RADIUS attribute or an extended attribute when developing RADIUS Extension DLLs.


RADIUS_ATTRIBUTE

The RADIUS_ATTRIBUTE structure represents a RADIUS attribute or an extended attribute.

typedef struct _RADIUS_ATTRIBUTE {
  DWORD             dwAttrType;    // attribute type
  RADIUS_DATA_TYPE  fDataType;     // type of value
  DWORD             cbDataLength;  // length of value
  union {
    DWORD   dwValue;  // for rdtAddress, rdtInteger, and rdtTime
    PCSTR   lpValue;  // for rdtUnknown, and rdtString
  };
} RADIUS_ATTRIBUTE, *PRADIUS_ATTRIBUTE;

Members

dwAttrType
Stores a value from the RADIUS_ATTRIBUTE_TYPE enumeration. This value specifies the type of the attribute represented by the RADIUS_ATTRIBUTE structure.
fDataType
Stores a value from the RADIUS_DATA_TYPE enumeration. This value specifies the type of the value stored in the union containing the dwValue and lpValue members.
cbDataLength
Stores the length, in bytes, of the data. The cbDataLength member is used only if lpValue member is used.
dwValue
Stores a value of type DWORD. The dwValue member is used if the fDataType member specifies rdtAddress, rdtInteger or rdtTime.
lpValue
Stores a pointer to a multi-byte data value. The lpValue member is used if the fDataType member specifies rdtUnknown or rdtString.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later. Available as a redistributable for Windows NT 4.0.
Header: Declared in AuthIf.h.

See Also

About Internet Authentication Service Overview, Internet Authentication Service Structures, RADIUS_ATTRIBUTE_TYPE, RADIUS_DATA_TYPE


Internet Authentication Service Enumerated Types

Use the following enumerated types when developing RADIUS Extension DLLs:

RADIUS_ACTION

RADIUS_ATTRIBUTE_TYPE

RADIUS_AUTHENTICATION_PROVIDER

RADIUS_DATA_TYPE


RADIUS_ACTION

The RADIUS_ACTION type enumerates the responses that a RADIUS Extension DLL can generate in response to an Access-Request.

typedef enum _RADIUS_ACTION {
  raContinue,
  raReject,
  raAccept
} RADIUS_ACTION, *PRADIUS_ACTION;

Values

raContinue
IAS continues to process the request. IAS also continues to call RadiusExtensionProcess in other Extension DLLs.
raReject
Return an Access-Reject packet. The Access-Request is declined. In this case, IAS does not call RadiusExtensionProcess in any other Extension DLLs.
raAccept
IAS accepts the Access-Request. IAS does not continue to call RadiusExtensionProcess in this case. However, it does continue to obtain authorizations for the user requesting access.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later. Available as a redistributable for Windows NT 4.0.
Header: Declared in AuthIf.h.

See Also

About Internet Authentication Service Overview, Internet Authentication Service Enumerated Types, RadiusExtensionProcess


RADIUS_ATTRIBUTE_TYPE

The RADIUS_ATTRIBUTE_TYPE type enumerates the possible types for a RADIUS attribute.

typedef enum _RADIUS_ATTRIBUTE_TYPE {
  ratMinimum = 0,      // Used to terminate attribute arrays.
  // RADIUS standard attributes.
  ratUserName = 1,
  ratUserPassword = 2,
  ratCHAPPassword = 3,
  ratNASIPAddress = 4,
  ratNASPort = 5,
  ratServiceType = 6,
  ratFramedProtocol = 7,
  ratFramedIPAddress = 8,
  ratFramedIPNetmask = 9,
  ratFramedRouting = 10,
  ratFilterId = 11,
  ratFramedMTU = 12,
  ratFramedCompression = 13,
  ratLoginIPHost = 14,
  ratLoginService = 15,
  ratLoginPort = 16,
  ratReplyMessage = 18,
  ratCallbackNumber = 19,
  ratCallbackId = 20,
  ratFramedRoute = 22,
  ratFramedIPXNetwork = 23,
  ratState = 24,
  ratClass = 25,
  ratVendorSpecific = 26,
  ratSessionTimeout = 27,
  ratIdleTimeout = 28,
  ratTerminationAction = 29,
  ratCalledStationId = 30,
  ratCallingStationId = 31,
  ratNASIdentifier = 32,
  ratProxyState = 33,
  ratLoginLATService = 34,
  ratLoginLATNode = 35,
  ratLoginLATGroup = 36,
  ratFramedAppleTalkLink = 37,
  ratFramedAppleTalkNetwork = 38,
  ratFramedAppleTalkZone = 39,
  ratAcctStatusType = 40,
  ratAcctDelayTime = 41,
  ratAcctInputOctets = 42,
  ratAcctOutputOctets = 43,
  ratAcctSessionId = 44,
  ratAcctAuthentic = 45,
  ratAcctSessionTime = 46,
  ratAcctInputPackets = 47,
  ratAcctOutputPackets = 48,
  ratAcctTerminationCause = 49,
  ratCHAPChallenge = 60,
  ratNASPortType = 61,
  ratPortLimit = 62,
  // Extended attribute types used to pass additional information.
  ratCode = 262,             /* Request type code. */
  ratIdentifier = 263,       /* Request identifier. */
  ratAuthenticator = 264,    /* Request authenticator. */
  ratSrcIPAddress = 265,     /* Source IP address. */
  ratSrcPort = 266,          /* Source IP port. */
  ratProvider = 267,         /* Authentication provider. */
  ratStrippedUserName = 268  /* User-Name with realm stripped. */
  ratFQUserName = 269,       /* Fully-Qualified-User-Name. */
  ratPolicyName = 270        /* Remote Access Policy name. */

} RADIUS_ATTRIBUTE_TYPE;

Values

ratMinimum
This value is equal to zero, and used as the null-terminator in any array of RADIUS_ATTRIBUTE structures.
ratUserName
Specifies the name of the user to be authenticated. The value field in RADIUS_ATTRIBUTE for this type is a pointer. See RFC 2865 for more information. Also see User Identification Attributes.
ratUserPassword
Specifies the password of the user to be authenticated. The value field in RADIUS_ATTRIBUTE for this type is a pointer. See RFC 2865 for more information.
ratCHAPPassword
Specifies the password provided by the user in response to an Challenge Handshake Authentication Protocol (CHAP) challenge. The value field in RADIUS_ATTRIBUTE for this type is a pointer. See RFC 2865 for more information.
ratNASIPAddress
Specifies the NAS IP address. An Access-Request should specify either an NAS IP address or an NAS identifier. The value field in RADIUS_ATTRIBUTE for this type is a 32-bit integral value. See RFC 2865 for more information.
ratNASPort
Identifies the physical or virtual private network (VPN) through which the user is connecting to the NAS. Note that this value is not a port number in the sense of TCP or UDP. The value field in RADIUS_ATTRIBUTE for this type is a 32-bit integral value. See RFC 2865 for more information.
ratServiceType
Specifies the type of service the user has requested or the type of service to be provided. The value field in RADIUS_ATTRIBUTE for this type is a 32-bit integral value. See RFC 2865 for more information.
ratFramedProtocol
Specifies the type of framed protocol to use for framed access, for example SLIP, PPP, or ARAP (AppleTalk Remote Access Protocol). The value field in RADIUS_ATTRIBUTE for this type is a 32-bit integral value. See RFC 2865 for more information.
ratFramedIPAddress
Specifies the IP address that will be configured for the user requesting authentication. This attribute is typically returned by the authentication provider. However, the NAS may use it in an authentication request to specify a preferred IP address. The value field in RADIUS_ATTRIBUTE for this type is a 32-bit integral value. See RFC 2865 for more information.
ratFramedIPNetmask
Specifies the IP network mask for a user that is a router to a network. The value field in RADIUS_ATTRIBUTE for this type is a 32-bit integral value. See RFC 2865 for more information.
ratFramedRouting
Specifies the routing method for a user that is a router to a network. The value field in RADIUS_ATTRIBUTE for this type is a 32-bit integral value. See RFC 2865 for more information.
ratFilterId
Identifies the filter list for the user requesting authentication. The value field in RADIUS_ATTRIBUTE for this type is a pointer. See RFC 2865 for more information.
ratFramedMTU
Specifies the Maximum Transmission Unit (MTU) for the user. This attribute is used in cases where the MTU is not negotiated through some other means, such as PPP. The value field in RADIUS_ATTRIBUTE for this type is a 32-bit integral value. See RFC 2865 for more information.
ratFramedCompression
Specifies a compression protocol to use for the connection. The value field in RADIUS_ATTRIBUTE for this type is a 32-bit integral value. See RFC 2865 for more information
ratLoginIPHost
Specifies the system with which to connect the user. The value field in RADIUS_ATTRIBUTE for this type is a 32-bit integral value. See RFC 2865 for more information.
ratLoginService
Specifies the service to use to connect the user to the host specified by ratLoginIPHost. The value field in RADIUS_ATTRIBUTE for this type is a 32-bit integral value. See RFC 2865 for more information.
ratLoginPort
Specifies the port to which to connect the user. This attribute is present only if the ratLoginService attribute is present. The value field in RADIUS_ATTRIBUTE for this type is a 32-bit integral value. See RFC 2865 for more information.
ratReplyMessage
Specifies a message to display to the user. The value field in RADIUS_ATTRIBUTE for this type is a pointer. See RFC 2865 for more information.
ratCallbackNumber
Specifies a callback number. The value field in RADIUS_ATTRIBUTE for this type is a pointer. See RFC 2865 for more information.
ratCallbackId
Identifies a location to callback. The value of this attribute is interpreted by the NAS. The value field in RADIUS_ATTRIBUTE for this type is a pointer. See RFC 2865 for more information.
ratFramedRoute
Provides routing information to configure on the NAS for the user. The value field in RADIUS_ATTRIBUTE for this type is a pointer. See RFC 2865 for more information.
ratFramedIPXNetwork
Specifies the IPX network number to configure for the user. The value field in RADIUS_ATTRIBUTE for this type is a 32-bit integral value. See RFC 2865 for more information.
ratState
This attribute is included in Access-Challenge and Access-Accept communications between the server and the client. Please refer to RFC 2865 for detailed information about this value. The value field in RADIUS_ATTRIBUTE for this type is a pointer.
ratClass
Specifies a value that is provided to the NAS by the authentication provider. The NAS should use this value when communicating with the accounting provider. The value field in RADIUS_ATTRIBUTE for this type is a pointer. See RFC 2865 for more information.
ratVendorSpecific
Allows vendors to provide their own extended attributes. The value field in RADIUS_ATTRIBUTE for this type is a pointer. See RFC 2865 for more information.
ratSessionTimeout
Specifies the maximum number of seconds for which to provide service to the user. After this time, the session is terminated. The value field in RADIUS_ATTRIBUTE for this type is a 32-bit integral value. See RFC 2865 for more information.
ratIdleTimeout
Specifies the maximum number of consecutive seconds the session can be idle. If the idle time exceeds this value, the session is terminated. The value field in RADIUS_ATTRIBUTE for this type is a 32-bit integral value. See RFC 2865 for more information.
ratTerminationAction
Please refer to the above-referenced files at www.ietf.org for detailed information about this value. The value field in RADIUS_ATTRIBUTE for this type is 32-bit integral value. See RFC 2865 for more information.
ratCalledStationId
Specifies the number that the user dialed to connect to the NAS. The value field in RADIUS_ATTRIBUTE for this type is a pointer. See RFC 2865 for more information.
ratCallingStationId
Specifies the number from which the user is calling. The value field in RADIUS_ATTRIBUTE for this type is a pointer. See RFC 2865 for more information.
ratNASIdentifier
Specifies the NAS identifier. An Access-Request should specify either an NAS identifier or an NAS IP address. The value field in RADIUS_ATTRIBUTE for this type is a pointer. See RFC 2865 for more information.
ratProxyState
Specifies a value that a proxy server includes when forwarding an authentication request. The value field in RADIUS_ATTRIBUTE for this type is a pointer. See RFC 2865 for more information.
ratLoginLATService
This attribute is not currently used for authentication on Windows 2000. See RFC 2865 for more information.
ratLoginLATNode
This attribute is not currently used for authentication on Windows 2000. See RFC 2865 for more information.
ratLoginLATGroup
This attribute is not currently used for authentication on Windows 2000. See RFC 2865 for more information.
ratFramedAppleTalkLink
Specifies the AppleTalk network number for a user that is another router. The value field in RADIUS_ATTRIBUTE for this type is 32-bit integral value. See RFC 2865 for more information.
ratFramedAppleTalkNetwork
Specifies the AppleTalk network number that the NAS should use to allocate an AppleTalk node for the user. This attribute is used only when the user is not another router. The value field in RADIUS_ATTRIBUTE for this type is a 32-bit integral value. See RFC 2865 for more information.
ratFramedAppleTalkZone
Specifies the AppleTalk default zone for the user. The value field in RADIUS_ATTRIBUTE for this type is a pointer. See RFC 2865 for more information.
ratAcctStatusType
Specifies whether the accounting provider should start or stop accounting for the user. The value field in RADIUS_ATTRIBUTE for this type is a 32-bit integral value. See Draft Radius Accounting v2 05 for more information.
ratAcctDelayTime
Specifies the length of time that the client has been attempting to send the current request. The value field in RADIUS_ATTRIBUTE for this type is a 32-bit integral value. See Draft Radius Accounting v2 05 for more information.
ratAcctInputOctets
Specifies the number of octets that have been received during the current accounting session. The value field in RADIUS_ATTRIBUTE for this type is a 32-bit integral value. See Draft Radius Accounting v2 05 for more information.
ratAcctOutputOctets
Specifies the number of octets sent during the current accounting session. The value field in RADIUS_ATTRIBUTE for this type is a 32-bit integral value. See Draft Radius Accounting v2 05 for more information.
ratAcctSessionId
Specifies a value to enable the identification of matching start and stop records within a log file. The start and stop records are sent in the ratAcctStatusType attribute. The value field in RADIUS_ATTRIBUTE for this type is a pointer. See Draft Radius Accounting v2 05 for more information.
ratAcctAuthentic
Specifies, to the accounting provider, how the user was authenticated; for example by Windows 2000 Directory Services, RADIUS, or some other authentication provider. The value field in RADIUS_ATTRIBUTEfor this type is a 32-bit integral value. See Draft Radius Accounting v2 05 for more information.
ratAcctSessionTime
Specifies the number of seconds that have elapsed in the current accounting session. The value field in RADIUS_ATTRIBUTE for this type is a 32-bit integral value. See Draft Radius Accounting v2 05 for more information.
ratAcctInputPackets
Specifies the number of packets that have been received during the current accounting session. The value field in RADIUS_ATTRIBUTE for this type is a 32-bit integral value. See Draft Radius Accounting v2 05 for more information.
ratAcctOutputPackets
Specifies the number of packets that have been sent during the current accounting session. The value field in RADIUS_ATTRIBUTE for this type is a 32-bit integral value. See Draft Radius Accounting v2 05 for more information.
ratAcctTerminationCause
Specifies how the current accounting session was terminated. The value field in RADIUS_ATTRIBUTE for this type is a 32-bit integral value. See Draft Radius Accounting v2 05 for more information.
ratCHAPChallenge
Specifies the CHAP challenge sent by the NAS to a CHAP user. The value field in RADIUS_ATTRIBUTE for this type is a pointer. See RFC 2865 for more information.
ratNASPortType
Specifies the type of the port through which the user is connecting, for example, asynchronous, ISDN, virtual. The value field in RADIUS_ATTRIBUTE for this type is a 32-bit integral value. See RFC 2865 for more information.
ratPortLimit
Specifies the number of ports the NAS should make available to the user for multilink sessions. The value field in RADIUS_ATTRIBUTE for this type is a 32-bit integral value. See RFC 2865 for more information
ratCode
Specifies the request type code. This is an extended attribute.
ratIdentifier
Specifies the request identifier. This is an extended attribute.
ratAuthenticator
Specifies the request authenticator. This is an extended attribute.
ratSrcIPAddress
Specifies the source IP address. This is an extended attribute.
ratSrcPort
Specifies the source IP port. This is an extended attribute.
ratProvider
Specifies the authentication provider. The value for this attribute is taken from the RADIUS_AUTHENTICATION_PROVIDER enumerated type. This is an extended attribute.
ratStrippedUserName
Specifies the user name with the realm removed. See User Identification Attributes for more information. This is an extended attribute.
ratFQUserName
Specifies the fully-qualified user name. See User Identification Attributes for more information. This is an extended attribute.
ratPolicyName
Specifies the policy name. This is an extended attribute.

Remarks

The value for an attribute of type ratProvider is taken from the RADIUS_AUTHENTICATION_PROVIDER enumerated type.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later. Available as a redistributable for Windows NT 4.0.
Header: Declared in AuthIf.h.

See Also

About Internet Authentication Service Overview, Internet Authentication Service Enumerated Types, RADIUS_ATTRIBUTE, RADIUS_AUTHENTICATION_PROVIDER


RADIUS_AUTHENTICATION_PROVIDER

The RADIUS_AUTHENTICATION_PROVIDER type enumerates the possible authentication providers that Internet Authentication Service can use.

typedef enum _RADIUS_AUTHENTICATION_PROVIDER {
  rapUnknown,
  rapUsersFile,
  rapProxy,
  rapWindowsNT,
  rapMCIS,
  rapODBC
} RADIUS_AUTHENTICATION_PROVIDER;

Values

rapUnknown
The authentication provider is unknown.
rapUsersFile
A users' file is providing the authentication information.
rapProxy
Authentication is provided by a RADIUS proxy server.
rapWindowsNT
Authentication is provided by Window 2000 Domain Authentication.
rapMCIS
Authentication is provided by a Microsoft Commercial Internet System (MCIS) database.
rapODBC
Authentication is provided by an Open Database Connectivity (ODBC) compliant database.

Remarks

The ratProvider extended attribute in RADIUS_ATTRIBUTE_TYPE uses values from the RADIUS_AUTHENTICATION_PROVIDER enumeration type.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later. Available as a redistributable for Windows NT 4.0.
Header: Declared in AuthIf.h.

See Also

About Internet Authentication Service Overview, Internet Authentication Service Enumerated Types, RADIUS_ATTRIBUTE, RADIUS_ATTRIBUTE_TYPE


RADIUS_DATA_TYPE

The RADIUS_DATA_TYPE type enumerates the possible data type for a RADIUS attribute or extended attribute.

typedef enum _RADIUS_DATA_TYPE {
  rdtUnknown,
  rdtString,
  rdtAddress,
  rdtInteger,
  rdtTime
} RADIUS_DATA_TYPE;

Values

rdtUnknown
The value is a pointer. However, the attribute is not recognized by the dictionary.
rdtString
The value of the attribute is a pointer to a character string.
rdtAddress
The value of the attribute is a 32-bit DWORD value representing address.
rdtInteger
The value of the attribute is a 32-bit DWORD value representing an integer.
rdtTime
The value of the attribute is a 32-bit DWORD value representing a time.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later. Available as a redistributable for Windows NT 4.0.
Header: Declared in AuthIf.h.

See Also

About Internet Authentication Service Overview, Internet Authentication Service Enumerated Types, RADIUS_ATTRIBUTE, RADIUS_ATTRIBUTE_TYPE


Topic Not Found

No matching topic was found. Some possible reasons and remedies are as follows:

  • The file (.chm) that contains the destination topic is not in the expected location.

    Remedy: Rerun the MSDN Library Setup.

  • The file (.chm) that contains the current topic or destination topic is out-of-date and the link is no longer valid.

    Remedy: Install the latest version of the MSDN Library.

  • The MSDN Library CD is not in the CD-ROM drive.

    Remedy: Insert the MSDN Library CD into the CD-ROM drive.