Skip to content

Commit 4b62cbc

Browse files
oshea00oshea00
authored
Merge pull request #2 from oshea00/v0.0.2
V0.0.2
2 parents 0f0706d + aca78c7 commit 4b62cbc

File tree

6 files changed

+744
-17
lines changed

6 files changed

+744
-17
lines changed

‎.python-version‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
3.11

‎CLAUDE.md‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Project Overview
6+
7+
This is a Python CLI tool called `okta-saml` that authenticates users against Okta and retrieves temporary JWT credentials for SAML-enabled APIs. The tool performs SAML assertion-based authentication and stores the resulting JWT tokens for API access.
8+
9+
## Architecture
10+
11+
The codebase is organized into the `oktasamlcli` package with the following key modules:
12+
13+
- **okta_samlcli.py**: Main CLI entry point using Click framework. Handles command-line arguments and orchestrates the authentication flow
14+
- **okta_auth.py**: Core Okta authentication logic - handles primary auth, session management, authorization code flow, and JWT token retrieval
15+
- **saml_auth.py**: SAML assertion processing and JWT token management - extracts client credentials from SAML assertions and manages credential storage
16+
- **okta_auth_config.py**: Configuration management for Okta profiles from `~/.okta-saml` file
17+
18+
### Authentication Flow
19+
20+
The application follows this flow:
21+
1. Authenticate with Okta using username/password
22+
2. Retrieve SAML assertion from configured app link
23+
3. Extract ClientID and ClientSecret from SAML assertion attributes
24+
4. Perform OAuth2 authorization code flow
25+
5. Obtain JWT access token
26+
6. Store credentials in `~/.saml/credentials` or output to console
27+
28+
## Development Commands
29+
30+
This project uses [uv](https://docs.astral.sh/uv/) for fast, reliable Python package management.
31+
32+
### Installation
33+
```bash
34+
# Install dependencies and the package in development mode
35+
uv sync
36+
37+
# Or install the package directly
38+
uv pip install .
39+
```
40+
41+
### Running the CLI
42+
```bash
43+
# Run with uv
44+
uv run okta-saml --profile <profile_name>
45+
46+
# Or if installed globally
47+
okta-saml --profile <profile_name>
48+
```
49+
50+
### Configuration
51+
```bash
52+
okta-saml --config # Initialize new Okta profile configuration
53+
```
54+
55+
### Dependency Management
56+
```bash
57+
# Add a new dependency
58+
uv add <package-name>
59+
60+
# Update dependencies
61+
uv lock --upgrade
62+
63+
# Sync dependencies (install/update based on lockfile)
64+
uv sync
65+
```
66+
67+
## Dependencies
68+
69+
This project uses:
70+
- **requests**: HTTP client for Okta API calls
71+
- **click**: CLI framework for command-line interface
72+
- **beautifulsoup4**: HTML/XML parsing for SAML responses
73+
- **validators**: Input validation
74+
- **configparser**: Configuration file management (Python built-in)
75+
76+
## Configuration Files
77+
78+
- **~/.okta-saml**: Main configuration file containing Okta profiles with base-url, app-link, username, etc.
79+
- **~/.saml/credentials**: Stored JWT credentials organized by profile
80+
- **pyproject.toml**: Python packaging configuration using setuptools and uv
81+
- **uv.lock**: Dependency lockfile for reproducible installations
82+
- **.python-version**: Specifies Python 3.11+ requirement
83+
- **requirements.txt**: Legacy dependency list (maintained for backwards compatibility)
84+
85+
## Key Classes and Methods
86+
87+
- `OktaAuth.get_assertion()`: Retrieves SAML assertion from Okta
88+
- `OktaAuth.get_auth_code()`: Performs OAuth2 authorization code flow
89+
- `OktaAuth.get_jwt_token()`: Exchanges auth code for JWT access token
90+
- `SamlAuth.extract_clientid_from()`: Extracts client ID from SAML assertion
91+
- `SamlAuth.check_jwt_token()`: Validates existing JWT token expiration
92+
- `SamlAuth.write_jwt_token()`: Stores JWT token to credentials file
93+
94+
## Security Considerations
95+
96+
The application handles sensitive authentication data including:
97+
- Okta user credentials (optionally stored in config)
98+
- JWT access tokens (stored in ~/.saml/credentials)
99+
- Client secrets from SAML assertions
100+
- Session tokens during authentication flow

‎oktasamlcli/version.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,2 @@
11
""" version string """
2-
__version__ = '0.0.1'
2+
__version__ = '0.0.2'

‎pyproject.toml‎

Lines changed: 15 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,28 @@
11
[build-system]
2-
requires = ["setuptools"]
2+
requires = ["setuptools>=61.0"]
33
build-backend = "setuptools.build_meta"
44

55
[project]
66
name = "okta-saml"
77
authors = [
8-
{name="Mike Oshea",email="oshea00@gmail.com"}
8+
{name="Mike Oshea", email="oshea00@gmail.com"}
99
]
1010
description = "Utility to obtain saml api jwt from OKTA"
1111
readme = "README.md"
12-
requires-python = ">=3.8"
13-
version = "0.0.1"
12+
requires-python = ">=3.11"
13+
version = "0.0.2"
1414
dependencies = [
15-
"requests==2.27.1",
16-
"click==7.0",
17-
"beautifulsoup4==4.11.1",
18-
"ConfigParser==3.5.0",
19-
"validators==0.11.2",
15+
"requests>=2.32.3",
16+
"click>=8.0",
17+
"beautifulsoup4>=4.12.0",
18+
"validators>=0.22.0",
2019
]
20+
2121
[project.scripts]
2222
okta-saml = "oktasamlcli.okta_samlcli:main"
23+
24+
[tool.uv]
25+
dev-dependencies = [
26+
"build>=1.0.0",
27+
"twine>=6.2.0",
28+
]

‎requirements.txt‎

Lines changed: 8 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,9 @@
1-
requests==2.27.1
2-
click==7.0
3-
beautifulsoup4==4.11.1
4-
ConfigParser==3.5.0
5-
validators==0.11.2
6-
setuptools
7-
build
1+
# This file is maintained for backwards compatibility.
2+
# The project now uses uv for dependency management.
3+
# See pyproject.toml for the canonical dependency list.
4+
5+
requests>=2.32.3
6+
click>=8.0
7+
beautifulsoup4>=4.12.0
8+
validators>=0.22.0
89

0 commit comments

Comments
 (0)