1. Windows API: Network Policy Server Extensions
Vilnius Unversity Faculty of Mathematics and Informatics
Software Engineering 4th course student
Gediminas Krasauskas

2. Content Network Policy Server Extensions About NPS Extensions
Setting up the Extension DLLs
Invoking the Extension DLLs
User Identification Attributes
Using NPS Extensions
NPS Extensions Reference
NPS Extensions Enumerations
NPS Extensions Functions
NPS Extensions Structures

3. Network Policy Server Extensions
NPS:
Enables developers to write extension DLLs that can be used for authentication, authorization, and accounting.
Supports the Remote Authentication Dial-In User Service (RADIUS) protocol.
Extension DLLs implemented using the NPS Extensions API can:
provide enhanced session control and accounting.
used for scenarios such as controlling the number of end-user network sessions, using a state server, and connecting to domain authentication databases and Active Directory services.
expand the remote access authorizations provided by NPS by adding their own authorizations when sending an Accept response back to an authenticating client.
NPS Extensions API 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).

4. About NPS Extensions NPS provides two extension points:
for authentication (verifying the identity of the user);
for authorization (determining what services the network should provide to the user).
The two extension points correspond to Authentication Extension DLLs and Authorization Extension DLLs. Each extension point can support multiple DLLs.
NPS provides both authentication and authorization services. Authentication Extension DLLs are called by NPS prior to the built-in NPS authentication and authorization. Authorization Extension DLLs are called after NPS authentication and authorization.

5. About NPS Extensions
The following diagram illustrates the flow of packets through an NPS RADIUS server that is expanded using Extension DLLs.
If an Authentication Extension DLL returns ACCEPT, the packet skips the NPS authentication and goes directly to NPS authorization.
If an Authentication Extension DLL returns CONTINUE, the packet goes to NPS authentication, and then to NPS authorization.

6. Setting Up the Extension DLLs
At startup, NPS checks the registry for a list of third-party DLLs to call.
To set up an Authentication or Authorization DLL on an NPS 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 Authentication Extension DLLs is:
ExtensionDLLs
The value in which to list the Authorization Extension DLLs is:
AuthorizationDLLs
Both the ExtensionDLLs and AuthorizationDLLs values must be of type REG_MULTI_SZ. This type allows you to list multiple DLLs.

7. Invoking the Extension DLLs
NPS Extension DLLs must export at least one of the following callback functions:  RadiusExtensionProcess, RadiusExtensionProcessEx, RadiusExtensionProcess2.
NPS calls these functions 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 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.

8. RadiusExtensionProcess
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.

9. RadiusExtensionProcessEx
This function enables the DLL to append additional authorization attributes to the authentication response.
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.

10. RadiusExtensionProcess2
This function enables the DLL to add, modify, and remove attributes to and from the authentication request or response.
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.

11. User Identification Attributes
The identity of the user requesting authentication is supplied to the NPS Extension 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.

12. Using NPS Extensions
The DialIn and MapName samples extend NPS functionality.
You can find the source code for the MapName and DialIn sample applications in the following list. Location, %Install Path%, designates the base installation directory for x64 computers.
Sample
Description
DialIn
This sample implements a RADIUS extension DLL that checks the dial-in bit for the user.
MapName
This sample extension DLL searches all trusted domains for the designated account. This allows users from multiple domains to be authenticated without the users having to supply their domain name.

13. NPS Extensions Reference
NPS Extensions API programming elements:
NPS Extensions Enumerations
NPS Extensions Functions
NPS Extensions Structures

14. NPS Extensions Enumerations
Use the following enumerated types when developing NPS Extension DLLs:
RADIUS_ACTION
RADIUS_ATTRIBUTE_TYPE
RADIUS_AUTHENTICATION_PROVIDER
RADIUS_CODE
RADIUS_DATA_TYPE
RADIUS_EXTENSION_POINT
RADIUS_REJECT_REASON_CODE

15. NPS Extensions Functions. Application Defined
The architecture for NPS Extension DLLs supports the following exported functions:
RadiusExtensionFreeAttributes RadiusExtensionInit RadiusExtensionProcess RadiusExtensionProcessEx RadiusExtensionProcess2 RadiusExtensionTerm
The RadiusExtensionInit and RadiusExtensionTerm functions are optional.
The Extension DLL may export RadiusExtensionProcess2 instead of RadiusExtensionProcess or RadiusExtensionProcessEx.
If the Extension DLL exports RadiusExtensionProcessEx, then it must also export RadiusExtensionFreeAttributes.

16. NPS Extensions Functions. System Defined
When NPS calls an implementation of RadiusExtensionProcess2, NPS passes the function a pointer to a RADIUS_EXTENSION_CONTROL_BLOCK structure.
The RADIUS_EXTENSION_CONTROL_BLOCK structure contains function pointers to the following functions provided by NPS:
GetRequest GetResponse SetResponseType
The functions GetRequest and GetResponse return pointers to a structure of type RADIUS_ATTRIBUTE_ARRAY.
The RADIUS_ATTRIBUTE_ARRAY structure contains function pointers to the following functions provided by NPS:
Add AttributeAt GetSize InsertAt RemoveAt SetAt

17. NPS Extensions Structures
Use the RADIUS_ATTRIBUTE structures to represent a RADIUS attribute or an extended attribute when developing NPS Extension DLLs.
RADIUS_ATTRIBUTE
RADIUS_ATTRIBUTE_ARRAY
RADIUS_EXTENSION_CONTROL_BLOCK
RADIUS_VSA_FORMAT

18. Bibliography