com.atlassian.confluence.content.render.xhtml.migration.exceptions.UnknownMacroMigrationException: The macro 'next_previous_link3' is unknown.

Configuring WSO2 IoT Server with WSO2 API Manager

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

This option is only available for the WUM-updated WSO2 API-M 2.1.0 pack or a later version as it requires some fixes that are missing in the vanilla pack.

  1. Download WSO2 API-M 2.1.0 or a later version.

  2. Update WSO2 API-M using WUM. For more information on how to do this, see Getting Started with WUM.

  3. Extract the WUM-updated API-M pack found in your WUM update repository. The unzipped file will be referred to as <APIM_HOME> throughout this documentation.
  1. Download the feature installation XML file and place it inside the <APIM_HOME> directory.

  2. Navigate to <APIM_HOME> on the terminal and execute the following command. This will install the required features to the WSO2 IoT Server pack. 

    mvn clean install -f apim-feature-installation.xml
  3. Open the identity.xml file found in the <APIM_HOME>/repository/conf/identity directory and add the following grant type under the <SupportedGrantTypes> element. 

    <SupportedGrantType>
        <GrantTypeName>urn:ietf:params:oauth:grant-type:jwt-bearer</GrantTypeName>
        <GrantTypeHandlerImplClass>org.wso2.carbon.device.mgt.oauth.extensions.handlers.grant.ExtendedJWTGrantHandler</GrantTypeHandlerImplClass>
        <GrantTypeValidatorImplClass>org.wso2.carbon.identity.oauth2.grant.jwt.JWTGrantValidator</GrantTypeValidatorImplClass>
    </SupportedGrantType>
  4. Update the OAuthScopeValidator class as follows.

    <OAuthScopeValidator class="org.wso2.carbon.device.mgt.oauth.extensions.handlers.ScopeValidationHandler"/>
  5. Open the <APIM_HOME>/repository/conf/carbon.xml file and port offset WSO2 API Manager by 1.

    <Offset>1</Offset>
  6. Open the <APIM_HOME>/repository/conf/api-manager.xml file:

    • Define true as the value forthe <EnableJWTGeneration> property.

      <EnableJWTGeneration>true</EnableJWTGeneration>
    • Uncomment the <JWTHeader><ConsumerDialectURI>, and <SignatureAlgorithm> properties:

      <JWTHeader>X-JWT-Assertion</JWTHeader>
      <ConsumerDialectURI>http://wso2.org/claims</ConsumerDialectURI>
      <SignatureAlgorithm>SHA256withRSA</SignatureAlgorithm>
  7. The defaultkeystoreused in WSO2 IoT Server has been updated from version 3.1.0 onwards. Since all servers must use the same certificate, do the following to update thekeystorein WSO2 API-M

    1. Navigate to the <IOTS_HOME>/repository/resources/security folder and copy the wso2carbon.jks and client-truststore.jks files. 
    2. Paste it in the <APIM_HOME>/repository/resources/security folder and replace the existing wso2carbon.jks and client-truststore.jks files. 
  8. Create a file based identity provider using the WSO2 IoT Server certificate (e.g., identity-provider.xml)and save it inside the <APIM_HOME>/repository/conf/identity/identity-providers directory. A sample of a file based identity provider configuration file is given below. 

    Make sure that the content defined in the <Certificate> tag is the same as the content in the <IOTS_HOME>/repository/conf/identity/identity-providers/iot-default.xml file's <Certificate> tag.

     Click to see a sample identity provider
    <!--
      ~ Copyright (c) 2016, WSO2 Inc. (http://www.wso2.org) All Rights Reserved.
      ~
      ~ WSO2 Inc. licenses this file to you under the Apache License,
      ~ Version 2.0 (the "License"); you may not use this file except
      ~ in compliance with the License.
      ~ You may obtain a copy of the License at
      ~
      ~ http://www.apache.org/licenses/LICENSE-2.0
      ~
      ~ Unless required by applicable law or agreed to in writing,
      ~ software distributed under the License is distributed on an
      ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
      ~ KIND, either express or implied. See the License for the
      ~ specific language governing permissions and limitations
      ~ under the License.
      -->
    
    <IdentityProvider>
    	<IdentityProviderName>wso2.org/products/iot</IdentityProviderName>
    	<DisplayName>wso2.org/products/iot</DisplayName>
    	<IdentityProviderDescription></IdentityProviderDescription>
    	<Alias>devicemgt</Alias>
    	<IsPrimary>true</IsPrimary>
    	<IsFederationHub></IsFederationHub>
    	<HomeRealmId></HomeRealmId>
    	<ProvisioningRole></ProvisioningRole>
    	<FederatedAuthenticatorConfigs></FederatedAuthenticatorConfigs>
    	<DefaultAuthenticatorConfig>
    	</DefaultAuthenticatorConfig>
    	<ProvisioningConnectorConfigs>
    		<!--<ProvisioningConnectorConfig>
    			<ProvisioningProperties>
    			</ProvisioningProperties>
    		</ProvisioningConnectorConfig>-->
    	</ProvisioningConnectorConfigs>
    	<!--<DefaultProvisioningConnectorConfig></DefaultProvisioningConnectorConfig>-->
    	<ClaimConfig></ClaimConfig>
    	<Certificate>MIIDSTCCAjGgAwIBAgIERUubMzANBgkqhkiG9w0BAQsFADBVMQswCQYDVQQGEwJVUzELMAkGA1UECBMCQ0ExFjAUBgNVBAcTDU1vdW50YWluIFZpZXcxDTALBgNVBAoTBFdTTzIxEjAQBgNVBAMTCWxvY2FsaG9zdDAeFw0xNzAzMjEwOTEzMDdaFw0xNzA2MTkwOTEzMDdaMFUxCzAJBgNVBAYTAlVTMQswCQYDVQQIEwJDQTEWMBQGA1UEBxMNTW91bnRhaW4gVmlldzENMAsGA1UEChMEV1NPMjESMBAGA1UEAxMJbG9jYWxob3N0MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAu8lfLCQV2hbiz8OGA8baKI1E1cgE/QLKefa4Od2G2KextaAwSESr5ICakVX8w6tU5+IhKYQQKt9U3/U0ae9tXf04g6iWh0dRllsr9mOgjSZxQK09/ygUsFH8syL5aD3heRUYzJWZ/KOsd57BXuI2QZnuEjN0g0+5jNvnswfwD/tM01totaJpI3xN+2JZsaBRCc0G5yA/pdW83Aa4IE30EL57wkK7u8YDl3UTcmi+HO74XQmK1VEqSnA+/mFo3M16cRlm2PTZ2Z1E5gd4j+5sV1P5v63uqyFniEU0zPXforBb06pgSBoIRQBintSSDyEmyuVzW0pc2eYC5Dhfgk337QIDAQABoyEwHzAdBgNVHQ4EFgQU4lneZCvKn04NH5DtJItdRXdXankwDQYJKoZIhvcNAQELBQADggEBAEnCNr0JEcAxtF/ypwGgFu1rYOv3i02PB4jDWbFj8s58l1zF1tMr480khVX4d3AmLjsUpvV+Jg83JFIk1rJFLEb48EFv0nJ/G7pTQrCypNKozyuyLzx5UvKNFBMmnGvkHVqt6j4MSiOjnRdlo7ofDluA/umSkSf/VmsOIZ+5610pCJpahnPUkb8GYK0HcwNV2NLU/0X4nSjKjGwWYv0tX8XW8RwJKb/r0GDehA8PESi76XOVrpXSjP9WPK8XaK//8B0SH3hm0xpzmSQYgtkNQwP2MqBe/ZEUuKxrn3pP6oxo9RxeSIQ8dTLiBA/mcsBmAlpQPPi0LqqDKpkyHt8Ar2w=</Certificate>
    	<PermissionAndRoleConfig></PermissionAndRoleConfig>
    	<JustInTimeProvisioningConfig></JustInTimeProvisioningConfig>
    </IdentityProvider>
  9. Download the _APIApplicationRegistration_.xml file and place it in the <APIM_HOME>/repository/deployments/server/synapse-configs/default/api folder. 
  10. Add the following environment variables to the wso2server.sh startup script found in the <APIM_HOME>/bin folder. 

    -Diot.core.host="localhost" \
    -Diot.core.https.port="9443" \
  11. Navigate to the <IOTS_HOME>/repository/deployment/server/jaggeryapps/devicemgt/app/conf/app-conf.json file and configure the identityProviderUrl and acs properties as shown below:

    "identityProviderUrl" : "https://localhost:9443/samlsso",
    "acs": "https://localhost:9443/devicemgt/uuf/sso/acs",
    • If you configured WSO2 IoT Server to use the IP or hostname, make sure to enter the respective value instead of localhost.
    • If you have changed the default port of the WSO2 IoT Server's core profile, make sure to enter the new port value.
  12. Open the iot-server.sh file found in the <IOTS_HOME>/bin folder and point the following endpoints to the WSO2 API Manager accordingly.  

    -Diot.keymanager.host="localhost" \
    -Diot.keymanager.https.port="9444" \
    -Diot.gateway.host="localhost" \
    -Diot.gateway.https.port="8244" \
    -Diot.gateway.http.port="8281" \
    -Diot.gateway.carbon.https.port="9444" \
    -Diot.gateway.carbon.http.port="9764" \
    -Diot.apimpublisher.host="localhost" \
    -Diot.apimpublisher.https.port="9444" \
    -Diot.apimstore.host="localhost" \
    -Diot.apimstore.https.port="9444" \
  13. Update the gateway configuration by updating the following properties in the broker.xml file of the broker runtime.

    If you are using the default WSO2 IoT Broker profile, update the broker.xml file found in the <IOTS_HOME>/wso2/broker directory. 

    <property name="hostURL">https://localhost:9444/services/OAuth2TokenValidationService</property>
    <property name="tokenEndpoint">https://localhost:8244</property>
    <property name="deviceMgtServerUrl">https://localhost:8244</property>
  14. Update the following endpoints in the wso2server.sh file of the analytics runtime. 

    If you using the default WSO2 IoT Server analytics profile, update the analytics.sh file found in the <IOTS_HOME>/bin directory

    -Diot.keymanager.host="localhost" \
    -Diot.keymanager.https.port="9444" \
    -Diot.gateway.host="localhost" \
    -Diot.gateway.https.port="8244" \
  15. You have finished all the configurations. Now start the WSO2 API Manager and WSO2 IoT Server in the following order.
    1. Start WSO2 API Manager.

      cd <API_HOME>/bin
      ./wso2server.sh  ----> for Linux/Mac/Solaris
      wso2server.bat   ----> for windows
    2. Start the WSO2 IoT Server's broker profile.

      cd <IOTS_HOME>/bin
      ./broker.sh  ----> for Linux/Mac/Solaris
      broker.bat   ----> for windows
    3. Start WSO2 IoT Server's core profile.

      ./iot-server.sh  ----> for Linux/Mac/Solaris
      iot-server.bat   ----> for windows
    4. Start WSO2 IoT Server's analytics profile.

      ./analytics  ----> for Linux/Mac/Solaris
      analytics.bat   ----> for windows
com.atlassian.confluence.content.render.xhtml.migration.exceptions.UnknownMacroMigrationException: The macro 'next_previous_links2' is unknown.