description
This page describes how to create and configure the default APIM resources

Resources

Overview

Every API Management installation includes several default resources that are commonly used in standard APIM implementations and can be configured during the API design phase. The recommended configuration method employs the Policy Studio.

The following sections summarize resource descriptions, configuration parameters, and configuration examples.

Resource descriptions

APIM includes several default resources, each of which is described in more detail below.

Cache: Maintains a cache linked to the API lifecycle, i.e., the cache is initialized when the API starts and released when the API stops. It is responsible for storing HTTP responses to avoid subsequent calls to the backend.
Cache Redis: Same as Cache (above), but the current implementation is based on Redis. The Cache Redis resource can be configured standalone or as part of the Redis Sentinel monitoring solution.
OAuth2 - Gravitee AM Authorization Server: Introspects an access_token generated by a Gravitee AM instance.
OAuth2 - Generic Authorization Server: Introspects an access_token generated by a generic OAuth2 authorization server. This resource provides a comprehensive configuration for how token introspection is applied in to accommodate common authorization servers.
Confluent Schema Registry: Fetches serialization/deserialization data from a Confluent schema registry.
HTTP Authentication Provider: Validates user credentials against an HTTP server.
Inline Authentication Provider: Authenticates a user in memory.
LDAP Authentication Provider: Authenticates a user in LDAP.
Keycloak Adapter: Introspects an access token.

{% hint style="warning" %} The Cache Redis plugin is not included in the default APIM distribution, but you can download and deploy it. For information on configuring cache in APIM, see Configure cache. For information on configuring the rate limit repository plugin for Redis, see Redis. {% endhint %}

OAuth2 APIM compatibility

APIM version	Gravitee Access Management plugin version	Generic Authorization Server plugin version
3.18.x to latest	2.x and upper	2.x and upper
3.10.x to 3.17.x	1.14.x and upper	1.16.x and upper
Up to 3.9.x	Up to 1.13.x	Up to 1.15.x

How to create a resource

To create a resource:

Log in to APIM Management Console.
Click APIs in the left sidebar.
Select the API you want to add the resource to.
Click Resources in the inner left sidebar.
Select the resource you want to configure:

Add a resource
In the CREATE RESOURCE form, configure the resource per the Configuration options section.

Configuration options

Each resource can be customized with a unique set of configuration options.

Cache resources

{% tabs %} {% tab title="Cache" %}

Create a Cache resource

Config param	Description	Default
Cache name	Name of the cache	my-cache
Time to idle	Maximum number of seconds an element can exist in the cache without being accessed. When this threshold is reached, the element expires and will no longer be returned from the cache. The default value is 0, i.e., no timeToIdle (TTI) eviction takes place (infinite lifetime).	0
Time to live	Maximum number of seconds an element can exist in the cache, regardless of usage. When this threshold is reached, the element expires and will no longer be returned from the cache. The default value is 0, i.e., no timeToLive (TTL) eviction takes place (infinite lifetime).	0
Max entries on heap	Maximum number of objects to be held in local heap memory (0 = no limit)	1000

{% endtab %}

{% tab title="Cache Redis" %}

Create a Cache Redis resource

The Cache Redis resource can operate standalone or with the Redis Sentinel monitoring solution. The majority of Cache Redis configuration options are common to both modes of operation, but several are exclusive to either standalone or Sentinel as indicated with a bold asterisk (*).

Config param	Description	Default
Cache name	Name of the cache	my-redis-cache
Release cache	Enabled: The resource will release the cache when the API is stopped Disabled: The cache must be managed manually on the Redis server	false
Max total	Maximum number of connections supported by the pool	8
Password	The password for the instance	-
Time to live	Maximum number of seconds an element can exist in the cache, regardless of usage. When this threshold is reached, the element expires and will no longer be returned from the cache. The default value is 0, i.e., no timeToLive (TTL) eviction takes place (infinite lifetime).	0
Timeout	Specifies the connection timeout and the read/write timeout	2000
Use SSL	Toggle to use SSL connections	true
Use standalone mode	Toggle to use standalone mode	true
Host	The host of the instance *Standalone config only	localhost
Port	The port of the instance *Standalone config only	6379
Use sentinel mode	Toggle to use sentinel mode. Sentinel provides high availability for Redis (effectively, the Redis deployment persists without human intervention, barring certain kinds of failures)	false
Master	Sentinel master ID *Sentinel config only	sentinel-master
Sentinel password	Sentinel password *Sentinel config only	-
Sentinel nodes	Array of sentinel nodes *Sentinel config only	-

{% endtab %} {% endtabs %}

OAuth2 resources

{% tabs %} {% tab title="Generic Authorization Server" %}

Create an OAuth2 Generic Authorization Server resource

Config param	Description	Default
Resource name	Name of the resource	-
Authorization server URL	URL of the authorization server	https://authorization_server
Token introspect endpoint	URL the resource uses to introspect an incoming access token	/oauth/check_token
System proxy	Toggle to use system proxy	false
Token introspect method	HTTP method to introspect the access token	GET
Client ID	Client identifier	-
Client secret	Client secret	-
Use HTTP header for client authorization	To prevent token scanning attacks, the endpoint MUST require access authorization. Gravitee uses an HTTP header for client authentication.	true
Authorization header	Authorization header	Authorization
Authorization scheme	Authorization scheme	Basic
Use a query parameter to supply access token	Access token is passed to the introspection endpoint using a query parameter	true
Token query param name	Query parameter that supplies access token	token
Use an HTTP header to supply access token	Access token is passed to the introspection endpoint using an HTTP header	false
HTTP header name	HTTP header used to supply access token	-
Use application/x-www-form-urlencoded form to send access token	Send access token in application/x-www-form-urlencoded form	false
Form param name	Form parameter name	token
User claim	User claim field to store end user in log analytics	sub

{% endtab %}

{% tab title="Gravitee AM Authorization Server" %}

Create an OAuth2 Gravitee AM Authorization Server resource

Config param	Description	Default
Resource name	Name of the resource	-
Server URL	URL of the Gravitee Access Management server	-
System proxy	Toggle to use system proxy	false
Version	Version of the Access Management server	V3_X
Security domain	Security domain (realm) from which the token has been generated and must be introspected	-
Client ID	Client identifier	-
Client secret	Client secret	-
User claim	User claim field to store end user in log analytics	sub

{% endtab %} {% endtabs %}

Authentication Provider resources

{% tabs %} {% tab title="HTTP" %}

Create an HTTP Authentication Provider resource

Config param	Description	Default
Resource name	The name of the resource	-
HTTP method	HTTP method to invoke the endpoint	POST
Use system proxy	Toggle to use the system proxy configured by your administrator	false
URL	Server URL	-
Request body	The body of the HTTP request. Supports the Gravitee Expression Language.	-
Authentication condition	The condition to be verified to validate that the authentication is successful. Supports the Gravitee Expression Language.	{#authResponse.status == 200}

{% endtab %}

{% tab title="Inline" %}

Create an Inline Authentication Provider resource

Config param	Description	Default
Resource name	The name of the resource	-
Inline users	List of inline users	-
{% endtab %}

{% tab title="LDAP" %}

Create an LDAP Authentication Provider resource

Config param	Description	Default
Resource name	The name of the resource	-
LDAP URL	The URL of the LDAP server, e.g., ldap://myserver.example.com:389. For SSL access, use the LDAPs protocol and the appropriate port, e.g., ldaps://myserver.example.com:636. For failover functionality, specify multiple URLs separated by commas (,).	-
Use StartTLS	Toggle to use StartTLS	false
Base DN	The base DN. Once configured, all Distinguished Names supplied to and received from LDAP operations are relative to the specified LDAP path.	-
Username	The username (principal) to use when authenticating with the LDAP server. Usually the DN of an admin user (e.g., Administrator), but may differ depending on server and authentication method.	-
Password	The password (credentials) to authenticate with the LDAP server	-
User search filter	Filter by user ID	uid={0}
User search base	If user search base isn't supplied, the search will be performed from the root	ou=users
Cache - maximum number of elements	Maximum number of cache elements used to store successful authentications	100
Cache - time to live	Maximum time to live of cache elements used to store successful authentications	60000
Connect timeout	Duration of time (milliseconds) that connections will block	5000
Response timeout	Duration of time (milliseconds) to wait for responses	5000
Min pool size	Minimum pool of initialized connections	5
Max pool size	Maximum pool of initialized connections	15

{% endtab %} {% endtabs %}

Confluent and Keycloak resources

{% tabs %} {% tab title="Confluent Schema Registry" %} {% hint style="warning" %} Enterprise only

As of Gravitee 4.0, the ability to use Confluent Schema Registry as a resource is an Enterprise Edition capability. To learn more about Gravitee Enterprise, and what's included in various enterprise packages, please:

Refer to the EE vs OSS documentation
Book a demo
Check out the pricing page {% endhint %}

Create a Confluent Schema Registry resource

Config param	Description	Default
Resource name	Name of the resource	-
Registry URL	URL of the schema registry	-
Use proxy	Toggle to use proxy to fetch schema	false
Proxy type	The type of the proxy	HTTP CONNECT proxy
Use system proxy	Toggle to use proxy configured at system level	false
Proxy host	Proxy host to connect to	-
Proxy port	Proxy port to connect to	-
Proxy username	Optional proxy username	-
Proxy password	Optional proxy password	-
Authentication mode	The authentication mode used to connect to Schema Registry	Basic
Authentication username	Authentication username	-
Authentication password	Authentication password	-
Verify host	Toggle to enable host name verification	true
Trust all	Toggle to force the Gateway to trust any origin certificates. Use with caution over the Internet. The connection will be encrypted but this mode is vulnerable to 'man in the middle' attacks.	false
Trust store type	The type of the trust store	None
Key store type	The type of the key store	None

{% endtab %}

{% tab title="Keycloak Adapter" %}

Create a Keycloak Adapter resource

Config param	Description	Default
Resource name	The name of the resource	-
Keycloak client configuration	The configuration of the Keycloak client	-
Local token validation	Toggle to use local token validation	true
User claim	User claim field to store end user in log analytics	sub
Verify host	Verify certificate on SSL connection to Keycloak host	false
Trust all	Trust all certificates, including self-signed	true
{% endtab %}
{% endtabs %}

Examples

Below are example JSON configuration files for several of the default resources.

{% tabs %} {% tab title="Cache" %}

{
    "name": "cache",
    "type": "cache",
    "enabled": true,
    "configuration": {
        "name": "my-cache",
        "timeToIdleSeconds":0,
        "timeToLiveSeconds":0,
        "maxEntriesLocalHeap":1000
    }
}

{% endtab %}

{% tab title="Cache Redis" %} Standalone configuration example:

{
    "name": "my-redis-cache",
    "type": "cache-redis",
    "enabled": true,
    "configuration": {
        "name": "my-redis-cache",
        "releaseCache": false,
        "maxTotal": 8,
        "password": "secret",
        "timeToLiveSeconds": 600,
        "timeout": 2000,
        "useSsl": true,
        "sentinelMode" : false,
        "standalone": {
            "host": "localhost",
            "port": 6379
        }
    }
}

Sentinel configuration example:

{
    "name" : "my-redis-cache",
    "type" : "cache-redis",
    "enabled" : true,
    "configuration" : {
        "name" : "my-redis-cache",
        "releaseCache": false,
        "maxTotal" : 8,
        "password" : "secret",
        "timeToLiveSeconds" : 600,
        "timeout" : 2000,
        "useSsl" : true,
        "sentinelMode" : true,
        "sentinel" : {
            "masterId" : "sentinel-master",
            "password" : "secret",
            "nodes": [
              {
                "host" : "localhost",
                "port" : 26379
              },
              {
                "host" : "localhost",
                "port" : 26380
              },
              {
                "host" : "localhost",
                "port" : 26381
              }
            ]
        }
    }
}

{% endtab %}

{% tab title="OAuth2 - Gravitee AM" %}

{
    "configuration": {
        "clientId": "my-client",
        "clientSecret": "f2ddb55e-30b5-4a45-9db5-5e30b52a4574",
        "securityDomain": "my-security",
        "serverURL": "https://graviteeio_access_management",
        "userClaim": "sub"
    }
}

{% endtab %}

{% tab title="OAuth2 - Generic Auth Server" %}

{
    "configuration": {
        "introspectionEndpoint": "https://my_authorization_server/oauth/check_token",
        "introspectionEndpointMethod": "POST",
        "clientAuthorizationHeaderName": "Authorization",
        "clientAuthorizationHeaderScheme": "Basic",
        "clientId": "my-client",
        "clientSecret": "f2ddb55e-30b5-4a45-9db5-5e30b52a4574",
        "tokenIsSuppliedByHttpHeader": false,
        "tokenIsSuppliedByQueryParam": true,
        "tokenQueryParamName": "token",
        "useClientAuthorizationHeader": true
    }
}

{% endtab %} {% endtabs %}

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

resources.md

resources.md

Resources

Overview

Resource descriptions

OAuth2 APIM compatibility

How to create a resource

Configuration options

Cache resources

OAuth2 resources

Authentication Provider resources

Confluent and Keycloak resources

Examples

Files

resources.md

Latest commit

History

resources.md

File metadata and controls

Resources

Overview

Resource descriptions

OAuth2 APIM compatibility

How to create a resource

Configuration options

Cache resources

OAuth2 resources

Authentication Provider resources

Confluent and Keycloak resources

Examples