habsi/authentik
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

website/docs: add SharePoint Subscription Edition Integration (#7358)

Browse Source 
Co-authored-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>
Co-authored-by: Tana M Berry <tanamarieberry@yahoo.com>
This commit is contained in:
vherrlein
2023-12-18 15:50:20 +01:00
committed by GitHub
parent 0fb0745401
commit 4a8fb8e14d
2 changed files with 377 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

376
website/integrations/services/sharepoint-se/index.md Normal file
View File

@ -0,0 +1,376 @@
---
title: SharePoint Server SE
---
<span class="badge badge--secondary">Support level: Community</span>
## 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](https://www.ldapcp.com/docs/overview/introduction/) 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:
| Name | Placeholder | Sample value |
| -------------------------------------------------- | ------------------------------------ | -------------------------------------------------------------------------------------- |
| authentik Application Name | `auth.applicationName` | SharePoint SE |
| authentik Application Slug | `auth.applicationSlug` | sharepoint-se |
| authentik OIDC Name | `auth.providerName` | OIDC-SP |
| authentik OIDC Configuration URL | `auth.providerConfigURL` | https://authentik.company/application/o/sharepoint-se/.well-known/openid-configuration |
| authentik OIDC Client ID | `auth.providerClientID` | 0ab1c234d567ef8a90123bc4567890e12fa3b45c |
| authentik OIDC Redirect URIs | `auth.providerRedirectURI` | https://sharepoint.company/.\* |
| (Optional) authentik LDAP Outpost URI | `ldap.outpostURI` | ak-outpost-ldap.authentik.svc.cluster.local |
| (Optional) authentik LDAP Service Account | `ldap.outpostServiceAccount` | cn=ldapservice,ou=users,dc=ldap,dc=goauthentik,dc=io |
| (Optional) authentik LDAP Service Account Password | `ldap.outpostServiceAccountPassword` | mystrongpassword |
| SharePoint Default Web Application URL | `sp.webAppURL` | https://sharepoint.company |
| SharePoint Trusted Token Issuer Name | `sp.issuerName` | Authentik |
| SharePoint Trusted Token Issuer Description | `sp.issuerDesc` | authentik 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:
- https://learn.microsoft.com/en-us/entra/identity-platform/id-tokens#validate-tokens
- https://learn.microsoft.com/en-us/entra/identity-platform/id-token-claims-reference#payload-claims
#### Add an OpenID scope mapping for SharePoint
From the authentik Admin Dashboard:
1. Open **Customisation > 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**:
```python
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
}
```
5. Click **Finish**.
#### Add a profile scope mapping for SharePoint
From the authentik Admin Dashboard:
1. Open **Customisation > 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**:
```python
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.
}
```
5. 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:
- **Name**: `auth.applicationName`
- **Slug**: `auth.applicationSlug`
- **Provider**: `auth.providerName`
- (Optional) **Launch URL**: `sp.webAppURL`
- (Optional) **Icon**: https://res-1.cdn.office.net/files/fabric-cdn-prod_20221209.001/assets/brand-icons/product/svg/sharepoint_48x1.svg
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
:::
```PowerShell
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.
```PowerShell
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.
:::
```PowerShell
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](https://www.ldapcp.com/docs/overview/introduction/) 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
:::
```PowerShell
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 type | Entity type | LDAP class | LDAP Attribute to query | LDAP attribute to display | PickerEntity metadata |
| ------------------------------------------------------------- | ----------- | ---------- | ----------------------- | ------------------------- | --------------------- |
| http://schemas.microsoft.com/identity/claims/objectidentifier | User | user | uid | sn | UserId |
| LDAP attribute linked to the main mapping for object User | User | user | mail | | Email |
| LDAP attribute linked to the main mapping for object User | User | user | sn | | DisplayName |
| http://schemas.microsoft.com/ws/2008/06/identity/claims/role | Group | group | cn | | DisplayName |
| LDAP attribute linked to the main mapping for object Group | Group | group | uid | | SPGroupID |
### 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](https://goauthentik.io/docs/).
:::
1. Follow authentik [LDAP Provider Generic Setup](https://version-2023-10.goauthentik.io/docs/providers/ldap/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_.

1
website/sidebarsIntegrations.js
View File

@ -32,6 +32,7 @@ module.exports = {
"services/paperless-ng/index", "services/paperless-ng/index",
"services/rocketchat/index", "services/rocketchat/index",
"services/roundcube/index", "services/roundcube/index",
"services/sharepoint-se/index",
"services/vikunja/index", "services/vikunja/index",
"services/wekan/index", "services/wekan/index",
"services/wiki-js/index", "services/wiki-js/index",