Skip to main content
Glama

Intent-Auditable Trust Object V2

This repository provides iato, a C# (.NET 8) command line tool that configures Debian hosts to authenticate Microsoft Entra ID users through the SSSD identity provider (idp) back end. SSSD reads users and groups from Microsoft Graph, signs users in with the OAuth 2.0 Device Authorization Grant (RFC 8628), and derives consistent POSIX UIDs and GIDs from Entra object IDs, so no ID mapping is managed by hand. It is not an identity provider, a directory service or a replacement for SSSD; it renders, checks and installs SSSD configuration and verifies the result.

The key words MUST, MUST NOT, SHALL, SHOULD and MAY in this document are to be interpreted as described in BCP 14 (RFC 2119 and RFC 8174).

Contents

Related MCP server: shipcheck-mcp

Key features

iato has four parts. Each one is a subcommand that runs against Microsoft Graph, a configuration file or a Debian host, and each states what checks it.

#

Feature

What runs

Checked by

1

Entra ID app registration

iato register-app against Microsoft Graph

xUnit test of the Graph request body; not run in CI, which has no tenant

2

Rendering of sssd.conf for the idp domain

iato render from the embedded template

xUnit tests; ci.yml renders the file in Debian forky (Figures 4 and 6)

3

Configuration and host checks

iato check, iato check --host

xUnit tests; ci.yml runs --host against SSSD in Debian forky (Figures 5 to 7)

4

Host installation and verification

iato install, iato verify on a Debian host

iato verify on a configured host; not covered by CI

1. Entra ID app registration

  • Creating the Entra ID app registration through Microsoft Graph (iato register-app).

  • An Entra ID app registration gives SSSD application permissions to read users and group membership, and allows public client flows for device code sign in.

  • Graph permissions requested: application User.Read.All and GroupMember.Read.All; delegated openid, profile and email. Admin consent is granted for both.

  • The client secret is written to entra-app.env with mode 0600. The token is taken from IATO_GRAPH_TOKEN or az account get-access-token.

2. Rendering of sssd.conf for the idp domain

  • Rendering sssd.conf for the idp domain (iato render).

  • The template sssd/sssd.conf is compiled into the binary, so hosts need nothing else on disk.

  • Missing or multi line values are rejected before any file is written, and the output file is created with mode 0600.

3. Configuration and host checks

  • Checking sssd.conf for the idp domain (iato check): placeholders, duplicate keys, required idp settings, https endpoints, idmap range and config_file_version.

  • --host also checks the installed SSSD version (2.11.0 or later), the presence of libsss_idp.so and the file mode.

  • The checks do not depend on the sssctl rule set, which can lag new back ends.

4. Host installation and verification

  • Installing and enabling SSSD, pam_sss and the sshd drop in on Debian hosts (iato install).

  • Verifying that a user resolves and may log in (iato verify).

  • iato install starts SSSD only after the configuration and host checks pass.

Scope

Out of scope:

  • Distributions other than Debian.

  • SSSD versions earlier than 2.11.0, which have no idp provider.

  • The OpenLDAP domain and Debian packaging, which are held on separate branches (see Branches).

Known limitations:

  • The ID mapping can, in rare cases, assign the same ID to two objects; only the first one resolved is available.

  • The client secret is the only credential type supported for this provider at present.

  • On Debian 12 and 13, SSSD packages are taken from Debian forky through an apt pin rather than from the installed release.

Planned work (not implemented):

  1. A certificate credential in place of the client secret, once SSSD supports one for the idp provider (see Configuration).

Architecture

How it works

  1. An Entra ID app registration gives SSSD application permissions to read users and group membership, and allows public client flows for device code sign in.

  2. SSSD runs with id_provider = idp and idp_type = entra_id. getent and id resolve Entra users and groups.

  3. At login, pam_sss shows a verification URL and code. The user signs in on any browser, Conditional Access and MFA apply, and SSSD completes the login once Entra confirms.

  4. access_provider = simple limits logins to one Entra group.

Components

 admin workstation                         Microsoft Entra ID
 -----------------                         ------------------
 iato register-app  ---- Graph v1.0 ---->  app registration, service principal,
   |                                       app role assignments, admin consent,
   v                                       client secret
 entra-app.env (0600)
   |
   v                    Debian host
 +---------------------------------------------------------------+
 | iato install / render / check --host                          |
 |   -> /etc/sssd/sssd.conf (root, 0600), [domain/entra]         |
 |   -> apt pin to forky on bookworm and trixie                  |
 |   -> pam-auth-update (sss, mkhomedir), sshd drop in           |
 |                                                               |
 | sssd (id_provider = idp) ---- token, Graph lookups ---------> | Entra ID, Graph
 | pam_sss <- sshd (keyboard-interactive)                        |
 |   device code prompt  ----- RFC 8628 device authorization --> | Entra ID
 | iato verify -> sssctl, getent, id                             |
 +---------------------------------------------------------------+

References

Repository layout

Path

Purpose

src/Iato/

The CLI (.NET 8)

tests/Iato.Tests/

xUnit tests for rendering, checks and the Graph request

sssd/sssd.conf

Template for the idp domain

apt/

forky source and pin so only SSSD packages come from forky

ssh/

sshd drop in enabling keyboard-interactive for the device code prompt

docs/screenshots/

Figures used in this README and the text logs they were captured from

.github/workflows/ci.yml

Build, test, then iato check --host against SSSD in a Debian forky container

.github/workflows/captures.yml

Produces the figures in this README on an Xvfb display

Branches

Branch

Holds

main

The iato CLI, the idp domain template, tests and CI

openldap

main plus an OpenLDAP domain (iato render --provider ldap) for hosts that must work offline from Entra ID or need LDAP binds

release/2.x

main plus Debian packaging and the release workflow; version tags are cut here

History

This repository was named agent-q until v2. Versions up to v0.3.0 were Agent Q, a pull request reviewer on Cloudflare Workers and Supabase. That code remains at the v0.3.0 tag and release. v1.0.0 was the first release of the SSSD project.

Requirements

Item

Detail

SSSD

2.11.0 or later MUST be installed. Debian 12 ships 2.8.2 and Debian 13 ships 2.10.1, so this repository pins SSSD packages from Debian forky (2.13). Debian forky and sid ship a suitable version as is.

Packages

sssd, sssd-idp, libnss-sss, libpam-sss, sssd-tools

Entra ID

Rights to create an app registration and grant admin consent

Graph permissions

Application: User.Read.All, GroupMember.Read.All. Delegated: openid, profile, email

Build

.NET 8 SDK, only when building from source

The released binary is self contained, so hosts do not need a .NET runtime. Templates are compiled into it.

Build

Build from source

dotnet test
dotnet publish src/Iato -c Release -r linux-x64 --self-contained -p:PublishSingleFile=true -o out

Figure 2 shows dotnet build -c Release and Figure 3 shows dotnet test on the CI runner.

Install from a release

Releases are cut from the release/2.x branch. Each one attaches iato_<version>_amd64.deb, iato_<version>_arm64.deb, standalone iato-linux-x64 and iato-linux-arm64 binaries, a source tarball and SHA256SUMS. Downloads SHOULD be checked against SHA256SUMS before installation.

V=2.0.0
curl -LO https://github.com/whatheheckisthis/Intent-Auditable-Trust-Object-V2/releases/download/v$V/iato_${V}_amd64.deb
curl -LO https://github.com/whatheheckisthis/Intent-Auditable-Trust-Object-V2/releases/download/v$V/SHA256SUMS
sha256sum --check --ignore-missing SHA256SUMS
sudo apt install ./iato_${V}_amd64.deb

Usage

iato register-app --name sssd-debian-hosts --out entra-app.env  # once per tenant
sudo iato install --env entra-app.env --group linux-admins      # on each host
iato verify alex@contoso.onmicrosoft.com

iato register-app runs once per tenant. iato install runs on each host and MUST run as root. On Debian 12 and 13, iato install adds the forky pin before installing SSSD.

Command

Behaviour

iato register-app

Creates the Entra app registration through Microsoft Graph, grants admin consent, and writes entra-app.env (mode 0600). Uses IATO_GRAPH_TOKEN or az account get-access-token.

iato render

Renders sssd.conf from the embedded template. Rejects missing or multi line values.

iato check

Checks a config: placeholders, duplicate keys, required idp settings, https endpoints, idmap range, config_file_version. --host also checks the SSSD version, libsss_idp.so and the file mode.

iato install

Pins SSSD from forky where needed, installs packages, writes the config, enables pam_sss and the sshd drop in, and starts SSSD only after the checks pass.

iato verify

Runs sssctl domain-status, getent, id and sssctl user-checks for a user.

iato version

Prints the tool version.

The built in help is shown in Figure 1.

Walkthrough

The steps below follow one tenant and one host from app registration to an SSH sign in. Steps 2, 3 and 7 have captured figures from the CI runner. Steps 1, 4, 5 and 6 require a live Entra ID tenant or a Debian host running systemd, which CI does not provide, so no figure is published for them; see Figures.

  1. Register the Entra ID app once per tenant. The client secret is written to a file only the owner can read. Without a Graph token, iato register-app stops before any request is sent (Figure 1).

  2. Render sssd.conf for the idp domain and check it before it reaches a host (Figures 4 and 5).

  3. iato check stops a broken configuration: an unrendered placeholder, a key SSSD 2.13 rejects and endpoints that are not https (Figure 5).

  4. Install on a Debian 13 host. SSSD packages are pinned from forky, and SSSD starts only after the host checks pass. Figure 7 shows the host check that fails on Debian 13 without the pin, and Figure 6 the same check passing against SSSD from forky.

  5. Verify that an Entra ID user resolves to a POSIX account and passes the access check for the allowed group.

  6. The user signs in over SSH. SSSD shows a device code, the user completes sign in on any browser with MFA and Conditional Access, and the session opens.

  7. The unit tests cover rendering, checks and the Graph request (Figure 3).

Configuration

  • sssd/sssd.conf is the template for the idp domain. iato render and iato install fill it from entra-app.env and the --group value.

  • apt/ holds the forky source and pin so that only SSSD packages come from forky.

  • ssh/ holds the sshd drop in that enables keyboard-interactive authentication for the device code prompt.

  • The client secret grants tenant wide read of users and group membership. It MUST be stored only in /etc/sssd/sssd.conf (root, 0600). A certificate credential SHOULD be preferred once SSSD supports one for this provider.

  • cache_credentials = false: every login goes to Entra, so revoked accounts lose access at the next sign in.

  • idmap_range_* values MUST be identical across hosts.

Verification and testing

  • dotnet test runs the xUnit tests in tests/Iato.Tests/, which cover rendering, checks and the Graph request.

  • .github/workflows/ci.yml builds and tests on each push and pull request, then runs iato check --host against SSSD in a Debian forky container. Continuous integration does not cover Debian 12, Debian 13 or sid hosts.

  • .github/workflows/captures.yml repeats the build and tests on an ubuntu-24.04 runner and captures the figures in this README.

  • On a configured host, iato verify <user@tenant> MAY be used to confirm that a user resolves and may log in.

Test results

The captures run of commit 57bda29 on an ubuntu-24.04 runner reported the following (Figures 2 and 3; logs in docs/screenshots/02-dotnet-build.log and docs/screenshots/03-dotnet-test.log).

Check

Result

dotnet build -c Release (SDK 11.0.100, target net8.0)

Build succeeded: 0 errors, 1 warning (xUnit analyzer xUnit2029 in tests/Iato.Tests/SssdConfigTests.cs, line 19)

dotnet test -c Release (xUnit 2.8.2 VSTest adapter, .NET 8.0.34)

10 tests in total, 10 passed, none failed

iato check --host in debian:forky (SSSD 2.13.1-5)

/etc/sssd/sssd.conf: ok, exit status 0

iato check --host in debian:trixie (SSSD 2.10.1-2+b1)

2 errors, exit status 1, as intended

The ten tests, in the order the runner reported them:

Test

Covers

DebianVersionsParse("2.13.1-5"), DebianVersionsParse("1:2.11.0~rc1-1")

Debian package version parsing used by --host

BadSettingsAreFound("config_file_version = 2"), BadSettingsAreFound("idp_type = entra_id")

Rejected key and duplicate key detection

NewlineInValueIsRejected

Multi line values cannot inject settings

MissingValueIsRejected

Rendering stops when a value is missing

ClientIdMustBeGuid

idp_client_id format check

RenderedTemplatePassesCheck

The rendered template has no placeholders and no errors

SecretFileIsOwnerOnly

Output files are created with mode 0600

ApplicationRequestsExpectedPermissions

The Graph application body requests the two application roles and allows public client flows

Figures

All figures are produced by .github/workflows/captures.yml on an ubuntu-24.04 runner, run 44444112722 of commit 57bda29. Each figure is an xterm window on an Xvfb display running the commands it shows, captured with ImageMagick import -window; the only edit is cropping of empty terminal space. No figure is drawn by hand. The text that each terminal printed is kept beside the image as a .log file in docs/screenshots/. The Entra identifiers and the client secret are the same placeholders used by ci.yml (00000000-... tenant, 11111111-... client, ci-placeholder), and no tenant is contacted. Select any figure to open it at full resolution.

Figure

Subject

Tool

Source

1

iato version, iato --help, iato register-app without a Graph token

iato 2.0.1

src/Iato/Program.cs, src/Iato/EntraRegistrar.cs

2

Release build

.NET SDK 11.0.100, MSBuild

Iato.sln

3

Unit tests

dotnet test, xUnit 2.9.2

tests/Iato.Tests/SssdConfigTests.cs

4

Rendered sssd.conf for the idp domain

iato render

sssd/sssd.conf, src/Iato/SssdConfig.cs

5

Configuration check on a valid and a broken file

iato check, GNU sed, diff

src/Iato/SssdConfig.cs

6

Host check against SSSD 2.13.1 in Debian forky

iato check --host, Docker debian:forky

src/Iato/HostSystem.cs

7

Host check against SSSD 2.10.1 in Debian 13

iato check --host, Docker debian:trixie

src/Iato/HostSystem.cs

The following are not captured, because they need resources that CI does not have: iato register-app against a real tenant (it requires a Graph token with rights to create an app registration), iato install (it requires a Debian host running systemd), iato verify (it requires a running SSSD joined to a tenant), and the SSSD device code prompt at SSH login (it is printed by pam_sss after a live device authorization request to Entra ID). The Graph request body is covered by a unit test instead (Figure 3).

Command line

Build and tests

Configuration

Host checks

Security

Security reporting and commit signature verification are described in SECURITY.md; the maintainer signing key is published in KEYS.asc.

License

This project is licensed under the Apache License, Version 2.0. See LICENSE.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      C
      quality
      D
      maintenance
      A policy-aware MCP server for GitHub and GitHub Actions that enables safe AI-assisted infrastructure workflows—inspecting repositories, preparing branches and pull requests, and constrained remote mutations behind explicit preview-bound approval tokens.
      18
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables MCP-compatible AI agents to scan code for leaked secrets, copyleft licenses, unprotected routes, missing privacy policies, and risky card handling before committing or shipping.
      63 npm
      MIT