How viasat/alohomora works
Project Type and Purpose
• The project is a CLI utility written in Python.
• Its purpose is to help SAML-federated users obtain AWS API keys by authenticating with an Identity Provider and optionally using MFA (e.g., Duo Security or WebAuthN).
• The README outlines several usage patterns, configuration options, and even integration scenarios (like custom configuration profiles and AWS partition selection), indicating a focus on both security and flexibility.
File Structure and Key Components
• The top-level directories/files indicate:
• The main application code under the "alohomora" directory, including the primary entry point (main.py) and modules for handling SAML (saml.py), AWS key generation (keys.py), and request flow (req.py).
• Build and packaging support through setup.py and setup.cfg.
• Specs in the “specs” directory, representing package metadata or distribution requirements.
• CI/CD configuration in the ".github/workflows" directory, hinting that automated testing and package publishing are in place.
• This structure reinforces that the project is highly modular, with distinct responsibilities spread across multiple modules.
Key Components
a. Main Application Flow:
• CLI Entry: Represented by alohomora/main.py (where command-line input is handled).
• Configuration Loader: Loads user config from ~/.alohomora and/or parses CLI parameters.
• SAML Authentication: Implemented using alohomora/saml.py, responsible for handling the SAML authentication flow.
• MFA Integration: For additional security through Duo and optional WebAuthN (this may branch out from SAML when MFA is required).
• Request Handling: Managed by alohomora/req.py to process SAML responses and determine the roles/accounts.
• AWS Credentials: Finally, handled through alohomora/keys.py to store the AWS API keys in the appropriate location.
b. Build & Integration Block:
• Packaging: Reflect the role of setup.py and setup.cfg in assembling and publishing the software.
• Specs: Represented by the “specs” directory, which may contain distribution or spec files.
• CI/CD Integration: Illustrated by the presence of GitHub Actions workflows (python-publish.yml) that automate tests and deployment processes.
Relationships and Interactions
• The user initiates the process via the CLI which then goes through a series of steps:
• User → CLI Entry Point (main.py)
• Main.py loads configurations and calls SAML authentication.
• In the SAML module, if multi-factor authentication is required, the flow branches to the MFA module (Duo/WebAuthN) which then returns control.
• SAML then calls the request handler, and based on the response, the keys module manages AWS credential processing.
• On the “build & integration” side, packaging components and CI/CD tools ensure quality and smooth deployment flows.
Incorporating the Provided Flowchart
Flowchart Breakdown:
• Flow from the User to the CLI Entry Point (alohomora/main.py) with a label such as “invokes”.
• From the CLI, illustrate the two parallel flows: one to load configuration (from ~/.alohomora and CLI parameters) and the other to initiate SAML.
• From the SAML component, if MFA is triggered, show the branch to “MFA Integration (Duo/WebAuthN)” and back.