Configuring WSO2 Identity Server as a Key Manager

Step 1 - Download WSO2 IS as a Key Manager (WSO2 IS-KM)

Download the prepackaged WSO2 Identity Server from here and unzip it.  <IS_KM_HOME> will refer to the root folder of the unzipped WSO2 IS-KM pack.

Step 2 - Optionally, configure port offset for WSO2 IS

Open the <IS_KM_HOME>/repository/conf/carbon.xml file and change the offset to 1. This increments the product's default port by one. 

<Offset>1</Offset>

Step 3 - Install and configure the databases

You can create the required databases for the API-M deployment on a separate server and point to the databases from the respective nodes.

Step 4 - Configure the Key Manager (WSO2 IS) with WSO2 API-M

1. Configure the Key Manager to enable communication between the Key Manager and the Gateway.

   This step is only applicable if you have enabled Hazelcast clustering in the API-M Gateway node.

    Click here for more information on configuring the WSO2 API-M Gateway with or without Hazelcast.

   • When should I use Hazelcast?

   • Distributed Deployment of the Gateway using a shared file system.

   • Configuring the Gateway in a Distributed Environment with rsync

   1. When users and roles are removed via the Key Manager, if the corresponding user tokens are cached on the Gateway, these tokens will only get invalidated when the cache is timed out. However, if Hazelcast clustering is enabled, token invalidation takes place immediately. Therefore, you need to enable communication between the Key Manager and Gateway to enable immediate token invalidation.
      
      For this purpose open the <IS_KM_HOME>/repository/conf/api-manager.xml file and change the <ServerURL> element that appears under the <APIGateway> section, so that it points to the API Manager server. 

      <ServerURL>https://${gateway-server-host}:{port}/services/</ServerURL>

      • If you are working with a hybrid single node or active-active node deployment where WSO2 IS is the Key Manager and the rest of the API-M components are in one node, you need to replace  {gateway-server-host} with the host of the WSO2 API-M node.
      • If you are working with a single Gateway in distributed set up, you need to replace {gateway-server-host} with the host of the Gateway node.
      • If you are working with Gateways in a High Availability (HA) set up that uses a shared file system (e.g., NFS), you need to replace {gateway-server-host} with the host of any Gateway node as all nodes have the worker manager capability when using shared file system.

      • If you are working with Gateways in a High Availability (HA) set up that uses rsync, you need to replace {gateway-server-host} with the host of the Gateway Manager node.

      • The port value you enter here should be the management transport port. For more information, see Default Product Ports.

   2. When tokens are revoked, the corresponding token cache entries should be cleared in the Gateway. For this purpose, open the <IS_KM_HOME>/repository/conf/api-manager.xml file and change the <RevokeAPIURL> element that appears under the <OAuthConfigurations> section, so that it points to the WSO2 API Manager server, or the Gateway worker server if it is a distributed setup. Note the port used here is the NIO port, which is 8243 by default for HTTPS.

      <RevokeAPIURL>https://${gateway-worker-server-host}:{nio-port}/revoke</RevokeAPIURL>

      If you are using a load balancer to front the API-M/Gateway nodes, you can use the load balancer endpoints for the configurations mentioned under step 1 and step 2 above.

2. Configure the JSON Web Token (JWT) in the <IS_KM_HOME>/repository/conf/api-manager.xml file in the WSO2 Identity Server. For more information on JWT Token generation, see Passing Enduser Attributes to the Backend Using JWT. 
   • Enable ClaimsRetrieverImplClass, ConsumerDialectURI, and SignatureAlgorithm by uncommenting the respective elements.
   • Set <SignatureAlgorithm> to one of the following values -NONE or SHA256withRSA


   If you wish to encrypt the Auth Keys (access tokens, client secrets and authorization codes) follow Encrypting OAuth Keys by modifying the <PRODUCT_HOME>/repository/conf/api-manager.xml file in both the WSO2 Identity Server and WSO2 API Manager products.

3. Change the datasource in the <IS_KM_HOME>/repository/conf/user-mgt.xml file to point to the WSO2UM_DB datasource.
   You need to do this in order to point to the correct database for user management purposes. By default, this configuration points to the embedded H2 database.

   user-mgt.xml

   <UserManager>
   	<Realm>        
   		<Configuration>
               ...
               <Property name="dataSource">jdbc/WSO2UM_DB</Property>
           </Configuration>
           ...
   	</Realm>
   </UserManager>

4. Make sure that the data source name defined under JDBCPersistenceManager is jdbc/WSO2AM_DB in the <IS_KM_HOME>/repository/conf/identity/identity.xml file.

   Make sure you add the user store configuration correctly. This is the same configuration that you added in WSO2 API Manager. For more information on how to do this, see Configuring User Stores in the Administration Guide.

       <JDBCPersistenceManager>
           <DataSource>
               <Name>jdbc/WSO2AM_DB</Name>
           </DataSource>
           ...
        <JDBCPersistenceManager>

Step 5 - Configure WSO2 API-M with the Key Manager (WSO2 IS)

1. Change the ServerURL of the  AuthManager  and the ServerURL of the  APIKeyValidator  to point to WSO2 IS in the <API-M_HOME>/repository/conf/api-manager.xml  file. 
   You need to add this configuration so that WSO2 API Manager will be aware of the URL of the Key Manager, which in this case is WSO2 Identity Server, in order to handover the Key validation and Authorization related tasks. 

   Make sure to import the Key Manager's public certificate to WSO2 API-M's client-truststore.jks. For more information, see Creating New Keystores.

   <APIManager>
       ...
   
       <!-- Authentication manager configuration for API publisher and API store. This is
            a required configuration for both web applications as their user authentication
            logic relies on this. -->
       <AuthManager>
           <!-- Server URL of the Authentication service -->
           <ServerURL>https://${IS-server-host}:{port}/services/</ServerURL>
           ...
       </AuthManager>
   
       ...
   
       <APIKeyValidator>
           <!-- Server URL of the API key manager -->
           <ServerURL>https://${IS-server-host}:{port}/services/</ServerURL>
   
           ...
   
       </APIKeyValidator>
   
       ...
   </APIManager>

   • If you are working with a single  Key Manager in hybrid single node setup where WSO2 IS is the Key Manager and the rest of the API-M components are in one node, you need to replace {IS-server-host} with the actual host of the WSO2 IS sever node.
   • If you are working with a single  Key Manager in distributed setup, you need to replace {IS-server-host} with the actual host of the WSO2 IS sever node.
   • If you are working with Key Managers in High Availability (HA) mode with a hybrid active-active node setup, where WSO2 IS is the Key Manager and the rest of the API-M components are in one node, you need to replace {IS-server-host} with the host of the Key Manager Load Balancer node.
   • If you are working with Key Managers in a High Availability (HA) setup, you need to replace {IS-server-host} with the host of the Key Manager Load Balancer node.

2. Enable WS Client and disable the Thrift Client.
   Do this by changing the <KeyValidatorClientType> from ThriftClient to WSClient, and by setting <EnableThriftServer>  to  false to optimize performance.

   As API Gateway and Key Manager are two separate components (distributed) they talk to each other via API calls. This API call happens out-of-the-box via Thrift in WSO2 API Manager. However, when it comes to a production environment with high availability, it’s recommended to switch to WSClient for key validation.

   api-manager.xml

   <APIManager>
       ...
       <APIKeyValidator>
   		...
           <KeyValidatorClientType>WSClient</KeyValidatorClientType>
           <EnableThriftServer>false</EnableThriftServer>
          ...
       </APIKeyValidator>
       ...
   </APIManager>

3. If you are using the embedded LDAP that comes with WSO2 IS, then you need to point to the particular LDAP user store from WSO2 API Manager. You can copy this configuration from the <IS_KM_HOME>/repository/conf/user-mgt.xml file to the <API-M_HOME>/repository/conf/user-mgt.xml file.

   When copying configurations, note that you must update the ports. For instance, when configuring the ConnectionURL property, you must update the port, because otherwise it will point to the port of the Identity Server when starting up if you copy it directly.

   <Property name="ConnectionURL">ldap://<ip_address_of_IS>:10389</Property>

   Note that if you have offset the IS port, then this port value 10389 should be incremented by the given WSO2 IS port offset.

4. Make sure the data source name that is defined under JDBCPersistenceManager is jdbc/WSO2AM_DB in the <API-M_HOME>/repository/conf/identity/identity.xml file.

   Make sure you add the user store configuration correctly. This is the same configuration that you added in the Identity Server. For more information on how to do this, see Configuring User Stores in the Administration Guide.

       <JDBCPersistenceManager>
           <DataSource>
               <Name>jdbc/WSO2AM_DB</Name>
           </DataSource>
           ...
        <JDBCPersistenceManager>

Step 6 - Optionally, configure High Availability (HA) for the Key Manager

1. Make a copy of the active instance configured above and use this copy as the second Key Manager active instance.

2. Configure a Load Balancer to front the two Key Manager nodes.
   For more information, see Configuring the Proxy Server and the Load Balancer.

Step 7 - Start the Key Manager(s)

Start WSO2 Identity Server for the changes to take effect. For more information, see Running the Product in the WSO2 Identity Server documentation. 

sh <IS_KM_HOME>/bin/wso2server.sh

Step 8 - Configure the other API-M components

Follow the instructions below to configure the other WSO2 API-M components, namely the Publisher, Store, Traffic Manager, and Gateway:

• If you are working with a single WSO2 API-M instance, which has all the API-M components in one instance, and a separate Key Manager, then configure the steps mentioned in Configuring a Single Node.
• If you are working with an Active-Active setup, which has two all-in-one instances of API-M, and a separate Key Manager in high availability (HA) mode, then configure the steps mentioned in Configuring an Active-Active Deployment.
• If you are working with a distributed API-M setup, see Deploying WSO2 API-M in a Distributed Setup to configure the other API-M components.