Edit

Configure SMB over QUIC client access control in Windows Server 2022 Azure Edition and Windows Server Insider (preview)

  • Article

Important

Windows Insider and Windows Server Insider builds are in PREVIEW. This information relates to a prerelease product that may be substantially modified before it's released. Microsoft makes no warranties, expressed or implied, with respect to the information provided here.

SMB over QUIC client access control enables you to restrict which clients can access SMB over QUIC servers. Client access control creates allow and blocklists for devices to connect to the file server. Client access control gives organizations more protection without changing the authentication used when making the SMB connection, nor does it alter the end user experience.

The article explains how to use PowerShell to configure client access control for SMB over QUIC on Windows 11 and Windows Server 2022 Datacenter: Azure Edition. To proceed with the instructions, you must have either the March Update KB5035853 or KB5035857 installed, be running a recent Windows 11 Insider build, or Windows Server Insider build.

To learn more about configuring SMB over QUIC, see SMB over QUIC.

How client access control works

Client access control checks clients connecting to a server are using a known client certificate or have a certificate issued by a shared root certificate. The admin issues this certificate to the client and adds the hash to an allowlist maintained by the server. When the client tries to connect to the server, the server compares the client certificate against the allowlist. If the certificate is valid, the server certificate creates a TLS 1.3-encrypted tunnel over UDP port 443 and grants the client access to the share. Client access control also supports certificates with subject alternative names.

You can also configure SMB over QUIC to block access by revoking certificates or explicitly denying certain devices access.

Prerequisites

Before you can configure client access control, you need an SMB server with the following prerequisites.

You also need an SMB client with the following prerequisites.

Note

We recommend using SMB over QUIC with Active Directory domains, however it isn't required. You can also use SMB over QUIC on a workgroup-joined server with local user credentials and NTLM.

Configure the SMB client

Gather the SMB client certificate information

To gather your client certificate hash using PowerShell:

  1. Open an elevated PowerShell prompt on the SMB client.

  2. List the certificates in the client's certificate store by running the following command.

    Get-ChildItem -Path Cert:\LocalMachine\My

  3. Run the following command to store the certificate in a variable. Replace <subject name> with the subject name of the certificate you want to use.

    $clientCert = Get-ChildItem -Path Cert:\LocalMachine\My | Where-Object {$_.Subject -Match "<subject name>"}

  4. Make a note of the client certificate's SHA256 hash by running the following command. You need this identifier when configuring client access control.

    $clientCert.GetCertHashString("SHA256")

Note

The thumbprint stored in the $clientCert object uses the SHA1 algorithm. This is used by commands like New-SmbClientCertificateMapping. You'll also need the SHA256 thumbprint to configure client access control, these thumbprints will be different derived using different algorithms against the same certificate.

Map the client certificate to the SMB client

To map the client certificate to the SMB client:

  1. Open an elevated PowerShell prompt on the SMB client.

  2. Run the New-SmbClientCertificateMapping command to map the client certificate. Replace <namespace> with the SMB server's fully qualified domain name (FQDN) and use the SHA1 client certificate thumbprint you gathered in the previous section using the variable.

    New-SmbClientCertificateMapping -Namespace <namespace> -Thumbprint $clientCert.Thumbprint -StoreName My

Once complete, the client certificated is used by the SMB client to authenticate to the SMB server matching the FQDN.

Configure client access control

Grant individual clients

Follow the steps to grant a specific client access to the SMB server using client access control.

  1. Sign in to the SMB server.

  2. Open an elevated PowerShell prompt on the SMB server.

  3. Run the Grant-SmbClientAccessToServer to grant access to the client certificate. Replace <name> with the SMB server's hostname and <hash> using the SHA256 client certificate identifier you gathered in the Gather the SMB client certificate information section.

    Grant-SmbClientAccessToServer -Name <name> -IdentifierType SHA256 -Identifier <hash>

You've now granted access to the client certificate. You can verify the client certificate access by running the Get-SmbClientAccessToServer command.

Grant specific certification authorities

Follow the steps to grant clients from a specific certification authority, also known as an issuer, using client access control.

  1. Sign in to the SMB server.

  2. Open an elevated PowerShell prompt on the SMB server.

  3. Run the Grant-SmbClientAccessToServer to grant access to the client certificate. Replace <name> with the SMB server's hostname and <subject name> with the complete X.500 distinguished name of the issuer certificate. For example, CN=Contoso CA, DC=Contoso, DC=com.

    Grant-SmbClientAccessToServer -Name <name> -IdentifierType ISSUER -Identifier "<subject name>"

Disable SMB over QUIC

Starting with Windows 11 Insider build 26090, admins can now disable SMB over QUIC for client by running the following command:

Set-SmbClientConfiguration -EnableSMBQUIC $false

Similarly, this operation can be performed in Group Policy by disabling the Enable SMB over QUIC policy in the following path:

  • Computer Configuration\Administrative Templates\Network\Lanman Workstation

Connect to the SMB server

When you're finished, test whether you can connect to the server by running one of the following commands:

NET USE \\<server DNS name>\<share name> /TRANSPORT:QUIC

Or

New-SmbMapping -RemotePath \\<server DNS name>\<share name> -TransportType QUIC

If you can connect to the server, you've successfully configured SMB over QUIC using client access control.

Related content