AWX in Action

OAuth Applications: Per-Integration Credentials

You can also use AWX applications to authenticate with the API. This is useful in different scenarios, such as:

• When you want a more secure and controlled way to access the API (e.g., for third-party integrations).
• When you want to configure tokens scoped to organizations, unlike PAT (Personal Access Token), which is user-scoped.

Here is how you can create an application and generate tokens in AWX:

• Go to Applications in the side menu.
• Click on Add.
• Choose a Name, a Description, an Organization, an Authorization Grant Type, Redirect URIs, and Client Type.

Authorization Grant Types

The Authorization Grant Type can be either Authorization Code or Resource Owner Password-Based. Before diving into the details, let's understand what an OAuth 2.0 grant type is.

Traditionally, when a user wants to access a resource on a server, they provide their credentials (e.g., username and password) to the server, which then validates them and grants access. This approach has limitations: the need to provide credentials for every request, the risk of credentials being intercepted, and the lack of a standardized way to delegate access to third-party applications.

If you want to read more about OAuth 2.0, you can find more information on the Internet Engineering Task Force (IETF) website (RFC 6749).

Many of the concepts and terms used in the explanation below show up when developing applications that interact with AWX. Even if we walk through the details, using the AWX CLI is straightforward and doesn't require an in-depth understanding of OAuth 2.0.

Let's look at the two grant types in AWX:

Authorization Code

Authorization Code is the OAuth2 grant type to use when an external web application needs to act on behalf of an AWX user. The app never sees the user's password. Instead, it exchanges a short-lived code for an access token through a back-channel call that includes the app's own client credentials, which makes interception harder than handing tokens out in the browser.

The full flow with AWX as the authorization server:

1. The user clicks a login link in the external app.
2. The app redirects the browser to /api/o/authorize/ with its client_id, redirect_uri, and requested scope (read or write).
3. AWX shows the login and consent screen.
4. The user authenticates and approves the requested scope.
5. AWX redirects the browser back to the app's redirect_uri with a one-time authorization code (valid for 10 minutes by default, controlled by AUTHORIZATION_CODE_EXPIRE_SECONDS).
6. The app's backend POSTs the code, its client_id, and client_secret to /api/o/token/.
7. AWX validates the code and credentials against its own records. No call to the resource API happens here.
8. AWX returns an access_token, refresh_token, token_type, and expires_in.
9. The app calls AWX resource endpoints like /api/v2/me/ with Authorization: Bearer.
10. AWX returns the requested data.

The following diagram illustrates the Authorization Code grant type flow: