userguide:llng

This is an old revision of the document!


Install LemonLDAP::NG SSO/IAM on Nethserver

Background

I'd discussed single sign-on/identity and access management (SSO/IAM) in this topic, and I think it'd bring a lot of capabilities to the table with Nethserver. The main ones I saw were:

  • Improved application security, as individual applications (like Nextcloud) never handle a user's credentials and therefore can't compromise them.
  • Centralized policy management–which applications require MFA, which require a hardware key, etc.
  • Implements MFA system-wide, regardless of individual application support
  • Provides standard SSO protocols for other applications that need them (what initially piqued my interest was SSO for SSH)

Based on the discussion there and some research of my own, I thought LemonLDAP::NG (LLNG) would be the solution with the broadest compatibility, so I've built a module for it.

LLNG (like, apparently, any SSO/IAM solution) is pretty complex to set up. This module will install the system, do basic configuration, and get LLNG talking to your OpenLDAP or Active Directory server, but from there, you'll be largely on your own. This guide will describe configuring Nextcloud to use LLNG for authentication, though, and may add other applications on a “best effort” basis.

Installation

Consult the README at the GitHub repo for more details: https://github.com/danb35/nethserver-lemonldap-ng

But in short,

  • Install my repo (if not already installed): yum install https://repo.familybrown.org/nethserver/7/noarch/nethserver-danb35-1.1.0-1.ns7.noarch.rpm
  • Create /etc/yum.repos.d/lemonldap-ng.repo with these contents:
[lemonldap-ng]
name=LemonLDAP::NG packages
baseurl=https://lemonldap-ng.org/redhat/stable/$releasever/noarch
enabled=1
gpgcheck=1
gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-OW2

[lemonldap-ng-extras]
name=LemonLDAP::NG extra packages
baseurl=https://lemonldap-ng.org/redhat/extras/$releasever
enabled=1
gpgcheck=1
gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-OW2
  • Download the LLNG GPG signing key: curl https://lemonldap-ng.org/_media/rpm-gpg-key-ow2 > /etc/pki/rpm-gpg/RPM-GPG-KEY-OW2
  • Install: yum install nethserver-lemonldap-ng --enablerepo=lemonldap-ng,lemonldap-ng-extras

Post-installation

This module creates two new virtual hosts on your Neth server, though they won't appear in the GUI server manager. By default, the authentication portal is at auth.yourdomain, and the management backend is at manager.yourdomain (you can change these names if desired; see the README for more details). Make sure you have DNS records for these hostnames that resolve appropriately.

For security reasons, and to avoid certificate errors, you'll need a TLS certificate covering those names. The simplest way to do this is to add those names to your default system certificate. In the (Cockpit) server manager, go to System → Certificates, and click on Let's Encrypt certificate. In the window that comes up, all the hostnames from your last cert should be listed; to them, add the names above.

For a default configuration, once installed, run /root/lemon_config.sh. For more advanced configuration, consult the GitHub repo.

Once that configuration is complete, you should be able to log in to the portal (auth.yourdomain) with any user on your server. Access to the manager (manager.yourdomain) will be available to any member of the “domain admins” group if you're using Active Directory, or to the “admin” user if you're using LDAP.

Application Configuration

This section will discuss using LLNG to authenticate for a variety of applications, broken down by authentication method.

These applications are configured using OpenID Connect (OIDC)

Introduction

Proxmox VE supports authentication via OIDC beginning with the 7.0 release. Configuration will be described below.

LLNG Configuration

If you haven't already done so, you'll need to enable the OIDC service, as described at the first three bullets below. If the service is already activated, skip to the fourth bullet below.

  • Enable the OIDC Service. General Parameters, Issuer modules, OpenID Connect
    • Activation → On
  • Set the issuer identifier. OpenID Connect Service, Issuer identifier
    • The URL for your portal. By default, this will be https://auth.yourdomain
  • Generate keys. OpenID Connect Service, Security, Keys
    • Click “New keys” at the top
  • Add a “relying party”. Click on OpenID Connect Relying Parties, then on Add OpenID Relying Party
    • Give a name, e.g., Proxmox VE.
    • Expand the new entry for Proxmox VE and click on Options, Basic
    • Client ID and Client secret should be random alphanumeric strings. One simple way to generate them is openssl rand -hex 16. Keep records of these, as you'll need them to configure Proxmox.
    • Allowed redirection addresses set to the full URL of your Proxmox VE host. If you have more than one host (i.e., if you have a cluster), add the URLs of all your hosts, separated by spaces.
    • Under Security, set ID token signature algorithm → RS256
  • Save your work

Proxmox VE configuration

Log in to your Proxmox VE instance.

  • On the left column, click on the Datacenter view, then Permissions in the next column, then Authentication.
  • Click Add, then OpenID Connect Server
  • In the window that pops up, you'll enter the following configuration items:
    • For Issuer URL, enter the URL for your authentication portal. By default, this will be https://auth.yourdomain.
    • For Realm, enter a name for the authentication realm–you can use LLNG.
    • For Client ID and Client Key, enter the client ID and client secret generated above.
    • Set Username Claim to subject.
    • Enter a comment if desired
    • Click Add.

Now you'll need to create a user in the LLNG realm, that will be able to authenticate this way. And before doing that, let's create a group for system administrators, and give that group administrative permissions.

  • On the left column, click on the Datacenter view, then Permissions in the next column, then Groups.
    • Click Create, enter the group name of admin, and any comment you may like.
  • Next, from the shell, run pveum acl modify / -group admin -role Administrator to give members of that group administrative permissions.

Now let's create the actual user.

  • On the left column, click on the Datacenter view, then Permissions in the next column, then Users.
    • Click Add
    • Enter the desired username–this must be a user that exists on your Neth server.
    • Set the realm to LLNG
    • Set the group to admin
    • Enter name, email, and comment if desired
    • Click Add

And now you're done. Log out of the Proxmox web GUI, and at the login screen, set the Realm to LLNG. Then click the Login (OpenID redirect) button. Your authentication portal will be opened in a new tab or window. Log in as the username you added above, give consent, and you'll be returned to the Proxmox web GUI. The first time you log in as this user, you may need to log in twice.

Introduction

This section describes configuration of LLNG as an OpenID Connect (OIDC) provider for a Smallstep-based local certificate authority, to sign SSH certificates for authentication of users (SSH host certificates are a different animal, and are discussed on this wiki page–you should also refer to this page for instructions on configuring your hosts to use SSH user certificates). It should also be a useful example for setting up LLNG as an OIDC provider for other applications.

SSH Certificates are probably overkill for a SOHO environment, and certainly for me at home, but they're what first got me interested in running a SSO system on Nethserver

Prerequisites and references

You'll need to have a local Smallstep certificate authority running. If you have an existing Smallstep CA that isn't configured to generate SSH certificates, see this wiki page for notes on adding this capability.

This guide also assumes you've installed LLNG following the instructions above, and either run the lemon_config.sh script, or manually configured it to authenticate against whatever users backend you're wanting to use.

This guide is heavily based on https://smallstep.com/blog/use-ssh-certificates/ and https://smallstep.com/blog/diy-single-sign-on-for-ssh/, but naturally substitutes your LLNG installation for Google in the latter case. It also uses https://lemonldap-ng.org/documentation/latest/applications/bigbluebutton.html as an example application using OIDC authentication.

LLNG configuration

You'd follow these instructions to set up any “relying party,” or application that you're going to allow to authenticate using OIDC. To add a second or further relying party, skip to the bullet for 'Add a “relying party”'.

  • Enable the OIDC Service. General Parameters, Issuer modules, OpenID Connect
    • Activation → On
  • Set the issuer identifier. OpenID Connect Service, Issuer identifier
    • The URL for your portal. By default, this will be https://auth.yourdomain
  • Generate keys. OpenID Connect Service, Security, Keys
    • Click “New keys” at the top
  • Add a “relying party”. Click on OpenID Connect Relying Parties, then on Add OpenID Relying Party
    • Give a name, all lower-case alphanumeric w/ hyphens if desired. e.g., rp-ssh.
    • Expand the new entry for rp-ssh and click on Options, Basic
    • Client ID and Client secret should be random alphanumeric strings. One simple way to generate them is openssl rand -hex 16. Keep records of these, as you'll need them to configure your CA.
    • Allowed redirection addresses set to http://127.0.0.1:10000
    • Under Advanced, set force claims to be returned in ID Token → On
    • Under Security, set ID token signature algorithm → RS256
  • Save your work

Smallstep CA configuration

Assuming your CA is already issuing SSH certificates, the only thing you need to add to it is the configuration to authenticate you via OpenID Connect. To do this, you'll need to add the OIDC provisioner pointing to your LLNG installation. Make appropriate substitutions for your domain, and client ID and secret, in the command below:

step ca provisioner add LLNG --type oidc --ca-config /etc/step-ca/config/ca.json \
  --client-id (your client ID) \
  --client-secret (your client secret) \
  --configuration-endpoint https://auth.yourdomain/.well-known/openid-configuration \
  --domain yourdomain --admin admin@yourdomain --ssh --listen-address :10000

The admin user you specify here will be able to generate certificates for any user; any other user will only be able to generate certificates for his/her own username. You can specify multiple admin users and domains if you like, with multiple invocations of --admin and --domain, respectively.

Then restart the CA with systemctl restart step-ca.

If you haven't made a note of the fingerprint of your CA's root signing key, now would also be a good time to do that. Run step certificate fingerprint /etc/step-ca/certs/root_ca.crt and make a note of the output.

Client configuration

You'll need to install the step-cli utility on your client systems; do this following the Smallstep docs. Then set up your client to use your CA and trust its root certificate by running step ca bootstrap --install --ca-url <ca.hostname> --fingerprint <root_certificate_fingerprint>

Usage

Before using SSH to connect to a host, you'll first need to run step ssh login <username>. You'll be asked which provisioner to use; select LLNG (OIDC). Your web browser will then open to the LLNG authentication portal. The first time you log in, you'll be asked if you agree to sharing username and email with SSH; agree to this. You'll then see a Success page, and your certificate will be issued.

Now, simply ssh to your desired host as the username you used above, and you should be authenticated.

If you're going to need to ssh as multiple users regularly (e.g., as fred to one system and barney to another), you can request a user certificate with multiple principals. To do this, you'd use the step ssh certificate command with both names: step ssh certificate fred@example.com fred -n fred -n barney. In this example, fred@example.com is the identity on the certificate. The first fred is the certificate file name, and the -n fred and -n barney identify the principals on the certificate. In order to obtain this certificate, you'll need to authenticate to LLNG as an admin user that you specified above.

When you use the step ssh certificate command, step will write the certificate to disk. The next time you run that command, it will ask for permission to overwrite the cert, which you can bypass by adding –force to the command. Also, because it's writing the key to disk, it will ask for a password for the key. To bypass that, you can add –insecure –no-password to the command. If you don't want to have to choose the provisioner each time you obtain a cert, you can specify it at the command line by adding –provisioner=LLNG to the command line.

But at this point, you have a pretty unwieldy command line: step ssh certificate fred@example.com fred -n fred -n barney –force –insecure –no-password –provisioner=LLNG. To avoid having to type this every time you want a certificate, you can set up an alias in your shell.

Applications in this section are configured to authenticate using SAML2

Now we’re going to configure Nextcloud to authenticate to LemonLDAP::NG. This follows the LLNG docs pretty closely.

WARNING

Do not follow these instructions on a Nextcloud installation with existing data. The standard Nethserver configuration of Nextcloud identifies users by their UUIDs, and creates directories based on them. These instructions will result in users identified by their usernames, who will not be able to see data they previously uploaded to the server.

  • First, in the LLNG Manager (manager.yourdomain), enable the SAML 2.0 issuer module. In the left gutter, expand General Parameters, Issuer modules, SAML, then click on Activation. Set to On.
  • Back in the left gutter, expand SAML2 Service, then Security parameters, then click on Signature. Click the New certificate link near the top of the page. Copy the certificate from the Public Key field on this page.
  • Now, in Nextcloud, add/enable the SSO & SAML authentication app.
  • Still in Nextcloud, go to User management: image|154x402 Find any users you want to have admin privileges in Nextcloud, and add them to the admin group. Make sure you add at least one. It will look like this: image|690x53
  • Still in Nextcloud, logged in as admin , go to the Settings page, then to SSO & SAML authentication. Click the button to use the built-in SAML authentication. Enter the parameters.
    • In the first field under General (with the default text of Attribute to map the UID to ), enter uid
    • Under Identity Provider Data, in the first field, enter https://auth.yourdomain/saml/metadata
    • In the second field, enter https://auth.yourdomain/saml/singleSignOn .
    • Expand the optional Identity Provider settings
    • In the third field, enter https://auth.yourdomain/saml/singleLogout
    • Ignore the fourth field
    • In the fifth field, paste the certificate you copied above.
    • Download the metadata XML file to a convenient location.
    • Note the warning at the top of the page–this will lose access to the built-in Nextcloud admin user unless you browse directly to https://$nextcloud_URL/index.php/login?direct=1. But since you added another user to the admin group above, you'll have administrative access using that user's credentials.
  • Back to the LLNG Manager. In the left gutter, click on SAML Service Providers, then click Add SAML SP at the top. Give it a descriptive name (like “Nextcloud”) and click OK.
  • Below SAML Service Providers, expand the new entry for Nextcloud, and click on Metadata . Upload the file you downloaded from Nextcloud (should be named metadata.xml ), or paste in its contents.
  • Back in the left gutter, below Metadata, click on Exported attributes. At the top, click on Add attribute, and add two attributes. For the first, both the Variable name and Attribute name should be cn; for the second, they should both be uid.
  • Back in the left gutter, two lines down, expand Options, then click on Signature. Set both Check SSO message signature and Check SLO message signature to Off.
  • Save your work.

Test

Browse to your Nextcloud URL. You’ll be directed to the LLNG authentication portal. Enter a user’s uid/password there and log in, whereupon you’ll be directed back to Nextcloud and logged in as that user.

Notes

  • This logs the user in as his username, rather than the UUID that’s normally used internally with Nextcloud when it’s authenticating to Nethserver’s OpenLDAP. I expect this could be addressed by changing the Exported attributes above, perhaps exporting entryUUID as uid –though I have to say, I like the users’ directories to have their usernames rather than UUIDs. But obviously this would be disruptive if done on a system with existing users.

TODO

  • Figure out the attribute mapping for the UUID
  • Get Nextcloud to sign the SSO/SLO messages–seems this would have to increase security
  • YubiKey authentication, of course. Yes, I know Nextcloud supports that internally, but I’m using it as a sample app here.

Education Perfect is a Home Learning WebApp for Years 5 – 12.

Instructions

EPSSO1

EPSSO2

  • Below SAML Service Providers , expand the new entry for Educationperfect , and click on Metadata . In the Load from URL : box enter the URL for “Issuer” that you receive from Intergrations team and click Load

EP Metadata

  • Back in the left gutter, below Options , click on Authentication Response . Select EMAIL in the dropdown box for Default NameID format

Authentication Response

  • Back in the left gutter, below Options , click on Security . Under Encryption mode select Name ID from the dropdown box

Encryption Mode Settings

  • Back in the left gutter, below Options , click on Security . Make sure Enable use of IDP initiated URL is enabled
  • Back in the left gutter, below Metadata , click on Exported attributes . At the top, click on Add attribute , and add 1 attribute. In the attribute box both the Variable name and Attribute name should be emailAddress

Metadata settings

  • Back in the left gutter, two lines down, expand Options , then click on Signature . Set both Check SSO message signature and Check SLO message signature to Off .

Signature Settings

  • Save your work.

Wordpress.

Instructions

Step 1.

Install the OneLogin SAML SSO Plugin on wordpress activate but don’t enable saml authentication yet in the plugin

Step 2.

Over in the lemonldap manager follow the same instructions i gave above for Education Perfect

adding https://wordpress.yourdomain/wp-login.php?saml_metadata for the metadata url. under General Parameters - Authentication Parameters - LDAP Parameters - Exported variables add New Entry: Key=Groups values=member

Save and ignore any errors

Step 3.

Enter the following info in the plugin in Wordpress
Change Single Log Out Service Url = https://auth.yourdomain/saml/singleLogout

Step 5.

Enable the following in options
  • Create user if not exists
  • Update user data
  • Force SAML login
  • set Match Wordpress account by to Username

ATTRIBUTE MAPPING

Username = uid
E-mail = mail
Nickname = cn
Role = groups

CUSTOMIZE ACTIONS AND LINKS
enable the following:

Prevent reset password
Prevent change password
Prevent change mail

ADVANCED SETTINGS
Encrypt nameID
Sign AuthnRequest
Sign LogoutRequest
Sign LogoutResponse
Reject Unsigned Messages
Retrieve Parameters From Server
set NameIDFormat to urn:oasis:names:tc:SAML:1.1:nameid-format:windows
in requestedAuthnContext select the last three ie urn:oasis:names:tc:SAML:2.0:ac:classes:password
under Service Provider X.509 Certificate and Service Provider Private Key enter the certs from signature in saml settings in lemonldap manager.

Zammad is a helpdesk/ticketing web app.

Instructions

Simply click the gear in bottom left then go to security and select third party applications enable Automatic account link on initial logon

then enable saml

settings are
IDP SSO Target URL=https://auth.yourdomain/saml/singleSignOn
IDP Certificate= the public cert under signature in lldapmanager
leave the next field blank
Name Identifier Format=urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress

In the manager create the sp
for metadata url https://zammad.yourdomain/auth/saml/metadata and load
under exported attributes see bellow

zammadexportattr

Under Authenticated Response chose email
and make the following changes under ldap exported attributes

ldapexported

obviously some of the attributes dont apply yet to the current config(im working on mapping other attributes).

  • userguide/llng.1634013134.txt.gz
  • Last modified: 2021/10/12 04:32
  • by Shane Treweek