# onelogin/onelogin_linux_pam_ssh architecture

> Architecture diagram of the GitHub repository onelogin/onelogin_linux_pam_ssh, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/onelogin/onelogin_linux_pam_ssh
- Repository: https://github.com/onelogin/onelogin_linux_pam_ssh

## Overview

##### Project type and purpose
- This is a containerized Linux PAM (Pluggable Authentication Module) integration for SSH that uses OneLogin’s REST API to perform role-based authorization and MFA.
- It’s not a traditional web full-stack app, but rather a security/infra tool: a PAM plugin written in Python, packaged in Docker, hooked into sshd to gate SSH logins through OneLogin.

##### File structure
- Top level:
- .gitignore, README.md
- docker-compose.yml → orchestrates the container
- docker/
– Dockerfile → builds the SSH + PAM + dependencies image
– dependencies/ → vendored Python libraries (requests, onelogin SDK, dateutil, etc.)
– etc/pam.d/sshd → SSH PAM config, points at our module
– etc/ssh/sshd_config → SSH daemon config, exposes port 2222
– src/onepam.py → the Python PAM module implementation
– src/template-onepam.json → template for the JSON config
– src/onepam.json → runtime config (region, client_id, secret, role IDs)
- writeup/ → documentation and images showing use-case and configuration

##### README for additional insights
- Describes the flow: user SSH → PAM module → prompts for OneLogin username and OTP → Python code calls OneLogin API → checks roles (admin vs. user) → grants or denies shell access.
- Explains how to provision roles in OneLogin, how to fill out onepam.json, and how to start via `docker-compose up`.

##### Final advice
- Every layer: host orchestration, container runtime, OS service (sshd), plugin (PAM), application logic (Python), external API.
- Don’t overcomplicate: break the system into these focused components and show the exact interactions.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Host Orchestration
    subgraph "Host & Orchestration"
        DOCKER_COMPOSE["Docker Compose Orchestration"]:::orchestration
        DOCKERFILE["Container Image Build Definition (Dockerfile)"]:::orchestration
        DOCKER_COMPOSE -->|"builds image via"| DOCKERFILE
    end

    %% Docker Container Boundary
    subgraph "Docker Container" 
        direction TB
        SSHD["SSH Daemon (sshd)"]:::service
        PAM_STACK["Linux PAM Stack\n(sshd invokes module)"]:::service
        ONEPAM_MODULE["onepam.py (PAM module)"]:::module
        JSON_CONFIG["onepam.json (Runtime Config)"]:::config
        TEMPLATE["template-onepam.json (Config Template)"]:::config
        DEPENDENCIES["Vendored Python Dependencies"]:::dependencies

        SSHD -->|"loads PAM"| PAM_STACK
        PAM_STACK -->|"executes module"| ONEPAM_MODULE
        JSON_CONFIG -->|"read config"| ONEPAM_MODULE
        DEPENDENCIES -->|"provides SDKs"| ONEPAM_MODULE
    end

    %% External Services
    subgraph "External Services"
        ONELOGIN_API["OneLogin Cloud REST API"]:::external
    end

    %% Documentation
    subgraph "Documentation"
        README["Project README"]:::docs
        WRITEUP_DOC["Writeup README"]:::docs
        WRITEUP_IMG["Writeup Images"]:::docs
    end

    %% User Interaction Flow
    SSH_CLIENT["SSH Client (User Terminal)"]:::external
    SSH_CLIENT -->|"ssh -p 2222"| SSHD
    ONEPAM_MODULE -->|"REST calls"| ONELOGIN_API
    ONELOGIN_API -->|"token & roles"| ONEPAM_MODULE
    ONEPAM_MODULE -->|"success/failure"| PAM_STACK
    PAM_STACK -->|"permit or deny"| SSHD
    SSHD -->|"shell granted or rejected"| SSH_CLIENT

    %% Click Events
    click DOCKER_COMPOSE "https://github.com/onelogin/onelogin_linux_pam_ssh/blob/master/docker-compose.yml"
    click DOCKERFILE "https://github.com/onelogin/onelogin_linux_pam_ssh/tree/master/docker/Dockerfile"
    click SSHD_CONFIG "https://github.com/onelogin/onelogin_linux_pam_ssh/tree/master/docker/etc/ssh/sshd_config"
    click PAM_CONFIG "https://github.com/onelogin/onelogin_linux_pam_ssh/tree/master/docker/etc/pam.d/sshd"
    click ONEPAM_MODULE "https://github.com/onelogin/onelogin_linux_pam_ssh/blob/master/docker/src/onepam.py"
    click TEMPLATE "https://github.com/onelogin/onelogin_linux_pam_ssh/blob/master/docker/src/template-onepam.json"
    click DEPENDENCIES "https://github.com/onelogin/onelogin_linux_pam_ssh/tree/master/docker/dependencies"
    click README "https://github.com/onelogin/onelogin_linux_pam_ssh/blob/master/README.md"
    click WRITEUP_DOC "https://github.com/onelogin/onelogin_linux_pam_ssh/blob/master/writeup/README.md"
    click WRITEUP_IMG "https://github.com/onelogin/onelogin_linux_pam_ssh/tree/master/writeup/img/"

    %% Styles
    classDef orchestration fill:#E8F1F2,stroke:#333,stroke-width:1px
    classDef service fill:#D1E8E2,stroke:#333,stroke-width:1px
    classDef module fill:#FDF6E3,stroke:#333,stroke-width:1px
    classDef config fill:#FEEFEF,stroke:#333,stroke-width:1px
    classDef dependencies fill:#EFEFFF,stroke:#333,stroke-width:1px
    classDef external fill:#FCF4D9,stroke:#333,stroke-width:1px
    classDef docs fill:#F0F0F0,stroke:#333,stroke-width:1px
```
