Blog Summary

In SharePoint 2019 and prior versions, SharePoint Server supported three types of authentication methods:

Windows authentication (NTLM, Kerberos, etc.)
Forms-based authentication
SAML 1.1-based authentication

SharePoint Server Subscription Edition now supports OpenID Connect (OIDC) 1.0 authentication protocol. OIDC is a modern authentication protocol that makes it easy to integrate applications and devices with your organization’s identity and authentication management solutions to better meet your evolving security and compliance needs.

Official Documentation: OpenID Connect 1.0 authentication – SharePoint Server | Microsoft Docs

This blog will guide the reader through creating a functional SharePoint Subscription Edition Farm with OIDC (Open ID Connect) to authenticate against Azure AD from an On-Prem Site.

In this guide you will complete the following steps:

Create a Certificate for the SharePoint Site using the new SharePoint Certificate Manager.
Create a new Authentication Application in Azure.
Create and Install the Nonce Cookie Cert on all Servers in the Farm.
Create a new SharePoint Token Issuer.
Extend an existing SharePoint Web Application to work with the new auth zone.
Modify DNS to use the new host name.
Provide permissions to the Web App vis User Policy.
Access the on-prem site with an Azure user.

To perform the configuration, you need the following resources:

Farm Admin rights to SharePoint Server Subscription Farm.
Global Admin privileges a M365 tenant.
A Local DC with Certification Authority Service installed in stand-alone mode.

Step 1: Create an SSL certificate for the SharePoint Site

In this step you will download ‘GenerateCerts.ps1’ from rainerasbach’s Github Site. This script will complete the 3-step certificate creation process (Request, Sign, and Complete) in with a single command using SharePoint’s new Certificate Manager feature.

Download and copy the script to a “c:\labfiles\scripts” folder on the DC.
Logon to your SharePoint Front End (SPWFE) as your Farm Administrator.
Launch an elevated PowerShell ISE session

Run the following command:

\\dc\Labfiles\scripts\GenerateCerts.ps1 -CertName 'SharePoint Site' -ServerCertFileFolder \\dc\Labfiles\certs -CertCommonName 'spaad.contoso.local' -AlternativeNames '*.contoso.local'

1	\\dc\Labfiles\scripts\GenerateCerts.ps1 -CertName 'SharePoint Site' -ServerCertFileFolder \\dc\Labfiles\certs -CertCommonName 'spaad.contoso.local' -AlternativeNames '*.contoso.local'

Step 2: Setup Identity Provider in AAD

In this step you will walk through setting up an Authentication Application in Azure Active Directory (AAD).

1. Access this link to create a new registration.

2. Select “+New Registration“

3. Complete the Wizard with the following properties:

Name: SharePoint On-Prem AAD Connection
Supported Types: Accounts in the organizational directory only (Microsoft Only – Single Tenant)
Redirect URI (Optional): Web = https://spaad.contoso.local

4. Select “Register“.

5. Save the “Directory(tenant) ID” and the “Application (client) ID” as they will be used as DefaultClientIdentifier in SharePoint setup.

6. After registering, go to Authentication page and enable “ID tokens” in the page. Select “Save

Example:

7. Select “API permissions”

8. Select “+Add a Permission”

9. Choose “Microsoft Graph”

10. Choose “Delegate Permissions”

11. Choose “email” then “Add permission“

12. Go to “Token configuration“

13. Select “+Add optional claim“.

14. In Token Type, Select ‘ID’.

15. Check, “email“.

16. Select “Add“

17. Select “+Add groups Claim“

18. Select all Check boxes.

19. Select “Add“.

20. When complete, the optional claims should be shown like this:

21. Go to “Manifest” page, and manually change “replyUrlsWithType” – “url” from “https://spaad.contoso.local/” to “https://spaad.contoso.local/*“. And select Save.

22. Select “Overview” from the top level of the new App Registration, then “End Points“.

23. Copy the “OpenID Connect metadata document” Endpoint.

https://login.microsoftonline.com/<tenantid>/v2.0/.well-known/openid-configuration

Step 3: Install the OIDC Nonce Cookie Cert in SharePoint

Please Note: The Nonce Cookie Cert is a Farm level setting. So, if it was already installed, you can skip this step.

Create the Nonce Cookie Certificate

In this step, you create a “Nonce Cookie Signing Cert” and add it into the Farm Properties.

Open server SPWFE
Launch PowerShell as Admin.

Run the script below.

#Create a cookie signing cert from the On-Prem Server
$cert = New-SelfSignedCertificate -CertStoreLocation Cert:\LocalMachine\My -Provider 'Microsoft Enhanced RSA and AES Cryptographic Provider' -Subject “CN=SharePoint Nonce Cookie Cert”


#Find the Private Key and Path
$privatekey_rsa = [System.Security.Cryptography.X509Certificates.RSACertificateExtensions]::GetRSAPrivateKey($cert)
$fileName = $privatekey_rsa.key.UniqueName
$path = "$env:ALLUSERSPROFILE\Microsoft\Crypto\RSA\MachineKeys\$fileName"


#Get current permisions for the Private Key
$permissions = Get-Acl -Path $path


#Modify permissions to include the "WSS_WPG" Group
$rule = new-object security.accesscontrol.filesystemaccessrule $env:COMPUTERNAME\WSS_WPG, ‘read’, allow
$permissions.AddAccessRule($rule)
Set-Acl -Path $path -AclObject $permissions


#Set the Farm Properties with the Nonce Cookie using the new Cert
$f = Get-SPFarm 
$f.Farm.Properties['SP-NonceCookieCertificateThumbprint']=$cert.Thumbprint
$f.Farm.Properties['SP-NonceCookieHMACSecretKey']='seed'
$f.Farm.Update()

#Create a cookie signing cert from the On-Prem Server

$cert = New-SelfSignedCertificate -CertStoreLocation Cert:\LocalMachine\My -Provider 'Microsoft Enhanced RSA and AES Cryptographic Provider' -Subject “CN=SharePoint Nonce Cookie Cert”

#Find the Private Key and Path

$privatekey_rsa = [System.Security.Cryptography.X509Certificates.RSACertificateExtensions]::GetRSAPrivateKey($cert)

$fileName = $privatekey_rsa.key.UniqueName

$path = "$env:ALLUSERSPROFILE\Microsoft\Crypto\RSA\MachineKeys\$fileName"

#Get current permisions for the Private Key

$permissions = Get-Acl -Path $path

#Modify permissions to include the "WSS_WPG" Group

$rule = new-object security.accesscontrol.filesystemaccessrule $env:COMPUTERNAME\WSS_WPG, ‘read’, allow

$permissions.AddAccessRule($rule)

Set-Acl -Path $path -AclObject $permissions

#Set the Farm Properties with the Nonce Cookie using the new Cert

$f = Get-SPFarm

$f.Farm.Properties['SP-NonceCookieCertificateThumbprint']=$cert.Thumbprint

$f.Farm.Properties['SP-NonceCookieHMACSecretKey']='seed'

$f.Farm.Update()

Important Note: For this Blog we are adding “WSS_WPG” with permissions to view the private cert. However, the best practice is always least-restrictive permissions and only provide the “App Pool” account with read access to the private key.

Check the Permissions of the Private Key

1. Check the “Private Key” to make sure the correct permissions were applied.

2. Launch MMC and add the “Certificates” Snap-in.

3. Choose “Computer Account”.

4. Then choose “Local Computer”

5. Find the SharePoint Nonce Cookie Cert and right-click on it, then choose “All Tasks” > Manage Private Keys”.

6. Ensure that the correct permissions were applied. You should identify “SPWFE\WSS_WPG”

Copy Nonce Certificate to all servers in the Farm

Important Notes:

If you have more than one SharePoint Server, the Certificate will need to be installed on all servers.
The Certificate can be exported from the “Certificate Manager” (with the private key) and imported into each server manually or with PowerShell.

For this blog, we will export and install the Cert on SPAPP and SPCORE by following these steps:

1. Export the Certificate using the following script from SPWFE

$cert = Get-ChildItem Cert:\LocalMachine\My |  Where-Object {$_.Subject -Match "SharePoint Nonce Cookie Cert"} 
Export-PfxCertificate -Password (Read-Host -AsSecureString) -Cert $cert -FilePath \\dc\labfiles\certs\SP_Nonce_CookieCert.pfx -Verbose

1 2	$cert = Get-ChildItem Cert:\LocalMachine\My \| Where-Object {$_.Subject -Match "SharePoint Nonce Cookie Cert"} Export-PfxCertificate -Password (Read-Host -AsSecureString) -Cert $cert -FilePath \\dc\labfiles\certs\SP_Nonce_CookieCert.pfx -Verbose

Note: You will be promoted for a password. Anything can be used in this case.

2. Log into the remaining servers in the Farm and run the following script on each server.

Write-Host "When Prompted for a password, use the password you entered when exporting the cert" -ForegroundColor Green
Import-PfxCertificate -FilePath "\\dc\labfiles\certs\SP_Nonce_CookieCert.pfx" -CertStoreLocation Cert:\LocalMachine\My -Password (Read-Host -AsSecureString) 
$cert = Get-ChildItem Cert:\LocalMachine\My |  Where-Object {$_.Subject -Match "SharePoint Nonce Cookie Cert"} 
$privatekey_rsa = [System.Security.Cryptography.X509Certificates.RSACertificateExtensions]::GetRSAPrivateKey($cert)
$fileName = $privatekey_rsa.key.UniqueName
$path = "$env:ALLUSERSPROFILE\Microsoft\Crypto\RSA\MachineKeys\$fileName"
$permissions = Get-Acl -Path $path
$rule = new-object security.accesscontrol.filesystemaccessrule $env:COMPUTERNAME\WSS_WPG, ‘read’, allow
$permissions.AddAccessRule($rule)
Set-Acl -Path $path -AclObject $permissions

Write-Host "When Prompted for a password, use the password you entered when exporting the cert" -ForegroundColor Green

Import-PfxCertificate -FilePath "\\dc\labfiles\certs\SP_Nonce_CookieCert.pfx" -CertStoreLocation Cert:\LocalMachine\My -Password (Read-Host -AsSecureString)

$cert = Get-ChildItem Cert:\LocalMachine\My | Where-Object {$_.Subject -Match "SharePoint Nonce Cookie Cert"}

$privatekey_rsa = [System.Security.Cryptography.X509Certificates.RSACertificateExtensions]::GetRSAPrivateKey($cert)

$fileName = $privatekey_rsa.key.UniqueName

$path = "$env:ALLUSERSPROFILE\Microsoft\Crypto\RSA\MachineKeys\$fileName"

$permissions = Get-Acl -Path $path

$rule = new-object security.accesscontrol.filesystemaccessrule $env:COMPUTERNAME\WSS_WPG, ‘read’, allow

$permissions.AddAccessRule($rule)

Set-Acl -Path $path -AclObject $permissions

3. Verify the private key permissions, using the same process in the previous section.

Step 4: Configure SharePoint SPTrustedTokenIssuer

In this step you will create a SPTrustedTokenIssuer that will store the configuration that SharePoint needs to trust AAD OIDC as OIDC provider.

There are 2 ways to configure this, Automatic with Metadata, or Manually by specifying the correct rotating certificate and endpoints.

Using the metadata endpoint provided from OIDC identity provider, the correct configuration can be retrieved from OIDC provider metadata endpoint directly and automatically configured in the STS.

Configuration of SharePoint SPTrustedTokenIssuer

Create the Trusted Identity Token Issue to use the E-mail claim.

Note: Be sure to update the script to use the Teant / Application ID from your tenant.

Create the Token Issuer using the E-mail Claim:

#Set the desired claim types
$emailClaimMap = New-SPClaimTypeMapping -IncomingClaimType "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress" -IncomingClaimTypeDisplayName "EmailAddress" -SameAsIncoming


#Replace with your "Directory (tenant) ID"
$MetadataEndpoint = 'https://login.microsoftonline.com/<TenantID>/v2.0/.well-known/openid-configuration'

#Replace with your "Application (Client) ID"
$clientIdentifier = ‘<Application ID>’

#Create a new SPTrustedIdentityTokenIssuer in SharePoint
New-SPTrustedIdentityTokenIssuer -Name 'SP to AAD TokenIssuer' -Description 'To Authorize users from AAD' -ClaimsMappings $emailClaimMap -IdentifierClaim $emailClaimMap.InputClaimType  -DefaultClientIdentifier $clientIdentifier -MetadataEndPoint $MetadataEndpoint

#Set the desired claim types

$emailClaimMap = New-SPClaimTypeMapping -IncomingClaimType "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress" -IncomingClaimTypeDisplayName "EmailAddress" -SameAsIncoming

#Replace with your "Directory (tenant) ID"

$MetadataEndpoint = 'https://login.microsoftonline.com/<TenantID>/v2.0/.well-known/openid-configuration'

#Replace with your "Application (Client) ID"

$clientIdentifier = ‘<Application ID>’

#Create a new SPTrustedIdentityTokenIssuer in SharePoint

New-SPTrustedIdentityTokenIssuer -Name 'SP to AAD TokenIssuer' -Description 'To Authorize users from AAD' -ClaimsMappings $emailClaimMap -IdentifierClaim $emailClaimMap.InputClaimType -DefaultClientIdentifier $clientIdentifier -MetadataEndPoint $MetadataEndpoint

Note: The automatic configuration will create the necessary Root Authorities as well.

Step 5: Configure the SharePoint web application

In this step you configure a web application in SharePoint to be federated with the AD FS or AAD OIDC, using the SPTrustedIdentityTokenIssuer that was created above.

There are some important rules to respect:

The default zone of the SharePoint web application must have Windows authentication enabled. This is required for the Search crawler.
SharePoint URL must be configured with HTTPS to use AAD OIDC federation.
If you extend an existing web application, set AAD OIDC authentication on a new zone

1. Logon to SPWFE

2. Start the SharePoint Management Shell as Admin

Run the following script:

#This script extends an existing web application to set AAD authentication on a new zone

#URL of the default zone of the web application
$webAppDefaultZoneUrl = "http://spwfe/"

#URL of the SharePoint site federated with ADFS
$trustedSharePointSiteUrl = "https://spaad.contoso.local/"

#Define Host Header Name
$hname = 'spaad.contoso.local'

#Setting the correct Cert to be used for extended Web APP
$spcert = Get-SPCertificate | Where-Object {$_.CommonName -Match "spaad.contoso.local"} 

#Set the correct SPTrustedIdentityTokenIssuer
$sptrust = Get-SPTrustedIdentityTokenIssuer "SP to AAD TokenIssuer"

#Create a new SP Auth Provider using the SPTrustedIdentityTokenIssuer
$ap = New-SPAuthenticationProvider -TrustedIdentityTokenIssuer $sptrust

#Set the Sp Web Application Object
$wa = Get-SPWebApplication $webAppDefaultZoneUrl

#Create the new extended zone to use the new Auth Provider
New-SPWebApplicationExtension -Name "SharePoint AAD" -Identity $wa -SecureSocketsLayer -Port 443 -Certificate $spcert -Zone Internet -Url $trustedSharePointSiteUrl -HostHeader $hname  -AuthenticationProvider $ap -UseServerNameIndication

#This script extends an existing web application to set AAD authentication on a new zone

#URL of the default zone of the web application

$webAppDefaultZoneUrl = "http://spwfe/"

#URL of the SharePoint site federated with ADFS

$trustedSharePointSiteUrl = "https://spaad.contoso.local/"

#Define Host Header Name

$hname = 'spaad.contoso.local'

#Setting the correct Cert to be used for extended Web APP

$spcert = Get-SPCertificate | Where-Object {$_.CommonName -Match "spaad.contoso.local"}

#Set the correct SPTrustedIdentityTokenIssuer

$sptrust = Get-SPTrustedIdentityTokenIssuer "SP to AAD TokenIssuer"

#Create a new SP Auth Provider using the SPTrustedIdentityTokenIssuer

$ap = New-SPAuthenticationProvider -TrustedIdentityTokenIssuer $sptrust

#Set the Sp Web Application Object

$wa = Get-SPWebApplication $webAppDefaultZoneUrl

#Create the new extended zone to use the new Auth Provider

New-SPWebApplicationExtension -Name "SharePoint AAD" -Identity $wa -SecureSocketsLayer -Port 443 -Certificate $spcert -Zone Internet -Url $trustedSharePointSiteUrl -HostHeader $hname -AuthenticationProvider $ap -UseServerNameIndication

3. Make sure the SP Certificate was added to the extended SharePoint Site correctly.

4. Verify the new Alternate Access Mapping was added properly.

5. Open the SharePoint Central Administration site. http://spwfe:7000

6. Under System Settings, select Configure Alternate Access Mappings.

7. Select the current Web Application in “Alternate Access Mapping Collection“.

8. Filter the display with the web application that was extended and confirm the new zone was added.

Step 6: Set the DNS name for the SPAAD Hostname

Create an A record in DNS so the new SharePoint hostname is accessible and pointing to the WFE.

1. From the DC open the DNS Manager

2. Choose the local “Contso.local” zone.

3. Right click on the zone and choose “New Alias (CNAME)…”

4. Enter “spaad” for the Name.

5. Enter ‘spwfe.contoso.local’ for the FQDN target host.

6. Select “Ok” to Add.

Note: This record can be added by the command line from the DC.

Here is an example:
dnscmd dc /recordadd contoso.local spaad CNAME spwfe.contoso.local

7. Ping SPAAD to verify the change.

Step 7: Give the AAD user permissions on the Site Collection

1. Open Central Admin (http://spwfe:7000)

2. Go to “Application Management” > “Manage web applications”

3. Select the default Web Application “SharePoint – 80” (The one that was extended).

4. Choose “User Policy”

5. Select “Add users”

6. Choose “Internet” in the Zones drop down.

7. Select Next.

8. Click on the “People Picker” “Address Book.

9. Type the full E-mail Address of your default Global Admin M365 Azure user and click on search.

10. The user should be displayed in the “E-mail Address” Claim, select the user, then add it with the Add-> button.

Note: This user should have an “email address” and “proxy address” in Azure Active directory. By default, the initial Global Admin account for M365 will always have an email address.

11. Select “Full Control” for the user.

12. After applying the change, you will see the user is stored with the correct claim, which includes the “Trusted Identity TokenIssuer”. It should like something like this:

Step 8: Access the site with an Azure AD User

1. From a client machine, launch the browser using “InPrivate Mode”

2. Access the site https://spaad.contoso.local

3. You may be presented with consent warning on the first access, just accept the warning.

4. You should be prompted for an account by AAD.

5. Use the email address that was added in the “Web Application” – “User Policy”

6. The local SharePoint site should be loaded using your “AAD Account”.

How to Remove the Token Issuer and Nonce Certificate if Needed

How to Delete the Nonce Farm Properties

If mistakes were made when creating the new Farm Properties, they can be removed with the following commands:

$f = Get-SPFarm
$f.Properties.Remove('SP-NonceCookieCertificateThumbprint')
$f.Properties.Remove('SP-NonceCookieHMACSecretKey')
$f.Farm.Update()

$f = Get-SPFarm

$f.Properties.Remove('SP-NonceCookieCertificateThumbprint')

$f.Properties.Remove('SP-NonceCookieHMACSecretKey')

$f.Farm.Update()

How to Delete the SharePoint SPTrustedTokenIssuer

If mistakes were made you can delete the “SPTrustedRootAuthority” and the “SPTrustedIdentityTokenIssuer”. However, before deleting these objects you will need to remove the authentication setting from authentication provider.

Example:

Once the SPTrustedIdentityTokenIssuer is no longer in use, it can be deleted with the following commands.

Get-SPTrustedIdentityTokenIssuer "SP to AAD TokenIssuer" | Remove-SPTrustedIdentityTokenIssuer
Get-SPTrustedRootAuthority "AAD signing root authority" | Remove-SPTrustedRootAuthority

1 2	Get-SPTrustedIdentityTokenIssuer "SP to AAD TokenIssuer" \| Remove-SPTrustedIdentityTokenIssuer Get-SPTrustedRootAuthority "AAD signing root authority" \| Remove-SPTrustedRootAuthority

Optional Step: Configure UPA Backing

If you would like to configure the new People Picker feature of SharePoint Subscription Edition and instruct SharePoint to search for users from the UPA directly, see the following blog for a simple guide.

Configure People Picker to find users from the UPA – Mike Lee’s Blog (mikesblogs.net)

Mike Lee's Blog

SharePoint, Exchange, Outlook and Hybrid Support Blogs

All Posts provided "AS IS" with no warranties, and confers no rights.
The opinions and views expressed in this blog are those of the author and do not necessarily state or reflect those of Microsoft.

Leave a ReplyCancel reply