

Subscription Validation¶

The subscription validation is configurable for JWT and Opaque/reference tokens. In order to mandate the subscriptions, subscription validation can be enabled. If validation has failed, it will send an error message with error code 900908.

In WSO2 Microgateway subscription validation can be done in two ways.

Self-contained token with subscribedAPIs claim

To authorize an API request with the self-contained JWT token under an issuer with subscription validation, the API name and version should be listed under subscribedAPIs claim of the JWT token.

Note

When an older version of WSO2 API Manager (3.1.* and below) is used as the key manager it sends the subscribed APIs as a list in the JWT under the subscribedAPIs claim. Therefore it is required to have the corresponding API name and version listed under subscribedAPIs claim to authorize the API request when JWT tokens issued by older API Manager versions are used.
Event Hub based subscription validation

For opaque/reference tokens and JWTs issued by API Manager 3.2.0 onwards, to enable subscription validation it requires the Event Hub to fetch Application and Subscription data from WSO2 API Manager.

The latest versions of API manager do not include the subscribedAPIs claim in the JWT, instead, subscription validation is done using the [eventhub]. Refer documentation on Event Hub and Subscription Validation Model to understand how WSO2 Microgateway validates subscriptions using Event Hub.

Configure Subscription Validation¶

You can enable or disable subscription validation using the following configuration and it is disabled by default. Add the following to the <MGW-RUNTIME_HOME>/conf/micro-gw.conf.

Configure Event Hub and key managers for token authentication.

In order to do subscription validation, the [eventHub] must be enabled for the latest versions of API Manager.

# Configurations for retrieving API and subscription data from API Manager.
[apim.eventHub]
    # Enable/ Disable the feature
    enable = true
    # The API Manager URL
    serviceUrl = "https://localhost:9443"
    # The internal data REST API context.
    internalDataContext="/internal/data/v1/"
    # User name and password of the internal data api.
    username="admin"
    password="admin"
    # The message broker connection URL.
    eventListeningEndpoints = "amqp://admin:admin@carbon/carbon?brokerlist='tcp://localhost:5672'"

For JWT, provide JWT issuer configurations. Follow document on configure Multiple JWT issuers. For Opaque / reference token, provide introspection configurations. Follow document on Secure APIs Using Opaque Tokens.

Note

Older versions of WSO2 API Manager (2.x series and 3.0.0, 3.1.0) do not have the Event Hub capabilities. Therefore, when using Microgateway with those APIM versions, disable the Event Hub and set enableLegacyKM to true. This will use the older key validation service to validate the token and subscriptions for reference/ opaque tokens.

# Key manager configurations
[keyManager]
# Connection URL of the Key Manager server
serverUrl = "https://localhost:9443"
# The token endpoint context of the Key Manager server
tokenContext = "oauth2"
# When Microgateway is used with older APIM versions for subscription validation by using KeyValidation service.
enableLegacyMode = true
...
[apim.eventHub]
# Enable / Disable the feature
enable = false

Enable subscription validation.
- Enable Subscription Validation for JWT and Opaque/Reference tokens globally by enabling validateSubscriptions in security configuration.
```
[security]
    # Enable/ Disable subscription validation for tokens.
    validateSubscriptions = true
```
- Enable/disable Subscription Validation for JWT tokens by configuring validateSubscription under the corresponding JWT issuer configuration.
```
[[jwtTokenConfig]]
    issuer = "https://localhost:9443/oauth2/token"
    audience = "http://org.wso2.apimgt/gateway"
    certificateAlias = "wso2apim310"
    # Validate subscribed APIs
    validateSubscription = true
```
Note

If validateSubscription is configured(i.e. enabled/disabled) in [[jwtTokenConfig]], regardless of the global validateSubscription configuration in [security], validateSubscription configuration in [[jwtTokenConfig]] will be effective for the particular JWT issuer

Top