This is the documentation of an pre-release opsi version. The documentation for the current version 4.3 can be found here.

Authorizations

This chapter focuses on user and group administration for the opsi server. You will learn about the default accounts and groups with administrative privileges and the process of creating custom accounts to manage the opsi server. Additionally, the chapter provides guidance on integrating an opsi server into a Windows domain, utilizing a directory service for authentication, and implementing two-factor authentication for enhanced server security.

Users and Groups

opsi uses the following user and group accounts:

  • opsiconfd: This account is for the system service opsiconfd (detailed in chapter opsiconfd Service). The account must be a member of the opsiadmin and opsifileadmins groups.

  • pcpatch: An account used by opsi clients for CIFS (Samba) access to the opsi depot. It must be a member of the opsifileadmins group (refer to section Password for User pcpatch).

To manage local users and groups on the opsi server, employ standard Linux tools such as useradd, usermod, groupadd, groupmod, etc. (see section Creating an Admin Account). Alternatively, you can connect the opsi config server to an existing Windows domain (see section Including opsi Server in Windows Domain) or to LDAP/Active Directory (see section Authentication against Directory Service (LDAP/AD)).

opsi uses specific groups to manage authorizations:

  • opsiadmin: Members of this group have administrative access to the opsi service. This means they are granted full access via various interfaces, including the management interface opsi-configed, the opsi WebGUI, and the opsiconfd admin page.

  • opsifileadmins: Members of this group have administrative access to opsi files (i.e. the depot, repository, and workbench).

  • opsireadonly: Members of this group are provided with read-only access to the opsi service.

The names of these groups can be modified in the configuration file /etc/opsi/opsi.conf, specifically within the groups section:

[groups]
fileadmingroup = "opsifileadmins"
admingroup = "opsiadmin"
readonly = "opsireadonlys"

Creating an Admin Account

To create local users and groups on the opsi config server, you should use the standard Linux tools. For instance, to set up a new user named adminuser and grant them full administrative access to the opsi server, you would add them to the opsiadmin and opsifileadmins groups.

The adminuser account already exists in the preconfigured virtual machine and in our Docker container. However, you can follow these steps to add more accounts.

Begin by creating the new account with the useradd command:

sudo useradd -m -s /bin/bash adminuser

Then set a Unix password (system) for the new account:

sudo passwd adminuser

If the user is also to have file access via CIFS (Samba), set a password for this as well:

sudo smbpasswd -a adminuser
Do not use the § character in passwords!

Next, add the new user to the opsiadmin and opsifileadmins groups:

usermod -aG opsiadmin adminuser opsifileadmins

Enter the command id to check that the account adminuser exists and belongs to both groups:

id adminuser
# uid=1000(adminuser) gid=1000(opsiadmin) groups=1000(opsiadmin),999(opsifileadmins)

Password for User pcpatch

Since opsi clients use this account for authentication, the opsi config server needs to be aware of the password. To ensure security, the password is stored in an encrypted format in the file /etc/opsi/passwd. Upon the installation of an opsi config server, a random password is automatically generated, which typically does not require modification.

However, if you need to change the password, you can do so using the command line tool opsi-admin. For more information on how to use this tool, refer to the section opsi-admin:

opsiconfd setup --set-depot-user-password

After pressing the [Enter] button, you will be prompted to enter the new password.

This action will change the password for both the local Unix and Samba account. If it concerns a domain account, you will also need to manually reset the new password within the domain settings.

Including opsi Server in Windows Domain

For an opsi server to work within a Windows or Samba 4 domain environment, as opposed to using local Unix and Samba accounts, the opsiadmin and opsifileadmins groups should be created within the domain.

If you wish to use different names for these groups or use existing domain groups, modify the group names in the /etc/opsi/opsi.conf configuration file accordingly.

Additionally, create a domain user pcpatch as a member of the opsifileadmins group, and opsiconfd as a member of both opsiadmin and opsifileadmins groups.

Next, remove the opsiadmin and opsifileadmins groups from the local Unix system using the groupdel command. Also, delete the local Unix accounts opsiconfd and pcpatch using the userdel command.

Proceed to add the opsi server to the Windows domain. The specific steps for this process vary and should be referenced from the documentation of the Linux distribution in use.

Once the server is joined to the domain, execute the following two commands:

opsiconfd setup
opsi-set-rights
For more information on the two commands, see the two sections opsiconfd setup Command and opsi-set-rights.

Finally, reset the password for the user pcpatch (see section Password for User pcpatch).

Authentication against Directory Service (LDAP/AD)

By default, opsi employs PAM (Pluggable Authentication Modules) for authentication across various services and applications. This method is compatible with both local users and groups, as well as with opsi servers integrated into a domain. Alternatively, directory services such as LDAP (Lightweight Directory Access Protocol) or AD (Active Directory) can be used. These directory services centralize user accounts, groups, and other identity information, facilitating authentication and authorization across different services and applications.

Samba authentication operates separately from this system. Therefore, the approach detailed in this section is particularly relevant for opsi environments where administrators access opsi shares via WebDAV instead of Samba, which is commonly the case with opsi servers running in Docker.
To use an LDAP server or an Active Directory for authentication instead of PAM, the opsi extension opsi directory connector is required.

Configuration

Configuration for connecting opsi to AD/Samba 4 or LDAP is done through the /etc/opsi/opsi.conf file, specifically in the [ldap_auth] section. In both scenarios—whether integrating with AD/Samba 4 or LDAP—you need to specify the address of the directory service using the ldap_url parameter. The URL should be structured as follows:

ldap[s]://<Adresse-des-LDAP-Servers>[:port]/<base-dn>

In addition to specifying the LDAP/AD address, you can set the username for authentication using the bind_user option in the configuration file. This option allows the use of placeholders such as {username} and {base}. Generally, providing the ldap_url is sufficient for most setups.

Here’s an example for connecting to an Active Directory or Samba 4:

[ldap_auth]
ldap_url = "ldaps://ad.company.de/dc=ad,dc=company,dc=de"
bind_user = "{username}@ad.company.de"

Example for connecting to an OpenLDAP service:

[ldap_auth]
ldap_url = "ldaps://ldap.company.org:636/dc=company,dc=org"
bind_user = "uid={username},dc=Users,{base}"
With the command opsiconfd test ldap_auth you can easily test the connection to the LDAP server and different configurations.

Once you have made and saved the necessary changes in the configuration file, you should restart the opsiconfd service to apply these changes.

It’s important to ensure that the group specified after admingroup in the /etc/opsi/opsi.conf file also exists in the directory service.

Two-Factor Authentication

The opsi server supports two-factor authentication (2FA) using the TOTP (Time-based One-Time Password) algorithm. This standard method for 2FA generates a one-time password comprising six digits, which is required in addition to the usual credentials for logging into the opsi server.

To implement two-factor authentication, the opsi extension WAN/VPN is required. i

General Setup

i To enable two-factor authentication, adjust the configuration of the opsiconfd service (refer to section Configuration). Modify the /etc/opsi/opsiconfd.conf file and specify one of the following values for the multi-factor-auth option:

  • inactive: Disables two-factor authentication (the default setting). This is also applicable to users with TOTP configured.

  • totp_optional: Makes TOTP-based two-factor authentication optional. Users who have TOTP enabled must use it.

  • totp_mandatory: Enforces TOTP as a mandatory requirement. Users who haven’t enabled TOTP will not be able to log in.

Remember to execute the command opsiconfd reload after making your changes.

User-specific Setup

The configuration is managed through the Users tab on the Admin Page. To initiate two-factor authentication for a specific user, click on Generate new secret and activate TOTP. This action generates a server-side secret and activates two-factor authentication for that user.

Following this, the displayed QR code can be scanned using an app like 2FA Authenticator (2FAS), available for both Android and iOS. The app then produces a new one-time password every 30 seconds, which the user needs to append to their regular password during authentication.

You can set up Two-Factor Authentication on the _Users_ Tab.
Figure 1. You can set up Two-Factor Authentication on the Users Tab.
Generating a new secret by clicking on Generate new secret and activate TOTP again will invalidate the user’s previous QR code.

To turn off two-factor authentication for an account, select Deactivate MFA.

Authorization via SAML

SAML 2.0 (Security Assertion Markup Language) is an open standard that enables cross-domain single sign-on (SSO). Users are authenticated via an identity provider (IdP) and thus gain access to services from service providers (SP). The opsi service can be configured as a service provider (SP) to authenticate users via SAML. Here, Microsoft Entra ID and Keycloak are supported as identity providers (IdP).

Configuration

The configuration is carried out in the opsiconfd service. The following parameters must be set:

saml-idp-entity-id

The entity ID of the identity provider (IdP).

saml-idp-x509-cert

The certificate of the identity provider (IdP) in Base64 format.

saml-idp-sso-url

The URL of the single sign-on (SSO) of the identity provider (IdP).

saml-idp-slo-url

(optional) The URL of the Single Logout (SLO) of the identity provider (IdP).

Microsoft Entra ID

The following steps must be carried out in the Microsoft Entra Admin Center:

Create Microsoft Entra SAML Toolkit App

  • Navigate to Identity ⇒ Applications ⇒ Enterprise applications ⇒ All applications

  • Click on New Application

  • Search the catalog for Microsoft Entra SAML Toolkit and click on the displayed app.

  • Enter a name for the app, e.g. opsi SAML.

  • Click on Create.

  • The newly created app is now displayed under All applications.

Configuration of the SAML app

  • Click on the newly created app opsi SAML to edit it.

  • Select the menu item Single sign-on (SSO).

  • Select SAML.

  • Edit the Basic SAML Configuration

  • Enter the ID of your opsi config server (e.g. opsi.company.com) as Entity ID.

  • Under Reply URL enter the following URL of your opsi server: https://<address-configserver>:4447/auth/saml/callback/login.

  • Save the configuration.

  • Download the SAML Certificate in Base64 format and store it as saml-idp-x509-cert in the configuration.

  • Enter the value displayed under Microsoft Entra Identifier as saml-idp-entity-id in the configuration.

  • Transfer the Login URL as saml-idp-sso-url in the configuration.

  • Optional: Enter the Logout URL as saml-idp-slo-url in the configuration.

Create app role

The app role opsiadmin is required to administratively login users at the opsi service.

  • Navigate to Identity ⇒ Applications ⇒ App registrations ⇒ All applications ⇒ opsi SAML

  • Add yourself as owner under Manage ⇒ Owners.

  • Select App roles

  • Click on Create app role

  • Enter opsiadmin as the Value

  • You can freely select the Display name (e.g. opsiadmin)

  • Check the box next to Enable this app role

  • Save the app role by clicking on Apply

Assign users

Users who are to log into the opsi service administratively must now be assigned to the app role opsiadmin.

  • Navigate again to Identity ⇒ Applications ⇒ Enterprise applications_ ⇒ All applications

  • Select the opsi SAML app again.

  • Click on Users and groups ⇒ Add user/group

  • Now select a user or group and assign the role 'opsiadmin' to it.

Apply changes

After you have made all changes to the configuration, restart the opsiconfd service.

Keycloak

The following steps must be carried out in the Keycloak Admin Console:

Apply realm settings

  • Navigate to Settings ⇒ Realm settings.

  • Click on the link SAML 2.0 Identity Provider Metadata

  • Enter the value displayed under <EntityDescriptor entityID="">_ as saml-idp-entity-id in the configuration.

  • Copy the value displayed under <X509Certificate> and store it as saml-idp-x509-cert in the configuration.

  • Enter the URL displayed under <SingleSignOnService Binding="HTTP-POST"> as saml-idp-sso-url in the configuration.

  • Optional: Enter the URL displayed under <SingleLogoutService Binding="HTTP-POST"> as saml-idp-slo-url in the configuration.

Create client

  • Navigate to Manage ⇒ Clients and click on Create Client

  • Select SAML as Client type.

  • Enter the ID of your opsi config server (e.g. opsi.company.com) under Client ID.

  • Save the client.

Configure client

  • Edit the client again by clicking on it under Client list.

  • Enter the URL of your opsi server under Access settings ⇒ Root URL: `https://<address-configserver>:4447.

  • Enter the same URL under Home URL.

  • Under Valid redirect URIs add the URL `https://<address-configserver>:4447/*.

  • Enter the same value under Valid post logout redirect URIs.

  • Deactivate Client signature required under Keys ⇒ Signing keys config.

Create role

The app role opsiadmin is required to administratively log users into the opsi service.

  • Create a new role opsiadmin. You can create this role globally in the Manage ⇒ Realm roles realm or specifically for the client under Roles.

  • You can now assign the role to individual users or groups.

Apply changes

After you have made all changes to the configuration, restart the opsiconfd service.