Fingerprint Authentication with swaylock: Difference between revisions

From Alpine Linux
No edit summary
(added wikitags, category, see also section and reworded introduction and few other sentence)
Line 1: Line 1:
= Fingerprint Authentication with swaylock =
This guide shows how to configure fingerprint authentication for swaylock on Alpine Linux, allowing you to unlock using fingerprint sensor with password as fallback.


Not all fingerprint readers are supported, see [https://fprint.freedesktop.org/supported-devices.html here].
== Prerequisites ==


<code>lsusb | grep finger</code>
* Enable [[Polkit|Polkit]]


will give you your USB ID.
== Installation ==


This guide shows how to configure fingerprint authentication for swaylock on Alpine Linux, allowing you to unlock using either:
Install the {{pkg|fprintd}} package:{{Cmd|$ doas apk add fprintd}}
* <code>&lt;enter password&gt;</code> → <code>&lt;hit enter&gt;</code>
* <code>&lt;hit enter&gt;</code> → <code>&lt;touch fingerprint sensor&gt;</code>


== Installation ==
== Configuration ==


Install the fprintd package:
To get the USB ID for your fingerprint reader, issue the command: {{Cmd|$ lsusb | grep finger}}


doas apk add fprintd
Once onfigured this allows you to unlock using either:
* <code>&lt;enter password&gt;</code> → <code>&lt;hit enter&gt;</code>
* <code>&lt;hit enter&gt;</code> → <code>&lt;touch fingerprint sensor&gt;</code>


== Configure PolicyKit Permissions ==
=== Configure policyKit permissions ===


Upon installation, standard users are not authorized to enroll fingerprints. Create a PolicyKit rule to allow members of the <code>input</code> group to manage fingerprints:
Upon installation, standard users are not authorized to enroll fingerprints. Create a PolicyKit rule {{Path|etc/polkit-1/rules.d/50-fingerprint.rules}} to allow members of the <code>input</code> group to manage fingerprints with contents as shown:{{Cat|etc/polkit-1/rules.d/50-fingerprint.rules|<nowiki>polkit.addRule(function (action, subject) {
    if (action.id.indexOf("net.reactivated.fprint.") == 0) {
        if (subject.isInGroup("input")) {
            return polkit.Result.YES;
        }
    }
});</nowiki>}}


doas tee /etc/polkit-1/rules.d/50-fingerprint.rules << 'EOF'
Ensure that correct permissions are set:{{Cmd|<nowiki># chown root:root /etc/polkit-1/rules.d/50-fingerprint.rules
polkit.addRule(function (action, subject) {
# chmod 644 /etc/polkit-1/rules.d/50-fingerprint.rules</nowiki>}}
    if (action.id.indexOf("net.reactivated.fprint.") == 0) {
        if (subject.isInGroup("input")) {
            return polkit.Result.YES;
        }
    }
});
EOF


Add your user to the <code>input</code> group:
Add your user to the <code>input</code> group:{{Cmd|$ doas adduser $USER input}}


doas adduser $USER input
{{Note| You must log out and back in (or reboot) for the group membership & PolicyKit rule to take effect.}}


'''Note:''' You must log out and back in (or reboot) for the group membership & PolicyKit rule to take effect.
=== Enroll fingerprints ===
 
== Enroll Fingerprints ==


If you previously enrolled fingerprints as root (or want to start fresh), delete existing enrollments:
If you previously enrolled fingerprints as root (or want to start fresh), delete existing enrollments:


# Delete fingerprints for current user
To delete fingerprints for current user: {{Cmd|$ fprintd-delete $(whoami)}}
fprintd-delete $(whoami)
   
   
# If you accidentally enrolled as root, delete those too
If you accidentally enrolled as root, delete those too {{Cmd|$ doas fprintd-delete root}}
doas fprintd-delete root


Enroll your fingerprint(s):
Enroll your fingerprint(s):{{Cmd|$ fprintd-enroll}}


fprintd-enroll
Verify the enrollment works:{{Cmd|$ fprintd-verify}}


Verify the enrollment works:
=== Configure PAM for swaylock ===


fprintd-verify
Create the PAM configuration file {{Path|/etc/pam.d/swaylock}} for swaylock with contents as shown: {{Cat|/etc/pam.d/swaylock|<nowiki># Try password authentication first
auth sufficient pam_unix.so nullok
# If no password provided, try fingerprint
auth sufficient pam_fprintd.so ignore-empty-password
auth required pam_deny.so


== Configure PAM for swaylock ==
# KWallet integration (optional)
-auth    optional        pam_kwallet.so
-auth    optional        pam_kwallet5.so
-session optional        pam_kwallet.so auto_start
-session optional        pam_kwallet5.so auto_start
</nowiki>}}


Create the PAM configuration for swaylock:
Ensure that correct permissions are set:{{Cmd|<nowiki># chown root:root /etc/pam.d/swaylock
# chmod 644 /etc/pam.d/swaylock</nowiki>}}


doas tee /etc/pam.d/swaylock << 'EOF'
== Extending to other services ==
# Try password authentication first
 
auth sufficient pam_unix.so nullok
You can apply similar fingerprint authentication to other services by adding the same PAM configuration pattern to files in <code>/etc/pam.d/</code> such as:
# If no password provided, try fingerprint
* <code>sudo</code>
auth sufficient pam_fprintd.so ignore-empty-password
* <code>polkit-1</code>
auth required pam_deny.so
* <code>login</code>
* <code>su</code>
# KWallet integration (optional)
-auth    optional        pam_kwallet.so
-auth    optional        pam_kwallet5.so
-session optional        pam_kwallet.so auto_start
-session optional        pam_kwallet5.so auto_start
EOF


== Usage ==
== Usage ==
Line 82: Line 81:
== Troubleshooting ==
== Troubleshooting ==


* '''Permission denied during enrollment:''' Ensure you're in the <code>input</code> group and have logged out/in after adding the group
=== Permission denied during enrollment===
* '''Fingerprint recognized but doesn't unlock:''' Check that fingerprints are enrolled for the correct user (not root)
 
* '''No fallback to password:''' Verify the PAM configuration has <code>pam_unix.so</code> before <code>pam_fprintd.so</code>
If you receive ''' Permission denied''' message during enrollment ensure you're in the <code>input</code> group and have logged out/in after adding the group.
 
=== Fingerprint recognized but doesn't unlock===
 
If Fingerprint is recognized but doesn't unlock, check that fingerprints are enrolled for the correct user (not root)
 
=== No fallback to password ===
 
If there is no fallback to password when using fingerprint authentication verify the PAM configuration has <code>pam_unix.so</code> before <code>pam_fprintd.so</code>
 
== See also ==


== Extending to Other Services ==
* [https://fprint.freedesktop.org/supported-devices.html list of supported fingerprint readers]


You can apply similar fingerprint authentication to other services by adding the same PAM configuration pattern to files in <code>/etc/pam.d/</code> such as:
[[Category:Authentication]]
* <code>sudo</code>
* <code>polkit-1</code>
* <code>login</code>
* <code>su</code>

Revision as of 04:34, 2 September 2025

This guide shows how to configure fingerprint authentication for swaylock on Alpine Linux, allowing you to unlock using fingerprint sensor with password as fallback.

Prerequisites

Installation

Install the fprintd package:

$ doas apk add fprintd

Configuration

To get the USB ID for your fingerprint reader, issue the command:

$ lsusb

Once onfigured this allows you to unlock using either:

  • <enter password> → <hit enter>
  • <hit enter> → <touch fingerprint sensor>

Configure policyKit permissions

Upon installation, standard users are not authorized to enroll fingerprints. Create a PolicyKit rule etc/polkit-1/rules.d/50-fingerprint.rules to allow members of the input group to manage fingerprints with contents as shown:

Contents of etc/polkit-1/rules.d/50-fingerprint.rules

polkit.addRule(function (action, subject) { if (action.id.indexOf("net.reactivated.fprint.") == 0) { if (subject.isInGroup("input")) { return polkit.Result.YES; } } });

Ensure that correct permissions are set:

# chown root:root /etc/polkit-1/rules.d/50-fingerprint.rules # chmod 644 /etc/polkit-1/rules.d/50-fingerprint.rules

Add your user to the input group:

$ doas adduser $USER input

Note: You must log out and back in (or reboot) for the group membership & PolicyKit rule to take effect.

Enroll fingerprints

If you previously enrolled fingerprints as root (or want to start fresh), delete existing enrollments:

To delete fingerprints for current user:

$ fprintd-delete $(whoami)

If you accidentally enrolled as root, delete those too

$ doas fprintd-delete root

Enroll your fingerprint(s):

$ fprintd-enroll

Verify the enrollment works:

$ fprintd-verify

Configure PAM for swaylock

Create the PAM configuration file /etc/pam.d/swaylock for swaylock with contents as shown:

Contents of /etc/pam.d/swaylock

# Try password authentication first auth sufficient pam_unix.so nullok # If no password provided, try fingerprint auth sufficient pam_fprintd.so ignore-empty-password auth required pam_deny.so # KWallet integration (optional) -auth optional pam_kwallet.so -auth optional pam_kwallet5.so -session optional pam_kwallet.so auto_start -session optional pam_kwallet5.so auto_start

Ensure that correct permissions are set:

# chown root:root /etc/pam.d/swaylock # chmod 644 /etc/pam.d/swaylock

Extending to other services

You can apply similar fingerprint authentication to other services by adding the same PAM configuration pattern to files in /etc/pam.d/ such as:

  • sudo
  • polkit-1
  • login
  • su

Usage

Once configured, swaylock will accept both authentication methods:

  • Password authentication: Type your password and press Enter
  • Fingerprint authentication: Press Enter without typing anything, then touch the fingerprint sensor

Troubleshooting

Permission denied during enrollment

If you receive Permission denied message during enrollment ensure you're in the input group and have logged out/in after adding the group.

Fingerprint recognized but doesn't unlock

If Fingerprint is recognized but doesn't unlock, check that fingerprints are enrolled for the correct user (not root)

No fallback to password

If there is no fallback to password when using fingerprint authentication verify the PAM configuration has pam_unix.so before pam_fprintd.so

See also

Retrieved from "https://wiki.alpinelinux.org/w/index.php?title=Fingerprint_Authentication_with_swaylock&oldid=30840"