TrainingSupportCommunity

MFA Unix PAM

Suggest Edits

You can use the ​Akamai MFA​ Pluggable Authentication Module (PAM) to enhance the security of your Unix and Linux logins. PAM provides you with a modular system with which you can configure authentication mechanisms for different applications. By installing the ​Akamai MFA​ libpam_akamaimfaPAM, you enable a two-step authentication for remote (SSH) access apps or local logins for Unix-based systems.

See this diagram that presents a conceptual model of the authentication process. For clarity reasons, some traffic flows are not covered.

📘

This authentication process refers to users who are enrolled in ​Akamai MFA​.

  1. The user authenticates to the Unix server using, for example, their username/password or private/public key pair.

  2. Upon successful authentication, the Unix server, using the ​Akamai​ plug-in, establishes a connection over TCP port 443 and redirects the user to ​Akamai MFA​.

  3. ​Akamai MFA​ challenges the user with secondary authentication.

  4. The user confirms their identity using the selected secondary authentication method.

  5. ​Akamai MFA​ redirects the user to the Unix server.

  6. The Unix server allows the user to proceed to the protected application.

ag-unix-diagram

Prerequisites

  • This integration communicates with ​Akamai MFA​ on TCP port 443. If your firewall blocks outbound traffic to the ​Akamai MFA​ service using, for example, rules based on IP address ranges, it may impact the service's availability.

  • To enable this integration for users, ensure that user accounts exist on the Linux-based OS server and in ​Akamai MFA​ under the same user ID. Also, make sure that the users are enrolled in ​Akamai MFA​ and their registered mobile devices have been activated.

  • You have to copy the libpam_akamaimfa to the Linux server.

  • For OS with SELinux, you have to first disable SELinux before deploying the pam_akamai_mfamodule.

  • Prior to the installation of the plugin, ensure that your server is correctly synchronized with an internet time source. Otherwise, you may be presented with a time-based error when attempting to use ​Akamai MFA​.

  • Before you can use the plugin, you need to install OpenSSL 1.1 on your system and ensure thatlibssl.so.1.1 is present in the /lib/security/ directory.

📘

This Unix PAM module has been tested on Linux (RedHat, CentOS, Debian, Ubuntu).

This integration supports only OpenSSH 6.2+, SSH protocol 2.

Add SSH integration

Follow this procedure to generate your integration credentials that you will need to provide in the following step to enable the communication between ​Akamai MFA​ and SSH server.

Next, follow the integration instructions for your Linux distribution.

  1. In the Enterprise Center navigation menu, select Multi-factor Authentication > Integrations.

  2. Click Add integration (+).

  3. In Integration Type, select SSH.

  4. In Name, enter a unique name for your SSH integration.

  5. Click Save and Deploy.
    You’ve just generated your API Host, Integration ID, and Signing Key. This data will be available for you on the integration page. Your integration credentials can be copied anytime and used in the following steps to configure the integration.

📘

Your Signing Key should be kept completely secret like any other password or secret key credential.

Follow instructions for one of the supported Linux distributions.

Integration instructions for CentOS distribution

Install libpam_akamaimfaprerequisites and pam_akamai_mfa

Follow these steps to install the OpenSSL development headers and libraries that are required to enable this integration.

  1. Download the following installation package and extract its contents:

  2. Launch the terminal as super user.

  3. Execute these commands according to the respective platform. You may need the root-level access to execute those commands.

    • For CentOS, execute yum install autoconf libtool pam-devel openssl-devel
    • For CentOS with SELinux enabled, execute yum install selinux-policy-devel

  4. When the installation completes, check if /etc/security/akamaimfa-config.tomlfile exists in your directory. If the file is not present, create it and edit the /etc/security/akamaimfa-config.tomlfile by entering the integration credentials that you generated in the previous step.

    [config]

signing_key = "<signing_key>"

app_uuid = "<integration_id>"

host = "<api_host domain with https://prefix>"

log_path = "<full_path_to_your_log_file>"

  5. Save and exit the file.

  6. Before using pam_akamai_mfa, make sure the logging file exists and has the necessary permission i.e. chmod 640 <log-file-name>. The logging file depends on the log_pathspecified in akamaimfa-config.toml. If it's left empty, it defaults to /var/log/akamaimfa.log.

📘

The chmod 640 <log-file-name> permission means that the owner has read and write permissions, and any other user has no rights to the file.

Configure ​Akamai MFA​ linux-based OS PAM

Enable public key authentication

If you want to use pam_akamai_mfawith SSH public key authentication, follow these steps:

  1. Open the sshd_configfile in the text editor. This file is usually located in /etcor /etc/ssh.

  2. Edit your sshd_configfile to enable the SSH public key authentication for the ​Akamai MFA​ libpam_akamaimfa:

    • Set PubkeyAuthenticationto yes

    • Set PasswordAuthenticationto no

    • Add this line to the file: AuthenticationMethods publickey,keyboard-interactive
      See how the updated properties should display in your terminal:
      pub-key-auth

📘

When you're introducing changes to your PAM configuration, leave a root shell open. This will prevent you from accidentally locking yourself out.

Enable OpenSSH authentication

If you want to use pam_akamai_mfawith the OpenSSH ssd, follow these steps.

📘

This integration supports only OpenSSH 6.2+, SSH protocol 2.

  1. Edit your sshd_configfile to enable the OpenSSH sshd that is usually located in /etc or /etc/ssh. This enables the sshd process for the ​Akamai MFA​ libpam_akamaimfaPAM:

    • Set UsePAMto yes

    • Set ChallengeResponseAuthenticationto yes

    • Remove comment sign and set UseDNSto no.

📘

When you're introducing changes to your PAM configuration, leave a root shell open. This will prevent you from accidentally locking yourself out.

  1. Save and exit the sshd_configfile.

  2. Restart the ssh service once you finish the configuration so that all the changes you've made to sshdand sshd_config files take effect.

Modify your PAM configuration

Follow these steps to edit your system's PAM configuration to enable ​Akamai MFA​ as the authentication system. Depending on your CentOS distribution, follow these instructions.

📘

If the libpam_akamaimfa.somodule is located in/lib64/security directory (instead of in /lib/security), enter the full path to the module in the PAM configuration file: /lib64/security/libpam_akamaimfa.so. I.e. auth sufficient /lib64/security/libpam_akamaimfa.so

CentOS 5

For SSH public key authentication, edit the sshdfile located in /etc/pam.d/sshd:

  1. Comment out #auth include system-auth and add the following configuration parameters:

    auth  required pam_env.so
auth  sufficient libpam_akamaimfa.so
auth  required pam_deny.so

  2. Save and exit the sshd file.

  3. Restart the ssh service.

For system-wide authentication, edit the system-auth file located in /etc/pam.d/system-auth:

  1. Comment out #auth sufficient pam_unix.so nullok try_first_pass and add the following configuration parameters:
    auth  requisite pam_unix.so nullok try_first_pass
auth  sufficient libpam_akamaimfa.so
  2. Save and exit the system-auth file.
  3. Restart the ssh service.

For SUDO MFA, edit the sudo file located in /etc/pam.d/sudo:

  1. Comment out #auth include system-auth and add the following configuration parameter:
    auth  required libpam_akamaimfa.so
  2. Save and exit the sudo file.

CentOS 6

For SSH public key authentication, edit the sshd file located in /etc/pam.d/sshd:

  1. Comment out #auth include password-auth and add the following configuration parameters:

    auth  required pam_env.so
auth  sufficient libpam_akamaimfa.so
auth  required pam_deny.so

  2. Save and exit the sshd file.

  3. Restart the ssh service.

For system-wide authentication, edit the system-auth file located in /etc/pam.d/system-auth:

  1. Comment out # auth sufficient pam_unix.so nullok try_first_pass and add the following
    configuration parameters:

    auth  requisite pam_unix.so nullok try_first_pass
auth  sufficient libpam_akamaimfa.so

  2. Save and exit the system-auth file.

  3. Restart the ssh service.

For SUDO MFA, edit the sudo file located in /etc/pam.d/sudo:

  1. Comment out #auth include system-auth and add the following configuration parameters:
    auth  required libpam_akamaimfa.so
  2. Save and exit the sudo file.

CentOS 7/8

For SSH public key authentication, edit the sshd file located in /etc/pam.d/sshd:

  1. Comment out #auth substack password-auth and add the following configuration parameters:
    auth  required pam_env.so
auth  sufficient libpam_akamaimfa.so
auth  required pam_deny.so
  2. Save and exit the sshd file.
  3. Restart the ssh service.

For system-wide authentication, edit the system-auth file located in /etc/pam.d/system-auth:

  1. Comment out #auth sufficient pam_unix.so nullok try_first_pass and add the following configuration parameters:
    auth  requisite pam_unix.so nullok try_first_pass
auth  sufficient libpam_akamaimfa.so
  2. Save and exit the system-auth file.
  3. Restart the ssh service.

For SUDO MFA, edit the sudo file in etc/pam.d/sudo.

  1. Comment out #auth include system-auth and add the following configuration parameters:
    auth required libpam_akamaimfa.so
  2. Save and exit the sudo file.

Integration instructions for Red Hat distribution

Install libpam_akamaimfa prerequisites and pam_akamai_mfa

Follow these steps to install the OpenSSL development headers and libraries that are required to enable this integration.

  1. Download the following installation package and extract its contents:

  2. Launch the terminal as super user.

  3. Execute the below commands according to the respective platform. You may need the root-level access to execute those commands.

    • For Red Hat, execute yum install autoconf libtool pam-devel openssl-devel
    • For Red Hat with SELinux enabled, execute yum install selinux-policy-devel

  4. When the installation completes, check if /etc/security/akamaimfa-config.toml file exists in your directory. If the file is not present, create it and edit the /etc/security/akamaimfa-config.toml file by entering the integration credentials that you generated in the previous step.

    [config]

signing_key = "<signing_key>"

app_uuid = "<integration_id>"

host = "<api_host domain with https://prefix>"

log_path = "<full_path_to_your_log_file>"

  5. Save and exit the file.

  6. Before using pam_akamai_mfa, make sure the logging file exists and has the necessary permission i.e. chmod 640 <log-file-name>. The logging file depends on the log_path specified in akamaimfa-config.toml. If it's left empty, it defaults to /var/log/akamaimfa.log.

📘

The chmod 640 <log-file-name> permission means that the owner has read and write permissions, and any other user has no rights to the file.

Configure ​Akamai MFA​ linux-based OS PAM

Enable public key authentication

If you want to use pam_akamai_mfa with SSH public key authentication, follow these steps:

  1. Open the sshd_config file in the text editor. This file is usually located in /etc or /etc/ssh.

  2. Edit your sshd_config file to enable the SSH public key authentication for the ​Akamai MFA​ libpam_akamaimfa:

    • Set PubkeyAuthentication to yes

    • Set PasswordAuthentication to no

    • Add this line to the file: AuthenticationMethods publickey,keyboard-interactive
      See how the updated properties should display in your terminal:
      pub-key-auth

📘

When you're introducing changes to your PAM configuration, leave a root shell open. This will prevent you from accidentally locking yourself out.

Enable OpenSSH authentication

If you want to use pam_akamai_mfawith the OpenSSH ssd, follow these steps.

📘

This integration supports only OpenSSH 6.2+, SSH protocol 2.

  1. Edit your sshd_config file to enable the OpenSSH sshd that is usually located in /etc or /etc/ssh. This enables the sshd process for the ​Akamai MFA​ libpam_akamaimfa PAM:

    • Set UsePAM to yes

    • Set ChallengeResponseAuthentication to yes

    • Remove comment sign and set UseDNS to no.

📘

When you're introducing changes to your PAM configuration, leave a root shell open. This will prevent you from accidentally locking yourself out.

  1. Save and exit the sshd_config file.

  2. Restart the ssh service once you finish the configuration so that all the changes you've made to sshd and sshd_config files take effect.

Modify your PAM configuration

Follow these steps to edit your system's PAM configuration to enable ​Akamai MFA​ MFA as the authentication system. Depending on your Red Hat Linux distribution, follow the below instructions.

📘

If the libpam_akamaimfa.somodule is located in /lib64/security directory (instead of in /lib/security), enter the full path to the module in the PAM configuration file: /lib64/security/libpam_akamaimfa.so. I.e. auth sufficient /lib64/security/libpam_akamaimfa.so.

Red Hat Enterprise Linux 5

For SSH public key authentication, edit the sshd file located in /etc/pam.d/sshd:

  1. Comment out #auth include system-auth and add the following configuration parameters:
    auth  required pam_env.so
auth  sufficient libpam_akamaimfa.so
auth  requisite pam_succeed_if.so uid >= 500 quiet
auth  required pam_deny.so
  2. Save and exit the sshd file.
  3. Restart the ssh service.

For system-wide authentication, edit the system-auth file located in /etc/pam.d/system-auth:

  1. Comment out # auth sufficient pam_unix.so nullok try_first_passand add the following configuration parameters:
    auth  requisite pam_unix.so nullok try_first_pass
auth  sufficient libpam_akamaimfa.so
  2. Save and exit the system-auth file.
  3. Restart the ssh service.

For SUDO MFA, edit the sudo file located in /etc/pam.d/sudo:

  1. Comment out #auth include system-auth and add the following configuration parameters:
    auth  required libpam_akamaimfa.so
  2. Save and exit the sudo file.

Red Hat Enterprise Linux 6

For SSH public key authentication, edit the sshd file located in /etc/pam.d/sshd:

  1. Comment out #auth include password-auth and add the following configuration parameters:
    auth  required pam_env.so
auth  sufficient libpam_akamaimfa.so
auth  required pam_deny.so
  2. Save and exit the sshd file.
  3. Restart the ssh service.

For system-wide authentication, edit the system-auth file located in /etc/pam.d/system-auth:

  1. Comment out #auth sufficient pam_unix.so nullok try_first_passand add the following configuration parameters:
    auth  requisite pam_unix.so nullok try_first_pass
auth  sufficient libpam_akamaimfa.so
  2. Save and exit the system-auth file.
  3. Restart the ssh service.

For SUDO MFA, edit the sudo file located in /etc/pam.d/sudo:

  1. Comment out #auth include system-auth and add the following configuration parameters:
    auth  required libpam_akamaimfa.so
  2. Save and exit the sudo file.

Red Hat Enterprise Linux 7/8

For SSH public key authentication, edit the sshd file located in /etc/pam.d/sshd:

  1. Comment out #auth substack password-auth and add the following configuration parameters:
    auth  required pam_env.so
auth  sufficient libpam_akamaimfa.so
auth  requisite pam_succeed_if.so uid >= 1000 quiet
auth  required pam_deny.so
  2. Save and exit the sshd file.
  3. Restart the ssh service.

For system-wide authentication, edit the system-auth file located in /etc/pam.d/system-auth:

  1. Comment out #auth sufficient pam_unix.so nullok try_first_pass and add the following configuration parameters:
    auth  requisite pam_unix.so nullok try_first_pass
auth  sufficient libpam_akamaimfa.so
  2. Save and exit the system-auth file.
  3. Restart the ssh service.

For SUDO MFA, edit the sudo file located in /etc/pam.d/sudo:

  1. Comment out #auth include system-auth and add the following configuration parameters:
    auth  required libpam_akamaimfa.so
  2. Save and exit the sudo file.

Integration instructions for Ubuntu distribution

Install libpam_akamaimfaprerequisites and pam_akamai_mfa

Follow these steps to install the OpenSSL development headers and libraries that are required to enable this integration.

  1. Download the pam_akamaimfa_ubuntu.tar.gz package and extract its contents.

  2. Launch the terminal as super user.

  3. Execute the below commands according to the respective platform. You may need the root-level access to execute those commands.

    • For Debian and Ubuntu, execute apt-get install build-essential autoconf libtool libpam-dev libpam0g-dev libpam0g libssl-dev

  4. When the installation completes, check if /etc/security/akamaimfa-config.tomlfile exists in your directory. If the file is not present, create it and edit the /etc/security/akamaimfa-config.toml file by entering the integration credentials that you generated in the previous step.

    [config]

signing_key = "<signing_key>"

app_uuid = "<integration_id>"

host = "<api_host domain with https://prefix>"

log_path = "<full_path_to_your_log_file>"

  5. Save and exit the file.

  6. Before using pam_akamai_mfa, make sure the logging file exists and has the necessary permission i.e. chmod 640 <log-file-name>. The logging file depends on the log_pathspecified in akamaimfa-config.toml. If it's left empty, it defaults to /var/log/akamaimfa.log.

📘

The chmod 640 <log-file-name>permission means that the owner has read and write permissions, and any other user has no rights to the file.

Configure ​Akamai MFA​ linux-based OS PAM

Enable public key authentication

If you want to use pam_akamai_mfa with SSH public key authentication, follow the below steps:

  1. Open the sshd_config file in the text editor. This file is usually located in /etcor /etc/ssh.

  2. Edit your sshd_configfile to enable the SSH public key authentication for ​Akamai MFA​ libpam_akamaimfa:

    • Set PubkeyAuthentication to yes

    • Set PasswordAuthentication to no

    • Add this line to the file: AuthenticationMethods publickey,keyboard-interactive
      See how the updated properties should display in your terminal:
      pub-key-auth

📘

When you're introducing changes to your PAM configuration, leave a root shell open. This will prevent you from accidentally locking yourself out.

Enable OpenSSH authentication

If you want to use pam_akamai_mfawith the OpenSSH ssd, follow the below steps.

📘

This integration supports only OpenSSH 6.2+, SSH protocol 2.

  1. Edit your sshd_configfile to enable the OpenSSH sshd that is usually located in /etc or /etc/ssh. This enables the sshd process for the ​Akamai MFA​ libpam_akamaimfaPAM:

    • Set UsePAMto yes

    • Set ChallengeResponseAuthenticationto yes

    • Remove comment sign and set UseDNSto no.

📘

When you're introducing changes to your PAM configuration, leave a root shell open. This will prevent you from accidentally locking yourself out.

  1. Save and exit the sshd_config file.

  2. Restart the ssh service once you finish the configuration so that all the changes you've made to sshd and sshd_config files take effect.

Modify your PAM configuration

Follow these steps to edit your system's PAM configuration to enable ​Akamai MFA​ as the authentication system. Depending on your Ubuntu distribution, follow these instructions.

📘

If the libpam_akamaimfa.so module is located in /lib64/security directory (instead of in /lib/security), enter the full path to the module in the PAM configuration file: /lib64/security/libpam_akamaimfa.so. I.e. auth sufficient /lib64/security/libpam_akamaimfa.so

Ubuntu 14

For SSH public key authentication, edit the sshd file located in /etc/pam.d/sshd:

  1. Comment out #@include common-auth and add the following configuration parameters:
    auth  sufficient libpam_akamaimfa.so
auth  requisite pam_deny.so
auth  required pam_permit.so
auth  required pam_cap.so
  2. Save and exit the sshd file.
  3. Restart the ssh service.

For system-wide authentication, edit the common-auth file located in /etc/pam.d/common-auth:

  1. Comment out #auth [success=1 default=ignore] pam_unix.so nullok_secure and add the following configuration parameters:
    auth  requisite pam_unix.so nullok_secure
auth  sufficient libpam_akamaimfa.so
  2. Save and exit the common-auth file.
  3. Restart the ssh service.

For SUDO MFA, edit the sudo file located in /etc/pam.d/sudo:

  1. Comment out #@include common-auth and add the following configuration parameters:
    auth  required libpam_akamaimfa.so
  2. Save and exit the sudo file.

Ubuntu 16/18/20

For SSH public key authentication, edit the sshd file located in /etc/pam.d/sshd:

  1. Comment out #@include common-auth and add the following configuration parameters:
    auth  sufficient libpam_akamaimfa.so
auth  requisite pam_deny.so
auth  required pam_permit.so
  2. Save and exit the sshd file.
  3. Restart the ssh service.

For system-wide authentication, edit the common-auth file located in /etc/pam.d/common-auth:

  1. Comment out #auth [success=1 default=ignore] pam_unix.so nullok_secure and add the following configuration parameters:
    auth  requisite pam_unix.so nullok_secure
auth  sufficient libpam_akamaimfa.so
  2. Save and exit the common-auth file.
  3. Restart the ssh service.

For SUDO MFA, edit the sudo file located in /etc/pam.d/sudo:

  1. Comment out #@include common-auth and add the following configuration parameters:
    auth  required libpam_akamaimfa.so
  2. Save and exit the sudo file.

Updated 20 days ago