Skip to content

FAQ: NFClogin plugin

Jump to bottom
Ente edited this page Apr 7, 2025 · 3 revisions

FAQ: NFC-Login plugin

Here's a Guide on how to get this plugin installed and used: At the end, there's a FAQ

Install requirements

  • Make sure your php.ini does not disable the use of the exec() function
  • Make sure you have a compatible NFC reader, e.g. ACR122U and at least one NFC-Tag/Card

Debian

Install required packages:

sudo apt update && apt install pcscd pcsc-tools libpcsclite-dev python3 python3-pip
pip3 install pyscard
sudo systemctl enable --now pcscd

Windows

pip install pyscard

That's it.

Technical Implementation

To read or write to NFC cards or tags, you could've guessed it, the python library pyscard is used. The plugin includes helper scripts (located in nfclogin/src):

  • read_nfc_block.py - Reads block 4 on the NFC tag, which is used to identify a user.
  • read_nfc_uid.py - Reads the UID of the NFC tag.
  • write_nfc.py - Writes new authentication data to a provided tag.

Since the plugin is enabled by default, users can simply login by holding the NFC card close to the reader and clicking the Login with NFC button on the login page. Beforehand, an administrator must assign the card to this specific user. You can read more about this in the next section.

Administrators can also verify whether an NFC tag is already assigned to an existing user. To do so, navigate to Plugins > [nfclogin] Manage cards, hold the desired NFC tag close to the reader, and press the Read NFC card (user block) button. A modal will open, either showing an error (if the card could not be read or verification failed) or confirming with USER VERIFICATION OK and the username the card is assigned to.

To just check if a card is present, click the Read card button in the same menu. On success it will display Card detected and the card UID. On failure it returns an error.

Assign card to user

To assign a card to a user navigate to Plugins > [nfclogin] Manage cards. Within the functions you can input a username and press write, while a NFC tag is close to the reader.

The card will then be assigned to entered user. You can verify this by clicking on the Read NFC card (user block) button or within All cards on the same page.

Login with assigned NFC card

  • Open up the login page of your instance
  • Hold your card close to the reader and press the Login with NFC button.
  • On success, you will be redirected to the main page
  • On failure, you will be redirected back to the login with an appropriate error message stating why.

FAQ

Q: I have installed the plugin, clicked Login with NFC but it returns forbidden?

A: You first have to access the plugin once for API routes to register and setting permissions.

Q: When writing to an NFC tag the "All cards" section does not update on reload?

A: Please make sure the webserver is able to read and write to the map.json file, therefore please check the file permissions.

Q: No matter what the helper scripts always return errors?

A: This most likely occurs on Windows operating systems. Please test the following:

  • Do you have the python3 Version from the Windows Store installed? If so, please either remove it or install the pyscard package there too.
  • Check the used version in CLI - if it differs from the installation process either align or install the pyscard package too.

Q: I can't remove a assigned card from a user. Can I overwrite it then?

A: Yes, you can overwrite an already assigned card. This does not remove the previous entry but allows the other user to login instead.

Clone this wiki locally