Add optional OTP (2FA) access

OTP_ACCESS=true requires a time based one time password on top of the ssh
key, or on top of the password when PASSWORD_ACCESS is enabled as well.
The secret lives in /config so it survives a container recreation, and
until it exists the user is let in on the key alone, which is what makes
the initial enrollment possible.

Two details of this image shape the PAM stack. The module answers
PAM_IGNORE rather than PAM_SUCCESS when nullok applies, and a stack whose
only module is ignored has nothing that succeeded, so an explicit action
list runs it and a trailing pam_permit carries the login; a wrong code
hits default=die before reaching it. And sshd runs as the ssh user here,
so it cannot read /etc/shadow, which the stock account and session checks
need. Those are left out rather than inherited: without OTP this image
does not enable PAM at all, so none of them run today either.

The sshd_config block is delimited by markers and rebuilt on every start,
so removing the variable cleans the persisted config back up.

Closes #121

Author: SckyzO

Dockerfile

@@ -12,6 +12,7 @@ LABEL maintainer="aptalca"
 RUN \
   echo "**** install runtime packages ****" && \
   apk add --no-cache --upgrade \
+    google-authenticator \
     logrotate \
     nano \
     netcat-openbsd \
@@ -28,6 +29,7 @@ RUN \
   printf "Linuxserver.io version: ${VERSION}\nBuild-date: ${BUILD_DATE}" > /build_version && \
   echo "**** setup openssh environment ****" && \
   sed -i 's/#PasswordAuthentication yes/PasswordAuthentication no/g' /etc/ssh/sshd_config && \
+  cp /etc/pam.d/sshd /etc/pam.d/sshd.default && \
   usermod --shell /bin/bash abc && \
   rm -rf \
     /tmp/* \

Dockerfile.aarch64

@@ -12,6 +12,7 @@ LABEL maintainer="aptalca"
 RUN \
   echo "**** install runtime packages ****" && \
   apk add --no-cache --upgrade \
+    google-authenticator \
     logrotate \
     nano \
     netcat-openbsd \
@@ -28,6 +29,7 @@ RUN \
   printf "Linuxserver.io version: ${VERSION}\nBuild-date: ${BUILD_DATE}" > /build_version && \
   echo "**** setup openssh environment ****" && \
   sed -i 's/#PasswordAuthentication yes/PasswordAuthentication no/g' /etc/ssh/sshd_config && \
+  cp /etc/pam.d/sshd /etc/pam.d/sshd.default && \
   usermod --shell /bin/bash abc && \
   rm -rf \
     /tmp/* \

README.md

@@ -80,6 +80,17 @@ It is also possible to run multiple copies of this container with different port
 You can volume map your own text file to `/etc/motd` to override the message displayed upon connection.
 You can optionally set the docker argument `hostname`
 
+## OTP (2FA)
+
+Setting `OTP_ACCESS` to `true` requires a time based one time password, on top of the ssh key, or on top of the password when `PASSWORD_ACCESS` is enabled as well. The codes are generated by any TOTP application, and the secret is kept in `/config/.google_authenticator` so it survives a container recreation.
+
+As long as that secret does not exist, the user is let in without being asked for a code, which is what makes the enrollment possible. Connect as usual and run:
+```
+google-authenticator -t -d -f -r 3 -R 30 -W -s /config/.google_authenticator
+```
+
+Scan the QR code with your authenticator application and write down the scratch codes, they are the only way back in if you lose it. Every login from that point on asks for a verification code.
+
 ## Key Generation
 
 This container has a helper script to generate an ssh private/public key. In order to generate a key please run:
@@ -116,6 +127,7 @@ services:
       - PUBLIC_KEY_URL=https://github.com/username.keys #optional
       - SUDO_ACCESS=false #optional
       - PASSWORD_ACCESS=false #optional
+      - OTP_ACCESS=false #optional
       - USER_PASSWORD=password #optional
       - USER_PASSWORD_FILE=/path/to/file #optional
       - USER_NAME=linuxserver.io #optional
@@ -142,6 +154,7 @@ docker run -d \
   -e PUBLIC_KEY_URL=https://github.com/username.keys `#optional` \
   -e SUDO_ACCESS=false `#optional` \
   -e PASSWORD_ACCESS=false `#optional` \
+  -e OTP_ACCESS=false `#optional` \
   -e USER_PASSWORD=password `#optional` \
   -e USER_PASSWORD_FILE=/path/to/file `#optional` \
   -e USER_NAME=linuxserver.io `#optional` \
@@ -169,6 +182,7 @@ Containers are configured using parameters passed at runtime (such as those abov
 | `-e PUBLIC_KEY_URL=https://github.com/username.keys` | Optionally specify a URL containing the public key. |
 | `-e SUDO_ACCESS=false` | Set to `true` to allow `linuxserver.io`, the ssh user, sudo access. Without `USER_PASSWORD` set, this will allow passwordless sudo access. |
 | `-e PASSWORD_ACCESS=false` | Set to `true` to allow user/password ssh access. You will want to set `USER_PASSWORD` or `USER_PASSWORD_FILE` as well. |
+| `-e OTP_ACCESS=false` | Set to `true` to require a one time password (2FA) in addition to the ssh key or the password. See the OTP section below. |
 | `-e USER_PASSWORD=password` | Optionally set a sudo password for `linuxserver.io`, the ssh user. If this or `USER_PASSWORD_FILE` are not set but `SUDO_ACCESS` is set to true, the user will have passwordless sudo access. |
 | `-e USER_PASSWORD_FILE=/path/to/file` | Optionally specify a file that contains the password. This setting supersedes the `USER_PASSWORD` option (works with docker secrets). |
 | `-e USER_NAME=linuxserver.io` | Optionally specify a user name (Default:`linuxserver.io`) |
@@ -337,6 +351,7 @@ Once registered you can define the dockerfile to use with `-f Dockerfile.aarch64
 
 ## Versions
 
+* **03.08.26:** - Add optional OTP (2FA) support via `OTP_ACCESS`.
 * **03.08.26:** - Add a healthcheck reporting whether sshd is listening.
 * **05.07.26:** - Rebase to Alpine 3.24.
 * **28.12.25:** - Rebase to Alpine 3.23.

readme-vars.yml

@@ -32,6 +32,7 @@ opt_param_env_vars:
   - {env_var: "PUBLIC_KEY_URL", env_value: "https://github.com/username.keys", desc: "Optionally specify a URL containing the public key."}
   - {env_var: "SUDO_ACCESS", env_value: "false", desc: "Set to `true` to allow `linuxserver.io`, the ssh user, sudo access. Without `USER_PASSWORD` set, this will allow passwordless sudo access."}
   - {env_var: "PASSWORD_ACCESS", env_value: "false", desc: "Set to `true` to allow user/password ssh access. You will want to set `USER_PASSWORD` or `USER_PASSWORD_FILE` as well."}
+  - {env_var: "OTP_ACCESS", env_value: "false", desc: "Set to `true` to require a one time password (2FA) in addition to the ssh key or the password. See the OTP section below."}
   - {env_var: "USER_PASSWORD", env_value: "password", desc: "Optionally set a sudo password for `linuxserver.io`, the ssh user. If this or `USER_PASSWORD_FILE` are not set but `SUDO_ACCESS` is set to true, the user will have passwordless sudo access."}
   - {env_var: "USER_PASSWORD_FILE", env_value: "/path/to/file", desc: "Optionally specify a file that contains the password. This setting supersedes the `USER_PASSWORD` option (works with docker secrets)."}
   - {env_var: "USER_NAME", env_value: "linuxserver.io", desc: "Optionally specify a user name (Default:`linuxserver.io`)"}
@@ -63,6 +64,17 @@ app_setup_block: |
   You can volume map your own text file to `/etc/motd` to override the message displayed upon connection.
   You can optionally set the docker argument `hostname`
 
+  ## OTP (2FA)
+
+  Setting `OTP_ACCESS` to `true` requires a time based one time password, on top of the ssh key, or on top of the password when `PASSWORD_ACCESS` is enabled as well. The codes are generated by any TOTP application, and the secret is kept in `/config/.google_authenticator` so it survives a container recreation.
+
+  As long as that secret does not exist, the user is let in without being asked for a code, which is what makes the enrollment possible. Connect as usual and run:
+  ```
+  google-authenticator -t -d -f -r 3 -R 30 -W -s /config/.google_authenticator
+  ```
+
+  Scan the QR code with your authenticator application and write down the scratch codes, they are the only way back in if you lose it. Every login from that point on asks for a verification code.
+
   ## Key Generation
 
   This container has a helper script to generate an ssh private/public key. In order to generate a key please run:
@@ -117,6 +129,7 @@ init_diagram: |
   "openssh-server:latest" <- Base Images
 # changelog
 changelogs:
+  - {date: "03.08.26:", desc: "Add optional OTP (2FA) support via `OTP_ACCESS`."}
   - {date: "03.08.26:", desc: "Add a healthcheck reporting whether sshd is listening."}
   - {date: "05.07.26:", desc: "Rebase to Alpine 3.24."}
   - {date: "28.12.25:", desc: "Rebase to Alpine 3.23."}

root/etc/s6-overlay/s6-rc.d/init-openssh-server-config/run

@@ -86,6 +86,75 @@ else
     echo "User/password ssh access is disabled."
 fi
 
+# otp (2FA) access
+OTP_SECRET=/config/.google_authenticator
+
+# rebuilt from a known state on every start so the variable can be turned back
+# off again. sshd resolves the plain sshd PAM service, not sshd.pam.
+if [[ "$OTP_ACCESS" == "true" ]] || grep -q "pam_google_authenticator.so" /etc/pam.d/sshd; then
+    cp /etc/pam.d/sshd.default /etc/pam.d/sshd
+
+    if [[ "$OTP_ACCESS" == "true" ]]; then
+        {
+            echo "#%PAM-1.0"
+
+            # the whole auth stack runs for keyboard-interactive, so the unix
+            # password prompt is only carried over when password access is on
+            if [[ "$PASSWORD_ACCESS" == "true" ]]; then
+                grep -E '^[[:space:]]*auth[[:space:]]' /etc/pam.d/sshd.default
+            fi
+
+            # nullok lets a user that has not enrolled yet log in, which is what
+            # makes the first otp-setup run possible. The module says so by
+            # answering PAM_IGNORE, and a stack whose only module is ignored has
+            # nothing that succeeded, so it is the trailing pam_permit that
+            # carries the login. A wrong code dies before reaching it.
+            echo "auth [success=ok ignore=ignore default=die] pam_google_authenticator.so nullok secret=${OTP_SECRET}"
+            echo "auth required pam_permit.so"
+
+            # the stock account and session checks read /etc/shadow, which sshd
+            # cannot do here because it runs as the ssh user rather than root.
+            # Nothing is lost by leaving them out: without OTP this image does
+            # not enable PAM at all, so none of them run today either.
+            echo "account required pam_permit.so"
+            echo "password required pam_permit.so"
+            echo "session required pam_permit.so"
+        } > /etc/pam.d/sshd
+    fi
+fi
+sed -i '/^# >>> OTP_ACCESS >>>$/,/^# <<< OTP_ACCESS <<<$/d' /config/sshd/sshd_config
+
+if [[ "$OTP_ACCESS" == "true" ]]; then
+    if [[ "$PASSWORD_ACCESS" == "true" ]]; then
+        AUTH_METHODS="keyboard-interactive publickey,keyboard-interactive"
+    else
+        AUTH_METHODS="publickey,keyboard-interactive"
+    fi
+
+    # sshd keeps the first value it reads for a keyword, so an active setting
+    # earlier in the file silently wins over the block appended below
+    if grep -qE '^[[:space:]]*(UsePAM|KbdInteractiveAuthentication|AuthenticationMethods)[[:space:]]' /config/sshd/sshd_config; then
+        echo "*** WARNING: /config/sshd/sshd_config already sets UsePAM, KbdInteractiveAuthentication or AuthenticationMethods. Remove those lines, otherwise OTP will not be enforced. ***"
+    fi
+
+    cat >> /config/sshd/sshd_config << EOF
+# >>> OTP_ACCESS >>>
+UsePAM yes
+KbdInteractiveAuthentication yes
+AuthenticationMethods ${AUTH_METHODS}
+# <<< OTP_ACCESS <<<
+EOF
+
+    if [[ -f "$OTP_SECRET" ]]; then
+        echo "OTP (2FA) ssh access is enabled."
+    else
+        echo "OTP (2FA) ssh access is enabled, but ${USER_NAME} has no secret yet and is not prompted for a code."
+        echo "Run 'google-authenticator -t -d -f -r 3 -R 30 -W -s ${OTP_SECRET}' as ${USER_NAME} to enroll."
+    fi
+else
+    echo "OTP (2FA) ssh access is disabled."
+fi
+
 # set umask for sftp
 UMASK=${UMASK:-022}
 sed -i "s|/usr/lib/ssh/sftp-server$|/usr/lib/ssh/sftp-server -u ${UMASK}|g" /config/sshd/sshd_config