OAuth 2.0 authorization

Create authentication configuration

1. In an .http file, in the Run with list, select an environment to which you want to add an authentication configuration.

2. In the toolbar, click and select Auth Configuration.

   This will add an authentication configuration template to the public environment file, in the "Auth" object under "Security" of the selected environment. For example:

   { "dev": { "Security": { "Auth": { "auth-id": { "Type": "OAuth2", "Grant Type": "", "Client ID": "" } } } } }

3. Replace the placeholder auth-id with a meaningful name that you will use to refer to this configuration in your .http file.

4. Specify the authentication parameters. The required parameters depend on the selected "Grant Type". Use Aqua coding assistance while filling out the authentication parameters: Start typing a parameter name or press Ctrl+Space to get the list of available JSON keys.

Use authentication configuration in HTTP requests

Once an authentication configuration is created, you can use it to get an access token and authenticate your requests.

1. Pass the name of an authentication configuration to the {{$auth.token()}} variable, for example, {{$auth.token("my-config")}}. You can use this variable in the request Authorization header or in query parameters.

2. Click to send the request. Before accessing the protected resource, the HTTP Client will send a request to the authorization server to obtain an access token.

3. When prompted, complete the authentication process. If the authentication is successfully completed, the HTTP Client will access the protected resource.

To quickly add the {{$auth.token()}} variable, you can use live templates: Under the HTTP method, in the header section, start typing AuthorizationToken and select an available authentication from the list of suggestions that appears.

When you run such a request, the Show Auth Log button will be available in the Services tool window. It lets you view the redirect page, access token, and other authentication details.

Manually acquire access token

When you refer to an authentication configuration in an HTTP request, the HTTP Client automatically gets (or refreshes) an access token before accessing the protected resource. If you want to get an access token without sending an actual request to the protected resource, you can acquire the access token manually.

1. In the http-client.env.json file, click next to your authentication configuration name.

2. If the authentication configuration contains private variables, select a private environment file in the popup that appears.

3. When prompted, complete the authentication process.

If the authentication is completed successfully, Aqua will get the access token. If you already have the access token, but it has expired, Aqua will refresh it.

Get new access token

Besides refreshing the token, you can get a new one by re-authenticating, that is, by repeating the original flow that you used to get the initial access token.

1. In the http-client.env.json file, place the caret on the authentication configuration name.

2. Press Alt+Enter (Show Context Actions), and select Force Acquire Auth Token.

3. If the authentication configuration contains private variables, select a private environment file in the popup that appears.

You can invoke the same action when your caret is on the $auth.token variable in the .http file. In this case, you don't need to select a private environment file because the HTTP Client will use the one located in the same folder as your .http file.

Clear browser cookies

Your authorization server may store authentication data in the browser cookies. If you want to test the authentication flow with different data, you may need to clear cookies of the built-in JCEF browser.

1. In the http-client.env.json file, place the caret on the authentication configuration name and press Alt+Enter (Show Context Actions).

2. Select Clear browser cookies.

Alternatively, you can clear cookies by clicking in the HTTP Client Authentication Log tool window.

Use ID token instead of access token

If your server requires the use of an ID token instead of an access token, you can configure the HTTP Client to do this in any of the following ways:

• In your authentication configuration, use the "Use ID Token": true parameter.

• In an .http file, use the $auth.idToken variable, for example, Authorization: Bearer {{$auth.idToken("auth-id-1")}}.

Use custom authentication parameters

The HTTP Client provides an option to define custom request parameters that your authorization server may require. This includes, for example, resource and audience that extend the OAuth 2.0 Authorization framework.

1. In your authentication configuration, add the "Custom Request Parameters" object.

2. Inside "Custom Request Parameters", enter your parameter name and value (a string or an array).

3. If you want to restrict the parameter usage to certain requests, define the value as an object with two keys:

   • "Value" (parameter value)

   • "Use" — The scope for using the parameter. It has three possible values:

     • "Use": "Everywhere" (in any request)

     • "Use": "In Auth Request" (use in authentication requests only)

     • "Use": "In Token Request" (use in token requests only)

   For example:

   "auth-id-1": { "Type": "OAuth2", "Custom Request Parameters": { "audience": { "Value": "https://my-audience.com/", "Use": "In Token Request" }, "resource": [ "https://my-resource/resourceId1", "https://my-resource/resourceId2" ], "my-custom-parameter": "my-custom-value" }, }

Use the HTTP Client Authentication Log tool window to view parameters and their values used in the request.