X-Road: Autologin User Guide

Version: 1.4 Doc. ID: UG-AUTOLOGIN

• 1 Introduction
  • 1.1 Terms and abbreviations
  • 1.2 References
• 2 Overview
  • 2.1 Usage
  • 2.2 Implementation details

This document describes the Autologin utility which automatically enters the PIN code after xroad-signer has started.

See X-Road terms and abbreviations documentation [TA-TERMS].

1. [TA-TERMS] X-Road Terms and Abbreviations. Document ID: TA-TERMS.

1. Install the package

• Ubuntu: apt install xroad-autologin
• RedHat: yum install xroad-autologin

2. If storing the PIN code on the server in plaintext is acceptable, create file /etc/xroad/autologin that contains the PIN code.

• File should be readable by user xroad
• If /etc/xroad/autologin does not exists, and you have not implemented custom-fetch-pin.sh, the service will not start

3. If you do not want to store PIN code in plaintext, implement bash script /usr/share/xroad/autologin/custom-fetch-pin.sh

• The script needs to output the PIN code to stdout
• Script should be readable and executable by user xroad
• Script should exit with exit code
  • 0 if it was able to fetch PIN code successfully
  • 127 if it was not able to fetch PIN code, but this is not an actual error that should cause the service to fail (default implementation uses this if /etc/xroad/autologin does not exist)
  • other exit codes in error situations that should cause the service to fail

#!/bin/bash
PIN_CODE=$(curl https://some-address)
echo "${PIN_CODE}"
exit 0

• Creates a new service xroad-autologin
• Service is started after xroad-signer has started
• On RHEL/Ubuntu 20.04, service calls wrapper script /usr/share/xroad/autologin/xroad-autologin-retry.sh which in turn calls autologin.expect
  • Wrapper script handles retries in error situations.
• Service tries to enter the PIN code using script signer-console
  • If the PIN was correct or incorrect, it exits
  • If an error occurred (for example because xroad-signer has not yet fully started), it keeps retrying indefinitely