freeipa/doc/designs/ldap_pam_passthrough.md

IMPORTANT: This is a design proposal and is not implemented yet.

LDAP PAM Passthrough support

Overview

Many organizations have authentication mechanisms already in place. They may not want to have IPA be the central repository for authentication.

RADIUS is a common authentication protocol used for external authentication into existing systems. IPA currently has support for verifying credentails over RADIUS for Kerberos connections using the radius authentication indicator, but this does not work with LDAP authentication.

For this document "PAM Passthrough" is defined as any subsequent plugin that handles authentication of the user entry using the PAM stack.

Expected Workflow

There are a lot of components potentially involved in LDAP authentication over RADIUS:

• 389-ds
• PAM
• SSSD
• KDC
• ipa-otpd
• the remote RADIUS server

The workflow starts with an LDAP bind.

• On an LDAP BIND with uid=user,cn=users,cn=accounts,$SUFFIX, the BIND request will get processed by the IPA password plugin preop. If both radius and otp auth types are set and there are no tokens the plugin will return 0, allowing further authentication to happen. 389-ds treats this as no authentication decision so allows other plugins to try.

• At this point another 389-ds plugin can step in to handle the authentication using the PAM stack.

• As PAM authentication processing happens, if pam_sss.so is present in the PAM stack, it will attempt to perform password-based authentication for the 'user' account using the provided credentials.

• Since the user account matches the IPA domain, it will be treated as Kerberos authentication against IPA KDC running on the same host, as we are authenticating on a IPA server.

• The IPA KDB driver in the KDC will notice that the 'user@IPA' principal has the 'radius' pre-authentication method configured with TL data "otp\0[{"indicators": ["radius"]}]" meaning it should advertise the OTP pre-auth mechanism to the Kerberos client.

• The client (SSSD) notices the availability of the OTP pre-auth mechanism and uses host principal's TGT as its FAST channel wrapper to proceed with OTP pre-auth.

• OTP pre-auth mechanism will talk between KDC and the client to ask for additional details (OTP value) via prompting mechanism it has.

• The client (SSSD) will return the OTP value and the KDC then will issue a RADIUS request "Accept-Request" to a RADIUS server configured in the KDC configuration. The OTP value in this case is the credentials the user provided.

• ipa-otpd handles OTP requests and will connect to LDAP (the LDAP URI is passed as part of ipa-otpd@.service definition from /etc/ipa/default.conf, so it'll be an LDAPI access). ipa-otpd will parse the RADIUS packet and look up requested user principal entry from LDAP.

• If the user principal entry has the 'radius' authentication indicator configured (or it is default for IPA deployment) and there is a RADIUS proxy link in the user entry (there is no default so it must be set per user), it will send the same RADIUS packet to the RADIUS server configured as a proxy link with the credentials provided by KDC

• For a native OTP setup where the user has the 'otp' authentication indicator the process is about the same: instead of sending a RADIUS proxy request, ipa-otpd will bind to LDAP with the user DN and pass the credentials provided by KDC.

Existing Workaround

Due to the way passwords and OTP are handled by the current IPA password plugin it is possible to make this work today using the 389-ds password plugin but it is complicated to setup and prone to error.

• Install IPA

• Configure the 389-ds PAM pass-through plugin to a PAM service that relies on pam_sss.so (e.g. system-auth)

• Add a RADIUS proxy configuration in IPA

• Add this proxy to one or more users

• Set default authentication indicator in IPA to 'radius, otp' or on one or more of those users

• The user has no userPassword or krbPrincipalKey set

• The user has no OTP tokens

The key is having otp as an authentication indictor. If otp is not set as an authentication indicator then ipapwd_pre_bind_otp() will return 1 and fail the authentication request. By setting otp but having no tokens ipapwd_pre_bind_otp() will return 0. Next a password comparison will happen but since the user has no password this will be skipped and 0 returned to 389-ds as the result and then PAM passthrough plugin can be initiated.

Workaround confusion

Strictly speaking, a user can have this configuration and still have a userPassword and krbPrincipalKey set but this is a no-op for an LDAP bind. Regardless of whether the provided password is valid or not authentication will proceed to the RADIUS server for the final word.

This is similar behavior if a user tries a raw kinit without armor: there may be a password/key but it isn't used.

This could lead to "I can't log in" calls and an admin resetting their password in IPA with no real effect.

Why is otp required in the workaround?

This scheme works because RADIUS isn't considered at all in the password plugin.

In prepost.c::ipapwd_pre_bind_otp() the user is checked to see if they have OTP auth enabled. If they do then the tokens are examined and if there aren't any, the function exits in a way that allows subsequent authentication. This will then fall out and return a 0 to 389-ds to allow PAM Passthrough to execute.

If the user does not have OTP auth enabled then that code will be skipped and return a 1 because the auth_type is not OTP_CONFIG_AUTH_TYPE_PASSWORD.

Proposal

This proposal may break existing installations who have found this workaround.

Currently PAM passthrough authentication basically works by accident and by working around the lack of direct handling of RADIUS in the password plugin. It would be better, and more secure, to deal directly with this in the IPA password plugin and not rely on side-effects.

IPA Framework plugin changes:

For users with the RADIUS authentication indicator set:

1. Require no userPassword and krbPrincipalKey
2. Require a radius proxy server set
3. Do not allow the RADIUS authentication indicator along with others since the point of it is to outsource authentication.

These will not be enforced retroactivly on upgrade since LDAP bind using RADIUS was not supported.

IPA password plugin changes:

If the RADIUS authentication indicator is set on a user and the user has a userPassword or krbPrincipalKey and does not have a radius proxy setting (ipatokenradiusconfiglink) then return LDAP_INVALID_CREDENTIALS.

If the OTP authentication indicator is not set, in ipapwd_pre_bind_otp() return 0 if any authentication indicator is set.

Additionally, multiple mechanisms should be supported simultaneously so a user configured with PKINIT and RADIUS can authenticate using either. Currently only RADIUS will work. See https://pagure.io/freeipa/issue/8820 for more details. This should also work for an LDAP bind for consistency.

The workflow

• RADIUS will be evaluated first.

• If RADIUS authtype is set:

  • require no userPassword and krbPrincipalKey
  • require radius proxy setting

• If RADIUS is an authentication indicator for a user on a BIND request

  • If these conditions are not set then LOG_FATAL() and end the authentication attempt by returning LDAP_INVALID_CREDENTIALS.
  • Otherwise continue the authentication process.

• If RADIUS is not an authentication indicator then proceed with authentication.

• If OTP is an authentication indictorn or the user

  • Evaluate tokens using the existing workflow
  • Otherwise fall back to PASSWORD authentication

OTP checking is done in ipapwd_pre_bind_otp() which is called unless there is a sync request. Authentication indicator type handling needs to be better centralized here. There are two paths that can return different results (assuming otpreq = False).

1. User has otp auth type and has no tokens it will return 0.
2. User does not have otp auth type it will only return 0 if the user has OTP_CONFIG_AUTH_TYPE_PASSWORD.

This loophole needs to be closed. Perhaps change to return false if auth type is OTP_CONFIG_AUTH_TYPE_NONE. This would likely be more future-proof if more authentication indicators are added.

If the OTP check doesn't return an error then the password will be authenticted, if there is one. This is the two-step first check OTP, then check the password.

Since a 389-ds plugin returning 0 will allow subsequent authentication, for the case of RADIUS we need to enforce the no password(s) and RADIUS server requirements because with any PAM passthrough method enabled it becomes the defacto default method. In fact we may want to always ensure there is no RADIUS server defined if the RADIUS authentication indicator is not set to set. This would need to check both the global and per-use authentication indicators.

389-ds FATAL logging is recommended because the authentication path is so opaque that administrators won't know why or where it failed. This will ensure a useful message is logged, at least for the administrators.

It might be nice to check that PAM passthrough is enabled but there is is no way to validate the configuration so we may well skip it.

Testing

This creates quite a large test matrix as a number of different tests are required. These are only for LDAP binds. Kerberos should be unaffected.

• RADIUS authentication indicator set globally and the user is not configured properly

  • user has a password
  • user has a principal key
  • user has no radius proxy set

• RADIUS authentication indicator set for the user and the user is not configured properly

  • user has a password
  • user has a principal key
  • user has no radius proxy set

• RADIUS authentication indicator set globally and user is ok

  • test user with correct password
  • test user with incorrect password

• RADIUS authentication indicator set for the user and user is ok

  • test user with correct password
  • test user with incorrect password

Others depending on whether we will allow the RADIUS authentication indicator with others. If we restrict the authentication indicators to either be only RADIUS or anything but RADIUS this should not affect other mechanisms and will be covered by other tests. But this poses a problem with upgrades.

Setup using the 389-ds PAM Passthrough plugin

In order to test we'll need to setup a RADIUS server to test against. The pyrad project provides a sample in https://raw.githubusercontent.com/pyradius/pyrad/master/example

It would need to be adapted for our needs to actually do authentication and ideally dynamically setup its listening hosts. The passwords could be hardcoded with a "good" one that is always accepted.

And the ldapserver PAM service needs to be created and cleaned up. Making a copy of system-auth is sufficient.

To enable the PAM Passthrough plugin in 389-ds can be done with this ldif:

dn: cn=PAM Pass Through Auth,cn=plugins,cn=config changetype: modify replace: nsslapd-pluginEnabled nsslapd-pluginEnabled: on

replace: pamSecure pamSecure: FALSE

replace: pamService pamService: ldapserver

Followed by a restart of dirsrv.target.

The dsconf configuration for enabling/configuring Passthrough is currently not working in 389-ds.

Creating a RADIUS proxy server

Create a radius proxy named 'pyrad' pointing to the current server.

$ echo somesecret | ipa radiusproxy-add pyrad --server ipa.example.test --secret

Creating an appropriate user to test with

Create a user with the RADIUS authentication indicator and a radius proxy link.

$ ipa user-add --first=tim --last=user --radius pyrad --user-auth-type radius tuser

Executing the search

$ ldapsearch -x -w password -D "uid=tuser1,cn=users,cn=accounts,dc=example,dc=test" -b "cn=users,cn=accounts,dc=example,dc=test" uid=admin

The password here is the RADIUS password. In the case of pyrad it currently accepts anything.

Backup/Restore

There should be no impact for backup and restore as this only modifies the IPA password plugin and does not ship new files or configuration.

Upgrades

The additional enforcement of no userPassword/krbPrincipalKey and radius link for the RADIUS authentication indicator could cause issues for some users. We will need to be absolutely clear in error logging why authentication is failing, and document the change in a release note.

If we require that RADIUS be a standalone indicator that could also pose upgrade problems.