DOM Customer Portal / Documentation / User Guide / Setting up SSO with AD FS and OpenID Connect

Setting up SSO with AD FS and OpenID Connect


Digi On-Prem Manager has support for single sign-on via OpenID connect. The integration allows users to log in via an existing Active Directory deployment.

This applies to v25.8 and later.

1: Configure Active Directory Federation Server

This guide explains how to configure the AD FS part of the process to allow users to authenticate users using OpenID Connect (OIDC) with group/role claims.

You need:

  • Windows Server 2022 or later
  • Active Directory configured with AD FS 6.0 or later
  • Administrator access
  • Hostname/IP-address for the DOM Server

1.1: Open AD FS Management

  • Go to Start → Administrative Tools → AD FS Management

1.2: Add a New Application Group

  • Navigate to Application Groups
  • Right-click → Add Application Group

“Welcome”

  • Enter a name for the integration, e.g. dom-server

  • Select Server application accessing a web API

  • Click Next

“Server application”

  • Make a note of the generated Client Identifier string, you will need it later.

  • Add the URLs that points to your DOM Server installation as Redirect URI, e.g. https://dom.example.com and https://192.0.2.100

  • Click Next

“Configure Application Credentials”

  • Check Generate a shared secret, and make a secure note of the generated secret string. You will need to provide it when configuring SSO in DOM Server.

  • Click Next

“Configure Web API”

  • Add the generated Client Identifier value from earlier to Identifier list

  • Click Next

“Choose Access Control Policy”

  • Either choose the default Permit everyone, or configure a more fine grained access policy if required in your organization. We will configure Security Group based access mapping separately in the the DOM Server configuration.

  • Click Next

“Configure Application Permissions”

  • In the Permitted scopes list, make sure the following scopes are checked:
    • allatclaims
    • openid
    • profile
    • email
  • Click Next

“Summary”

  • Click Next and Finish complete the Add Application Group Wizard

1.3: Configure Claim Issuance Rules

After finishing the wizard:

  • Double-click the dom-server Application Group
  • Double-click dom-server - Web API
  • Open the Issuance Transform Rules tab

  • Click Add Rule to access the Add Transform Claim Rule Wizard

  • Select: Send LDAP Attributes as Claims

  • Click Next

  • Provide a suitable name, e.g. DOM Server Claims
  • Choose Active Directory as the source
  • Map these attributes:
LDAP Attribute Outgoing Claim Type
Token-Groups - Unqualified Names roles
E-Mail-Addresses email
Given-Name first_name
Surname last_name

  • Click Finish

  • Click OK or Apply

2: Configure SSO on DOM Server

To complete the setup on your DOM Server we need to log in as the root system user via the terminal, usually using SSH.

Prerequisites:

  • The Client ID and Client Secret parameters from the AD FS setup
  • The URL endpoint for the AD FS server, e.g. https://adfs.example.com/adfs
  • Digi On-Prem Manager version 25.8 or later installed on a supported OS
  • System administrator (root) access to the server
  • The server must be able to connect to the HTTPS /adfs endpoint on the AD FS server, usually over port 443.
  • If a custom PKI has been used to issue HTTPS certificates on the AD FS server, the public CA certificate (in PEM format) must be provided in the DOM server configuration.

2.1: Access the DOM Server using SSH as root

Log in as the root user on the server running DOM using SSH.

ssh root@192.0.2.100

NOTE: Depending on your server configuration, you might need to log in as a personal user and escalate privileges using sudo.

ssh username@192.0.2.100
sudo -i

2.2: Verify that the application is running

Before we continue, let’s check heck that the application is running and is installed.

  • Run the dom-check command in the terminal to get system status

  • In your browser, access the URL for the web dashboard at https://192.0.2.100 to confirm that you have network access.

2.3: Edit the dom-server.com configuration file

All system level configuration is done in the INI-style configuration file located at /etc/dom-server/dom-server.conf. It must be edited with a plain text editor, in the examples below we’ll use the user friendly nano editor in the terminal as the root user.

The file will already have been populated with some hostname and IP address values that were autodetected when installed.

Keep in mind that the dom-server system services must be restarted before configuration file changes take effect.

  • Open the dom-server.conf file in your editor
nano /etc/dom-server/dom-server.conf
  • At the bottom of the file, under any other configuration sections, add the sso configuration. You can modify the following example, replacing placeholders with values for your installation.
[sso]
enabled       = 1
server        = https://adfs.example.com/adfs

client_id     = aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
client_secret = AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA


# Local path to the CA certificate to use for trust when DOM Server 
# connects to the AD FS server
cacert        = /etc/dom-server/ad-fs-ca.crt

# Optional: Disable certificate checks, only recommended for 
# testing purposes.
#
#   insecure      = 1
#

#####  Access control
#
# Rules are evaluated according to priority, in decending order. If
# a user has multiple matches only the first one is used.
#
# Optional: You can define a default access rule for users who are
# not matched by the access rules below. 
#
#   default_access = device/view group/admin
#   default_group = 1
#

[sso.access.admins]
priority = 1
from     = roles
ref      = Network Admins
group    = 1
access   = super

[sso.access.support-new-york]
priority = 5
from     = roles
ref      = New York Support Team
group    = 1001
access   = device/edit group/view

2.4: Restart DOM and test the SSO integration

Once the changes have been made to the configuration, restart the application with the following command:

systemctl restart dom-server

After the application has been restarted an SSO Login button will appear on the login page. Clicking it should redirect you to the authentication flow on your AD FS server, and log you in.