Skip to main content

SharePoint Server SE

Support level: Community

What is Microsoft SharePoint​

SharePoint is a proprietary, web-based collaborative platform that integrates natively with Microsoft 365.

Launched in 2001, SharePoint is primarily sold as a document management and storage system, although it is also used for sharing information through an intranet, implementing internal applications, and for implementing business processes.

-- https://en.wikipedia.org/wiki/SharePoint

Organizations use Microsoft SharePoint to create websites.

You can use it as a secure place to store, organize, share, and access information from any device. All you need is a web browser, such as Microsoft Edge, Internet Explorer, Chrome, or Firefox.

-- https://support.microsoft.com/en-us/office/what-is-sharepoint-97b915e6-651b-43b2-827d-fb25777f446f

note

There are many ways to implement SSO mechanism within Microsoft SharePoint Server Subscription Edition.

These guidelines provides the procedure to integrate authentik with an OIDC provider based on Microsoft documentation. (cf. https://learn.microsoft.com/en-us/sharepoint/security-for-sharepoint-server/set-up-oidc-auth-in-sharepoint-server-with-msaad)

In addition, it provides the procedure to enable claims augmentations in order to resolve group memberships.

For all other integration models, read Microsoft official documentation. (cf. https://learn.microsoft.com/en-us/sharepoint/security-for-sharepoint-server/plan-user-authentication)

caution

This setup only works starting with authentik version 2023.10 and Microsoft SharePoint Subscription Edition starting with the Cumulative Updates of September 2023.

Preparation​

When you configure OIDC with authentik, you need the following resources:

  1. A SharePoint Server Subscription Edition farm starting with CU of September 2023
  2. An authentik instance starting with version 2023.10
  3. (Optional) LDAPCP installed on the target SharePoint farm
info

Ensure that the authentik and SharePoint Server clocks are synchronized.

These guidelines use the following placeholders for the overall setup:

NamePlaceholderSample value
authentik Application Nameauth.applicationNameSharePoint SE
authentik Application Slugauth.applicationSlugsharepoint-se
authentik OIDC Nameauth.providerNameOIDC-SP
authentik OIDC Configuration URLauth.providerConfigURLhttps://authentik.company/application/o/sharepoint-se/.well-known/openid-configuration
authentik OIDC Client IDauth.providerClientID0ab1c234d567ef8a90123bc4567890e12fa3b45c
authentik OIDC Redirect URIsauth.providerRedirectURIhttps://sharepoint.company/.\*
(Optional) authentik LDAP Outpost URIldap.outpostURIak-outpost-ldap.authentik.svc.cluster.local
(Optional) authentik LDAP Service Accountldap.outpostServiceAccountcn=ldapservice,ou=users,dc=ldap,dc=goauthentik,dc=io
(Optional) authentik LDAP Service Account Passwordldap.outpostServiceAccountPasswordmystrongpassword
SharePoint Default Web Application URLsp.webAppURLhttps://sharepoint.company
SharePoint Trusted Token Issuer Namesp.issuerNameAuthentik
SharePoint Trusted Token Issuer Descriptionsp.issuerDescauthentik IDP

authentik configuration​

Step 1: Create authentik OpenID Property Mappings​

SharePoint requires additional properties within the OpenID and profile scopes in order to operate OIDC properly and be able to map incoming authentik OID Claims with Microsoft Claims.

Additional information from Microsoft documentation:

Add an OpenID scope mapping for SharePoint​

From the authentik Admin Dashboard:

  1. Open Customization > Property Mappings page from the sidebar.
  2. Click Create from the property mapping list command bar.
  3. Within the new property mapping form, select Scope Mapping.
  4. Click Next and enter the following values:
    • Name: SPopenid
    • Scope name: openid
    • Expression:
return {
  "nbf": "0",           # Identifies the time before which the JWT can't be accepted for processing.
                        # 0 stand for the date 1970-01-01 in unix timestamp
  "oid": user.uid,      # This ID uniquely identifies the user across applications - two different applications signing in the same user receives the same value in the oid claim.
  "upn": user.username  # (Optional) User Principal Name, used for troubleshooting within JWT tokens or to setup SharePoint like ADFS
}
  1. Click Finish.

Add a profile scope mapping for SharePoint​

From the authentik Admin Dashboard:

  1. Open Customization > Property Mappings page from the sidebar.
  2. Click Create from the property mapping list command bar.
  3. Within the new property mapping form, select Scope Mapping.
  4. Click Next and enter the following values:
    • Name: SPprofile
    • Scope name: profile
    • Expression:
return {
    "name": request.user.name,                                         # The name claim provides a human-readable value that identifies the subject of the token.
    "given_name": request.user.name,                                   # Interoperability with Microsoft Entra ID
    "unique_name": request.user.name,                                  # (Optional) Used for troubleshooting within JWT tokens or to setup SharePoint like ADFS
    "preferred_username": request.user.username,                       # (Optional) The primary username that represents the user.
    "nickname": request.user.username,                                 # (Optional) Used for troubleshooting within JWT tokens or to setup SharePoint like ADFS
    "roles": [group.name for group in request.user.ak_groups.all()],   # The set of roles that were assigned to the user who is logging in.
}
  1. Click Finish.

Step 2: Create authentik Open ID Connect Provider​

From the authentik Admin Dashboard:

  1. Open Applications > Providers page from the sidebar.
  2. Click Create from the provider list command bar.
  3. Within the new provider form, select OAuth2/OpenID Provider.
  4. Click Next and enter the following values:
    • Name: auth.providerName
    • Authentication flow: default-authentication-flow
    • Authorization flow: default-provider-authorization-implicit-consent
      note

      use the explicit flow if user consents are required

    • Redirect URIs / Origins: auth.providerRedirectURI
    • Signing Key: authentik Self-signed Certificate
      note

      The certificate is used for signing JWT tokens;, if you change it after the integration do not forget to update your SharePoint Trusted Certificate.

    • Access code validity: minutes=5
      note

      The minimum is 5 minutes, otherwise SharePoint backend might consider the access code expired.

    • Access Token validity: minutes=15
      note

      The minimum is 15 minutes, otherwise SharePoint backend will consider the access token expired.

    • Scopes: select default email, SPopenid and SPprofile
    • Subject mode: Based on the User's hashed ID
  5. Click Finish.

Step 3: Create an application in authentik​

From the authentik Admin Dashboard:

  1. Open Applications > Applications page from the sidebar.
  2. Click Create from the application list command bar.
  3. Within the new application form, enter the following values:
  4. Click Create.

Step 4: Setup OIDC authentication in SharePoint Server​

Pre-requisites​

Update SharePoint farm properties​

The following PowerShell script must be updated according to your environment and executed as Farm Admin account with elevated privileges on a SharePoint Server.

caution
  • Update placeholders
  • Read all script's comments
Add-PSSnapin microsoft.sharepoint.powershell

# Setup farm properties to work with OIDC
$cert = New-SelfSignedCertificate -CertStoreLocation Cert:\LocalMachine\My -Provider 'Microsoft Enhanced RSA and AES Cryptographic Provider' -Subject "CN=SharePoint Cookie Cert"
$rsaCert = [System.Security.Cryptography.X509Certificates.RSACertificateExtensions]::GetRSAPrivateKey($cert)
$fileName = $rsaCert.key.UniqueName

#If you have multiple SharePoint servers in the farm, you need to export certificate by Export-PfxCertificate and import certificate to all other SharePoint servers in the farm by Import-PfxCertificate and apply the same permissions as below.

#After certificate is successfully imported to SharePoint Server, we will need to grant access permission to certificate private key.

$path = "$env:ALLUSERSPROFILE\Microsoft\Crypto\RSA\MachineKeys\$fileName"
$permissions = Get-Acl -Path $path

#Please replace the <web application pool account> with the real application pool account of your web application.
$access_rule = New-Object System.Security.AccessControl.FileSystemAccessRule("$($env:computername)\WSS_WPG", 'Read', 'None', 'None', 'Allow')
$permissions.AddAccessRule($access_rule)
Set-Acl -Path $path -AclObject $permissions

#Then we update farm properties only once.
$f = Get-SPFarm
$f.Farm.Properties['SP-NonceCookieCertificateThumbprint']=$cert.Thumbprint
$f.Farm.Properties['SP-NonceCookieHMACSecretKey']='seed'
$f.Farm.Update()
SharePoint settings in case of SSL offloading​

Update the SharePoint farm to accept OAuth authentication over HTTP.

The following PowerShell script must be updated according to your environment and executed as Farm Admin account with elevated privileges on a SharePoint Server.

Add-PSSnapin microsoft.sharepoint.powershell
$c = get-spsecuritytokenserviceconfig
$c.AllowOAuthOverHttp = $true
$c.update()

Create SharePoint authentication provider​

The following PowerShell script must be updated according to your environment and executed as Farm Admin account with elevated privileges on a SharePoint Server.

caution
  • Update placeholders
  • Read all script's comments.
Add-PSSnapin microsoft.sharepoint.powershell

# OIDC Settings
$metadataendpointurl = "auth.providerConfigURL"
$clientIdentifier = "auth.providerClientID"
$trustedTokenIssuerName = "sp.issuerName"
$trustedTokenIssuerDescription = "sp.issuerDesc"

# OIDC Claims Mapping
## Identity claim: oid => defined within the Authentik scope mapping
$idClaim = New-SPClaimTypeMapping "http://schemas.microsoft.com/identity/claims/objectidentifier" -IncomingClaimTypeDisplayName "oid" -SameAsIncoming

## User claims mappings
$claims = @(
    $idClaim
    ## User Roles (Group membership)
    ,(New-SPClaimTypeMapping ([System.Security.Claims.ClaimTypes]::Role) -IncomingClaimTypeDisplayName "Role" -SameAsIncoming)
    ## User email
    ,(New-SPClaimTypeMapping ([System.Security.Claims.ClaimTypes]::Email) -IncomingClaimTypeDisplayName "Email" -SameAsIncoming)
    ## User given_name
    ,(New-SPClaimTypeMapping ([System.Security.Claims.ClaimTypes]::GivenName) -IncomingClaimTypeDisplayName "GivenName" -SameAsIncoming )
    ## (Optional) User account name
    #,(New-SPClaimTypeMapping ([System.Security.Claims.ClaimTypes]::NameIdentifier) -IncomingClaimTypeDisplayName "Username" -SameAsIncoming)

)

# Trust 3rd party identity token issuer
$trustedTokenIssuer = New-SPTrustedIdentityTokenIssuer -Name $trustedTokenIssuerName -Description $trustedTokenIssuerDescription -ClaimsMappings $claims -IdentifierClaim $idClaim.InputClaimType -DefaultClientIdentifier $clientIdentifier -MetadataEndPoint $metadataendpointurl -Scope "openid email profile"
#Note: Remove the profile scope if you plan to use the LDAPCP claims augmentation.

# Create the SharePoint authentication provider based on the trusted token issuer
New-SPAuthenticationProvider -TrustedIdentityTokenIssuer $trustedTokenIssuer

Configure SharePoint web applications​

From the Central Administration opened as a Farm Administrator:

  1. Open the Application Management > Manage web applications page.
  2. Select your web application sp.webAppURL.
  3. Click Authentication Providers from the ribbon bar.
  4. According to your environment, click on the target zone such as "Default".
  5. Update the authentication provider form as following:
    • Check Trusted Identity Provider
    • Check the newly created provider named sp.issuerName
    • (Optional) Set Custom Sign In Page: /_trust/default.aspx
  6. Click Save.

Repeat all steps for each target web applications that matches with auth.providerRedirectURI.

(Optional) SharePoint enhancements​

Objectives :

  • Integrate SharePoint People Picker with authentik to search users and groups
  • Augment SharePoint user claims at login stage
  • Resolve user's membership
caution

LDAPCP must be installed on the target SharePoint farm.

Step 1: Assign LDAPCP as claim provider for the identity token issuer​

The following PowerShell script must be updated according to your environment and executed as Farm Admin account with elevated privileges on a SharePoint Server.

caution
  • Update placeholders
  • Read all script's comments
Add-PSSnapin microsoft.sharepoint.powershell
$trustedTokenIssuerName = "sp.issuerName"

$sptrust = Get-SPTrustedIdentityTokenIssuer $trustedTokenIssuerName
$sptrust.ClaimProviderName = "LDAPCP"
$sptrust.Update()

Step 2: Configure LDAPCP claim types​

From the SharePoint Central Administration opened as a Farm Administrator:

  1. Open Security > LDAPCP Configuration > Claim types configuration page.
  2. Update the mapping table to match these value:
Claim typeEntity typeLDAP classLDAP Attribute to queryLDAP attribute to displayPickerEntity metadata
http://schemas.microsoft.com/identity/claims/objectidentifierUseruseruidsnUserId
LDAP attribute linked to the main mapping for object UserUserusermailEmail
LDAP attribute linked to the main mapping for object UserUserusersnDisplayName
http://schemas.microsoft.com/ws/2008/06/identity/claims/roleGroupgroupcnDisplayName
LDAP attribute linked to the main mapping for object GroupGroupgroupuidSPGroupID

Step 3: Create an authentik LDAP Outpost​

From the authentik Admin Dashboard:

note

The following procedure apply to an authentik deployment within Kubernetes.

For other kinds of deployment, please refer to the authentik documentation.

  1. Follow authentik LDAP Provider Generic Setup with the following steps :
    • Create User/Group to create a "service account" for ldap.outpostServiceAccount and a searchable group of users & groups
    • LDAP Flow to create the authentication flow for the LDAP Provider
    • LDAP Provider to create an LDAP provider which can be consumed by the LDAP Application
  2. Open Applications > Applications page from the sidebar.
  3. Open the edit form of your application auth.applicationName.
  4. In the edit form:
    • Backchannel Providers: add the LDAP provider previously created
  5. Click Update.

Step 4: Configure LDAPCP global configuration​

From the SharePoint Central Administration opened as a Farm Administrator:

  1. Open the Security > LDAPCP Configuration > Global configuration page.
  2. Add an LDAP connection with th following properties:
    • LDAP Path: LDAP://ldap.outpostURI/dc=ldap,dc=goauthentik,dc=io
    • Username: ldap.outpostServiceAccount
    • Password: ldap.outpostServiceAccountPassword
    • Authentication types: check ServerBind
  3. Augmentation - Check Enable augmentation
  4. Augmentation - Select the Role claim "http://schemas.microsoft.com/ws/2008/06/identity/claims/role"
  5. Augmentation - Check only "Query this server" for your ldap.outpostURI
  6. User identifier properties:
    • LDAP class: user
    • LDAP attribute: uid
  7. Display of user identifier results:
    • Tick Show the value of another LDAP attribute: sn
  8. Click on "OK"

Note: The ldap.outpostURI should be the IP, hostname, or FQDN of the LDAP Outpost service deployed accessible by your SharePoint farm.