Platform gateway

Platform gateway is the service that handles authentication and authorization for Ansible Automation Platform. It provides a single ingress into the Platform and serves the Platform’s user interface.

About this task
Copy link

From the Settings > Platform gateway menu, you can configure Platform gateway, Security, Session, Platform Security, Custom Login, and Other settings.

Procedure
Copy link

  1. From the navigation panel, select Settings > Platform gateway.
  2. The Platform gateway settings page is displayed.
  3. To configure the options, click Edit platform gateway settings.
  4. You can configure the following platform gateway options:
    • Platform gateway proxy url: URL to the platform gateway proxy layer.
    • Platform gateway proxy url ignore cert: Ignore the certificate to the platform gateway proxy layer.
  5. Click Save platform gateway settings to save the changes or proceed to configure the other platform options available.

Configure platform security
Copy link

From the Platform gateway settings page, you can configure platform security settings.

Procedure
Copy link

  1. From the navigation panel, select Settings > Platform gateway.
  2. The Platform gateway settings page is displayed.
  3. To configure the options, click Edit.
  4. You can configure the following Security settings:
    • Allow system administrators to set insecure user passwords: Whether a superuser account can save an insecure password when editing any local user account.
    • Gateway basic auth enabled: Enable basic authentication to the platform gateway API.

      Turning this off prevents all basic authentication (local users), so customers need to make sure they have their alternative authentication mechanisms correctly configured before doing so.

      Turning it off with only local authentication configured also prevents all access to the UI.

      Gateway token name: The header name to push from the proxy to the backend service.

    • Gateway access token expiration: How long the access tokens are valid for.
    • Jwt private key: The private key used to encrypt the JWT tokens sent to backend services.

      This should be a private RSA key and one should be generated automatically on installation.

      Note

      Use caution when rotating the key as it will cause current sessions to fail until their JWT keys are reset.
    • (Read only) Jwt public key: The private key used to encrypt the JWT tokens sent to backend services.

      This should be a private RSA key and one should be generated automatically on installation.

      Note

      See other services' documentation on how they consume this key.

       Warning

      If this name is changed, backends must be updated to compensate.

      Social auth username is full email: Enabling this setting alerts social authentication to use the full email as username instead of the full name.

    • Csrf trusted origins: If the service is behind a reverse proxy or load balancer, use this setting to configure the schema://addresses from which the service should trust Origin header values.
  5. Click Save changes to save the changes or proceed to configure the other platform options available.

Configure platform sessions
Copy link

From the Platform gateway settings page, you can configure platform session settings.

Procedure
Copy link

  1. From the navigation panel, select Settings > Platform gateway.
  2. The Platform gateway settings page is displayed.
  3. To configure the options, click Edit platform gateway settings.
  4. Enter the time in seconds before a session expires in the Session cookie age field.
  5. Click Save platform gateway settings to save the changes or proceed to configure the other platform options available.

Configure a platform password security policy
Copy link

From the Platform gateway settings page, you can configure a password security policy.

Procedure
Copy link

  1. From the navigation panel, select Settings > Platform gateway.
  2. The Platform gateway settings page is displayed.
  3. To configure the options, click Edit platform gateway settings.
  4. You can configure the following Password Security options:
    • Password minimum uppercase letters: How many uppercase characters need to be in a local password.
    • Password minimum length: The minimum length of a local password.
    • Password minimum numerical digits: How many numerical characters need to be in a local password.
    • Password minimum special characters: How many special characters need to be in a local password.
  5. Click Save platform gateway settings to save the changes or proceed to configure the other platform options available.

Encrypt the platform gateway database password
Copy link

System administrators can encrypt the database password used by platform gateway and apply it directly to the configuration file, resolving issues related to the SECRET_KEY loading order.

About this task
Copy link

Note

Platform gateway uses the Django framework, which requires the SECRET_KEY to be fully loaded into memory before the decryption function (ansible_encryption.decrypt_string()) is called. If the decryption call runs before the key is loaded, the process fails, preventing platform gateway from accessing the database.

Procedure
Copy link

  1. Access the command line on the platform gateway node.
  2. Use the aap-gateway-manage shell_plus command to open an interactive Django shell: 
    aap-gateway-manage shell_plus
  3. Inside the shell, run the following commands to import the encryption library, set your password, and generate the encrypted string: 
    >>> from ansible_base.lib.utils.encryption import ansible_encryption
>>> value = 'your-database-password' # REPLACE with your actual password
>>> encrypted_value = ansible_encryption.encrypt_string(value)
>>> print(encrypted_value)
  4. Copy the entire output string starting with $encrypted$. This is your encrypted password.
  5. Exit the shell using quit().
  6. Open the platform gateway configuration file for editing: 
    vi /etc/ansible-automation-platform/gateway/settings.py
  7. Locate the section defining the DATABASES variable. You must insert the code to load the SECRET_KEY before the DATABASES dictionary is defined.
  8. Update the file to include the highlighted code, replacing only the placeholder text for the PASSWORD key with your copied encrypted string: 
    from ansible_base.lib.utils.encryption import ansible_encryption
from django.conf import settings

# ... other configuration settings ...

# The GATEWAY_SECRET_KEY_FILE is typically defined earlier in settings.
# The SECRET_KEY must be loaded before the decryption function is called.
with open(GATEWAY_SECRET_KEY_FILE, 'rb') as f:
    settings.SECRET_KEY = f.read().strip()

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'HOST': '10.0.108.77', # Example host, use your value
        # ... other database settings ...
        'PASSWORD':
        ansible_encryption.decrypt_string('$encrypted$UTF8$AESCBC$Z0FBQUFBQnBBNU...
        <YOUR_ENCRYPTED_STRING>...QWdPUHM9'),
        # ... other database settings ...
        'PORT': '5432', # Example port, use your value
    }
}
  9. Save and close the file.
  10. Restart platform gateway to load the new encrypted configuration: 
    sudo systemctl restart aap-gateway

Results
Copy link

Confirm that platform gateway starts without errors and that you can access the platform UI, which indicates a successful database connection.

Configure additional platform options
Copy link

Configure extra settings in platform gateway, such as the JWT expiration buffer. Adjusting these options helps ensure continuous token validity and smooth communication between platform services.

Procedure
Copy link

  1. From the navigation panel, select Settings > Platform gateway.
  2. The Platform gateway settings page is displayed.
  3. Click Edit platform gateway settings.
  4. You can configure the following Other settings:
    • Jwt expiration buffer in seconds: The number of seconds before a JWT token’s expiration to revoke from the cache.

      When authentication happens a JWT token is created for the user and that token is cached. When subsequent calls happen to services such as automation controller or Event-Driven Ansible, the token is taken from the cache and sent to the service. Both the token and the cache of the token have an expiration time. If the token expires while in the cache the authentication process attempts results in a 401 error (unauthorized). This setting gives Red Hat Ansible Automation Platform a buffer by removing the JWT token from the cache before the token expires. When a token is revoked from cache a new token with a new expiration is generated and cached for the user. As a result, expired tokens from the cache are never used. This setting defaults to 2 seconds. If you have a large latency between platform gateway and your services and observe 401 responses you must increase this setting to lower the number of 401 responses.

    • Status endpoint backend timeout seconds: Timeout (in seconds) for the status endpoint to wait when trying to connect to a backend.
    • Status endpoint backend verify: Specifies whether SSL/TLS certificates of the services are verified when calling individual nodes for statuses.
    • Resource client request timeout: The timeout (in seconds) before the resource client will drop requests after forming connections.
    • Request timeout: Specifies, in seconds, the length of time before the proxy will report a timeout and generate a 504.
    • Manage organization auth: Controls whether any organization administrator has the privileges to create and manage users and teams. You might want to disable this ability if you are using an LDAP or SAML integration. Important

      The MANAGE_ORGANIZATION_AUTH setting is moved to platform gateway during an upgrade from Ansible Automation Platform 2.4 to 2.6. However, the values are not automatically synchronized between platform gateway and automation controller after the migration. To prevent administrative issues, keep the MANAGE_ORGANIZATION_AUTH value consistent across both environments, especially if automation workflows run directly against automation controller.
    • Stream idle timeout: Timeout in seconds for idle streaming connections, for example, for the Red Hat Ansible Lightspeed chatbot. Stream is closed if no data is transmitted within this period.
    • Max stream duration: Maximum total duration in seconds for streaming connections, for example, for the Red Hat Ansible Lightspeed chatbot. Stream is closed after this time regardless of activity.
    • Aap deployment type: The deployment type for this Ansible Automation Platform instance.
  5. Click Save platform gateway settings to save the changes or proceed to configure the other platform options available.

Overlapping administrative settings
Copy link

Manually synchronize duplicate operational and administrative settings between platform gateway and component services like automation controller. This helps ensure your workflows and scripts can interact directly with the component API without issues.

Effective settings table

The following table clarifies the authoritative source for administrative settings that you can configure in both automation controller and platform gateway.

Expand
Setting name (UI text) API variable name Platform gateway configuration location Automation controller configuration location Synchronization requirement and notes

Organization Admins Can Manage Users and Teams

MANAGE_ORGANIZATION_AUTH

Settings > Platform gateway

Settings > Automation Execution > System

Keep a consistent value across both systems. The automation controller setting might be used by direct API workflows.

All Users Visible to Organization Admins

ORG_ADMINS_CAN_SEE_ALL_USERS

Settings > Platform gateway

Settings > Automation Execution > System

Keep a consistent value across both systems. Automation controller does not follow gateway settings for this variable; direct API workflows use the controller’s local value.

Allow External Users to Create OAuth2 Tokens

ALLOW_OAUTH2_FOR_EXTERNAL_USERS

Settings > Platform gateway

N/A

Platform gateway is authoritative. Configure this setting in the unified UI or through the gateway API.