Page Comparison

WSO2 API Manager is a complete API management solution, used for creating and publishing APIs, creating and managing a developer community, and scalably routing API traffic. The API Manager solution includes a Publisher, Store, Gateway, and Key Manager component.

...

API Manager uses the following four main components:

Publisher	Enables API providers to easily publish their APIs, share documentation, provision API keys, and gather feedback on API features, quality, and usage.
Store	Enables consumers to self-register, discover API functionality, subscribe to APIs, evaluate them, and interact with API publishers.
Key Manager	Responsible for all security and key-related operations.
Gateway	Responsible for securing, protecting, managing, and scaling API calls.

For more information on the above, see the main components of a distributed system.

...

The API Manager components use the databases as follows:

(API Manager Database) apimgtdb	(User Manager Database) userdb	(Registry Database) regdb
Publisher	Used	Used	Used
Store	Used	Used	Used
Key Manager	Used	Used	Used (in multi-tenancy mode)
Gateway	Not used	Used (in multi-tenancy mode)	Used (in multi-tenancy

mode/in multiple gateway

mode)

Note
Note: Although the Gateway does not use the API Manager database, this connection is required so do not remove the default configuration in the `<APIM_HOME>/repository/conf/datasources/master-datasources.xml` file.

When we consider distributed deployment of WSO2 API Manager, we have the option of separating its four components and clustering each component as needed. Let's look more closely at how the API Manager components are deployed separately.

...

In each of the directories you just created, open the <PRODUCT_HOME>/repository/conf/carbon.xml file.

Edit the <Offset> attribute in each file as shown in the Port Offset column in the following table. The port value will automatically be increased as shown in the Port Value column, allowing all five WSO2 server instances to run on the same machine.

WSO2 Server instance	Port Offset	Port Value
KeyManager	0	9443
Gateway	1	9444
Publisher	2	9445
Store	3	9446

Warning
This step is optional and only required if all server instances are running in the same machine. This is not a recommended approach for production environments. Note that you need to change all ports used in your configurations based on the offset value if you are to do this. See Changing the Default Ports with Offset for more information.

...

Download and install MySQL Server.
Download the MySQL JDBC driver.
Unzip the downloaded MySQL driver zipped archive, and copy the MySQL JDBC driver JAR (mysql-connector-java-x.x.xx-bin.jar) into the <PRODUCT_HOME>/repository/components/lib directory of all the nodes in the cluster.
Define the host name for configuring permissions for the new database by opening the /etc/hosts file and adding the following line:
```
<MYSQL-DB-SERVER-IP> carbondb.mysql-wso2.com
```
Info
You would do this step only if your database is not on your local machine and on a separate server.
Enter the following command in a terminal/command window, where username is the username you want to use to access the databases:
mysql -u username -p
When prompted, specify the password that will be used to access the databases with the username you specified.

Create the three databases using the following commands, where <APIM_HOME> is the path to any of the API Manager instances you installed, and username and password are the same as those you specified in the previous steps.

Info

title	About using MySQL in different operating systems

For users of Microsoft Windows, when creating the database in MySQL, it is important to specify the character set as latin1. Failure to do this may result in an error (error code: 1709) when starting your cluster. This error occurs in certain versions of MySQL (5.6.x) and is related to the UTF-8 encoding. MySQL originally used the latin1 character set by default, which stored characters in a 2-byte sequence. However, in recent versions, MySQL defaults to UTF-8 to be friendlier to international users. Hence, you must use latin1 as the character set as indicated below in the database creation commands to avoid this problem. Note that this may result in issues with non-latin characters (like Hebrew, Japanese, etc.). The following is how your database creation command should look.

mysql> create database <DATABASE_NAME> character set latin1;

For users of other operating systems, the standard database creation commands will suffice. For these operating systems, the following is how your database creation command should look.

mysql> create database <DATABASE_NAME>;

Code Block

language	none

mysql> create database apimgtdb;
mysql> use apimgtdb;
mysql> source <APIM_HOME>/dbscripts/apimgt/mysql.sql;
mysql> grant all on apimgtdb.* TO username@localhost identified by "password";


mysql> create database userdb;
mysql> use userdb;
mysql> source <APIM_HOME>/dbscripts/mysql.sql;
mysql> grant all on userdb.* TO username@localhost identified by "password";


mysql> create database regdb;
mysql> use regdb;
mysql> source <APIM_HOME>/dbscripts/mysql.sql;
mysql> grant all on regdb.* TO username@localhost identified by "password";

Note
Ensure that MySQL is configured so that all nodes can connect to it.

Configure the data sources for the three database as follows:

Open the <APIM_HOME>/repository/conf/datasources/master-datasources.xml file in all four API Manager components.

Enable the components to access the API Manager database by modifying the WSO2AM_DB data source in the master-datasources.xml files in the Publisher, Store and Key Manager nodes as indicated below.

Code Block

language	none

<datasource>
 <name>WSO2AM_DB</name>
 <description>The datasource used for the API Manager database</description>
 <jndiConfig>
   <name>jdbc/WSO2AM_DB</name>
 </jndiConfig>
 <definition type="RDBMS">
   <configuration>
     <url>jdbc:mysql://apimgtdb.mysql-wso2.com:3306/apimgtdb?autoReconnect=true</url>
     <username>user</username>
     <password>password</password>
     <defaultAutoCommit>false</defaultAutoCommit>
     <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>

Enable the Key Manager, Publisher, and Store components to access the users database by configuring the WSO2UM_DB data source in their master-datasources.xml files as follows:

Code Block

language	none

<datasource>
 <name>WSO2UM_DB</name>
 <description>The datasource used by user manager</description>
 <jndiConfig>
   <name>jdbc/WSO2UM_DB</name>
 </jndiConfig>
 <definition type="RDBMS">
   <configuration>
     <url>jdbc:mysql://userdb.mysql-wso2.com:3306/userdb?autoReconnect=true</url>
     <username>user</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>

Enable the Publisher and Store components to access the registry database by configuring the WSO2REG_DB data source in their master-datasources.xml files as follows:

Code Block

language	none

<datasource>
 <name>WSO2REG_DB</name>
 <description>The datasource used by the registry</description>
 <jndiConfig>
   <name>jdbc/WSO2REG_DB</name>
 </jndiConfig>
 <definition type="RDBMS">
   <configuration>
     <url>jdbc:mysql://regdb.mysql-wso2.com:3306/regdb?autoReconnect=true</url>
     <username>user</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>

Modify the /etc/hosts entries to map the IP addresses to the data source URLs:

- 127.0.0.1 apimgtdb.mysql-wso2.com
- 127.0.0.1 userdb.mysql-wso2.com
- 127.0.0.1 regdb.mysql-wso2.com

To give each of the components access to the API Manager database, open the <APIM_HOME>/repository/conf/api-manager.xml file in each of the components and add the following line as the first child node of the root element (if it is not already there):
<DataSourceName>jdbc/WSO2AM_DB</DataSourceName>

To give the Key Manager, Publisher, and Store components access to the users database with shared permissions, open the <APIM _HOME>/repository/conf/user-mgt.xml file in each of these three components and add or modify the dataSource property of the <configuration> element as follows:

Code Block

language	none

<configuration> 
...
	<Property name="dataSource">jdbc/WSO2UM_DB</Property>
</configuration>
 
<UserStoreManager class="org.wso2.carbon.user.core.jdbc.JDBCUserStoreManager">
	<Property name="TenantManager">org.wso2.carbon.user.core.tenant.JDBCTenantManager</Property>
    <Property name="ReadOnly">false</Property>
    <Property name="MaxUserNameListLength">100</Property>
    <Property name="IsEmailUserName">false</Property>
    <Property name="DomainCalculation">default</Property>
    <Property name="PasswordDigest">SHA-256</Property>
    <Property name="StoreSaltedPassword">true</Property>
    <Property name="ReadGroups">true</Property>
    <Property name="WriteGroups">true</Property>
    <Property name="UserNameUniqueAcrossTenants">false</Property>
    <Property name="PasswordJavaRegEx">^[\S]{5,30}$</Property>
    <Property name="PasswordJavaScriptRegEx">^[\S]{5,30}$</Property>
    <Property name="UsernameJavaRegEx">^[^~!#$;%^*+={}\\|\\\\&lt;&gt;,\'\"]{3,30}$</Property>
    <Property name="UsernameJavaScriptRegEx">^[\S]{3,30}$</Property>
    <Property name="RolenameJavaRegEx">^[^~!#$;%^*+={}\\|\\\\&lt;&gt;,\'\"]{3,30}$</Property>
    <Property name="RolenameJavaScriptRegEx">^[\S]{3,30}$</Property>
    <Property name="UserRolesCacheEnabled">true</Property>
    <Property name="MaxRoleNameListLength">100</Property>
    <Property name="MaxUserNameListLength">100</Property>
    <Property name="SharedGroupEnabled">false</Property>
    <Property name="SCIMEnabled">false</Property>
</UserStoreManager>

To give the Publisher and Store components access to the registry database, open the <APIM_HOME>/repository/conf/registry.xml file in each of these two components and configure them as follows:

Info
Although it is mentioned that you need to do this on the Publisher and Store components only, if you are planning to create this setup for a multi-tenanted environment (create and work with tenants), it is required to perform the steps below on the Gateway and Key-Manager components as well.

Note

Note: Do not replace the following configuration when adding in the mounting configurations. The registry mounting configurations mentioned in the below steps must be added in addition to the following.

Code Block
<dbConfig name="wso2registry"> <dataSource>jdbc/WSO2CarbonDB</dataSource> </dbConfig>

In the Publisher component's registry.xml file, add or modify the dataSource attribute of the <dbConfig name="govregistry"> element as follows:

Code Block

language	none

<dbConfig name="govregistry">
  <dataSource>jdbc/WSO2REG_DB</dataSource>
</dbConfig>
<remoteInstance url="https://publisher.apim-wso2.com"> 
   <id>gov</id>
   <cacheId>user@jdbc:mysql://regdb.mysql-wso2.com:3306/regdb</cacheId>
   <dbConfig>govregistry</dbConfig>
   <readOnly>false</readOnly>
   <enableCache>true</enableCache>
   <registryRoot>/</registryRoot>
</remoteInstance>
<mount path="/_system/governance" overwrite="true">
   <instanceId>gov</instanceId>
   <targetPath>/_system/governance</targetPath>
</mount>
<mount path="/_system/config" overwrite="true">
   <instanceId>gov</instanceId>
   <targetPath>/_system/config</targetPath>
</mount>

In the Store component's registry.xml file, add or modify the dataSource attribute of the <dbConfig name="govregistry"> element as follows (note that this configuration is nearly identical to the previous step with the exception of the remoteInstance URL):

Code Block

language	none

<dbConfig name="govregistry">
  <dataSource>jdbc/WSO2REG_DB</dataSource>
</dbConfig>
<remoteInstance url="https://store.apim-wso2.com"> 
   <id>gov</id>
   <cacheId>user@jdbc:mysql://regdb.mysql-wso2.com:3306/regdb</cacheId> 
   <dbConfig>govregistry</dbConfig>
   <readOnly>false</readOnly>
   <enableCache>true</enableCache>
   <registryRoot>/</registryRoot>
</remoteInstance>
<mount path="/_system/governance" overwrite="true">
   <instanceId>gov</instanceId>
   <targetPath>/_system/governance</targetPath>
</mount>
<mount path="/_system/config" overwrite="true">
   <instanceId>gov</instanceId>
   <targetPath>/_system/config</targetPath>
</mount>

Modify the /etc/hosts entries to map the relevant IP addresses to the remoteInstance URLs.

- 127.0.0.1 publisher.apim-wso2.com
- 127.0.0.1 store.apim-wso2.com

Once registry caching is enabled, sync the published APIs between the Publisher and Store nodes by enabling clustering in both Store and Publisher nodes. To do this, open the <APIM_HOME>/repository/conf/axis2/axis2.xml file in each of these two components and configure them as follows:
<clustering class="org.wso2.carbon.core.clustering.hazelcast.HazelcastClusteringAgent" enable="true">

...

You will now configure the inter-component relationships illustrated in the following diagram by modifying their <APIM_HOME>/repository/conf/api-manager.xml files.

Note

In a clustered environment, you use Session Affinity to ensure that requests from the same client always get routed to the same server.
It is mandatory to set up Session Affinity in the Load Balancers when it is fronting the Publisher and Store clusters and it is not mandatory when configuring a Key Manager cluster with a Load Balancer. However, authentication via session ID fails when Session Affinity is disabled in the Load Balancer.
The Key Manager first tries to authenticate the request via the session ID. If it fails, the Key Manager tries to authenticate via basic authentication.

Open the <APIM_HOME>/repository/conf/api-manager.xml files in the Gateway, Publisher, Key Manager and Store components.

Modify each of the files as follows:

Key Manager:

Localtabgroup

Localtab

active	true
title	API Manager 1.9.0

Code Block

<APIGateway>
	<Environments>
		<Environment type="hybrid">
		...
			<ServerURL>https://<IP of the Gateway>:9443/services/</ServerURL>
			<Username>admin</Username>
			<Password>admin</Password> 
			<GatewayEndpoint>http://<IP of the Gateway>:8280,https://<IP of the Gateway>:8243</GatewayEndpoint>
		</Environment>
	</Environments> 
...
</APIGateway>

Localtab

title	API Manager 1.8.0 and 1.7.0

Configure the <RevokeAPIURL> element in in the api-manager.xml file by providing the URL of the Revoke API that is deployed in the API Gateway node.

Code Block

<RevokeAPIURL>https://${carbon.local.ip}:${https.nio.port}/revoke</RevokeAPIURL>
...
<APIGateway>
	<Environments>
		<Environment type="hybrid">
		...
			<ServerURL>https://<IP of the Gateway>:9443/services/</ServerURL>
			<Username>admin</Username>
			<Password>admin</Password> 
			<GatewayEndpoint>http://<IP of the Gateway>:8280,https://<IP of the Gateway>:8243</GatewayEndpoint>
		</Environment>
	</Environments> 
...
</APIGateway>

Localtab

title	API Manager 1.6.0 and 1.5.0

No changes required in the Key Manager node.

Gateway: configure the connection to the Key Manager component as follows:

Localtabgroup

Localtab

active	true
title	API Manager 1.9.0

Code Block

language	none

<APIKeyValidator> 
  <ServerURL>https://<IP of the Key Manager>:9443/services/</ServerURL>
  <Username>admin</Username>
  <Password>admin</Password>
  ...
</APIKeyValidator>

Localtab

title	API Manager 1.8.0, 1.7.0, 1.6.0 and 1.5.0

Code Block

language	none

<APIKeyManager> 
  <ServerURL>https://<IP of the Key Manager>:9443/services/</ServerURL>
  <Username>admin</Username>
  <Password>admin</Password>
  ...
</APIKeyManager>

Publisher: configure connections to the Key Manager and Gateway as follows:

Localtabgroup

Localtab

active	true
title	API Manager 1.9.0

Code Block

language	none

<APIKeyValidator>
	<ServerURL>https://<IP of the Key Manager>:9443/services/</ServerURL>
	<Username>admin</Username>
	<Password>admin</Password>
...
</APIKeyValidator>


<AuthManager>
	<ServerURL>https://<IP of the Key Manager>:9443/services/</ServerURL>
	<Username>admin</Username>
	<Password>admin</Password>
</AuthManager>


<APIGateway>
	<Environments>
		<Environment type="hybrid">
		...
			<ServerURL>https://<IP of the Gateway>:9443/services/</ServerURL>
			<Username>admin</Username>
			<Password>admin</Password> 
			<GatewayEndpoint>https://<IP of the Gateway>:8280,https://<IP of the Gateway>:8243</GatewayEndpoint>
		</Environment>
	</Environments> 
...
</APIGateway>

Localtab

title	API Manager 1.8.0, 1.7.0, 1.6.0 and 1.5.0

Configure the <RevokeAPIURL> element in in the api-manager.xml file by providing the URL of the Revoke API that is deployed in the API Gateway node.

Code Block

language	none

<APIKeyManager>
	<ServerURL>https://<IP of the Key Manager>:9443/services/</ServerURL>
	<Username>admin</Username>
	<Password>admin</Password>
...
</APIKeyManager>


<AuthManager>
	<ServerURL>https://<IP of the Key Manager>:9443/services/</ServerURL>
	<Username>admin</Username>
	<Password>admin</Password>
</AuthManager>


<APIGateway>
	<Environments>
		<Environment type="hybrid">
		...
			<ServerURL>https://<IP of the Gateway>:9443/services/</ServerURL>
			<Username>admin</Username>
			<Password>admin</Password> 
			<GatewayEndpoint>https://<IP of the Gateway>:8280,https://<IP of the Gateway>:8243</GatewayEndpoint>
		</Environment>
	</Environments> 
...
</APIGateway>

Info
Creating a connection to the Key Manager from the Publisher is required in API Manager 1.3.0 but is no longer required from API Manager 1.4.0 onwards.

Store

Localtabgroup

Localtab

active	true
title	API Manager 1.9.0

Code Block

language	none

<RevokeAPIURL>https://${carbon.local.ip}:${https.nio.port}<IP of the Gateway>:8243/revoke</RevokeAPIURL>
 
 
<APIKeyValidator>
	<ServerURL>https://<IP of the Key Manager>:9443/services/</ServerURL>
	<Username>admin</Username>
	<Password>admin</Password>
...
</APIKeyValidator>


<AuthManager>
	<ServerURL>https://<IP of the Key Manager>:9443/services/</ServerURL>
	<Username>admin</Username>
	<Password>admin</Password>
</AuthManager>


<APIGateway>
	<Environments>
		<Environment type="hybrid">
		...
			<ServerURL>https://<IP of the Gateway>:9443/services/</ServerURL>
			<Username>admin</Username>
			<Password>admin</Password> 
			<GatewayEndpoint>https://<IP of the Gateway>:8280,https://<IP of the Gateway>:8243</GatewayEndpoint>
		</Environment>
	</Environments> 
...
</APIGateway>

Localtab

title	API Manager 1.8.0, 1.7.0, 1.6.0 and 1.5.0

Code Block

language	none

<APIKeyManager>
	<ServerURL>https://<IP of the Key Manager>:9443/services/</ServerURL>
	<Username>admin</Username>
	<Password>admin</Password>
...
</APIKeyManager>


<AuthManager>
	<ServerURL>https://<IP of the Key Manager>:9443/services/</ServerURL>
	<Username>admin</Username>
	<Password>admin</Password>
</AuthManager>


<APIGateway>
	<Environments>
		<Environment type="hybrid">
		...
			<ServerURL>https://<IP of the Gateway>:9443/services/</ServerURL>
			<Username>admin</Username>
			<Password>admin</Password> 
			<GatewayEndpoint>https://<IP of the Gateway>:8280,https://<IP of the Gateway>:8243</GatewayEndpoint>
		</Environment>
	</Environments> 
...
</APIGateway>

Tip
Tip: For more information on how different environment types, see Maintaining Separate Production and Sandbox Gateways. This is useful when configuring environments in different geographical locations.

...

As explained in the sections above, the API Publisher and API Store use a shared registry for sharing API artifacts. Therefore, whenever an artifact is added/modified on the Publisher, the change needs to be reflected on the API Store appropriately. Due to the fact that the API Store fetches artifacts from the registry cache, modifications to artifacts done on the Publisher may not immediately be reflected on the Store unless the relevant cache entry is explicitly cleared off or the cache expires. For the cache to be explicitly cleared off, the Publisher and Store need to be in the same cluster domain and need to be aware of each other's existence. See Configuring Caching for more information.

...

Configure key management related communication.

Localtabgroup

Localtab

active	true
title	Cluster fronted by a load balancer

In a clustered setup if the Key Manager is fronted by a load balancer, you have to use WSClient as KeyValidatorClientType in <APIM_HOME>/repository/conf/api-manager.xml. This should be configured in all Gateway and Key Manager components.

Code Block

language	none

<KeyValidatorClientType>WSClient</KeyValidatorClientType>

Localtab

title	Cluster without a load balancer

In a clustered setup if the Key Manager is NOT fronted by a load balancer, you have to use ThriftClient as KeyValidatorClientType in <APIM_HOME>/repository/conf/api-manager.xml. This should be configured in all Gateway and Key Manager components.
Code Block
language none
<KeyValidatorClientType>ThriftClient</KeyValidatorClientType>
Ensure that the Thrift server is enabled only in the Key Manager. This is enabled by default in all instances of the product, so you need to disable the Thrift server in the Gateway, the Publisher and the Store by setting EnableThriftServer to false in <APIM_HOME>/repository/conf/api-manager.xml for each node.
Code Block
language none
<EnableThriftServer>false</EnableThriftServer>

Specify the ThriftClientPort and ThriftServerPort values. 10397 is the default.

Code Block
<ThriftClientPort>10397</ThriftClientPort> <ThriftServerPort>10397</ThriftServerPort>

Specify the host name or IP of the Key Manager. The default is localhost. In a distributed deployment we must set this parameter in both keymanager nodes and gateway nodes only if the Key Manager is running on a separate machine. Gateway uses this parameter to connect to the key validation thrift service.
Code Block
<ThriftServerHost>localhost</ThriftServerHost>

If you need to enable JWT you have to enable it in all key-manager and publisher Gateway components. Refer Generating JSON Web Token on how to configure JWT.

In the Gateway, set up the Key Manager endpoint in the following files:

_TokenAPI_xml found in the <APIM_HOME>/repository/deployment/server/synapse-configs/default/api/_TokenAPI_xml file.
_AuthorizeAPI_xml found in the <APIM_HOME>/repository/deployment/server/synapse-configs/default/api/_AuthorizeAPI_xml file.
_RevokeAPI_xml found in the <APIM_HOME>/repository/deployment/server/synapse-configs/default/api/_RevokeAPI_xml file.

This value needs to be the host or IP of the Key Manager.

Localtabgroup

Localtab

active	true
title	Api Manager 1.9.0

Code Block

<inSequence>
            <property name="uri.var.portnum" expression="get-property('keyManager.port')"/>
	        <property name="uri.var.hostname" expression="get-property('keyManager.hostname')"/>
            <send>
                <endpoint>
                     <http uri-template="https://{uri.var.hostname}:{uri.var.portnum}/oauth2/token">
                        <timeout>
                            <duration>60000</duration>
                            <responseAction>fault</responseAction>
                        </timeout>
                    </http>
                </endpoint>
            </send>
</inSequence>

Note

Note: If there is additional context required for the Key Manager URL, you must change the uri-template value by adding a context value as show below.

Code Block

language	xml

<http uri-template="https://{uri.var.hostname}:{uri.var.portnum}/context/oauth2/token">

Localtab

title	Api Manager 1.8.0

Code Block

<inSequence>
         <property name="uri.var.portnum" expression="get-property('mgtHttpsPort')"/> 
         <send> 
             <endpoint> 
                 <http uri-template="https://localhost:{uri.var.portnum}/oauth2/revoke"> 
                     <timeout> 
                         <duration>60000</duration> 
                         <responseAction>fault</responseAction> 
                     </timeout> 
                 </http> 
             </endpoint> 
         </send> 
</inSequence>

Localtab

title	API Manager 1.7.0, 1.6.0 and 1.5.0

Code Block
<inSequence> <send> <endpoint> <address uri="https://{KEY_MANAGER_IP}:{KEY_MANAGER_PORT}/oauth2/token"/> </endpoint> </send> </inSequence>

...

Versions Compared

Old Version 122

New Version Current

Key