pam-onelogin

What is it ?

pam-onelogin is a pretty complete pam/nss stack for using OneLogin as authentication source (with MFA) and user/group lookups.

It consists of the following parts,

• a standalone binary which fetches and caches users and groups
• a standalone nss-library which handles user/group lookups
• a standalone pam-library which handles authentication from the pam-stack.

The idea is simple and the goal is to have OneLogin as authentication source, as well as users/group information.

You simply specify a required onelogin-role that the users must have to gain access to the system (primarily via SSH). Only users that has that required role in OneLogin will be able to access the system, the role will also be 'translated' into standard Linux group (ie. users that has the role example-role in oneLogin, will belong to a Linux group called example-role).

Users do not need to exist on the system since they will be created dynamically when running the onelogin-mkcache-binary. Users and group information will then be fetched from OneLogin and cached locally. This information is then used when looking up users and groups through the onelogin-nss-library.

When an authentication attempt is being made, the users is looked up from cache, and if found, the user is the asked to authenticate with password and OTP.

⚠️ NOTE ⚠️

• This should only be used as proof-of-concept - you have been warned.

Why ?

Well the reason is quite simple,

• If you have an organization that uses OneLogin for user and group administration and you want to utilize this on servers, you can simply use this pam/nss-stack. This gives you the benefit of moving the administration for user, groups and access from your servers to OneLogin.

💻 How do I use it ?

Prerequisites

• A working OneLogin organization
• OneLogin API-keys
• A standard Linux distro with gcc, curl-devel and pam-devel libraries available.
  • Tested configuration on CentOS 7, 8 and 9.

Note

You need two OneLogin keys.

• One API-key with the "read all" permission
• One API key with the "authentication only" permission

For some reason there is no API-permission that grants you both "read all" and "authentication only", except the permissions "Manage users" and "Manage all", which both gives you permission to delete users, which you probably don't want.

You can read more about the API permissions here. If you however decide to use one API-key (that has "Manage users/ Manage all" permission), you can just configure pam-onelogin (onelogin_client_read_id/secret, onelogin_client_auth_id/secret) to use the same API-key (although I don't recommend it).

Installation

While this has only been tested on CentOS 7 / 8 / 9, it should work on any modern distribution. It only has two "external" requirements,

• pam-devel
• libcurl-devel

CentOS 7 / 8 / 9

This is literally a copy and paste from a clean install of CentOS 9.

1. Install dependencies and compile pam-onelogin
2. Edit config and create cache
3. Add onelogin to nsswitch and verify user / group lookup
4. Add pam_onelogin.so to SSH
5. Configure SSH and SELinux

Install dependencies and compile pam-onelogin

# Get dependencies and clone repo
$ > sudo [ dnf | yum ] install git gcc libcurl-devel make pam-devel
$ > git clone https://github.com/patchon/pam-onelogin
$ > cd pam-onelogin

# Compile and copy libraries and binary into correct path's
$ > sudo make install

Edit config and create cache

# Edit configuration-file
$ > sudo vim /etc/pam-onelogin/pam_onelogin.yaml

# You *must* specifically set the following parameters,
# * onelogin_client_read_id
# * onelogin_client_read_secret
# * onelogin_client_auth_only_id
# * onelogin_client_auth_only_secret
# * onelogin_region
# * onelogin_subdomain
# * onelogin_user_domain_append
# * onelogin_user_roles

# Once these parameters are set, run the onelogin-mkcache-binary
$ > sudo onelogin-mkcache

# If no errors occured you should be good to go, you can verify that the cache
# has been generated by looking at the 'cache-files'.
#
# In the example below, jane.doe and uncle.tom both has a onelogin-role called
# 'sysadmins'. Jane Doe also has a onelogin-role called 'developers'. Both
# these roles has been added to the 'onelogin_user_roles' parameter in the
# pam_onelogin.yaml

$ > cat /etc/pam-onelogin/.cache_passwd
 jane.doe::12345678:12345678:jane.doe@example-domain.org:/home/jane.doe:/bin/bash
 uncle.tom::87654321:87654321:uncle.tom@example-domain.org:/home/uncle.tom:/bin/bash

$ > cat /etc/pam-onelogin/.cache_group
 jane.doe:x:12345678:
 uncle.tom:x:87654321:
 sysadmins:x:12345:jane.doe,uncle.tom
 developers:x:54321:jane.doe

Note

For a detailed description for each option, have a look at pam_onelogin.yaml

Add onelogin to nsswitch and verify user / group lookup

# Add onelogin to nsswitch
$ > sudo vim /etc/nsswitch.conf
                                  ⤹ Add 'onelogin' to passwd and group
 passwd:     sss files systemd onelogin
 group:      sss files systemd onelogin

# At this point you should be able to verify user lookup
$ > id jane.doe
 uid=12345678(jane.doe) gid=12345678(jane.doe) groups=12345678(jane.doe),12345(sysadmis),54321(developers)

# And same for group lookups
$ > groups jane.doe
 jane.doe : jane.doe sysadmins developers

Add pam_onelogin.so to SSH

# Add pam_onelogin.so to the pam-config for SSH
$ > sudo vim /etc/pam.d/sshd
                                           # Add the following row
 auth       sufficient   pam_onelogin.so  ⤶
 auth       substack     password-auth
 auth       include      postlogin
 account    required     pam_sepermit.so

Note

Adding this row first in your pam stack, in the authentication section, means that, if the onelogin-pam-module succeeds, no other pam-modules will be tried. If that is not what you want, you have to configure your pam accordingly.

Configure SSH and SELinux

# Enable ChallengeResponseAuthentication for SSH
$ > sudo sed -i 's/ChallengeResponseAuthentication no/ChallengeResponseAuthentication yes/' /etc/ssh/sshd_config.d/50-redhat.conf

# Allow SSH daemon to connect to your onelogin server (denied default by SELinux)
$ > sudo setsebool -P authlogin_yubikey 1

# Restart SSHd
$ > sudo systemctl restart sshd

# Enable autocreation of home directory,
$ > sudo [ dnf | yum ] install oddjob-mkhomedir
$ > sudo systemctl --now enable oddjobd
$ > sudo vim /etc/pam.d/password-auth

session     optional                                     pam_keyinit.so revoke
session     required                                     pam_limits.so
-session    optional                                     pam_systemd.so
                                                                                  # Add the following row
session     optional                                     pam_oddjob_mkhomedir.so ⤶
session     [success=1 default=ignore]                   pam_succeed_if.so service in crond quiet use_uid
session     required                                     pam_unix.so
session     optional                                     pam_sss.so

Note

For CentOS 7 / 8 the SSH configuration file is '/etc/ssh/sshd_config'

At this point, your users should be able to use their OneLogin usernames for authenticating to your server.

⚠️ Caveats

This is a proof of concept and the author does not take any responsibility for what may happen if you decide to use it.

A few other warnings,

• I'm no developer, not in C, nor in any other language, hence the code certainly contains quite a few bugs and might not be the most beautiful thing you've looked at. Please don't judge.

• The configuration file for pam-onelogin is readable by everyone that has access to the system.

• Using the option 'auto_add_group_to_user' with the group 'wheel' makes the users members of the group 'wheel', however, if you intend to let the users run sudo, you either need to enable "passwordless sudo for wheel", or update the pam-stack for sudo and include the 'pam_onelogin.so' module (this however means that you require two factor auth everytime someone does 'sudo', which may not be what you want).

• Enabling the 'log_stdout' option can lead to weird side-effects for all users - only use this when debugging.

• When authentication is being made against OneLogin, both password and OTP is required. One could argue (even though it's not implemented at the moment) that you never want to enter your OneLogin password anywhere else than to OneLogin.com website. This would mean that you only would have to enter the OTP when accessing a server and no password. Option to disable password verification has been added.

With that being said, it seems to work as expected in my testing environment.

🔨 Todo's

• Major cleanup (in all regards).
• More dynamic allocations instead of all those static buffers that are used everywhere.
• Make onelogin-mkcache a daemon so it can sync users / groups at configured interval, also create systemd service for it.
• Make an option for not verifying user password and only ask for OTP.
• Make the '/etc/pam-onelogin/pam_onelogin.yaml' only readable by root and redesign the pam_module so it somehow can get the API credentials, without being root.
• Make the 'auto_add_group_to_user'-option configurable so it can accept different additional groups depending on which role you may have. Today it only accepts one group, and all users that have any of the Onelogin-roles will get this additional group.
• The delimiter for the username is hardcoded to '@' at the moment. We should make this configurable (not sure if everyone has @ in their OneLogin usernames)
• Make integration against Active Directory group membership, if your OneLogin is backed by it
• Package everything into an RPM.

™️ Trademarks

• OneLogin® is a trademark owned by One Identity LLC and is not affiliated with this repository in any way. Logo is based on the font Metropolis and inspired by the design of adrlyx.
• Linux® is the registered trademark of Linus Torvalds in the U.S. and other countries.