Working with OAuth 2.0 clients

This article explains how to manage OAuth 2.0 clients in the context of Airlock SaaS. OAuth 2.0 clients are typically used for system-to-system communication on behalf of a user. In Airlock SaaS, an OAuth 2.0 client enables access to the Airlock SaaS public API in order to perform specific actions on your tenants. Currently, supported actions include uploading and activating IAM configurations for the selected tenant.

This article details how to create, edit, and delete OAuth 2.0 clients in the Airlock Console. It also shows how to authenticate with the API and perform specific actions on your tenants.

Managing OAuth 2.0 clients

Prerequisites

To create, edit, and delete OAuth 2.0 clients, you need the SaaS Administrator role. See also SaaS roles and permissions.

Location in the Airlock Console

You manage the OAuth 2.0 clients in the OAuth 2.0 clients dialog of the SaaS Management Center. For this, go to Administration > OAuth 2.0 clients.

Creating an OAuth 2.0 client

In the OAuth 2.0 clients dialog, click the New OAuth 2.0 client button.
Specify the fields in the appearing window:
- Name: Give the new OAuth client a meaningful name.
- Permissions: Choose the actions this OAuth client is permitted to perform. Select at least one permission. Note: Once the OAuth client is created, you can no longer change its permissions.
- Currently (June 2025), the following permissions are available:
  - Config activate (for non-production tenants only): Permission to perform the action “Activate configuration”.
  - Config upload: Permission to perform the action “Upload configuration”.
- More permissions may be added later.
- Tenant access: Select the tenant(s) that this OAuth client will be allowed to access. Select at least one tenant from the list of available tenants. You can modify your selection after the OAuth client has been created.
Click Save to create the new OAuth 2.0 client.
The next dialog displays the new OAuth client's credentials in the Client ID and Client secret fields. Copy and securely store these credentials - you need them to access the SaaS public API.
Notice
Copy and store the client secret now. For security reasons, you cannot view it again later.
Click Close to finish the procedure.
The OAuth 2.0 client is created. The next dialog shows the settings of the newly-created client.

Reading and editing an OAuth 2.0 client

To view and edit the details of an existing OAuth 2.0 client, click its entry in the list shown in the OAuth 2.0 clients dialog. The next dialog displays the OAuth client's current settings, including its name, ID, granted permissions and tenant access. If needed, you can modify the client's name or adjust the tenants to access. The client secret and granted permissions, however, cannot be changed.

Deleting an OAuth 2.0 client

Currently, it is not possible to delete an OAuth 2.0 client. If you want to remove one, contact SaaS Support.

Accessing the SaaS public API with an OAuth 2.0 client

You can use the OAuth 2.0 clients to access the SaaS public API and perform granted actions on your tenants. To be able to do so, the OAuth client must authenticate to the public API using an access token, which is obtained via the OAuth Client Credentials Grant flow - a standard mechanism for machine-to-machine authentication without user involvement.

This section first explains how to obtain the access token. It then shows how to authenticate to the Saas public API and perform a granted action.

Info

For more information on OAuth in general and on OAuth grants, see the Airlock IAM online documentation:

Step one: Obtaining an access token

To obtain an access token for an OAuth 2.0 client, you must call the OAuth 2.0 token endpoint of the Loginapp REST API.

Prerequisites

You must include the OAuth 2.0 client's ID and secret in the request. These credentials are provided by the SaaS Management Center when you created the OAuth 2.0 client. Make sure you have them available now.

Instructions

Configure your POST request as follows:

Terminal box

POST https://manage.airlock.cloud/login/rest/oauth2/authorization-servers/management-center/token 
Authorization: Basic {{oauth-client-id oauth-client-secret}} 
Accept: */* 
Content-Type: application/x-www-form-urlencoded; charset=utf-8 
 
grant_type = client_credentials & 
scope = CONFIG_ACTIVATE CONFIG_UPLOAD

Path to the OAuth 2.0 token endpoint

https://manage.airlock.cloud/login/rest/oauth2/authorization-servers/management-center/token

Request headers

Authorization: Defines the authentication type. Here, a basic authentication (Basic) is sufficient. As username/password (oauth-client-id oauth-client-secret), enter the OAuth 2.0 client's ID and secret that you stored earlier when you created the OAuth 2.0 client.
Accept: Defines the accepted media types in the response. Here, the response may contain any media type (*/*).
Content-Type: Specifies the format of the request body. Must be set to URL-encoded form data with UTF-8 character encoding (application/x-www-form-urlencoded; charset=utf-8)

Request body

grant_type: Must be client_credentials (for the OAuth Client Credentials Grant flow).
scope: Specifies the permissions that you granted to this OAuth 2.0 client.
- CONFIG_ACTIVATE : Permission to activate a configuration
- CONFIG_UPLOAD : Permission to upload a configuration

The above POST request returns the following response:

Example

{ 
    "access_token": "...", 
    "scope": "CONFIG_ACTIVATE CONFIG_UPLOAD", 
    "token_type": "Bearer", 
    "expires_in": 180 
}

access_token: This token is required to authenticate the OAuth 2.0 client with the SaaS public API. Store the token value for the following step.

Notice

Note that the returned access_token is only valid for 180 seconds (“expires_in”: 180)!

Step two: Accessing the SaaS public API to perform a granted action

After having obtained the access token, the OAuth 2.0 client can authenticate with the SaaS public API and perform the previously granted permissions.