Contributing to the code

authd consists of multiple components. These are described in the architecture overview.

For using and testing authd, one or more brokers need to be available, which run on the host to interface with remote identity providers.

Steps for building the components, testing authd, and contributing to the code, are described on this page.

Required dependencies

This project has several build dependencies. You can install these dependencies from the top of the source tree using the apt command as follows:

sudo apt update
sudo apt build-dep .
sudo apt install devscripts

Building and running the binaries

The project consists of the following binaries:

  • authd: The main authentication service.

  • authctl: The command-line tool for managing authd users and groups.

  • pam_authd.so: A PAM native module (used by GDM).

  • pam_authd_exec.so, authd-pam: A PAM module and its helper executable (used by other PAM applications).

  • libnss_authd.so: An NSS module.

authd can be built as a Debian package. This process will compile all the binaries, run the test suite and produce the Debian packages.

Alternatively, for development purposes, each binary can be built manually and separately.

Building the Debian package from source

Building the Debian package from source is the most straightforward and standard method for compiling the binaries and running the test suite. To do this, run the following commands from the top of the source tree:

Note

This is required to vendorize the Rust crates and must be done only once.

sudo apt install libssl-dev
cargo install cargo-vendor-filterer

Then build the Debian package:

debuild --prepend-path=${HOME}/.cargo/bin

The Debian packages are available in the parent directory.

Building authd only

To build authd only, run the following command from the top of the source tree:

go build ./cmd/authd

The built binary will be found in the current directory. The daemon can be run directly from this binary without installing it on the system.

Building authctl only

To build authctl from the top of the source tree:

go build ./cmd/authctl

Building the PAM module only

To build the PAM module, you first need to install the tooling to hook up the Go gRPC modules to protoc. From the top of the source tree run the following commands:

cd tools/
grep -o '_ ".*"' *.go | cut -d '"' -f 2 | xargs go install
cd ..

Then build the PAM module:

go generate ./pam/
go build -o ./pam/authd-pam ./pam

The go generate step produces two PAM modules (./pam/pam_authd.so and ./pam/go-exec/pam_authd_exec.so).

The go build step produces the PAM helper executable (./pam/authd-pam).

These modules must be copied to /usr/lib/$(gcc -dumpmachine)/security/ while the executable must be copied to /usr/libexec/authd-pam.

For further information about the PAM module architecture and testing see the README for the authd PAM module.

Building the NSS module only

To build the NSS module, from the top of the source tree run the command:

cargo build

This will build a debug release of the NSS module.

The library resulting from the build is located in ./target/debug/libnss_authd.so. This module must be copied to /usr/lib/$(gcc -dumpmachine)/libnss_authd.so.2.

Building the broker

The authd brokers are packaged as separate snaps that are built and released independently from authd. The source code for the brokers is located in ./authd-oidc-brokers and the snap packaging files are located in ./snap.

Building the broker requires snapcraft

If you do not have snapcraft installed, run:

sudo snap install snapcraft --classic

To build the broker snap for a specific broker variant, follow these steps from the top of the source tree:

  1. Ensure that the submodules are checked out:

    git submodule update --init --recursive
    
  2. Prepare the snapcraft.yaml for the desired broker variant:

    ./snap/scripts/prepare-variant --broker <broker>
    

    where <broker> is one of oidc, msentraid, or google.

  3. Build the broker snap:

    snapcraft pack
    

When the build succeeds, the resulting .snap file is created in the current working directory. You can install the locally built broker snap for development with a command such as:

snap install --dangerous ./path/to/broker.snap

About the test suite

The project includes a comprehensive test suite made of unit, integration, and end-to-end tests. All the tests must pass before the review is considered. If you have trouble with the test suite, feel free to mention it in your PR description.

From the repository root, run authd’s Go unit tests and the PAM and NSS integration tests with: go test ./... (add the -race flag for race detection).

Every package has a suite of at least package-level tests. They may integrate more granular unit tests for complex functionalities. Integration tests are located in ./pam/integration-tests for the PAM module and ./nss/integration-tests for the NSS module.

The end-to-end tests for authd and its brokers run in a provisioned Ubuntu VM. See the end-to-end testing guide for details.

The test suite must pass before merging the PR to our main branch. Any new feature, change or fix must be covered by corresponding tests.

Code style

This project follows Google Go style conventions. For more detailed information about the code style in use, please check https://google.github.io/styleguide/go/.