From de464957fb7ed6ee31f883c1f88550eab6f9ea5b Mon Sep 17 00:00:00 2001
From: Dominik George <dominik.george@teckids.org>
Date: Wed, 19 May 2021 11:45:00 +0200
Subject: [PATCH] Fully document example configuration
---
etc/nss_pam_webapi.example.toml | 21 +++++++++++++++++++++
1 file changed, 21 insertions(+)
diff --git a/etc/nss_pam_webapi.example.toml b/etc/nss_pam_webapi.example.toml
index a48444f..ad8f0e5 100644
--- a/etc/nss_pam_webapi.example.toml
+++ b/etc/nss_pam_webapi.example.toml
@@ -1,24 +1,44 @@
+# Example configuration for nss-pam-webapi
+#
+# This configuration uses almost all features of the library.
+# It is tailored to the backend implemented in AlekSIS-App-NIS,
+# which is the de facto reference implementation.
+
+# Enable debug globally (NSS and PAM)
+# This may leak sensitive information to syslog!
debug = true
+
+# OAuth endpoints to acquire tokens, used globally (NSS and PAM)
auth_url = "https://ticdesk-dev.teckids.org/oauth/authorize/"
token_url = "https://ticdesk-dev.teckids.org/oauth/token/"
+# Configuration for the PAM component
[pam]
+# Client ID and secret for acquiring OAuth tokens
# You might want to put these into a separate file nss_pam_webapi.secret.toml!
client_id = "Df1cpPEBsbG64oZ1Q1L8NetH1UKNBUyA5qhxg1Zh"
client_secret = ""
[nss]
+# Client ID and secret for acquiring OAuth tokens
# You might want to put these into a separate file nss_pam_webapi.secret.toml!
client_id = "z8Oz0tG56QRo9QEPUZTs5Eda410FMiJtYxlInxKE"
client_secret = ""
+# Endpoint URLs for retrieving information for NSS databases
+# For single-object URLs, the placeholder `{}` will be replaced with the lookup key
+# list - retrieve a list of users, e.g. `getent passwd`
urls.passwd.list = "https://ticdesk-dev.teckids.org/app/nis/api/passwd/"
+# by_uid - get informatio non one user by their numeric ID, e.g. getent passwd 1234
urls.passwd.by_uid = "https://ticdesk-dev.teckids.org/app/nis/api/passwd/{}/"
+# by_name - get informatio non one user by their login name, e.g. getent passwd jdoe
urls.passwd.by_name = "https://ticdesk-dev.teckids.org/app/nis/api/passwd/{}/"
# The following configuration maps the attributes as returned by AlekSIS, as
# example onto a system that also has local accounts (thus mapping IDs and
# home directories).
+# The map is a jq program that gets one user object from the API backend as
+# input and outputs an object with the expected keys for the passwd struct.
maps.passwd = """
{
name: .username,
@@ -36,4 +56,5 @@ maps.passwd = """
"""
# Reverse mapping to make sure uid lookups on entries mapped above still work
+# Will be applied with jq to the lookup key before inserting into the endpoint URL
maps.rev.passwd.by_uid = ". - 10000"
--
GitLab