External Broker and Gateway Integration with API Manager¶
Solace is an advanced event broker which efficiently streams events and information across cloud, on-premises, and IoT environments. In this section, you will integrate the Solace gateway environment with API Manager.
A Solace Event API will be represented as an API in WSO2 API Manager. This API can be subscribed by applications in WSO2 Developer Portal, and the tokens generated by the Developer Portal applications can be used to authenticate and authorize requests to the Solace Event Broker via the Solace Event API.
Notice
This feature is supported from WSO2 API Manager 4.5.0 U2 Update level 4 onwards.
Prerequisites¶
Create a Solace Event API in Solace PubSub+ Cloud¶
- You must have a valid Solace API token. This can be created from Solace PubSub+ Cloud, by going to User Management > Token Management. To generate this, you need to have a Solace PubSub+ Cloud account with a manager role (or higher).
- You must have a Solace Event API created in Solace PubSub+ Cloud. An API in WSO2 API Manager will correspond to a Solace Event API.
- The Solace Event API must be bundled within a Solace Event API Product, associated with one or more Solace Plans. Note that, this Solace Event API Product must bundle only one Solace Event API (the one you created above). Solace Event API Products that bundle more than one Solace Event API will not be fetched by WSO2 API Manager.
- For each Solace Plan you are planning to use with Solace Event APIs, a corresponding Subscription Level Policy must be created in WSO2 API Manager. The Subscription Level Policy's name must be equal to the Solace Plan's name, and its Quota Limits should be Event Based (Async API). Other values are ignored, therefore you can set only the mandatory values as you wish, in order to successfully create a policy.
Create an OAuth Profile for a Solace Event Broker Service¶
An OAuth Profile will be used to authenticate the tokens obtained from WSO2 API Manager Developer Portal Applications, and allow access to requests made to the Solace Event Broker.
In Solace PubSub+ Cloud, go to Cluster Manager, and choose your Service which has the event broker that will be accessed by your Solace Event API. Create a new OAuth Profile under this. Provide the following values when creating the OAuth Profile, and leave the rest of the values as default.
| Configuration | Value |
|---|---|
| OAuth Client ID | wso2apim |
| OAuth Role | Resource Server |
| Issuer Identifier | https://<WSO2_APIM_HOST>:<WSO2_APIM_PORT>/oauth2/token (eg: https://<WSO2_APIM_HOST>:9443/oauth2/token. This can be obtained by decoding a JWT token generated from an APIM Developer Portal Application, and looking at the value of "iss") |
| JWKS Endpoint | <PUBLICLY_ACCESSIBLE_URL_OF_WSO2_APIM>/jwks.json |
| Authorization Groups Claim Name | aud |
| Username Claim Name | aud |
| Validate Access Token Audience | False |
| Validate Access Token Issuer | False |
| Validate Access Token Scope | False |
| Validate Access Token Type | False |
Configure the Solace APIM API Endpoint in WSO2 APIM¶
Go to the <WSO2_APIM_HOME>/repository/conf/deployment.toml file and add the following configurations.
[apim.solace_config]
apim_api_endpoint = "https://apim-production-api.solace.cloud/api/v2/apim"
token = "<YOUR_SOLACE_API_TOKEN>"
Create an API for the Solace Event API¶
A Solace Event API corresponds to an API in WSO2 API Manager. Follow the steps below to create an API in WSO2 APIM, for a Solace Event API which you have already created in Solace PubSub+ Cloud.
- Log in to the API Publisher via going to
https://<hostname>:9443/publisher, and providing your username & password. - Click on CREATE API and then click on Import an AsyncAPI under Streaming API.
- Choose the Solace Event API option. This will fetch the available Solace Event APIs - that are bundled within Solace Event API Products - from the Solace Event Portal, and display them along with associated Solace Plans. Only Solace Event APIs bundled as the sole API in a Solace Event API Product are displayed here.
- Choose the required Solace Event API and click on Next.
- The Name and Context will be automatically filled. Modify them if you need, and click on Create & Publish. The API will be published, and you will be taken to the API Overview page.
- Click on Portal Configurations, go to Subscriptions and choose the Subscription Level Policy (which you have already created as part of the prerequisites) that corresponds to the Solace Plan that you want to use for the API. Click on Save.
Subscribe to the API¶
- Log in to the Developer Portal via
https://<hostname>:9443/devportal, and provide your username & password. - Subscribe to the API you have created above with an Application. When subscribing, choose the Subscription Level Policy that corresponds to the Solace Plan that you want to use for the API.
- Obtain a token for the subscribed application.
Warning
Subscribing to a Solace API creates an Access Request in the Solace broker, which will be used to authorize the token generated from the Application in WSO2 API Manager Developer Portal. If the application keys are generated after subscribing to the API, the Access Request may not become live immediately, after which the generated tokens will not be usable with the Solace broker immediately.
To ensure smooth integration, it is recommended to follow the steps below:
- First, create an application (or select an existing one).
- Next, generate the required keys for the chosen application.
- Finally, proceed to subscribe to the Solace API.
Invoke the API¶
- Get the URL of the broker service. This can be obtained from the API definition in the Developer Portal, or from the Event Broker Service in the Solace Event Portal. Let's assume that the URL of the broker service is:
mqtts://mr-connection-4***9k.messaging.solace.cloud:8883, which uses MQTT protocol. - In your API client (eg: Postman), use the obtained URL and the generated token as follows, to establish a connection to the broker service.
| Configuration | Value |
|---|---|
| URL | mqtts://mr-connection-4***9k.messaging.solace.cloud:8883 |
| Auth Type | Basic Auth |
| Username | test (Username gets ignored, so any value is fine) |
| Password | OAUTH~{OAUTH_PROFILE_NAME}~{TOKEN} (eg: OAUTH~wso2apim~eyJ4N...) |