# nithe14/pam_oauth2_device architecture

> Architecture diagram of the GitHub repository nithe14/pam_oauth2_device, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nithe14/pam_oauth2_device
- Repository: https://github.com/nithe14/pam_oauth2_device

## Overview

This repository is a PAM authentication module using OAuth 2.0 Device Authorization Grant. Its main workflow loads configuration and logging options, obtains a device code, prompts the user to authorize, polls for an access token, introspects it, and validates the returned identity, scopes, and expiry before reporting a PAM result. The graph includes configuration, prompt rendering, OAuth operations, validation, and logging; external PAM and authorization-server interactions are shown where documented or evidenced by the excerpts.

Main entry points: [`src/lib.rs`](https://github.com/nithe14/pam_oauth2_device/blob/master/src/lib.rs) (Authentication Handler), [`src/oauth_device.rs`](https://github.com/nithe14/pam_oauth2_device/blob/master/src/oauth_device.rs) (Device Authorization), [`src/prompt.rs`](https://github.com/nithe14/pam_oauth2_device/blob/master/src/prompt.rs) (User Prompt), [`src/config.rs`](https://github.com/nithe14/pam_oauth2_device/blob/master/src/config.rs) (Config Loader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_pam["PAM Authentication"]
  node_auth_entry["Authentication Handler<br/>[lib.rs]"]
  node_pam_prompt["PAM Conversation"]
  node_prompt_render["User Prompt<br/>[prompt.rs]"]
  node_qr_render["QR Rendering<br/>[prompt.rs]"]
end

subgraph group_oauth["OAuth Device Flow"]
  node_oauth_client["OAuth Client<br/>[oauth_device.rs]"]
  node_device_auth["Device Authorization<br/>[oauth_device.rs]"]
  node_token_poll["Token Polling<br/>[oauth_device.rs]"]
  node_introspection["Token Introspection<br/>[oauth_device.rs]"]
  node_token_validation["Token Validation<br/>[oauth_device.rs]"]
end

subgraph group_support["Configuration and Support"]
  node_config["Config Loader<br/>[config.rs]"]
  node_logger[("File Logger<br/>[logger.rs]")]
end

node_user(("Login User"))
node_pam_framework["PAM Framework"]
node_auth_server["Authorization Server"]

node_user -->|"requests login"| node_pam_framework
node_pam_framework -->|"dispatches auth"| node_auth_entry
node_auth_entry -->|"loads config"| node_config
node_auth_entry -->|"initializes logging"| node_logger
node_auth_entry -->|"builds client"| node_oauth_client
node_auth_entry -->|"requests device code"| node_device_auth
node_oauth_client -->|"configures flow"| node_device_auth
node_device_auth -->|"requests device code"| node_auth_server
node_auth_entry -->|"builds prompt"| node_prompt_render
node_prompt_render -->|"generates QR"| node_qr_render
node_auth_entry -->|"sends prompt"| node_pam_prompt
node_pam_prompt -->|"displays instructions"| node_user
node_auth_entry -->|"polls token"| node_token_poll
node_token_poll -->|"requests access token"| node_auth_server
node_auth_entry -->|"introspects token"| node_introspection
node_introspection -->|"sends introspection request"| node_auth_server
node_auth_entry -->|"validates response"| node_token_validation
node_auth_entry -->|"returns PAM result"| node_pam_framework

click node_auth_entry "https://github.com/nithe14/pam_oauth2_device/blob/master/src/lib.rs"
click node_config "https://github.com/nithe14/pam_oauth2_device/blob/master/src/config.rs"
click node_logger "https://github.com/nithe14/pam_oauth2_device/blob/master/src/logger.rs"
click node_oauth_client "https://github.com/nithe14/pam_oauth2_device/blob/master/src/oauth_device.rs"
click node_device_auth "https://github.com/nithe14/pam_oauth2_device/blob/master/src/oauth_device.rs"
click node_prompt_render "https://github.com/nithe14/pam_oauth2_device/blob/master/src/prompt.rs"
click node_qr_render "https://github.com/nithe14/pam_oauth2_device/blob/master/src/prompt.rs"
click node_token_poll "https://github.com/nithe14/pam_oauth2_device/blob/master/src/oauth_device.rs"
click node_introspection "https://github.com/nithe14/pam_oauth2_device/blob/master/src/oauth_device.rs"
click node_token_validation "https://github.com/nithe14/pam_oauth2_device/blob/master/src/oauth_device.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_auth_entry,node_pam_prompt,node_prompt_render,node_qr_render,node_user toneBlue
class node_oauth_client,node_device_auth,node_token_poll,node_introspection,node_token_validation toneAmber
class node_config,node_logger,node_auth_server toneMint
class node_pam_framework toneIndigo
```

## Components

### PAM Authentication

- [Authentication Handler](https://github.com/nithe14/pam_oauth2_device/blob/master/src/lib.rs): `src/lib.rs`
- **PAM Conversation**
- [User Prompt](https://github.com/nithe14/pam_oauth2_device/blob/master/src/prompt.rs): `src/prompt.rs`
- [QR Rendering](https://github.com/nithe14/pam_oauth2_device/blob/master/src/prompt.rs): `src/prompt.rs`

### OAuth Device Flow

- [OAuth Client](https://github.com/nithe14/pam_oauth2_device/blob/master/src/oauth_device.rs): `src/oauth_device.rs`
- [Device Authorization](https://github.com/nithe14/pam_oauth2_device/blob/master/src/oauth_device.rs): `src/oauth_device.rs`
- [Token Polling](https://github.com/nithe14/pam_oauth2_device/blob/master/src/oauth_device.rs): `src/oauth_device.rs`
- [Token Introspection](https://github.com/nithe14/pam_oauth2_device/blob/master/src/oauth_device.rs): `src/oauth_device.rs`
- [Token Validation](https://github.com/nithe14/pam_oauth2_device/blob/master/src/oauth_device.rs): `src/oauth_device.rs`

### Configuration and Support

- [Config Loader](https://github.com/nithe14/pam_oauth2_device/blob/master/src/config.rs): `src/config.rs`
- [File Logger](https://github.com/nithe14/pam_oauth2_device/blob/master/src/logger.rs): `src/logger.rs`

### Other components

- **Login User**
- **PAM Framework**
- **Authorization Server**

## Connections

- Login User → PAM Framework: requests login (evidence: `README.md`)
- PAM Framework → Authentication Handler: dispatches auth (evidence: `src/lib.rs`)
- Authentication Handler → Config Loader: loads config (evidence: `src/lib.rs`)
- Authentication Handler → File Logger: initializes logging (evidence: `src/lib.rs`)
- Authentication Handler → OAuth Client: builds client (evidence: `src/lib.rs`)
- Authentication Handler → Device Authorization: requests device code (evidence: `src/lib.rs`)
- OAuth Client → Device Authorization: configures flow (evidence: `src/oauth_device.rs`)
- Device Authorization → Authorization Server: requests device code (evidence: `README.md`)
- Authentication Handler → User Prompt: builds prompt (evidence: `src/lib.rs`)
- User Prompt → QR Rendering: generates QR (evidence: `src/prompt.rs`)
- Authentication Handler → PAM Conversation: sends prompt (evidence: `src/lib.rs`)
- PAM Conversation → Login User: displays instructions (evidence: `README.md`)
- Authentication Handler → Token Polling: polls token (evidence: `src/lib.rs`)
- Token Polling → Authorization Server: requests access token (evidence: `README.md`)
- Authentication Handler → Token Introspection: introspects token (evidence: `src/lib.rs`)
- Token Introspection → Authorization Server: sends introspection request (evidence: `README.md`)
- Authentication Handler → Token Validation: validates response (evidence: `src/lib.rs`)
- Authentication Handler → PAM Framework: returns PAM result (evidence: `src/lib.rs`)
