Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 3. Configuring access to external applications with token-based authentication

Token-based authentication permits authentication of third-party tools and services with the platform through integrated OAuth 2 token support. Ansible Automation Platform utilizes both OAuth Tokens and Personal Access Tokens (PATs).

OAuth Tokens
OAuth Tokens are tied to specific applications and allow applications to access data without disclosing user login information.
Personal Access Tokens
PATs are personal to a user and not tied to a specific application. They are created directly by a user for their own use.

The default expiration for access tokens has been updated from 1000 years to 1 year. This change ensures frequent token rotation for increased credential security.

Note

Access tokens in controller 2.4 and previous versions of the platform gateway were valid for 1000 years. Any existing tokens created prior to the 2.5.20250604 patch release will retain a 1000 year expiration.

You can customize this setting to meet your specific requirements by modifying the expiration time in your settings.py file as follows: 

OAUTH2_PROVIDER__ACCESS_TOKEN_EXPIRE_SECONDS = 31536000
Copy to Clipboard Toggle word wrap

For more information about the settings.py file and how it can be used to configure aspects of the platform, see settings.py in Operating Ansible Automation Platform.

For more information about the OAuth2 specification, see The OAuth 2.0 Authorization Framework.

For more information about using the manage utility to create tokens, see Token and session management.

3.1. Applications
Copy link

Create and configure token-based authentication for external applications such as ServiceNow and Jenkins. With token-based authentication, external applications can easily integrate with Ansible Automation Platform.

Important

Automation controller OAuth applications on the platform UI are not supported for 2.4 to 2.5 migration. See this Knowledgebase article for more information.

As a platform administrator, you can configure a custom external application URL within the platform, providing seamless integration with external services. This functionality is currently available as a Technology Preview. Once configured, the external application URL appears in the platform UI navigation panel, providing users with easy access to the application. This feature streamlines workflows by ensuring quick access to external services from within the platform UI.

Note

Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

For more information about the support scope of Red Hat Technology Preview features, see Technology Preview Features Support Scope.

With OAuth 2 you can use tokens to share data with an application without disclosing login information. You can configure these tokens as read-only.

You can create an application that is representative of the external application you are integrating with, then use it to create tokens for the application to use on behalf of its users.

Associating these tokens with an application resource enables you to manage all tokens issued for a particular application. By separating the issue of tokens under OAuth Applications, you can revoke all tokens based on the application without having to revoke all tokens in the system.

3.1.1. Getting started with OAuth Applications
Copy link

You can access the OAuth Applications page from the navigation panel by selecting Access Management OAuth Applications. From there you can view, create, sort and search for applications currently managed by Ansible Automation Platform and automation controller.

If no applications exist, you can create one by clicking Create OAuth application.

Access rules for applications are as follows:

  • Platform administrators can view and manipulate all applications in the system.
  • Platform auditors can only view applications in the system.
  • Tokens, on the other hand, are resources used to authenticate incoming requests and mask the permissions of the underlying user.

Access rules for tokens are as follows:

  • Users can create personal access tokens for themselves.
  • Platform administrators are able to view and manipulate every token in the system.
  • Platform auditors can only view tokens in the system.
  • Other normal users are only able to view and manipulate their own tokens.
Note

Users can only view the token or refresh the token value at the time of creation.

3.1.1.1. Application functions
Copy link

Several OAuth 2 utilities are available for authorization, token refresh, and revoke. You can specify the following grant types when creating an application:

Password
This grant type is ideal for users who have native access to the web application and must be used when the client is the resource owner.
Authorization code
This grant type should be used when access tokens must be issued directly to an external application or service.
Note

You can only use the authorization code type to acquire an access token when using an application. When integrating an external web application with Ansible Automation Platform, that web application might need to create OAuth2 tokens on behalf of users in that other web application. Creating an application in the platform with the authorization code grant type is the preferred way to do this because:

  • This allows an external application to obtain a token from Ansible Automation Platform for a user, using their credentials.
  • Compartmentalized tokens issued for a particular application enables those tokens to be easily managed. For example, revoking all tokens associated with that application without having to revoke all tokens in the system.

The default expiration for access tokens is 1 year.

The best way to set up application integrations using the Authorization code grant type is to allowlist the origins for those cross-site requests. More generally, you must allowlist the service or application you are integrating with the platform, for which you want to provide access tokens.

To do this, have your administrator add this allowlist to their local Ansible Automation Platform settings file: 

CORS_ORIGIN_ALLOW_ALL = True
CORS_ALLOWED_ORIGIN_REGEXES = [
    r"http://django-oauth-toolkit.herokuapp.com*",
    r"http://www.example.com*"
]
Copy to Clipboard Toggle word wrap

Where http://django-oauth-toolkit.herokuapp.com and http://www.example.com are applications requiring tokens with which to access the platform.

3.1.2. Creating a new application
Copy link

When integrating an external web application with Ansible Automation Platform, the web application might need to create OAuth2 tokens on behalf of users of the web application.

Creating an application with the Authorization Code grant type is the preferred way to do this for the following reasons:

  • External applications can obtain a token for users, using their credentials.
  • Compartmentalized tokens issued for a particular application, enables those tokens to be easily managed. For example, revoking all tokens associated with that application.

Procedure

  1. From the navigation panel, select Access Management OAuth Applications.
  2. Click Create OAuth application. The Create Application page opens.

  3. Enter the following details:

    Name
    (required) Enter a name for the application you want to create.
    URL
    (optional) Enter the URL of the external application. This link is added to the navigation panel for easy access. This setting is currently offered as a Technology Preview only.
    Description
    (optional) Include a short description for your application.
    Organization
    (required) Select an organization with which this application is associated.
    Authorization grant type
    (required) Select one of the grant types to use for the user to get tokens for this application. For more information, see Application functions for more information about grant types.
    Client Type
    (required) Select the level of security of the client device.
    Redirect URIS
    Provide a list of allowed URIs, separated by spaces. You need this if you specified the grant type to be Authorization code.

  4. Click Create OAuth application, or click Cancel to abandon your changes.

    The Client ID and Client Secret display in a window. This will be the only time the client secret will be shown.

    Note

    The Client Secret is only created when the Client type is set to Confidential.

  5. Click the copy icon and save the client ID and client secret to integrate an external application with Ansible Automation Platform.

3.2. Adding tokens
Copy link

You can view a list of users that have tokens to access an application by selecting the Tokens tab in the OAuth Applications details page.

Note

You can only create OAuth 2 Tokens for your own user, which means you can only configure or view tokens from your own user profile.

When authentication tokens have been configured, you can select the application to which the token is associated and the level of access that the token has.

Procedure

  1. From the navigation panel, select Access Management Users.
  2. Select the username for your user profile to configure OAuth 2 tokens.

  3. Select the Tokens tab.

    When no tokens are present, the Tokens screen prompts you to add them.

  4. Click Create token to open the Create Token window.

  5. Enter the following details:

    Application

    Enter the name of the application with which you want to associate your token. Alternatively, you can search for it by clicking Browse. This opens a separate window that enables you to choose from the available options. Select Name from the filter list to filter by name if the list is extensive.

    Note

    To create a Personal Access Token (PAT) that is not linked to any application, leave the Application field blank.

    Description
    (optional) Provide a short description for your token.
    Scope

    (required) Specify the level of access you want this token to have. The scope of an OAuth 2 token can be set as one of the following:

    • Write: Allows requests sent with this token to add, edit and delete resources in the system.
    • Read: Limits actions to read only. Note that the write scope includes read scope.

  6. Click Create token, or click Cancel to abandon your changes.

    The Token information is displayed with Token and Refresh Token information, and the expiration date of the token. This will be the only time the token and refresh token will be shown. You can view the token association and token information from the list view.

  7. Click the copy icon and save the token and refresh token for future use.

Verification

You can verify that the application now shows the user with the appropriate token using the Tokens tab on the Applications details page.

  1. From the navigation panel, select Access Management OAuth Applications.
  2. Select the application you want to verify from the Applications list view.

  3. Select the Tokens tab.

    Your token should be displayed in the list of tokens associated with the application you chose.

Additional resources

3.2.1. Application token functions
Copy link

The refresh and revoke functions associated with tokens, for tokens at the /o/ endpoints can currently only be carried out with application tokens.

3.2.1.1. Refresh an existing access token
Copy link

The following example shows an existing access token with a refresh token provided: 

{
    "id": 35,
    "type": "access_token",
    ...
    "user": 1,
    "token": "omMFLk7UKpB36WN2Qma9H3gbwEBSOc",
    "refresh_token": "AL0NK9TTpv0qp54dGbC4VUZtsZ9r8z",
    "application": 6,
    "expires": "2017-12-06T03:46:17.087022Z",
    "scope": "read write"
}
Copy to Clipboard Toggle word wrap

The /o/token/ endpoint is used for refreshing the access token: 

curl -X POST \
    -d "grant_type=refresh_token&refresh_token=AL0NK9TTpv0qp54dGbC4VUZtsZ9r8z" \
    -u "gwSPoasWSdNkMDtBN3Hu2WYQpPWCO9SwUEsKK22l:fI6ZpfocHYBGfm1tP92r0yIgCyfRdDQt0Tos9L8a4fNsJjQQMwp9569eIaUBsaVDgt2eiwOGe0bg5m5vCSstClZmtdy359RVx2rQK5YlIWyPlrolpt2LEpVeKXWaiybo" \
    http://<gateway>/o/token/ -i
Copy to Clipboard Toggle word wrap

Where refresh_token is provided by refresh_token field of the preceding access token.

The authentication information is of format <client_id>:<client_secret>, where client_id and client_secret are the corresponding fields of the underlying related application of the access token.

Note

The special OAuth 2 endpoints only support using the x-www-form-urlencoded Content-type, so as a result, none of the /o/* endpoints accept application/json.

On success, a response displays in JSON format containing the new (refreshed) access token with the same scope information as the previous one: 

HTTP/1.1 200 OK
Server: nginx/1.12.2
Date: Tue, 05 Dec 2017 17:54:06 GMT
Content-Type: application/json
Content-Length: 169
Connection: keep-alive
Content-Language: en
Vary: Accept-Language, Cookie
Pragma: no-cache
Cache-Control: no-store
Strict-Transport-Security: max-age=15768000

{"access_token": "NDInWxGJI4iZgqpsreujjbvzCfJqgR", "token_type": "Bearer", "expires_in": 315360000000, "refresh_token": "DqOrmz8bx3srlHkZNKmDpqA86bnQkT", "scope": "read write"}
Copy to Clipboard Toggle word wrap

The refresh operation replaces the existing token by deleting the original and then immediately creating a new token with the same scope and related application as the original one.

Verify that the new token is present and the old one is deleted in the api/gateway/v1/tokens/ endpoint.

3.2.1.2. Revoke an access token
Copy link

You can revoke an access token by deleting the token in the platform UI, or by using the /o/revoke-token/ endpoint.

Revoking an access token by this method is the same as deleting the token resource object, but it enables you to delete a token by providing its token value, and the associated client_id (and client_secret if the application is confidential). For example: 

curl -X POST -d "token=rQONsve372fQwuc2pn76k3IHDCYpi7" \
-u "gwSPoasWSdNkMDtBN3Hu2WYQpPWCO9SwUEsKK22l:fI6ZpfocHYBGfm1tP92r0yIgCyfRdDQt0Tos9L8a4fNsJjQQMwp9569eIaUBsaVDgt2eiwOGe0bg5m5vCSstClZmtdy359RVx2rQK5YlIWyPlrolpt2LEpVeKXWaiybo" \
http://<gateway>/o/revoke_token/ -i
Copy to Clipboard Toggle word wrap
Note
  • The special OAuth 2 endpoints only support using the x-www-form-urlencoded Content-type, so as a result, none of the /o/* endpoints accept application/json.
  • The Allow External Users to Create Oauth2 Tokens (ALLOW_OAUTH2_FOR_EXTERNAL_USERS in the API) setting is disabled by default. External users refer to users authenticated externally with a service such as LDAP, or any of the other SSO services. This setting ensures external users cannot create their own tokens. If you enable then disable it, any tokens created by external users in the meantime will still exist, and are not automatically revoked. This setting can be configured from the Settings Platform gateway menu.

Alternatively, to revoke OAuth2 tokens, you can use the manage utility, see Revoke oauth2 tokens.

On success, a response of 200 OK is displayed. Verify the deletion by checking whether the token is present in the api/gateway/v1/tokens/ endpoint.

3.2.2. Token and session management
Copy link

Ansible Automation Platform supports the following commands for OAuth2 token management:

3.2.2.1. create_oauth2_token
Copy link

Use the following command to create OAuth2 tokens (specify the username for example_user): 

$ aap-gateway-manage create_oauth2_token --user example_user

New OAuth2 token for example_user: j89ia8OO79te6IAZ97L7E8bMgXCON2
Copy to Clipboard Toggle word wrap

Ensure that you provide a valid user when creating tokens. Otherwise, an error message that you attempted to issue the command without specifying a user, or supplied a username that does not exist, is displayed.

3.2.2.2. revoke_oauth2_tokens
Copy link

Use this command to revoke OAuth2 tokens, both application tokens and personal access tokens (PAT). It revokes all application tokens (but not their associated refresh tokens), and revokes all personal access tokens. However, you can also specify a user for whom to revoke all tokens.

To revoke all existing OAuth2 tokens use the following command: 

$ aap-gateway-manage revoke_oauth2_tokens
Copy to Clipboard Toggle word wrap

To revoke all OAuth2 tokens and their refresh tokens use the following command: 

$ aap-gateway-manage revoke_oauth2_tokens --revoke_refresh
Copy to Clipboard Toggle word wrap

To revoke all OAuth2 tokens for the user with id=example_user (specify the username for example_user): 

$ aap-gateway-manage revoke_oauth2_tokens --user example_user
Copy to Clipboard Toggle word wrap

To revoke all OAuth2 tokens and refresh token for the user with id=example_user: 

$ aap-gateway-manage revoke_oauth2_tokens --user example_user --revoke_refresh
Copy to Clipboard Toggle word wrap

3.2.2.3. cleartokens
Copy link

Use this command to clear tokens which have already been revoked.

For more information, see cleartokens in Django’s Oauth Toolkit documentation.

3.2.2.4. clearsessions
Copy link

Use this command to delete all sessions that have expired.

For more information, see Clearing the session store in Django’s Oauth Toolkit documentation.

For more information on OAuth2 token management in the UI, see the Applications.

Red Hat Ansible Automation Platform is designed with a default security posture that prevents users authenticated through external providers, such as LDAP, SAML, or SSO, from creating OAuth2 tokens for programmatic API access. When an external user tries to generate such a token, the following message appears: 403: Forbidden' error with the message: '(access_denied) OAuth2 Tokens cannot be created by users associated with an external authentication provider.

This default behavior is a deliberate security measure. Ansible Automation Platform prioritizes centralized control over token generation, which encourages administrators to select the appropriate method for enabling OAuth 2.0 user token generation for external authentication providers.

It is important to understand that an OAuth2 token is created within Ansible Automation Platform, and Ansible Automation Platform itself manages its lifecycle, including its expiration. This lifecycle is independent of the user’s session with their external Identity Provider (IdP). For example, if a user generates an Ansible Automation Platform token and their account is later disabled in the external IdP, the Ansible Automation Platform token remains valid until it expires or is manually revoked. Being aware of this interaction is crucial for a secure configuration, as it highlights the need for compensating controls if you enable token creation for external users.

To enable external users to create OAuth2 tokens, change the appropriate setting in your Ansible Automation Platform environment. Ensure the implementation of compensating security controls after enabling this setting.

Procedure

  1. From the navigation panel, go to Settings Platform gateway.
  2. Click Edit platform gateway settings.
  3. Change the Allow external users to create OAuth2 tokens setting to Enabled.
  4. Click Save platform gateway settings.

Next steps

Implement the recommended security controls as described in Implementing security controls for external user OAuth2 tokens.

After enabling OAuth2 token creation for external users, implement the following compensating controls to keep a strong security posture.

Procedure

  • Limit token lifetime: Configure a shorter duration for OAuth2 tokens to reduce the window of exposure.

    • In your Ansible Automation Platform settings, adjust the OAUTH2_ACCESS_TOKEN_EXPIRE_SECONDS value. A value of 28800 (8 hours) is recommended, limiting token validity to a standard workday.

  • Enforce strict role-based access control (RBAC): Grant users only the minimum necessary permissions.

    • Assign users who create tokens to Teams with highly restrictive roles. Avoid granting broad permissions that could lead to privilege escalation.
  • Establish a clear offboarding process: Integrate token revocation into your organizational offboarding procedures. Your HR and IT offboarding processes must include a step for an Ansible Automation Platform administrator to revoke all active tokens for a departing user. Tokens can be manually revoked from the user’s profile under the Tokens tab.
  • Audit and monitor: Regularly review token-related activities for legitimacy in the Activity Stream.
Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2025 Red Hat