Skip to content

awxkit: Support --conf.token/CONTROLLER_OAUTH_TOKEN#16384

Open
lalten wants to merge 4 commits intoansible:develfrom
lalten:awxkit-token-auth
Open

awxkit: Support --conf.token/CONTROLLER_OAUTH_TOKEN#16384
lalten wants to merge 4 commits intoansible:develfrom
lalten:awxkit-token-auth

Conversation

@lalten
Copy link
Copy Markdown

@lalten lalten commented Apr 1, 2026

SUMMARY

Add OAuth2 Bearer token authentication to the awx CLI.

The CLI currently only supports session-based login (POST /api/login/ with username+password) and HTTP Basic auth (via AWXKIT_FORCE_BASIC_AUTH). Neither works for users who authenticate through social auth providers (e.g. GitHub SSO), since they have no local AWX password.

AWX supports creating OAuth2 personal access tokens (User → Tokens → Add), and the API accepts them via Authorization: Bearer <token>. This PR adds native CLI support for this auth method through:

  • A new --conf.token CLI flag
  • CONTROLLER_OAUTH_TOKEN / TOWER_OAUTH_TOKEN environment variables
  • token field in AWXKIT_CREDENTIAL_FILE

When a token is provided, it is sent as a Bearer token in the Authorization header, bypassing session and basic auth entirely.

ISSUE TYPE
  • New or Enhanced Feature
COMPONENT NAME
  • CLI
STEPS TO REPRODUCE AND EXTRA INFO

n/a

Summary by CodeRabbit

  • New Features

    • Added OAuth2 token authentication as an alternative to username/password.
    • Tokens can be supplied via CLI flag, environment variables, or credential files.
    • Token-based auth takes precedence over basic auth; empty tokens fall back to session-based auth.
  • Tests

    • Added comprehensive tests covering token sources, precedence, and fallback behavior.
  • Documentation

    • Added guidance and examples for OAuth2 token usage and the new CLI option.

@coderabbitai
Copy link
Copy Markdown

coderabbitai bot commented Apr 1, 2026

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: da0caee1-6173-4374-9fd8-86cc6771419b

📥 Commits

Reviewing files that changed from the base of the PR and between e6e97a4 and 20740fa.

📒 Files selected for processing (2)
  • awxkit/awxkit/cli/docs/source/authentication.rst
  • awxkit/awxkit/cli/docs/source/usage.rst
✅ Files skipped from review due to trivial changes (2)
  • awxkit/awxkit/cli/docs/source/usage.rst
  • awxkit/awxkit/cli/docs/source/authentication.rst

📝 Walkthrough

Walkthrough

Adds OAuth2 Bearer-token support to the CLI: config/CLI parsing now supplies a token, and CLI.authenticate() uses a non-empty token to set Authorization: Bearer <token> on the session and returns early, bypassing username/password or session-based authentication.

Changes

Cohort / File(s) Summary
OAuth2 Authentication Implementation
awxkit/awxkit/cli/client.py
authenticate() reads token from config and, if present/non-empty, sets session.headers['Authorization'] = 'Bearer <token>' and returns early instead of performing basic/session auth.
CLI Configuration & Arguments
awxkit/awxkit/cli/format.py
get_config_credentials() now returns (username, password, token). add_authentication_arguments() adds --conf.token with defaults from CONTROLLER_OAUTH_TOKEN/TOWER_OAUTH_TOKEN and documents that token overrides username/password.
Authentication Tests
awxkit/test/cli/test_authentication.py
Added setup_token_auth() helper and tests verifying Bearer header set from CLI/env, that token auth takes precedence over basic auth, and that an empty token falls through to session-based auth.
Configuration Tests
awxkit/test/cli/test_config.py
New tests for token resolution: CONTROLLER_OAUTH_TOKEN vs TOWER_OAUTH_TOKEN, CLI flag precedence, credential file fallback, and env-var precedence over credential file.
Documentation
awxkit/awxkit/cli/docs/source/authentication.rst, awxkit/awxkit/cli/docs/source/usage.rst
Added OAuth2 Token Authentication docs and --conf.token usage notes; state token precedence over username/password.

Sequence Diagram(s)

sequenceDiagram
    participant CLI
    participant Config
    participant Auth
    participant Session

    CLI->>Config: get_config('token')
    Config-->>CLI: token

    alt token present and non-empty
        CLI->>Auth: authenticate()
        Auth->>Session: set session.headers['Authorization'] = "Bearer {token}"
        Session-->>Auth: header set
        Auth-->>CLI: return (early)
    else token absent or empty
        CLI->>Auth: authenticate()
        Auth->>Session: load_session() / login() (basic/session auth)
        Session-->>Auth: session established
        Auth-->>CLI: return
    end
Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

🚥 Pre-merge checks | ✅ 3
✅ Passed checks (3 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title directly and concisely summarizes the main change: adding OAuth2 token authentication support via the --conf.token flag and CONTROLLER_OAUTH_TOKEN environment variable to the awxkit CLI.
Docstring Coverage ✅ Passed Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

Copy link
Copy Markdown

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick comments (2)
awxkit/test/cli/test_authentication.py (2)

140-155: Assert session path is skipped in all token-auth tests

test_oauth_token_from_env_var and test_oauth_token_precedence_over_basic_auth should also assert load_session is never called, to fully lock in the “Bearer token returns early” behavior.

Proposed patch
 def test_oauth_token_from_env_var():
@@
     assert mock_connection.session.headers['Authorization'] == 'Bearer env_token_value'
     mock_connection.login.assert_not_called()
+    mock_root.load_session.assert_not_called()
@@
 def test_oauth_token_precedence_over_basic_auth(monkeypatch):
@@
     assert mock_connection.session.headers['Authorization'] == 'Bearer my_token'
     mock_connection.login.assert_not_called()
+    mock_root.load_session.assert_not_called()

Also applies to: 157-165

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@awxkit/test/cli/test_authentication.py` around lines 140 - 155, The tests for
token-based auth need to assert that session loading is skipped; update
test_oauth_token_from_env_var and test_oauth_token_precedence_over_basic_auth to
verify load_session is never invoked. Mock or spy on the CLI.load_session (or
the instance method used to restore sessions) before calling cli.authenticate(),
then add an assertion like cli.load_session.assert_not_called() after
authenticate() to lock in the “Bearer token returns early” behavior; reference
the CLI.parse_args and CLI.authenticate calls already in the test to locate
where to add the mock and assertion.

133-133: Fix Ruff RUF059: unused unpacked variable

mock_root is unpacked but unused in two tests, which trips lint and adds noise.

Proposed patch
-    cli, mock_root, mock_connection = setup_token_auth(['awx', '--conf.token', 'cli_token_value'])
+    cli, _mock_root, mock_connection = setup_token_auth(['awx', '--conf.token', 'cli_token_value'])
@@
-    cli, mock_root, mock_connection = setup_token_auth(['awx', '--conf.token', 'my_token', '--conf.username', 'user', '--conf.password', 'pass'])
+    cli, _mock_root, mock_connection = setup_token_auth(['awx', '--conf.token', 'my_token', '--conf.username', 'user', '--conf.password', 'pass'])

Also applies to: 159-159

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@awxkit/test/cli/test_authentication.py` at line 133, The test unpacks a
third-party helper return into cli, mock_root, mock_connection but never uses
mock_root, triggering Ruff RUF059; update the unpacking in the tests that call
setup_token_auth (e.g., where variables cli, mock_root, mock_connection are
assigned) to ignore the unused value by renaming it to a throwaway identifier
(for example cli, _mock_root, mock_connection or cli, _, mock_connection) or by
only assigning the two used values from the tuple, and apply the same change to
the other occurrence of the pattern in the file.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@awxkit/test/cli/test_authentication.py`:
- Around line 140-155: The tests for token-based auth need to assert that
session loading is skipped; update test_oauth_token_from_env_var and
test_oauth_token_precedence_over_basic_auth to verify load_session is never
invoked. Mock or spy on the CLI.load_session (or the instance method used to
restore sessions) before calling cli.authenticate(), then add an assertion like
cli.load_session.assert_not_called() after authenticate() to lock in the “Bearer
token returns early” behavior; reference the CLI.parse_args and CLI.authenticate
calls already in the test to locate where to add the mock and assertion.
- Line 133: The test unpacks a third-party helper return into cli, mock_root,
mock_connection but never uses mock_root, triggering Ruff RUF059; update the
unpacking in the tests that call setup_token_auth (e.g., where variables cli,
mock_root, mock_connection are assigned) to ignore the unused value by renaming
it to a throwaway identifier (for example cli, _mock_root, mock_connection or
cli, _, mock_connection) or by only assigning the two used values from the
tuple, and apply the same change to the other occurrence of the pattern in the
file.

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: d0463233-939f-46bc-a51c-62f96fbccdbd

📥 Commits

Reviewing files that changed from the base of the PR and between d48a8c5 and e6e97a4.

📒 Files selected for processing (1)
  • awxkit/test/cli/test_authentication.py

lalten and others added 2 commits April 2, 2026 12:17
Document the new --conf.token flag, CONTROLLER_OAUTH_TOKEN and
TOWER_OAUTH_TOKEN environment variables, and credential file token
support in the authentication and usage documentation.
@lalten
Copy link
Copy Markdown
Author

lalten commented Apr 2, 2026

ha, I just saw that this was already added very recently in #16281 and then removed in #16293...

@stevensonmichel can you shine some light on what is the plan here? As far as I can see there is no other way than tokens to use the awx cli for SSO users, right?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant