Support for Windows Authentication

Windows authentication allows clients to get DPE tokens without explicitly entering credentials.

Preconditions

• Active Directory users must be synced to DigaSystem (AD Sync)

• DPE Nano Services is running self-hosted with Kestrel (IIS or HttpSys is not supported)

• DPE Nano Services is running under Windows and the machine is part of the AD domain
  (Linux is supported but complicated to configure)

• Client application must support windows authentication for getting DPE tokens,
  e.g. DPE ContentManager >= v3.5.6, DPE Admin >= v3.4.8

• Kerberos/NTLM must be configured correctly so that clients (e.g. Browsers) are allowed to use it

• We recommend to use standard HTTP/HTTPS ports when using Kerberos handshake

appsettings.json

Add the following top-level option

  "EnableNegotiate": true,

Browser Support

Windows authentication is triggered by a backend HTTP response signaling that it wants to negotiate authentication.

If enabled, browsers first try Kerberos authentication (more secure) and if this fails they try to fallback to NTLM authentication (less secure).

Enable automatic windows authentication via Kerberos/NTLM for specific backend URLs.

This can be done by directly modifying windows registry configuration on your client machines or applying group policies by your Administrator.

Chrome

Windows Registry: HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Google\Chrome

• AuthServerAllowlist = <comma-separated list of DNS names + port where your service is hosted> e.g. dpe.davidsystems-test.com:7878 (standard ports are recommmend, which means no port is specified here)

• EnableAuthNegotiatePort = 1 (needed when service is not on default ports 80 or 443)

Corresponding Group Policy

An alternative to setting the AuthServerAllowlist is to add the service URL to Internet Options|Security|Local Internet|Sites, e.g. http://dpe.davidsystems-test.com.

In any case, EnableAuthNegotiatePort must be set to 1 if the service is hosted on a non standard port.

Edge

Group policies or windows registry HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Microsoft\Edge (key names see Chrome above)

Firefox

Allow Kerberos for DPE Nano Services in Active Directory

Kerberos tickets are issued for a specific service.

Active directory must be configured to allow tickets for such services.

We recommend to avoid non-standard ports, which means also not specifying a port for the setspn command.Make

This is done with the setspn tool on your Active Directory machine using the following command:

setspn -S HTTP/<service-address> <domain-user-running-service>

Example:

setspn -S HTTP/dpe.davidsystems-test.com david-gmbh.de\dpedemo

Existing service principal names (SPN) can be listed on any windows client that is part of the domain, e.g.

setspn -L david-gmbh.de\dpedemo

Using Kerberos with DpeNanoServices under Linux

Make sure the Linux machine has joined the Active Directory domain

How to join a linux computer to an active directory domain

Allow to use Kerberos tickets for the machine running DPE Nano Service and the user it is running under

• We recommend to use a dedicated domain user as a service user for running DpeNanoServices

• We recommend to use standard ports (i.e. not specifying any port) for setspn

• Run the following command on your Active Directory Server:

  setspn -S HTTP/<service-address> <domain-user-running-service>
  

  e.g.

  setspn -S HTTP/dpenano3.davidsystems-test.com david-gmbh.de\dpelinux
  

• Export a keytab file, casing is important

  ktpass -princ HTTP/<service-address>@EXAMPLE.COM -mapuser <domain-user-running-service> -pass * -out C:\app.keytab -ptype KRB5_NT_PRINCIPAL -crypto AES256-SHA1
  

  ktpass -princ HTTP/dpenano3.davidsystems-test.com@DAVID-GMBH.DE -mapuser david-gmbh\dpelinux -pass * -out C:\app.keytab -ptype KRB5_NT_PRINCIPAL -crypto AES256-SHA1
  

• Copy the created keytab file to your Linux machine

• Make sure that the user executing DpeNanoServices has permissions to read the keytab file

• Make the keytab file used by exporting its path to the environment, e.g.

  export KRB5_KTNAME=/var/www/app.keytab
  

• …

Run DpeNanoServices as Linux daemon under a service user

• See also Running as Linux daemon (Ubuntu/Debian)

• Adapt the service file, e.g.

• …specify the service user and

• …set the path to the keytab file and

• …optionally allow to open standard ports for non-root
  Only needed when you have no reverse proxy like nginx in front. Otherwise you can host DpeNanoServices under a custom port like 5000 and route through reverse proxy.

  [Unit]
  Description=DpeNanoServices running on Linux
  [Service]
  WorkingDirectory=/var/www/dpenanoservices
  ExecStart=/usr/bin/dotnet /var/www/dpenanoservices/DpeNanoServices.dll --urls "http://0.0.0.0:5000" DpeParFile:DigaSystemRegistryXmlFilePath=DigaSystemRegistry_Linux.xml --environment Development
  Restart=always
  RestartSec=10
  KillSignal=SIGINT
  SyslogIdentifier=dpenanoservices
  User=dpelinux@DAVID-GMBH.DE
  CapabilityBoundingSet=CAP_NET_BIND_SERVICE
  AmbientCapabilities=CAP_NET_BIND_SERVICE
  Environment=ASPNETCORE_ENVIRONMENT=Production
  Environment=DOTNET_PRINT_TELEMETRY_MESSAGE=false
  Environment=KRB5_KTNAME=/var/www/app.keytab
  [Install]
  WantedBy=multi-user.target
  

Make sure that firewall allows traffic for HTTP/HTTPS and Kerberos

• For example list firewall rules

  sudo ufw status
  Status: active
  
  To                         Action      From
  --                         ------      ----
  22/tcp                     ALLOW       Anywhere                   # Allow SSH access
  80/tcp                     ALLOW       Anywhere                   # Allow HTTP traffic
  443/tcp                    ALLOW       Anywhere                   # Allow HTTPS traffic
  22/tcp (v6)                ALLOW       Anywhere (v6)              # Allow SSH access
  80/tcp (v6)                ALLOW       Anywhere (v6)              # Allow HTTP traffic
  443/tcp (v6)               ALLOW       Anywhere (v6)              # Allow HTTPS traffic