AAP 2.7: Removing Direct API Access — Migration Guide and aap-detect-direct-component-access Tool

Ansible Automation Platform 2.7 removes direct external API access to platform components — automation controller, Automation Hub, and Event-Driven Ansible (automation decisions). All external API calls now go through the platform gateway, and basic authentication and personal access tokens (PATs) for direct component access are disabled. This is a breaking change for any scripts, CI pipelines, or integrations that call component APIs directly.

This article explains exactly what changed, how to find affected scripts using the aap-detect-direct-component-access CLI tool, and how to migrate to the gateway API.

What Was Removed

Direct External Routes and Ingress

In AAP 2.7 containerized and operator deployments, the external routes and ingress endpoints that previously exposed automation controller, Automation Hub, and EDA directly to the network are removed. Traffic that previously hit https://controller.corp.example.com/api/v2/ now must go through https://aap.corp.example.com/api/controller/v2/ via the platform gateway.

Basic Authentication

Basic auth (username/password in HTTP headers) is disabled for:

• Automation controller API
• Automation Hub API
• Event-Driven Ansible API

Personal Access Tokens for Direct Component APIs

PATs issued directly by automation controller or Automation Hub for component-level access are disabled. Tokens must now be issued by the platform gateway and scoped at the gateway level.

External Authentication Providers in Components

Third-party authentication providers (LDAP, SAML, OIDC) configured directly in automation controller or Automation Hub are removed. Authentication is now configured once at the platform gateway level and applies uniformly across all components.

See also: Ansible AAP as OIDC Authentication Provider for HashiCorp Vault: Zero Trust Workflow

What Remains Available

Finding Legacy Usage with aap-detect-direct-component-access

Red Hat ships a new CLI utility — aap-detect-direct-component-access — to identify scripts, playbooks, and configurations that still call component APIs directly. It is available on containerized and operator-based deployments.

Running the Tool

On a containerized AAP deployment:

# Run from the AAP installer host
aap-detect-direct-component-access \
  --inventory /etc/ansible-automation-platform/inventory \
  --report-format table

On OpenShift operator deployments:

# Run as a job in the AAP namespace
oc run detect-direct-access \
  --image=registry.redhat.io/ansible-automation-platform/aap-utils-rhel9:2.7 \
  --restart=Never \
  --env="AAP_NAMESPACE=ansible-automation-platform" \
  -- aap-detect-direct-component-access --report-format json > direct-access-report.json

Reading the Report

The tool scans audit logs and active connections to identify direct component access. Example output:

Direct component API access detected — last 30 days

SOURCE                          COMPONENT     ENDPOINT                        COUNT   LAST SEEN
ci-pipeline@jenkins             controller    /api/v2/job_templates/          847     2026-06-28
monitoring@nagios               hub           /api/automation-hub/v3/         23      2026-06-25
legacy-script@deploy-server     controller    /api/v2/inventories/            156     2026-06-29
vault-sync@hashicorp             controller    /api/v2/credentials/            412     2026-06-28

Total: 4 sources making direct component API calls
Run `aap-detect-direct-component-access --explain <source>` for migration steps per source.

Per-Source Migration Guidance

aap-detect-direct-component-access --explain "ci-pipeline@jenkins"

Source: ci-pipeline@jenkins
Component: automation controller
Endpoints used: /api/v2/job_templates/, /api/v2/jobs/
Current auth: Personal Access Token (controller-issued)

Recommended migration:
  1. Create a gateway service account: ansible-galaxy collection install ansible.platform
  2. Issue a gateway token for the CI service account
  3. Update API base URL: /api/v2/ → /api/controller/v2/
  4. Update Authorization header: Token <controller-token> → Bearer <gateway-token>

See: https://docs.redhat.com/en/ansible-automation-platform/2.7/gateway-api-migration

Migration Steps

Step 1: Audit with aap-detect-direct-component-access

Run the tool and export a full report of all sources making direct component calls.

Step 2: Create Gateway Service Accounts

Replace per-component service accounts with gateway-level service accounts using the ansible.platform collection:

- name: Create CI pipeline service account
  hosts: localhost
  connection: local
  tasks:
    - name: Create gateway user for Jenkins CI
      ansible.platform.user:
        username: svc-jenkins-ci
        password: "{{ vault_jenkins_svc_password }}"
        email: ci-alerts@corp.example.com
        is_system_auditor: false
        state: present

    - name: Assign execute permission on CI job templates
      ansible.platform.role_user_assignment:
        role_definition: "JobTemplate Execute"
        user: svc-jenkins-ci
        object_ids:
          - "Deploy Web Application"
          - "Deploy API Service"
          - "Run Smoke Tests"
        state: present

    - name: Create gateway token for Jenkins
      ansible.platform.token:
        description: "Jenkins CI pipeline token"
        scope: write
        user: svc-jenkins-ci
        state: present
      register: jenkins_token

    - name: Display token (store immediately in Jenkins credentials)
      ansible.builtin.debug:
        msg: "Gateway token: {{ jenkins_token.token }}"

Step 3: Update API Base URLs

All component APIs are now served under the gateway URL:

Step 4: Update Authentication Headers

Replace component-issued tokens and basic auth with gateway-issued Bearer tokens:

# Before — direct controller with basic auth
import requests

response = requests.get(
    "https://controller.corp.example.com/api/v2/job_templates/",
    auth=("admin", "password"),
    verify="/etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem"
)

# After — gateway API with Bearer token
response = requests.get(
    "https://aap.corp.example.com/api/controller/v2/job_templates/",
    headers={"Authorization": f"Bearer {gateway_token}"},
    verify="/etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem"
)

For Ansible content using awx.awx or ansible.controller collections:

# Before
- name: Launch job
  ansible.controller.job_launch:
    job_template: "Deploy Web Application"
    controller_host: https://controller.corp.example.com
    controller_username: admin
    controller_password: "{{ vault_controller_password }}"

# After
- name: Launch job
  ansible.controller.job_launch:
    job_template: "Deploy Web Application"
    controller_host: https://aap.corp.example.com
    controller_oauthtoken: "{{ gateway_token }}"

Step 5: Migrate Authentication Providers

If you had LDAP, SAML, or OIDC configured directly in automation controller or Automation Hub, you must reconfigure these providers at the platform gateway level using ansible.platform:

- name: Configure LDAP authentication at gateway level
  ansible.platform.authenticator:
    name: "Corporate LDAP"
    type: ldap
    configuration:
      SERVER_URI: "ldaps://ldap.corp.example.com:636"
      BIND_DN: "cn=ansible-svc,ou=serviceaccounts,dc=corp,dc=example,dc=com"
      BIND_PASSWORD: "{{ vault_ldap_bind_password }}"
      USER_SEARCH:
        - "ou=users,dc=corp,dc=example,dc=com"
        - SCOPE_SUBTREE
        - "(uid=%(user)s)"
      GROUP_SEARCH:
        - "ou=groups,dc=corp,dc=example,dc=com"
        - SCOPE_SUBTREE
        - "(objectClass=groupOfNames)"
    state: present

See also: AAP 2.7 Workload Identity: Configure OIDC Credential Types for HashiCorp Vault (Step-by-Step)

Common Migration Scenarios

Jenkins Pipelines

Jenkins jobs calling the controller /api/v2/ endpoint typically use the Ansible Tower Plugin or raw HTTP steps.

Update plugin configuration:

1. Change Tower URL from https://controller.corp.example.com to https://aap.corp.example.com
2. Replace Username/Password credential with an API Token credential containing the gateway-issued Bearer token

Monitoring Systems (Nagios, Zabbix, Datadog)

Monitoring checks that poll https://controller.corp.example.com/api/v2/ping/ need to update their target to https://aap.corp.example.com/api/controller/v2/ping/ and switch from basic auth to a Bearer token.

Custom Scripts and awx CLI

The awx CLI reads from ~/.config/awx/credentials. Update:

# ~/.config/awx/credentials
[general]
host = https://aap.corp.example.com
token = <gateway-issued-bearer-token>
verify_ssl = true

Timeline Guidance

FAQ

Is the gateway API available in AAP 2.6?

Yes. The platform gateway was introduced in AAP 2.5 and the gateway API was available in AAP 2.6. You can migrate scripts to gateway endpoints before upgrading to 2.7, allowing you to test the migration without the breaking change pressure.

Does this affect internal automation (playbooks calling the controller API)?

Internal playbooks running inside AAP (e.g., workflow templates calling the controller API for dynamic inventory) continue to work because internal component-to-component communication is not affected. The change applies to external access only.

What happens to existing PATs after the upgrade?

Existing controller-issued and Hub-issued PATs stop working after the upgrade to 2.7. You must create gateway-issued tokens before upgrading any consumers.

Can I re-enable basic auth temporarily?

No. Basic auth is removed at the platform level in 2.7 and cannot be re-enabled via configuration. This is a security enforcement, not a default setting.

See also: Red Hat Ansible Automation Platform 2.7: What's New — Features, AI, and Security Enhancements

Related Articles

• ansible.platform Collection: Configuration as Code for AAP 2.7
• AAP 2.7 Upgrade Path: RPM Removed, Containerized Only
• Ansible AAP as OIDC Authentication Provider for HashiCorp Vault