By default WSO2 IoT Server is configured to be accessible via localhost. When in a production environment or if you wish to make WSO2 IoT Server IP based instead of localhost, you need to configure it accordingly. This is more relevant in a clustered deployment where different profiles are hosted on different machines/hosts/IPs.
WSO2 IoT Server supports Secure Socket Layer (SSL), which establishes an encrypted channel between a client and a server. SSL enables a client to verify its reciprocal server as a trusted entity using digital signatures. With SSL in place, when a client tries to access a server using the server URL, the server sends a response (SSL handshake) in return. The client then verifies whether the CN attribute (of the underlying certificate) sent in the response matches with the server URL or not. When the CN attribute does not match with server URL, the client fails to connect to the server. In this case, the client gets a hostname verification failure. Therefore, when running WSO2 IoT Server in a clustered environment, it is essential to configure the correct IP or hostname.
Let's take a look at the steps you need to follow to configure WSO2 IoT Server with the IP or hostname:
Before you begin
You need to open the ports listed under Required Ports for WSO2 IoT Server for WSO2 IoT Server to connect following messaging systems, and enroll devices:
- Android: Google Cloud Messaging (GCM), Firebase Cloud Messaging (FCM)
- iOS: Apple Push Notification Service (APNS)
Replace the default certificate with a new self-signed certificate, and import it to the
client-truststore.jks
by following the steps below:- Navigate to
<IoT_HOME>/core/repository/resources/security
via command prompt. Delete the existing
wso2carbon.
jks certificate file.keytool -delete -alias wso2carbon -keystore wso2carbon.jks
Create a new
wso2carbon.jks
certificate file.keytool -genkey -alias wso2carbon -keyalg RSA -keysize 2048 -keystore wso2carbon.jks
Setup the hostname by providing the following certificate attributes for the newly created
wso2carbon.
jks certificate file when prompted:Common Name (CN)
- Organizational Unit (OU)
- Organization (O)
- Locality (L)
- State of Province Name (S)
Country Name (C)
You can create the wso2carbon.jks certificate file and provide the certificate attributes using a single command. Example:
keytool -genkey -alias wso2carbon -keyalg RSA -keysize 2048 -keystore wso2carbon.jks -dname "CN=wso2,OU=Home,O=Home,L=SL,S=WS,C=LK" -storepass wso2carbon -keypass wso2carbon
Replace the public key with the
-alias wso2carbon
available in theclient-
trustore.jks
with the public key in the newly generated certificate.keytool -delete -alias wso2carbon -keystore client-truststore.jks keytool -export -alias wso2carbon -keystore wso2carbon.jks -file wso2carbon.pem keytool -import -alias wso2carbon -file wso2carbon.pem -keystore client-truststore.jks -storepass wso2carbon
Convert the .pem file associated with the newly created certificate into a readable .pem file.
keytool -exportcert -keystore wso2carbon.jks -alias wso2carbon -file exportcert.pem openssl x509 -inform der -in <<file name>> -out <<file name>>
-in <<file name>>
: This is the .pem file associated with the newly created certificate.-out <<file name>>
: This is a preferred name to identify the .pem, which is used to view the certificate content.Example:
keytool -exportcert -keystore wso2carbon.jks -alias wso2carbon -file exportcert.pem openssl x509 -inform der -in exportcert.pem -out certificate.pem
Open the readable .pem file at
<IOT_HOME>/core/repository/conf/identity/identity-providers/iot_default.xml
via vi/vim editor, and copy the content.When copying the content please ensure to exclude the
BEGIN CERTIFICATE
andEND CERTIFICATE
.Navigate to the
<IoT_HOME>/core/repository/conf/identity/identity-providers/iot_default.
xml file and paste the content between the<Certificate>
and</Certificate>
tags.
- Navigate to
Next, copy the
client
-truststore.jks
andwso2carbon.jks
to broker and analytics profile locations mentioned below.Broker:
<IoT_HOME>/broker/repository/resources/security/
- Analytics:
<IoT_HOME>/analytics/repository/resources/security/
Open the
<IoT_HOME>/conf/carbon.xml
fileIf you configuring WSO2 IoT Server with the IP, comment out the
<HostName>
and<MgtHostName>
attributes.<!--<HostName>localhost</HostName>--> <!--<MgtHostName>localhost</MgtHostName>-->
If you are configuring WSO2 IoT Server with the hostname, define the hostname as the value for the
<HostName>
and<MgtHostName>
attributes.<HostName>{ENTER_THE_HOSTNAME}</HostName> <MgtHostName>{ENTER_THE_HOSTNAME}</MgtHostName>
Open the
<IOTS_HOME>/core/bin/wso2server.sh
file and configure the following properties by replacing localhost with the<IoT_SERVER_IP/HOSTNAME>
.-Diot.core.host="<IoT_SERVER_IP/HOSTNAME>" \ -Diot.keymanager.host="<IoT_SERVER_IP/HOSTNAME>" \ -Diot.gateway.host="<IoT_SERVER_IP/HOSTNAME>" \
- Open the
<IOTS_HOME>/core/repository/conf/identity/sso-idp-config.xml
file, and find and replacelocalhost
withthe<IoT_SERVER_IP/HOSTNAME>
. Open the
<IOTS_HOME>/core/repository/conf/app-manager.xml
file, and configure the<IdentityProviderUrl>
attribute that is under<SSOConfiguration>
byreplacinglocalhost
with the IoT Server IP.<!-- URL of the IDP use for SSO --> <IdentityProviderUrl>https://<IoT_SERVER_IP/HOSTNAME>:${mgt.transport.https.port}/samlsso</IdentityProviderUrl>
Open the
<IOTS_HOME>/core/repository/conf/etc/webapp-publisher-config.xml
file, and settrue
as the value for<EnabledUpdateApi>
.<!-- If it is true, the APIs of this instance will be updated when the webapps are redeployed --> <EnabledUpdateApi>true</EnabledUpdateApi>
If you have not started WSO2 IoT Server previously, you don't need this configuration. When the server starts for the first time it will update the APIs and web apps with the new server IP.
Make sure to configure this property back to
false
if you need to restart the server again after the configuring the IP.
By enabling the update API property you will be updating the APIs and the respective web apps with the server IP when the server restarts. This takes some time, therefore, if you need to restart the server many times after this configuration or when in a production environment, you need to revert back to the default setting.- Open the
<IOTS_HOME>
/
core/repository/deployment/server/jaggeryapps/devicemgt/app/conf/app-conf.json
file, and configure the following attributes:identityProviderUrl
: Replace%iot.keymanager.host%:%iot.keymanager.https.port%
with the IoT Server IP or hostname and port, which is 9443."identityProviderUrl" : "https://<IoT_SERVER_IP/HOSTNAME>:9443/samlsso",
acs
: Replace%iot.keymanager.host%:%iot.keymanager.https.port%
with the IoT Server IP or hostname and port, which is 9443."acs": "https://<IoT_SERVER_IP/HOSTNAME>:9443/devicemgt/uuf/sso/acs",
Open the
<IOTS_HOME>/core/repository/deployment/server/jaggeryapps/api-store/site/conf/site.json
file, and configure theidentityProviderUrl
attribute by replacing localhost with the IoT Server IP or hostname."identityProviderURL" : "https://<IoT_SERVER_IP/HOSTNAME>:9443/samlsso",
Open the
<IOTS_HOME>/analytics/repository/deployment/server/jaggeryapps/portal/configs/designer.json
file, and configure theidentityProviderUrl
,acs
andhost
attributes by replacing localhost with the IoT Server IP or hostname and the respective profiles port."identityProviderURL": "https://<IoT_SERVER_IP>:9443/samlsso", "acs": "https://<IoT_SERVER_IP/HOSTNAME>:9445/portal/acs", "host":{"hostname":"<IoT_SERVER_IP/HOSTNAME>","port":"","protocol":""},
The default port of the WSO2 IoT Server profiles are as follows:
WSO2 IoT Server core profile 9443 WSO2 IoT Server analytics profile 9445 WSO2 IoT Server broker profile 9446 Therefore, the analytics portal needs to be assigned the 9445 port.
Run the following commands so that the self-signed certificate refers to the IP you just configured instead of
localhost
.This step is required if your devices are accessing WSO2 IoT Server from outside the server.
Open the
<IoT_HOME>/analytics/bin/wso2server.sh
file and replace localhost with the hostname. Example:-Dmqtt.broker.host="wsstjo10" \ -Diot.keymanager.host="wsstjo10" \ -Diot.gateway.host="wsstjo10" \
Open the <IoT_HOME>/broker/repository/conf/broker.xml file and replace localhost with the hostname. Example:
<property name="hostURL">https://wsstjo10:9443/services/OAuth2TokenValidationService</property> <property name="tokenEndpoint">https://wsstjo10:8243</property> <property name="deviceMgtServerUrl">https://wsstjo10:8243</property>
If you are using the hostname instead of the IP, open the
<IOTS_HOME>/core/repository/deployment/server/jaggeryapps/devicemgt/app/conf/config.json
file and configure thehost
property."host" : "<ENTER_THE_HOSTNAME>"
Once you are done with the above steps, restart or start the message broker, IoT Server core, and the analytics profiles in the given order. For more information, see Starting the Server.