Prerequisites for Red Hat Ansible Automation Platform integration

Copy link

Before you integrate Red Hat Edge Manager with Red Hat Ansible Automation Platform, ensure that the following requirements are met:

• Red Hat Ansible Automation Platform 2.5.
• Network connectivity from the Red Hat Edge Manager server to the Red Hat Ansible Automation Platform platform gateway over HTTPS (port 443).
• For automatic OAuth application creation: an Red Hat Ansible Automation Platform user whose OAuth token has write access to the Default organization.
• For manual OAuth setup: permission to create OAuth applications in Red Hat Ansible Automation Platform, and the Default organization selected for the application.
• If your organization uses an external identity provider with Red Hat Ansible Automation Platform: administrator access to platform gateway settings (see Enabling external identity provider users in the Additional resources section).
• If the Red Hat Ansible Automation Platform platform gateway uses TLS certificates signed by a private or organizational CA: install that CA in the drop-in trust file at /etc/flightctl/pki/auth/ca.crt. See Custom CA certificates for Red Hat Ansible Automation Platform in the Additional resources section.

These prerequisites reduce failed integrations caused by missing network paths, tokens, administrative access, or untrusted TLS to the gateway.

Configuring Red Hat Ansible Automation Platform authentication

Copy link

Setting up an OAuth application in Red Hat Ansible Automation Platform

Red Hat Edge Manager uses an OAuth 2.0 client registered in Red Hat Ansible Automation Platform to complete the authorization code flow. You can choose one of the following approaches:

• Automatic: Provide an OAuth token with write access to the Default organization (or to another organization if you set organizationId). On startup, Red Hat Edge Manager can create the OAuth application in Red Hat Ansible Automation Platform for you.
• Manual: Create the OAuth application yourself in the Red Hat Ansible Automation Platform interface (typically under Default) and copy the client ID into service-config.yaml.

Setting up an OAuth application automatically

Use this procedure when you have, or can create, an OAuth token with write permissions to the Default organization, or to another organization if you will set organizationId in service-config.yaml.

1. In the Red Hat Ansible Automation Platform web interface, open Access Management and select Users.
2. Select a user that has write permissions to the Default organization, or to the organization that matches your organizationId value when you use that field.
3. Open the Tokens tab for that user.
4. Click Create token.
5. Set Scope to Write.
6. Create the token and copy its value. You will add it to service-config.yaml as token (see Updating service-config.yaml for Red Hat Ansible Automation Platform authentication in the Additional resources section).

Setting up an OAuth application manually

Use this procedure when you cannot use a write-scoped token or you prefer to register the client yourself.

1. In the Red Hat Ansible Automation Platform web interface, open Access Management and select OAuth Applications.
2. Click Create OAuth application.
3. Set the following fields:
   • Name:Red Hat Edge Manager (or another descriptive name).
   • URL:https://YOUR_RHEM_HOST/
   • Organization:Default (recommended), or another organization if your site requires it
   • Authorization grant type: Authorization code
   • Client: Public
   • Redirect URIs:
     • User interface: https://YOUR_RHEM_HOST/callback
     • Command-line interface: http://127.0.0.1/callback
4. Save the application and copy the Client ID. You will add it to service-config.yaml as clientId (see Updating service-config.yaml for Red Hat Ansible Automation Platform authentication in the Additional resources section).

Updating service-config.yaml for Red Hat Ansible Automation Platform authentication

Configure the auth section in /etc/flightctl/service-config.yaml by using the current field names. Do not use the deprecated keys oAuthToken, oAuthApplicationClientId, or externalApiUrl.

• The Red Hat Ansible Automation Platform platform gateway base URL (HTTPS), referred to in the examples as https://aap-gateway.example.com.
• For automatic setup: the OAuth token from Setting up an OAuth application automatically.
• For manual setup: the client ID from Setting up an OAuth application manually.
  1. Stop the Red Hat Edge Manager services:

     sudo systemctl stop flightctl.target

  2. Edit the configuration file:

     sudo vi /etc/flightctl/service-config.yaml

  3. Under global, set auth.type to aap and configure the aap map.

     Use one of the following examples. Replace aap-gateway.example.com with your platform gateway hostname. Replace placeholder values with your token or client ID. For automatic setup, optional appName and organizationId fields are documented in the field reference.

     Automatic setup (token-based OAuth application creation):

     global:
       baseDomain: <your-edge-manager-ip-or-domain>
       auth:
         type: aap
         insecureSkipTlsVerify: false
         aap:
           apiUrl: https://aap-gateway.example.com
           token: <your-oauth-token>
           authorizationUrl: https://aap-gateway.example.com/o/authorize/
           tokenUrl: https://aap-gateway.example.com/o/token/
           enabled: true

     Note

     Optional appName and organizationId keys in the aap map support advanced deployments:

     • organizationId: Register the OAuth application outside the Default organization. Use an OAuth token with write access to that organization (see Prerequisites for Red Hat Ansible Automation Platform integration in the Additional resources section).
     • appName: Red Hat Ansible Automation Platform requires a unique OAuth application name within each organization. By default, Red Hat Edge Manager uses Red Hat Edge Manager. If multiple Red Hat Edge Manager instances register against the same Red Hat Ansible Automation Platform organization, set a different appName for each instance to avoid name conflicts.

     Manual setup (existing OAuth application):

     global:
       baseDomain: <your-edge-manager-ip-or-domain>
       auth:
         type: aap
         insecureSkipTlsVerify: false
         aap:
           apiUrl: https://aap-gateway.example.com
           clientId: <client-id-from-oauth-app>
           authorizationUrl: https://aap-gateway.example.com/o/authorize/
           tokenUrl: https://aap-gateway.example.com/o/token/
           enabled: true

  4. For automatic setup, omit clientId or leave it empty. For manual setup, omit token or leave it empty.
  5. Start the services:

     sudo systemctl start flightctl.target

  6. Verify that the API service is running and review recent logs:

     sudo systemctl status flightctl-api
     sudo journalctl -u flightctl-api -n 50

     For automatic setup, if the OAuth application does not appear in Red Hat Ansible Automation Platform or startup looks incomplete, review flightctl-api-init.service logs (see Automatic OAuth application creation issues in the Additional resources section).

Field reference

apiUrl

Base URL of the Red Hat Ansible Automation Platform platform gateway for API requests from Red Hat Edge Manager. Do not include a trailing slash on the URL. For example, use https://gateway.example.com rather than https://gateway.example.com/.

token

OAuth token with write access to the organization where the OAuth application is created. For the default Default organization, the token must have write access there. If you set organizationId, the token must have write access to that organization instead. Used only for automatic OAuth application creation.

organizationId

Optional. Advanced setting. Red Hat Ansible Automation Platform organization ID under which Red Hat Edge Manager registers the OAuth application during automatic setup. Omit this field to use the Default organization.

appName

Optional. Advanced setting. Display name for the OAuth application that Red Hat Edge Manager creates in Red Hat Ansible Automation Platform during automatic setup. Defaults to Red Hat Edge Manager. The name must be unique among OAuth applications in the target Red Hat Ansible Automation Platform organization. Use distinct values when more than one Red Hat Edge Manager deployment automatically registers a client in the same organization so that creation does not fail.

clientId

Client ID from the OAuth application in Red Hat Ansible Automation Platform, used only for manual setup.

authorizationUrl

OAuth authorization endpoint. Use your apiUrl host with the path /o/authorize/.

tokenUrl

OAuth token endpoint. Use your apiUrl host with the path /o/token/.

enabled

Set to true to enable Red Hat Ansible Automation Platform authentication.

Configuring Red Hat Edge Manager roles in Red Hat Ansible Automation Platform

After a user signs in through Red Hat Ansible Automation Platform, Red Hat Edge Manager validates the session with the Red Hat Ansible Automation Platform platform gateway and applies role-based access control (RBAC) by using standard role names. Red Hat Ansible Automation Platform organization membership is mapped to Red Hat Edge Manager organizations automatically; users only see resources for organizations they belong to in Red Hat Ansible Automation Platform.

Assign the following roles in Red Hat Ansible Automation Platform (or equivalent automation your site uses for gateway-visible roles) so that the correct permissions reach Red Hat Edge Manager. Role and organization changes can take effect after the user signs in again or after a short cache interval (often on the order of five to ten minutes).

1. Decide which flightctl-* role each person or automation account needs in each Red Hat Ansible Automation Platform organization that should map to a Red Hat Edge Manager organization.
2. In Red Hat Ansible Automation Platform, create or assign custom roles that include the flightctl-* permissions your users need, and assign users to the correct organizations. The exact UI labels depend on your Red Hat Ansible Automation Platform version. In one validated configuration, a custom role used Organization as the content type and included View Organization for gateway visibility. Adapt this pattern if your site uses different RBAC models.
3. Ask affected users to sign out of Red Hat Edge Manager and sign in again, or wait up to approximately ten minutes, so updated roles and organizations are applied.

Custom CA certificates for Red Hat Ansible Automation Platform

Copy link

The Red Hat Edge Manager services read a single drop-in CA certificate file to trust TLS connections to the Red Hat Ansible Automation Platform platform gateway when the gateway certificate is not publicly trusted. Use this fixed path:

/etc/flightctl/pki/auth/ca.crt

Place the PEM-encoded certificate of the CA that signs your gateway certificate (or an intermediate that completes the chain your server must trust) in that file. You do not need this file when the gateway presents a certificate that is already trusted by the default system truststore.

1. Copy the CA certificate to the drop-in location on the Red Hat Edge Manager host:

   sudo cp /path/to/your/ca.crt /etc/flightctl/pki/auth/ca.crt

   Ensure the directory exists (it is created by a normal Red Hat Edge Manager installation). Use a single PEM file; if you must combine multiple CAs, concatenate them into one file at this path.

2. Ensure that TLS verification remains enabled for production. Do not set insecureSkipTlsVerify to true unless you are troubleshooting in a non-production environment:

   global:
     auth:
       type: aap
       insecureSkipTlsVerify: false

   You can omit insecureSkipTlsVerify when the default secure behavior is correct.

3. Restart the services:

   sudo systemctl restart flightctl.target

Enabling external identity provider users

Copy link

If Red Hat Ansible Automation Platform authenticates users through an external identity provider (for example, LDAP, Active Directory, or SAML), those users are treated as external users in the platform gateway. By default, external users can be prevented from creating OAuth2 tokens. Red Hat Edge Manager relies on OAuth2 tokens from Red Hat Ansible Automation Platform after the authorization code flow. Those users must be allowed to create OAuth2 tokens, or sign-in and API access to Red Hat Edge Manager will fail.

Users who exist only in the built-in Red Hat Ansible Automation Platform database typically do not need this change.

If this setting stays disabled, LDAP-, SAML-, or SSO-backed users can complete the browser login at Red Hat Ansible Automation Platform but token exchange fails. Gateway or API logs might show a POST /o/token/ request that returns HTTP status code 403. Red Hat Edge Manager might also log a failure to parse JSON from the token response because the body is plain text or HTML. The gateway error text often includes the following phrase:

(access_denied) OAuth2 Tokens cannot be created by users associated with an external authentication provider

When you see that message, enable Allow external users to create OAuth2 tokens instead of bypassing Red Hat Ansible Automation Platform with a separate SSO integration for Red Hat Edge Manager.

• Red Hat Ansible Automation Platform is configured to use an external identity provider for interactive login.
• You can change platform gateway settings as an Red Hat Ansible Automation Platform administrator.
  1. Sign in to Red Hat Ansible Automation Platform as an administrator.
  2. Go to Settings Platform Gateway.
  3. Enable Allow external users to create OAuth2 tokens.
  4. Save the settings.

Sign in to Red Hat Edge Manager with a user sourced from the external identity provider (for example, an LDAP-backed account). Confirm that authentication completes and expected roles apply. See Configuring Red Hat Edge Manager roles in Red Hat Ansible Automation Platform in the Additional resources section.

Troubleshooting Red Hat Ansible Automation Platform authentication

Copy link

Service fails to start after configuration

1. Run:

   sudo journalctl -u flightctl-api -n 100

2. Confirm that apiUrl matches your platform gateway and is reachable from the Red Hat Edge Manager server.
3. Confirm that authorizationUrl is formed as apiUrl with path /o/authorize/ and tokenUrl is formed as apiUrl with path /o/token/.
4. For automatic setup, confirm that the token has write permissions to the Default organization, or to the organization specified by organizationId if you set that field.
5. For automatic setup, if registration fails because an OAuth application name already exists, set a unique appName for each Red Hat Edge Manager instance. See Field reference in the Additional resources section.
6. For manual setup, confirm that clientId matches the OAuth application in Access Management OAuth Applications.

Automatic OAuth application creation issues

When you use automatic setup on a Red Hat Enterprise Linux host (token in the aap map and no clientId), flightctl-api-init.service runs during startup to create the OAuth application in Red Hat Ansible Automation Platform. If the application is not created or authentication still fails before you can use a client ID, check this service before you investigate other causes.

1. Review recent logs from the init unit:

   sudo journalctl -u flightctl-api-init.service -n 100

   • Confirm token permissions, optional organizationId, and optional appName (see Field reference in the Additional resources section).
   • Confirm TLS trust and that the Red Hat Ansible Automation Platform gateway is reachable from the Red Hat Edge Manager server (see Service fails to start after configuration in the Additional resources section).

Users cannot authenticate

• Verify that the OAuth application exists and that redirect URIs match Setting up an OAuth application manually.
• If you use an external identity provider with Red Hat Ansible Automation Platform, confirm that Allow external users to create OAuth2 tokens is enabled. See Enabling external identity provider users in the Additional resources section.
• If the browser flow reaches Red Hat Ansible Automation Platform but Red Hat Edge Manager fails right after redirect, check API logs for token proxy errors. An HTTP 403 from the token endpoint together with JSON parse errors often means the response body is not OAuth JSON. Capture the response body from the gateway (for example, with curl from the Red Hat Edge Manager host) and compare it to the external-user message in Enabling external identity provider users.
• If token exchange still fails, confirm that apiUrl has no trailing slash (see Updating service-config.yaml for Red Hat Ansible Automation Platform authentication in the Additional resources section).
• Test connectivity from the Red Hat Edge Manager host or pod, for example:

  curl -sS -o /dev/null -w "%{http_code}" https://YOUR_AAP_GATEWAY_HOSTNAME/o/authorize/

Users see restricted access after sign-in

Sign-in can succeed while the user still has no effective flightctl-* roles in Red Hat Ansible Automation Platform. The UI then shows limited or empty content.

• Assign the appropriate flightctl-* roles (see Configuring Red Hat Edge Manager roles in Red Hat Ansible Automation Platform in the Additional resources section). Users who need full administrative access across organizations typically need privileges that map to flightctl-admin (often aligned with Red Hat Ansible Automation Platform System Administrator). Red Hat Ansible Automation Platform Platform Auditor users receive flightctl-viewer at the user level in the same way System Administrator maps to flightctl-admin.
• After role changes, wait up to approximately ten minutes or sign out and sign in again before retesting.

Custom CA certificates are not trusted

• Confirm that the CA file is present at /etc/flightctl/pki/auth/ca.crt and is readable by the flightctl services.
• Confirm that insecureSkipTlsVerify is not set to true for production.
• Restart flightctl.target after you change certificates or paths.