3scale Immutable Registry

The 3scale immutable registry uses a 3scale backend to derive its configuration, rather than the Apiman manager. It works with both 3scale SaaS and 3scale on-prem.

This version of the registry is immutable; configuration is loaded only once at startup, and a restart is required to reflect new changes.

This initial 3scale integration is on the apiman side only; applying policies requires a separate JSON overlay file to be provided and is not yet stored in the 3scale backend.

After loading your APIs will be available at: /services/<API SYSTEM NAME>. For example, http://localhost:8081/services/mycoolapi.
Table 1. Available implementations:
Implementation Notes

io.apiman.gateway.engine.threescale.ThreeScaleImmutableRegistry

Recommended. Works well in multi-node setups.

This registry is optimised for the Vert.x gateway implementation. Although it should work for other platforms, it is unlikely to be as performant.

Example

"registry": {
  "class": "io.apiman.gateway.engine.threescale.ThreeScaleImmutableRegistry",
  "config": {
    "accessToken": "<YOUR ACCESS TOKEN>", (1)
    "apiEndpoint": "https://<YOUR-USERNAME>-admin.3scale.net/", (2)
    "backendEndpoint": "https://su1.3scale.net:443", (3)
    "defaultOrgName": "${3scale.defaultOrgName}",
    "defaultVersion": "${3scale.defaultVersion}",
    "policyConfig": {
      "overlayUri": "file:///my/overlay.json", (4)
      // For HTTP(S), BASIC and OAuth2 are supported. Refer to docs for more info.
      "auth": "NONE" (5)
    },
  }
}
  1. 3scale access token.

  2. API endpoint, if SaaS is usually the https://<username>-admin.3scale.net provided.

  3. 3scale backend to do auth and reports. By default this is the SaaS endpoint, but if you are deploying on-prem you should alter this.

  4. Apiman policy overlay JSON file, can be HTTP, HTTPS or File, as detailed in Policy Config.

  5. If using HTTP/S Authentication can be provided.

Required Parameters

Name Type Description

accessToken

String

3scale access token to provide access to various APIs.

apiEndpoint

String

API do auth and reports. API endpoint, if SaaS is provided and usually in the format https://<username>-admin.3scale.net.

backendEndpoint

3scale backend endpoint

3scale backend to do auth and reports. By default this is the SaaS endpoint, but if you are deploying on-prem you should alter this. Default value: https://su1.3scale.net:443.

environment

String

Which environment to use (e.g. production, staging). Default value: production.

strategy

Enum

Various strategies for auth and reporting.

Must be one of:
  • STANDARD: Standard 3scale rate-limiting.

  • BATCHED_HYBRID: A hybrid approach that should provide substantially lower volumes of traffic to the 3scale backend when the gateway is under higher load.

    Rather than using the standard rate-limiting algorithm that issues one request to the backend per request, it batches reports and flushes at a high frequency.

    Following a report flush a number of subsequent requests are issued using the standard algorithm to allow the backend to inform the gateway of the current rate-limiting status.

    The tradeoff is that there is a slightly wider window allowing quota overruns.

policyConfig

Policy Config

Apiman policy overlay config.

Default Value: Empty

Policy Config

Table 2. Required Parameters
Name Type Description

overlayUri

String

URI to apiman policy overlay to load as JSON from file, http or https.

Refer to Policy Overlay Configuration for format information.

auth

Enum

See: Authentication. Auth mechanism to access resource indicated in overlayUri when HTTP or HTTPS.

Refer to the subsections for each auth mechanism for respective configuration options.

Must be one of:
  • NONE: No auth needed.

  • BASIC: BASIC auth.

  • KEYCLOAKOAUTH2: Convenience Keycloak OAuth2 implementation.

  • OAUTH2: Generic OAuth2.

Default value: NONE.

Example
"policyConfig": {
    "overlayUri": "file:///path/to/your/apiman-your-3scale-overlay.json",
    "auth": "NONE"
}

Policy Overlay Configuration

Configuration of the registry is via a simple JSON file consisting of a list of APIs mapping to your 3scale APIs; enabling you to augment them with apiman policies.

Importantly, the apiId field maps to your 3scale system name.

Example
{
  "apis": [{
    "apiId": "My3ScaleSystemID", (1)
    // Plugin's JSON config.
    "apiPolicies": [{ (2)
      "policyJsonConfig": "{ \"responseCode\" : \"403\", \"ipList\" : [ \"1.2.3.4\" ] }", (3)
      // Plugin coordinates.
      "policyImpl": "plugin:io.apiman.plugins:apiman-plugins-url-whitelist-policy:1.3.1.Final:war/io.apiman.gateway.engine.policies.IPWhitelistPolicy" (4)
    }]
  }]
}
  1. See API ID.

  2. The ordered policy chain to be applied to your API.

  3. See Policy Config.

  4. See Policy Implementation URI.

API ID

The API ID should match your 3scale system ID. For example if your system name is anotherservice then you should set your apiId field as anotherservice:

3scale system id.png

Apiman will map the defined policy chain into the same 3scale API.

Policy Config

policyJsonConfig is an escaped string containing the policy plugin’s configuration, and must be valid according to the plugin’s schema.

For in-built policies, you can refer to the Policies section of the User Guide to see the available configuration options and samples.

However, for custom policies without explicit documentation a bit more effort may be required:

Each plugin’s schema is defined in source code and bundled within the plugin’s WAR, as defined by the form element in src/main/apiman/policyDefs/<policy-Name>-policyDef.json.

For example, the Simple Header Policy’s simple-header-policyDef.json file points to a JSON schema at schemas/simple-header-policyDef.schema.

In the following sample we’ve built a JSON configuration corresponding to the schema.

Example Simple Header Policy config
{
  "addHeaders": [{
    "headerName": "X-Clacks-Overhead",
    "headerValue": "GNU Terry Pratchett",
    "valueType": "String",
    "applyTo": "Request",
    "overwrite": true,
    "resolvedHeaderValue": "GNU Terry Pratchett"
  }],
  "stripHeaders": []
}

And escaped it, before inserting into policyJsonConfig: [1]

Example Simple Header Policy in policyJsonConfig
"policyJsonConfig": "{\"addHeaders\":[{\"headerName\":\"X-Clacks-Overhead\",\"headerValue\":\"GNU Terry Pratchett\",\"valueType\":\"String\",\"applyTo\":\"Request\",\"overwrite\":true,\"resolvedHeaderValue\":\"GNU Terry Pratchett\"}],\"stripHeaders\":[]}"
For more information, refer to the plugin developer’s guide.

Policy Implementation URI

The policy implementation URI is used by the apiman gateway to look up your plugins. You can find this in the plugin’s policyDef.json file, usually located in src/main/apiman/policyDefs/.

The format is:

plugin:{pluginGroupId}:{pluginArtifactId}:{pluginVersion}:{pluginType}/{fullyQualifiedClassname}

In our example of the Simple Header Policy it’s:

plugin:${project.groupId}:${project.artifactId}:${project.version}:${project.packaging}/io.apiman.plugins.simpleheaderpolicy.SimpleHeaderPolicy

Which then informs us that the URI is:

plugin:io.apiman.plugins:apiman-plugins-simple-header-policy:1.3.1.Final:war/io.apiman.plugins.simpleheaderpolicy.SimpleHeaderPolicy

Note that the classifier is almost certainly war.

For more information, refer to the plugin developer’s guide.

Authentication

This is authentication to retrieve the apiman policy overlay, not into the 3scale backend. This is not needed if you are just providing a file:// (or not using a policy overlay).

BASIC

Standard BASIC auth with static credentials.

Table 3. Required Parameters
Name Type Description

username

String

A username. Consider using variable substitution.

password

String

A password. Consider using variable substitution.

Example
"config": {
  "policyConfig": {
    "overlayUri": "file:///path/to/your/apiman-your-3scale-overlay.json",
    "auth": "BASIC",
    "username": "foo",
    "password": "bar" (1)
  }
}
  1. Consider using environment substitution, like ${foo}

Keycloak OAuth2

A convenience Keycloak OAuth2 implementation, allowing you to paste your chosen client configuration from the Keycloak console into the config section.

To retrieve it:

  1. Log into Keycloak (e.g. http://localhost:8080/auth).

  2. Clients<Your-Client>Installation.

  3. Select Keycloak OIDC JSON for Format Option.

  4. Copy the contents and merge into the config selection where indicated below.

The precise configuration you need to provide will vary depending upon your Keycloak setup.

Due to a current limitation in the underlying OAuth2 library you may be required to provide a credentials section to avoid issues. You can change your client type to confidential, or simply provide a dummy credentials section.
Example
"config": {
  "policyConfig": {
    "auth": "KeycloakOAuth2",
    "flowType": "password",
    "username": "foo",
    "password": "bar",
    // Start paste & replace your Keycloak config here.
    "realm": "apiman",
    "realm-public-key": "< snip >",
    "auth-server-url": "http://localhost:8080/auth",
    "ssl-required": "none",
    "resource": "apiman-gateway-api",
    "credentials": {
      "secret": "217b725d-7790-47a7-a3fc-5cf31f92a8db"
    }
    // End paste here.
  }
}
Table 4. Required Parameters
Name Type Description

flowType

Enum

The OAuth2 flow for your configuration.

Must be one of:
  • PASSWORD

  • CLIENT

  • AUTH_CODE

  • AUTH_JWT

Table 5. Optional Parameters
Name Type Description

username

String

A username. Usually only useful if using the password flowType.

password

String

A password. Usually only useful if using the password flowType.

OAuth2

The combination of required parameters and optional parameters will vary considerably depending upon your configuration.
Table 6. Required Parameters
Name Type Description

flowType

Enum

The OAuth2 flow for your configuration.

Must be one of:
  • PASSWORD

  • CLIENT

  • AUTH_CODE

  • AUTH_JWT

oauthUri

String

The OAuth2 URI.

clientId

String

The OAuth2 client ID.

clientSecret

String

The OAuth2 client secret.

Table 7. Optional Parameters
Name Type Description

site

String

Site URI

publicKey

String

Public key

clientSecret

String

Client secret

username

String

A username. Usually only useful if using the password flowType.

password

String

A password. Usually only useful if using the password flowType.

authorizationPath

String

The authorization path

tokenPath

String

The token path

recovationPath

String

The revocation path

scopeSeparator

String

The introspection path

logoutPath

String

The logout path (OIDC)

useBasicAuthorizationHeader

boolean

Whether to use BASIC auth header (OIDC)

clientSecretParameterName

String

Client secret query parameter name (OIDC)

userInfoPath

String

User info path (OIDC)

introspectionPath

String

User info path (RFC7662)

userAgent

String

User agent

privateKey

String

Private key


1. One might wonder why JSON is escaped inside of JSON. The field name is somewhat of a misnomer, it is intended to be generic and could be XML, YAML, etc.

results matching ""

    No results matching ""