Invoking the Extension DLLs
Note
Internet Authentication Service (IAS) was renamed Network Policy Server (NPS) starting with Windows Server 2008. The content of this topic applies to both IAS and NPS. Throughout the text, NPS is used to refer to all versions of the service, including the versions originally referred to as IAS.
NPS Extension DLLs must export at least one of the following callback functions: RadiusExtensionProcess, RadiusExtensionProcessEx, or RadiusExtensionProcess2. NPS calls these function for each valid authentication or accounting packet that it receives from the Network Access Server (NAS). NPS calls these functions in each of the DLLs listed below the NPS' Parameters registry key. The DLLs are called in the order in which they are listed.
If an NPS Extension DLL exports more than one of the above functions, NPS invokes just one of them: the newest function that is supported by the operating system.
Note
IAS originally supported only RadiusExtensionProcess. IAS supports also RadiusExtensionProcessEx. IAS (and later NPS) supports also RadiusExtensionProcess2.
NPS Extension DLLs may also export RadiusExtensionInit and RadiusExtensionTerm functions. If they are present, NPS calls these functions when the service starts and stops, respectively.
RadiusExtensionProcess Callback Function
In an Authentication Extension DLL, RadiusExtensionProcess receives all the attributes that are received by NPS in the authentication or accounting request. Using these attributes, the function can perform additional validations, verify the user's authorizations, or send accounting records to a central state server.
In an Authorization Extension DLL, RadiusExtensionProcess receives all the attributes generated by the NPS authorization service. These are the attributes that are returned in the Access-Accept packet.
After calling RadiusExtensionProcess, the action performed by NPS depends on the return value of RadiusExtensionProcess, and the value returned in the pfAction parameter. These values are listed in the following table.
| pfAction | Authentication Extension DLL | Authorization Extension DLL |
|---|---|---|
| Accept | Bypasses any further Authentication Extension DLLs and also bypasses the NPS authentication mechanism. | Accept not allowed. |
| Reject | Bypasses any further Authentication Extension DLLs and also bypasses the NPS authentication mechanism. Access-Reject packet is sent. | Bypasses any further Authorization Extension DLLs. |
| Continue | The packet is sent to the next Authentication Extension DLL or to the NPS authentication mechanism if no more Authentication Extension DLLs are listed in the registry. | The packet is sent to the next Authorization Extension DLL or to the NPS accounting log if no more Authorization Extension DLLs are listed in the registry. |
For all Extension DLLs, if RadiusExtensionProcess returns an error, the packet is discarded. Packets that are discarded because of an error are not processed by the NPS accounting log.
If an error occurs, NPS posts a generic error event to the Event Log. It is recommended that the Extension DLL provide additional error logging.
For more information and a diagram that represents the preceding process, see About NPS Extensions.
RadiusExtensionProcess should return an error if it cannot verify the acceptance or rejection of the packet. This situation might arise if a network problem prevents RadiusExtensionProcess from communicating with its user authentication database.
When processing an accounting packet, the pfAction parameter is NULL, so pfAction cannot be set. Returning an error from the RadiusExtensionProcess function while processing an accounting request causes the request to be discarded by NPS.
Note
After receiving an accept, NPS does not call RadiusExtensionProcess in the remaining DLLs in the sequence. Because some authentication functions may also implement authorizations, skipping such authentication functions may cause authorizations to be omitted. If an instance of RadiusExtensionProcess returns Accept, it is important not to make any assumptions about the authorizations retrieved.
If Continue or Accept is returned, the profile corresponding to the realm is sent back in the Access-Accept packet.
Authentication Extension DLLs should be designed to coexist with the built-in NPS authentication providers and with other Extension DLLs. If an extension is only applicable to a certain user database (for example Windows Active Directory), then it should verify the ratProvider attribute passed in 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 DLLs should not reject requests because required 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.
NPS 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. NPS supports various authentication databases including the Windows Active Directory.
RadiusExtensionProcessEx Callback Function
NPS Extension DLLs may export RadiusExtensionProcessEx instead of, or in addition to, RadiusExtensionProcess. This function enables the DLL to append additional authorization attributes to the authentication response.
The same information described in the RadiusExtensionProcess Callback Function section applies to the RadiusExtensionProcessEx function.
RadiusExtensionProcessEx cannot modify or remove any of the attributes that are present. If a scenario arises in which the DLL must modify or remove attributes, the only option is to use the NPS user interface to ensure that the attributes are not present. By default, no authorization attributes are present. Any that are present must have been added through the user interface.
If multiple Authorization DLLs are configured and some of these DLLs implement RadiusExtensionProcessEx, the RadiusExtensionProcess/Ex function in a given DLL does not receive the attributes from the previously called Authorization DLLs. It receives only those attributes generated by the NPS authorization service.
RadiusExtensionProcess2 Callback Function
NPS Extension DLLs may also export RadiusExtensionProcess2 instead of, or in addition to, RadiusExtensionProcess and RadiusExtensionProcessEx. This function enables the DLL to add, modify, and remove attributes to and from the authentication request or response.
The same information described in the RadiusExtensionProcessEx Callback Function section applies to the RadiusExtensionProcess2 function, with the following exceptions:
- In an Authorization DLL, RadiusExtensionProcess2 receives both the attributes generated by the NPS authorization service and the attributes generated from previously called Authorization DLLs.
- RadiusExtensionProcess2 does not have a pfAction parameter. RadiusExtensionProcess2 sets the final disposition of the request using the SetResponseType function provided in the RADIUS_EXTENSION_CONTROL_BLOCK structure.
- NPS always calls the RadiusExtensionProcess2 function in any remaining DLLs regardless of whether functions in previous DLLs returned Accept.
Related topics
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for