ez_token/lib.rs
1#![warn(missing_docs)]
2//! A CLI tool for requesting OAuth2 access tokens from Microsoft Entra ID and Auth0.
3//!
4//! > **Pronunciation:** `ez-token` is pronounced *"easy token"* — because getting
5//! > an OAuth2 token should be.
6//!
7//! # Contents
8//!
9//! - [Getting Started](#getting-started)
10//! - [Interactive Login](#interactive-login)
11//! - [Machine-to-Machine](#machine-to-machine)
12//! - [Configuration Profiles](#configuration-profiles)
13//! - [Security Warning](#security-warning)
14//!
15//! # Getting Started
16//!
17//! `ez-token` allows you to easily fetch and manage tokens without leaving the terminal.
18//! It supports standard OAuth2 flows and manages the heavy lifting of PKCE, local
19//! callbacks, and client credentials across multiple identity providers.
20//!
21//! If no `--provider` is passed and no profile is configured, you will be prompted
22//! to select an identity provider interactively using arrow keys.
23//!
24//! ## Interactive Login
25//!
26//! Starts an interactive PKCE flow that opens your default web browser to authenticate
27//! with your identity provider.
28//!
29//! ```text
30//! # Microsoft Entra ID
31//! ez-token login --provider microsoft --tenant-id <TENANT> --client-id <CLIENT>
32//!
33//! # Auth0
34//! ez-token login --provider auth0 --domain <DOMAIN> --client-id <CLIENT> --audience <AUDIENCE>
35//! ```
36//!
37//! ## Machine-to-Machine
38//!
39//! For machine-to-machine environments, CI/CD pipelines, or scripts, use the Client Credentials grant:
40//!
41//! ```text
42//! # Microsoft Entra ID
43//! ez-token m2m --provider microsoft --client-secret <SECRET>
44//!
45//! # Auth0 (requires a dedicated M2M application)
46//! ez-token m2m --provider auth0 --domain <DOMAIN> --audience <AUDIENCE> --client-secret <SECRET>
47//! ```
48//!
49//! # Configuration Profiles
50//!
51//! You can set up different profiles for different environments or providers
52//! using the `config` subcommand. This prevents you from having to re-enter
53//! your credentials every time.
54//!
55//! ```text
56//! # Save settings to a new "prod" profile
57//! ez-token --profile prod config set --provider microsoft --tenant-id <TENANT> --client-id <CLIENT>
58//!
59//! # Save an Auth0 profile
60//! ez-token --profile auth0-dev config set --provider auth0 --domain <DOMAIN> --client-id <CLIENT> --audience <AUDIENCE>
61//!
62//! # Use a profile for future logins
63//! ez-token --profile prod login
64//! ez-token --profile auth0-dev login
65//! ```
66//!
67//! # Security Warning
68//!
69//! Tokens and configuration data are stored locally on your machine. Ensure your
70//! configuration directory has the correct file permissions to prevent unauthorized access.
71//! The client secret used for M2M flows is never persisted to disk.
72
73/// Command-line interface definitions and user interaction layer.
74///
75/// Contains argument parsing via `clap`, interactive prompts, input history,
76/// and terminal output helpers. This module is intentionally kept separate
77/// from authentication logic — it handles only how the user communicates
78/// with the tool.
79pub mod cli;
80/// Subcommand handlers that orchestrate the CLI-to-service flow.
81///
82/// Each module corresponds to a top-level `ez-token` subcommand and is
83/// responsible for resolving inputs, invoking the appropriate service,
84/// and presenting results to the user.
85pub mod commands;
86/// Configuration file management for profiles and settings.
87///
88/// Handles loading and persisting user configuration via `confy`, including
89/// named profiles that store provider, Tenant ID or Domain, Client ID, and default Scopes.
90pub mod config;
91/// Core service implementations for authentication, HTTP, and local server.
92///
93/// Contains the OAuth2 flow implementations ([`services::authentication`]),
94/// the shared HTTP client ([`services::http_client`]), and the local callback
95/// server ([`services::local_server`]) used during interactive login.
96pub mod services;