OAuth

OAuth (Open Authorization) is an industry-standard protocol for authorization that allows secure access to resources without exposing user credentials. It facilitates secure, third-party access to your APIs using tokens instead of credentials, ensuring that only authorized clients with the proper scope can access your endpoints.

liblab OAuth integration focuses on the clientCredentials flow, used for server-to-server communication, such as API authentication. This method is secure, scalable, and aligns with OpenAPI standards for easy implementation.

info

For additional information on how to configure the OpenAPI specification to  use the clientCredentials flow, access the OpenAPI Specification or OAuth 2.0 pages.

The liblab OAuth approach provides seamless API authentication, efficient token management, and flexible scope control, ensuring users can access APIs securely with the correct permissions. The configuration is designed to be adaptable to your needs, whether you require OAuth at a global level or for specific endpoints.

Supported SDK languages and versions

The following table lists the programming languages that support the OAuth feature.

TypeScript v1	TypeScript v2	Java v1	Java v2	Python v1	Python v2	C#	Go	PHP
❌	❌	❌	❌	❌	✅	❌	❌	❌

liblab is constantly working to integrate the OAuth feature into more programming languages.

liblab OAuth configuration

You can configure OAuth in two ways through the liblab configuration file:

1. Global Configuration: Set OAuth globally for all API endpoints.
2. Endpoint-Specific Configuration: Customize OAuth settings for individual endpoints.

1. Global OAuth configuration

To enable OAuth globally for all API endpoints, you can modify the auth array in the liblab config file. Add "oauth" as follows:

auth: ["oauth"]

The above configuration only enables OAuth for the endpoints. To fully implement OAuth and require clients to authenticate using the specified OAuth flow, you must configure the oauth object under customizations -> authentication in the OpenAPI specification.

OAuth settings

To customize OAuth settings, defined in the OpenAPI specification, you have to add parameters under the customization -> authentication -> oauth section. Below is a list of customizable parameters:

Key	Description	Required
enabled	(Boolean) Specifies if OAuth is enabled.	✅
basic	(Bollean) If true, sends client_id and client_secret as basic authentication in the OAuth request.	❌
tokenEndpoint	Object that customizes retrieving and using the access token. If an endpoint is already defined by the path and method in the OpenAPI specification, this object can override that definition to apply custom OAuth settings.	❌
tokenEndpoint.method	The HTTP method, post or get, used to retrieve the token. It's only required if the tokenEndpoint is defined.	✅
tokenEndpoint.path	The path to use for the token endpoint. It's only required if the tokenEndpoint is defined.	✅
tokenEndpoint.definition	The definition of the token endpoint, using OpenAPI specification syntax. It's only required if the tokenEndpoint is defined.	✅
securityScheme	Object that specifies the security scheme used for OAuth.	❌
securityScheme.name	The name of the security scheme. If it exists in the OpenAPI specification, it will be overwritten. It's only required if the securityScheme is defined.	✅
securityScheme.definition	The definition of the security scheme, following OpenAPI specification syntax. It's only required if the securityScheme is defined.	✅

The next code block presents an example of global OAuth configuration:

"oauth": {
  "enabled": true,
  "basic": true,
  "tokenEndpoint": {
    "path": "/oauth/token",
    "method": "post",
    "definition": { ... }  // token endpoint definition
  },
  "securityScheme": {
    "name": "mySecurityScheme",
    "definition": { ... }  // security scheme definition
  }
}

2. Configuring OAuth for specific endpoints

To configure OAuth for specific API endpoints, use the endpointCustomizations feature. This allows you to apply OAuth to individual endpoints while bypassing others.

The next code block presents an example of an endpoint-specific configuration. In this example, OAuth is applied only to the GET /pets endpoint:

{
 ...
  "customizations": {
    "endpointCustomizations": {
      "/pets": {
        "get": {
 ...
          "security": [
            {
              "<securitySchemaName>": ["read:scope"]
            }
          ]
        }
      }
    }
  }
}

In this case, the GET /pets endpoint requires OAuth authentication with the specified scope read:scope.