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

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

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).

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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

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.

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

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

Bibliography https://docs.microsoft.com/en-us/windows/desktop/nps/ias-extensions