Configuring IoTS with WSO2 API Manager

This section is WIP!

WSO2 IoTS is prepackaged with WSO2 API Manager (WSO2 API-M) features and your device APIs are published to the internal API-M in the developer/testing environment. In a production environment publishing the device APIs on WSO2 IoTS will not be sufficient. Therefore, you need to integrate WSO2 IoTS with WSO2 API-M. Follow the steps given below to publish device APIs to the externally configured WSO2 API-M that is deployed on one node:

Prerequisite

Download WSO2 API-M.

Port offset WSO2 API-M by 2 and start the server. There are two ways to set an offset to a port:
- Pass the port offset to the server during startup. The following command starts the server with the default port incremented by 2.
```
./wso2server.sh -DportOffset=10
```
- Set the ports section of the <APIM_HOME>/repository/conf/carbon.xml file as follows: <Offset>2</Offset>
  Once you have port offset, start WSO2 API-M using the following command.
```
./wso2server.sh
```

Both WSO2 API-M and WSO2 IoTS must use the same database:

Open the master-datasources.xml file that is in the <IoTS_HOME>/repository/conf/datasources directory and configure the WSO2_CARBON_DB and WSO2AM_DB datasources.
Open the master-datasources.xml file that is in the <APIM_HOME>/repository/conf/datasources directory and configure the WSO2_CARBON_DB and WSO2AM_DB datasources.

Example: The datasource settings for the WSO2_CARBON_DB datasource, if you are using MySQL as the database.

<datasource>
   <name>WSO2_CARBON_DB</name>
   <description>The datasource used for registry and user manager</description>
   <jndiConfig>
      <name>jdbc/WSO2CarbonDB</name>
   </jndiConfig>
   <definition type="RDBMS">
      <configuration>
         <url>jdbc:mysql://localhost:3306/WSO2CARBON_DB</url>
         <username>username</username>
         <password>password</password>
         <driverClassName>com.mysql.jdbc.Driver</driverClassName>
         <maxActive>50</maxActive>
         <maxWait>60000</maxWait>
         <testOnBorrow>true</testOnBorrow>
         <validationQuery>SELECT 1</validationQuery>
         <validationInterval>30000</validationInterval>
      </configuration>
   </definition>
</datasource>

Configure WSO2 IoTS to identify the external WSO2 API-M.
Open the api-manager.xml file that is in the <IoTS_HOME>/repository/conf repository and configure the serverURL fields.

Each field is explained in the api-manager.xml file.
By default, <APIM_HTTPS_PORT> has been set to 9443. In step 1 above, the port offset was incremented by 2, therefore the default port value needs to be 9445.

Configure the ServerURL filed under the AuthManager tag as follows: https://<APIM_HOST>:<APIM_HTTPS_PORT>/services.
Example:

<AuthManager>
   <!-- Server URL of the Authentication service -->
   <ServerURL>https://localhost:9453/carbon/services/</ServerURL>
   <!-- Admin username for the Authentication manager. -->
   <Username>${admin.username}</Username>
   <!-- Admin password for the Authentication manager. -->
   <Password>${admin.password}</Password>
   <!-- Indicates whether the permissions checking of the user (on the Publisher and Store) should be done via a
        remote service. The check will be done on the local server when false.
   -->
   <CheckPermissionsRemotely>false</CheckPermissionsRemotely>
</AuthManager>

Configure the fields under the APIGateway tag. Each field is explained in the api-manager.xml file.
Example:

<APIGateway>
   <!-- The environments to which an API will be published -->
   <Environments>
      <!-- Environments can be of different types. Allowed values are 'hybrid', 'production' and 'sandbox'.
		     An API deployed on a 'production' type gateway will only support production keys.
		     An API deployed on a 'sandbox' type gateway will only support sandbox keys.
		     An API deployed on a 'hybrid' type gateway will support both production and sandbox keys. -->
      <!-- api-console element specifies whether the environment should be listed in API Console or not -->
      <Environment type="hybrid" api-console="true">
         <Name>Production and Sandbox</Name>
         <Description>Description of environment</Description>
         <!--Server URL of the API gateway.-->
         <ServerURL>https://localhost:9453/carbon/services/</ServerURL>
         <!--Admin username for the API gateway.-->
         <Username>${admin.username}</Username>
         <!--Admin password for the API gateway.-->
         <Password>${admin.password}</Password>
         <!--Endpoint URLs for the APIs hosted in this API gateway.-->
         <GatewayEndpoint>http://localhost:9773,https://localhost:9445</GatewayEndpoint>
      </Environment>
   </Environments>
   <!--Enable/Disable token caching at gateway node.-->
   <EnableGatewayKeyCache>true</EnableGatewayKeyCache>
   <!--Enable/Disable API resource caching at gateway node.-->
   <EnableGatewayResourceCache>true</EnableGatewayResourceCache>
   <!-- Header name can be configurable, as you preferred. When API invocation is restricted to access only
        for authorized domains, client request should send his domain, as the value of this header.
    -->
   <ClientDomainHeader>referer</ClientDomainHeader>
</APIGateway>

Configure the fields under the APIKeyValidator tag.
Example:

<APIKeyValidator>
   <!-- Server URL of the API key manager -->
   <ServerURL>https://localhost:9453/carbon/services/</ServerURL>
   <!--Admin username for API key manager. -->
   <Username>${admin.username}</Username>
   <!-- Admin password for API key manager.-->
   <Password>${admin.password}</Password>
   <!-- Enable/Disable API key validation information caching at key-management server-->
   <EnableKeyMgtValidationInfoCache>false</EnableKeyMgtValidationInfoCache>
   <!-- Expiry time for the apim key mgt validation info cache -->
   <!--APIMKeyCacheExpiry>900</APIMKeyCacheExpiry-->
   <!--Configurations related to enable thrift support for key-management related communication. 
       If you want to switch back to Web Service Client, change the value of "KeyValidatorClientType" to "WSClient".
       In a distributed environment:
        -If you are at the Gateway node, you need to point "ThriftClientPort" value to the "ThriftServerPort" value given at
         KeyManager node.
        -If you need to start two API Manager instances in the same machine, you need to give different ports to "ThriftServerPort"
         value in two nodes.
        -ThriftServerHost - Allows to configure a hostname for the thrift server. It uses the carbon hostname by default.
     	-Gateway use this parameter to connect key validation thrift service. 
    -->
   <KeyValidatorClientType>ThriftClient</KeyValidatorClientType>
   <ThriftClientPort>10399</ThriftClientPort>
   <ThriftClientConnectionTimeOut>10000</ThriftClientConnectionTimeOut>
   <ThriftServerPort>10399</ThriftServerPort>
   <!--ThriftServerHost>localhost</ThriftServerHost-->
   <EnableThriftServer>true</EnableThriftServer>
   <!--  Scope used for marking Application Tokens. If a token is generated with this scope, they will be treated as Application Access Tokens -->
   <ApplicationTokenScope>am_application_scope</ApplicationTokenScope>
   <!-- Specifies the implementation to be used for KeyValidationHandler. Steps for validating a token can be controlled by plugging in a custom KeyValidation Handler -->
   <KeyValidationHandlerClassName>org.wso2.carbon.apimgt.keymgt.handlers.DefaultKeyValidationHandler</KeyValidationHandlerClassName>
   <!-- Name of the token API -->
   <TokenEndPointName>/oauth2/token</TokenEndPointName>
   <!-- This the API URL for revoke API. When we revoke tokens revoke requests should go through this
        API deployed in API gateway. Then it will do cache invalidations related to revoked tokens.
	    In distributed deployment we should configure this property in key manager node by pointing
	    gateway https( /http, we recommend users to use 'https' endpoints for security purpose) url.
        Also please note that we should point gateway revoke service to key manager
	-->
   <RevokeAPIURL>https://${carbon.local.ip}:${https.nio.port}/revoke</RevokeAPIURL>
   <!-- Whether to encrypt tokens when storing in the Database
	Note: If changing this value to true, change the value of <TokenPersistenceProcessor> to
	org.wso2.carbon.identity.oauth.tokenprocessor.EncryptionDecryptionPersistenceProcessor in the identity.xml -->
   <EncryptPersistedTokens>false</EncryptPersistedTokens>
</APIKeyValidator>

The port offset specified earlier in carbon.xml does not affect the ports of the Thrift client and server because Thrift is run as a separate server within WSO2 servers. Therefore, you must change the Thrift ports separately using <ThriftClientPort> and <ThriftServerPort> elements in the <APIM_HOME>/repository/conf/api-manager.xml file. For example, the following configuration sets an offset of 2 to the default Thrift port, which is 10397:

Configure the ServerURL field under the APIStore tag, as follows: https://<APIM_HOST>:<APIM_HTTPS_PORT>/servicesExample:https://localhost:9453/services
Configure the URL field under the APIPublisher tag, as follows: https://<APIM_HOST>:<APIM_HTTPS_PORT>/publisher
Example:https://localhost:9453/publisher

Configure the fields under the CORSConfiguration.

Example:

<CORSConfiguration>
   <!--Configuration to enable/disable sending CORS headers from the Gateway-->
   <Enabled>true</Enabled>
   <!--The value of the Access-Control-Allow-Origin header. Default values are API Store addresses, 
       which is needed for swagger to function.
   -->
   <Access-Control-Allow-Origin>*</Access-Control-Allow-Origin>
   <!--Configure Access-Control-Allow-Methods-->
   <Access-Control-Allow-Methods>GET,PUT,POST,DELETE,PATCH,OPTIONS</Access-Control-Allow-Methods>
   <!--Configure Access-Control-Allow-Headers-->
   <Access-Control-Allow-Headers>authorization,Access-Control-Allow-Origin,Content-Type</Access-Control-Allow-Headers>
   <!--Configure Access-Control-Allow-Credentials-->
   <!-- Specifying this header to true means that the server allows cookies (or other user credentials) 
        to be included on cross-origin requests. 
        It is false by default and if you set it to true then make sure that the Access-Control-Allow-Origin header 
        does not contain the wildcard (*) 
   -->
   <Access-Control-Allow-Credentials>false</Access-Control-Allow-Credentials>
</CORSConfiguration>

Restart WSO2 API-M. Once you restart, WSO2 IoTS will publish the device APIs to the external API-M.
To view the published APIs login to the external API store using admin as the username and the password:http://<APIM_HOST>:<APIM_HTTPS_PORT>/store

If you wish to configure WSO2 API-M on clustered environment, you need to configure it as mentioned under Configuring the connections among the components.

Additionally, you need to do the following configurations.

The installed features require an Identity provider (IdP). Therefore, you need to configure and IDP via the WSO2 management console or you can configure one manually.
Example: Take a look at a sample on an IdP that was configured manually.