diff --git a/en/docs/tutorials/integrating-with-solace.md b/en/docs/tutorials/integrating-with-solace.md index 2d96aad55f..138ed145bb 100644 --- a/en/docs/tutorials/integrating-with-solace.md +++ b/en/docs/tutorials/integrating-with-solace.md @@ -1,166 +1,84 @@ # External Broker and Gateway Integration with API Manager -WSO2 API Manager now supports integrating external third party Gateways and Brokers. Solace is an advanced event broker which is efficiently streaming events and information across cloud, on-premises, and IoT environments. In this section, you will integrate the Solace gateway environment 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. -## Integrating the Solace Event Broker +A [**Solace Event API**](https://docs.solace.com/Cloud/Event-Portal/event-portal-designer-event-apis.htm#Creating_an_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. !!! warning "Notice" - This feature is currently not supported. WSO2 is actively working on resolving the issues. For the latest updates or inquiries, please contact [WSO2 Support](https://wso2.com/contact/). + This feature is supported from WSO2 API Manager 4.5.0.4 onwards. +## Prerequisites -1. Go to the [Solace PubHub+](https://solace.com/products/event-broker/) portal. - -2. Create a new account and configure a Solace Broker. -
Create new account - - !!! tip - See the [Getting Started Guide](https://github.com/solace-iot-team/platform-api/wiki/WSO2-API-Manager-Quickstart) for info on how to setup an account with Solace PubHub+. -3. Extract the required configurations mentioned in Step-4 from the Solace broker. -4. Open the `/repository/conf/deployment.toml` file and add the following according to your account details. Make sure to restart the server after adding the configurations. - ```toml - [[apim.gateway.environment]] - name = - display_name = - type = - display_in_api_console = - description = - provider = - service_url = - username = - password = - ws_endpoint = - wss_endpoint = - http_endpoint = - https_endpoint = - show_as_token_endpoint_url = false - - [apim.gateway.environment.properties] - Organization = - DevAccountName = - ``` - Note that only all these properties are **mandatory**, except `show_as_token_endpoint_url`. - -5. The Solace broker gateway is now available in the API Publisher. - View Solace Broker - -## Creating and deploying an API - -You can use the Async API specification generated from the Solace PubSub+ Hub to create APIs in WSO2 API Manager. - -### Step 1 - Importing the Async API from Solace - -Before you begin: Make sure that you have integrated the Solace event broker with WSO2 API Manager as shown in the above section. +### 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**](https://docs.solace.com/Cloud/Event-Portal/event-portal-designer-event-apis.htm#Creating_an_Event_API) created in [Solace PubSub+ Cloud](https://console.solace.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**](https://docs.solace.com/Cloud/Event-Portal/event-portal-designer-event-api-products.htm#Creating_an_EAP), 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]({{base_path}}/design/rate-limiting/adding-new-throttling-policies/#adding-a-new-subscription-level-rate-limiting-tier) 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. -1. Login to the API Publisher via **https://<hostname>:9443/publisher** -2. Click **CREATE API** and then click **Import AsyncAPI Definition** - Import AsyncAPI Definition +### Create an OAuth Profile for a Solace Event Broker Service -3. The following two options to import the AsynAPI definition appear. - 1. AsyncAPI URL - If you select this option, you need to provide a URL of a Solace API Specification. - 2. AsyncAPI File - If you select this option, click Browse File to Upload and upload a file, which contains a Solace AsyncAPI definition. - Select your preferred method and click **NEXT**. +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. -!!! info - If the Async API specification is a valid Solace Async API specification, the portal will display the `Identified as Solace Event Portal API` tag. +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**](https://docs.solace.com/Cloud/enable_oauth_for_broker.htm#configuring-an-oauth-profile-for-an-event-broker-service) under this. Provide the following values when creating the OAuth Profile, and leave the rest of the values as default. -4. Edit the Solace Async API information and click **Create**. +| Configuration | Value | +|--------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| OAuth Client ID | `wso2apim` | +| OAuth Role | Resource Server | +| Issuer Identifier | `https://:/oauth2/token` (eg: `https://: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 | `/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 | -!!! note - The Async API definition of the Solace API will contain the specific API definition, with the supported protocols, such as HTTP, MQTT, AMQP, that the API topics have to use. You do not need to provide the protocol information separately -### Step 2 - Configuring Topics +## Configure the Solace APIM API Endpoint in WSO2 APIM -1. Click **Topics** to navigate to the topics page. - navigate to Topics +Go to the `/repository/conf/deployment.toml` file and add the following configurations. -The topics will be created automatically from the Solace AsyncAPI definition provided in the previous step. +```toml +[apim.solace_config] +apim_api_endpoint = "https://apim-production-api.solace.cloud/api/v2/apim" +token = "" +``` -### Step 3 - Viewing the Async API definition +## Create an API for the Solace Event API -1. Go to **API Configurations** and click **AsyncAPI Definition** to see the definition of the API you created in the previous step. - AsyncAPI Definition - - !!! warn - The current version of WSO2 API Manager **only** supports AsyncUnlimited Protocol as the API level subscription policy for Solace APIs. Once a subscription is made, that policy will be added automatically. +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. +1. Log in to the API Publisher via going to `https://:9443/publisher`, and providing your username & password. +2. Click on **CREATE API** and then click on **Import an AsyncAPI** under **Streaming API**. +3. 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. +4. Choose the required **Solace Event API** and click on **Next**. +5. 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. +6. 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**. -### Step 4 - Deploying the API to the Solace broker +## Subscribe to the API -1. Navigate to the **Deploy** section and go to **Deployments**. - Deployments +1. Log in to the Developer Portal via `https://:9443/devportal`, and provide your username & password. +2. [Subscribe to the API]({{base_path}}/consume/manage-subscription/subscribe-to-an-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. +3. Obtain a token for the subscribed application. -2. Select the Deployment environment and click **Deploy**. -3. The API revision will be created. Select the API revision and click **Deploy**. -4. The Solace API will be deployed to the Solace Broker environment that is user-provided. - View Deployments +!!! warning "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. -### Step 5 - Publishing the API - -See [Publish an API]({{base_path}}/deploy-and-publish/publish-on-dev-portal/publish-an-api) for instructions on publishing the API created in the previous steps. - -## Subscribing to an API - -You have to subscribe to a published Solace API before consuming them. The subscription process fulfills the authentication process and provides you with access tokens that you can use to invoke an API. The subscription flow will be controlled by the WSO2 API Manager. - -When the Application is attached with a Solace API Subscription, the solace broker will keep a copy of that Application for the authentication and validation process of the tokens generated by the WSO2 API Manager. - -The following are the two methods available in the Developer Portal to subscribe an API to an application. - -- **Subscribe to an existing application** - You can subscribe to a current API by [selecting an existing application]({{base_path}}/consume/manage-subscription/subscribe-to-an-api/#subscribe-to-an-existing-application). -- **Subscribe to an API using Key Generation Wizard** - You can use the **[SUBSCRIPTION & KEY GENERATION WIZARD]({{base_path}}/consume/manage-subscription/subscribe-to-an-api/#subscribe-to-an-api-using-key-generation-wizard)** option to start the subscription process from scratch. - -Note that the artifacts are deployed in the Solace broker, therefore API level and application-level throttling will not be supported for the Solace API subscriptions. - -!!! note - The Applications subscribed to Solace APIs have pre-generated Production keys. Therefore, only the corresponding subscription will be made in the Solace broker. If you have not generated any keys such as Sandbox keys, then subscriptions will not be made in the Solace broker. If you subscribed to an application without Production keys and if you generate the Production keys then a subscription is created internally. + To ensure smooth integration, it is recommended to follow the steps below: -!!! Info - Internally an application is created for the subscription, and for a successful subscription, you can see a log like this in the carbon logs. - - `INFO - SolaceNotifierUtils Solace application 'app1' created successfully` - -## Invoking an API - -In this section, you will subscribe to the AsyncAPI through the Developer Portal - -### Step 1 - Subscribing to the Solace API - -1. Log in to the Developer Portal via https://<hostname>:9443/devportal -2. Select your Solace API and navigate to the **Overview**. -3. Subscribe to your API using the sample application. You can also create a new application for this purpose. - -### Step 2 - Generating keys - -1. In the sample application, click **Production Keys** and navigate to **OAuth2 Tokens**. - Oauth Tokens - -2. Select the required grant types and other options and click **GENERATE KEYS**. Copy the generated access token. - Generate Keys - -For instructions on generating keys see, Application Keys. - -### Step 3 - Selecting the Async Protocol and Topic - -1. Select the Solace API and click on the **Solace Info** section in the left menu. This will render an information page like the following. - View Solace Info - -2. Select the **Application**, **Environment**, and **Protocol** from the dropdowns of the info page. - 1. **Application** - Select the required application of the subscribed Application of the Solace API. - 2. **Environment** - Select the deployed Solace broker environment that needs to be used. - 3. **Protocol** - Type of the transport protocol to invoke the Async topics with. - - The topics supported for the selected Application, Environment and Protocol will be rendered. - -3. Copy the **endpoint URL** of the protocol of the selected environment. - Add endpoint URL - -4. Copy the topic that needs to be consumed. Click on the **Copy** icon in front of the topic. - Consume Topic - -5. Use this information to create a request on the desired protocol to invoke the topic and consume the topic. + 1. First, create an application (or select an existing one). + 2. Next, generate the required keys for the chosen application. + 3. Finally, proceed to subscribe to the Solace API. -## Viewing Solace Info +## Invoke the API -If you have successfully created a subscription for the API, you can navigate to the Solace info page to view it. A successful subscription means subscribing from an application with production keys generated. If the subscription is unsuccessful, the subscriptions and topic info of the Solace API will not be viewable. +1. 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. +2. In your API client (eg: Postman), use the obtained URL and the generated token as follows, to establish a connection to the broker service. - View Solace Info + | 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...`) |