docs: document okta_saml configuration and auth flow

README.md

@@ -6,7 +6,7 @@ It combines a Bubble Tea application, Cobra-based CLI commands, and AWS SDK v2 c
 ## What It Does
 
 - Browse AWS services from a single terminal UI
-- Switch between credential, assume-role, and SSO contexts
+- Switch between credential, assume-role, SSO, and Okta SAML contexts
 - Export shell environment variables for the active context
 - Drill down into resources with filters, detail views, and action screens
 - Open a context-aware keyboard shortcut help screen with `?`
@@ -209,6 +209,13 @@ contexts:
     profile: staging
     region: eu-west-1
     auth_type: credential
+
+  - name: okta-prod
+    region: ap-northeast-2
+    auth_type: okta_saml
+    okta_org_url: https://acme.okta.com
+    okta_app_id: amazon_aws/0oa1b2c3d4e5f6g7h8i9/272
+    role_arn: arn:aws:iam::123456789012:role/OktaAdmin   # required when the assertion carries multiple roles
 ```
 
 ### Auth Types
@@ -227,6 +234,28 @@ Legacy flat fields (`auth_type`, `profile`, `region`, `regions`, `sso_region`, a
 
 TUI startup is passive for SSO contexts: it loads the context picker without launching `aws sso login`. SSO login is prompted when you explicitly select or set up an SSO context, or when an AWS-backed workflow needs credentials.
 
+### Okta SAML Contexts
+
+`okta_saml` contexts federate into AWS through an Okta AWS app:
+
+```bash
+# Sign in to Okta and export session credentials
+eval "$(unic env okta-prod)"
+
+# Non-interactive (CI or scripts)
+UNIC_OKTA_USERNAME=user@acme.com UNIC_OKTA_PASSWORD=... unic env okta-prod
+```
+
+Runtime flow: Okta primary authentication → optional MFA challenge → SAML assertion from the app embed link → `sts:AssumeRoleWithSAML` → session credentials cached under `~/.config/unic/cache/okta-saml/` until expiry. The TUI reuses a valid cached session passively and otherwise asks you to run `unic env <context>` first — it never prompts for Okta credentials itself.
+
+`okta_app_id` is the app-specific part of the Okta app embed link: for `https://acme.okta.com/home/amazon_aws/0oa1b2c3d4e5f6g7h8i9/272`, use `amazon_aws/0oa1b2c3d4e5f6g7h8i9/272`.
+
+v1 limitations:
+
+- MFA factors: TOTP (`token:software:totp`) and Okta Verify push only. TOTP is preferred when both are enrolled; push polls for approval with a 60s deadline. Other factors fail with a list of what was found.
+- Role selection is deterministic: `role_arn` wins, a single assertion role is auto-selected, and multiple roles without `role_arn` produce an explicit error listing the ARNs.
+- Passwords, one-time codes, and Okta session tokens are never persisted; only the exchanged AWS session credentials are cached (0600 files in a 0700 directory).
+
 Optional context fields:
 
 | Field | Meaning |

docs/architecture.en.md

@@ -165,7 +165,7 @@ Supporting files include `styles.go`, `filter.go`, and `messages.go`.
 
 ## Authentication Model
 
-UNIC supports four main auth modes.
+UNIC supports five main auth modes.
 
 ### `credential`
 
@@ -189,6 +189,15 @@ UNIC supports four main auth modes.
 - with `mfa_serial` set, CLI flows (`unic env`, `unic context setup`) prompt for a token code on stderr and cache the session credentials under `~/.config/unic/cache/assume-role/` until expiry
 - the TUI passively reuses a valid cached session and otherwise fails with a pointer to `unic env <context>`
 
+### `okta_saml`
+
+- SAML federation through an Okta AWS app
+- `unic env` runs Okta primary authentication and, when required, an MFA challenge (v1: TOTP and Okta Verify push)
+- the SAML assertion is fetched from the app embed link and exchanged via `sts:AssumeRoleWithSAML`
+- role selection is deterministic: `role_arn` wins, a single role is auto-selected, multiple roles error explicitly
+- only the exchanged AWS session credentials are cached under `~/.config/unic/cache/okta-saml/`; passwords, one-time codes, and Okta session tokens are never persisted
+- the TUI passively reuses a valid cached session and otherwise points at `unic env <context>`
+
 ### `sso`
 
 Two shapes exist:

docs/architecture.ko.md

@@ -165,7 +165,7 @@ Bubble Tea 앱의 상태, 화면 전환, 렌더링을 담당한다.
 
 ## 인증 모델
 
-UNIC은 현재 세 가지 인증 모드를 지원한다.
+UNIC은 현재 다섯 가지 인증 모드를 지원한다.
 
 ### `credential`
 
@@ -189,6 +189,15 @@ UNIC은 현재 세 가지 인증 모드를 지원한다.
 - login 이후에도 profile 기반이므로 `unic env`는 `AWS_PROFILE`과 region 변수를 export
 - 현재는 standalone context로만 지원하며 `role_arn` chaining은 지원하지 않음
 
+### `okta_saml`
+
+- Okta AWS 앱을 통한 SAML federation
+- `unic env`가 Okta primary authentication을 수행하고, 필요하면 MFA challenge(v1: TOTP, Okta Verify push)를 처리한다
+- app embed link에서 SAML assertion을 가져와 `sts:AssumeRoleWithSAML`로 교환한다
+- role 선택은 결정적이다: `role_arn` 우선, 단일 role 자동 선택, 복수 role은 명시적 에러
+- 교환된 세션 자격증명만 `~/.config/unic/cache/okta-saml/`에 캐시하고, 비밀번호/OTP/Okta 세션 토큰은 저장하지 않는다
+- TUI는 유효한 캐시 세션을 passive하게 재사용하고, 없으면 `unic env <context>`를 안내한다
+
 ### `sso`
 
 두 가지 형태가 있다.

docs/project-overview.en.md

@@ -4,7 +4,7 @@ UNIC is a Go-based AWS terminal console that combines:
 
 - a Bubble Tea TUI for browsing and operating AWS resources
 - Cobra CLI helpers for context setup and environment export
-- context-aware authentication across credential, assume-role, and SSO workflows
+- context-aware authentication across credential, assume-role, SSO, and Okta SAML workflows
 
 ## Current Scope
 
@@ -48,6 +48,7 @@ The app supports:
 - `console_login` auth for AWS CLI `aws login`-backed local development profiles
 - `assume_role` auth
 - `sso` auth, including base contexts resolved by `unic context setup`
+- `okta_saml` auth using the Okta app embed link and `sts:AssumeRoleWithSAML` (v1 MFA: TOTP and Okta Verify push)
 
 ## Repository Layout
 

docs/project-overview.ko.md

@@ -4,7 +4,7 @@ UNIC은 다음 세 가지를 결합한 Go 기반 AWS 터미널 콘솔이다.
 
 - AWS 리소스를 탐색하고 조작하는 Bubble Tea TUI
 - context setup / env export를 위한 Cobra CLI helper
-- credential, assume-role, SSO를 아우르는 context-aware 인증 흐름
+- credential, assume-role, SSO, Okta SAML을 아우르는 context-aware 인증 흐름
 
 ## 현재 범위
 
@@ -48,6 +48,7 @@ Inspector mode는 이제 built-in security scan과 함께 RDS, security group, s
 - AWS CLI `aws login` 기반 로컬 개발 profile을 위한 `console_login` 인증
 - `assume_role` 인증
 - `unic context setup`으로 concrete context를 만드는 `sso` 인증
+- Okta 앱 embed link와 `sts:AssumeRoleWithSAML`을 사용하는 `okta_saml` 인증 (v1 MFA: TOTP, Okta Verify push)
 
 ## 저장소 구조