General Server Configurations

WSO2 EMM Agent configurations to enroll and manage devices

General server configurations

Follow the instructions below to configure general server configurations:

1. Configure the DeviceMonitorFrequency parameter in the cdm-config.xml file, which is in the <EMM_HOME>/repository/conf directory. Specify thE value in milliseconds. The EMM server uses this parameter to determine how often the devices enrolled with WSO2 EMM need to be monitored. By default, this value has been configured to 60000ms (1min).

   Example:

   <DeviceMonitorFrequency>60000</DeviceMonitorFrequency>

2. Uncomment the following code in the carbon.xml file, which is in the <EMM_HOME>/repository/conf directory, and enter your organization domain. 

   This step is only required for the production environment.

   Example:

   <HostName>www.wso2.org</HostName>
   <MgtHostName>www.wso2.org</MgtHostName>

3. Configure the following fields that are under the <APIKeyValidator> tag in the <EMM_HOME>/repository/conf/api-manager.xml file. 

   This step is only applicable in the production environment.

   • Configure the <serverURL> field by replacing ${carbon.local.ip} with the hostname or public IP of the production environment.

     <ServerURL>https://${carbon.local.ip}:${mgt.transport.https.port}${carbon.context}/services/</ServerURL>

     Example:

     <ServerURL>https://45.67.89.100:${mgt.transport.https.port}${carbon.context}/services/</ServerURL>

   • Configure the <RevokeAPIURL> field by replacing ${carbon.local.ip} with the hostname or public IP of the production environment.

     <RevokeAPIURL>https://${carbon.local.ip}:${https.nio.port}/revoke</RevokeAPIURL>

     Example:

     <RevokeAPIURL>https://45.67.89.100:${https.nio.port}/revoke</RevokeAPIURL>

4. Enable HTTPS communication.  

   • This step is only required for the production environment. Once enabled, the HTTP requests will be redirected to use HTTPS automatically.
   • You will need to setup the BKS file in the android agent once HTTPS is enabled.

   1. To enable HTTPS redirection for a specific web application, uncomment the following code in the respective web application's web.xml.
      Example: Enable HTTPS redirection for the mdm-android-agent web app by navigating to the <WSO2_EMM>/repository/deployment/server/webapps/mdm-android-agent/WEB-INF/web.xml file.

       <security-constraint>
         <web-resource-collection>
            <web-resource-name>MDM-Admin</web-resource-name>
            <url-pattern>/*</url-pattern>
         </web-resource-collection>
         <user-data-constraint>
            <transport-guarantee>CONFIDENTIAL</transport-guarantee>
         </user-data-constraint>
      </security-constraint>

   2. To enable HTTPS redirection for the entire servlet container, configure the web.xml file, which is in the wso2emm-2.0.1/repository/conf/tomcat folder, by including the following:

      <security-constraint>
         <web-resource-collection>
            <web-resource-name>MDM-Admin</web-resource-name>
            <url-pattern>/*</url-pattern>
         </web-resource-collection>
         <user-data-constraint>
            <transport-guarantee>CONFIDENTIAL</transport-guarantee>
         </user-data-constraint>
      </security-constraint>

5. Configure the email client to send out registration confirmation emails through EMM to the respective users.

   In EMM, user registration confirmation emails are disabled by default, and the admin needs to provide the required configuration details to enable it.

   1. Create an email account to send out emails to users that register with EMM (e.g., no-reply@foo.com).

   2. Open the <EMM_HOME>/repository/conf/axis2/axis2.xml file, uncomment the mailto transportSender section, and configure the EMM email account.

      <transportSender name="mailto" class="org.apache.axis2.transport.mail.MailTransportSender">
         <parameter name="mail.smtp.host">smtp.gmail.com</parameter>
         <parameter name="mail.smtp.port">587</parameter>
         <parameter name="mail.smtp.starttls.enable">true</parameter>
         <parameter name="mail.smtp.auth">true</parameter>
         <parameter name="mail.smtp.user">synapse.demo.0</parameter>
         <parameter name="mail.smtp.password">mailpassword</parameter>
         <parameter name="mail.smtp.from">synapse.demo.0@gmail.com</parameter>
      </transportSender>

      For mail.smtp.from, mail.smtp.user, and mail.smtp.password, use the email address, username, and password (respectively) from the mail account you set up.

      Example:

      <transportSender name="mailto" class="org.apache.axis2.transport.mail.MailTransportSender">
         <parameter name="mail.smtp.host">smtp.gmail.com</parameter>
         <parameter name="mail.smtp.port">587</parameter>
         <parameter name="mail.smtp.starttls.enable">true</parameter>
         <parameter name="mail.smtp.auth">true</parameter>
         <parameter name="mail.smtp.user">foo</parameter>
         <parameter name="mail.smtp.password">$foo1234</parameter>
         <parameter name="mail.smtp.from">no-reply@foo.com</parameter>
      </transportSender>

   3. Customize the email that is being sent out by navigating to the notification-messages.xml file, which is in the <EMM_HOME>/repository/conf directory.

   4. Customize the link being sent in the email to download the EMM application by navigating to the cdm-config.xml file, which is in the <EMM_HOME>/repository/conf directory, and configuring the following fields under <EmailClientConfiguration>.

      • LBHostPortPrefix: Provide the load balancer host and port prefix.

      • enrollmentContextPath: Provide the path to download the application.

       Click here to view an example.

      <EmailClientConfiguration>
         <minimumThread>8</minimumThread>
         <maximumThread>100</maximumThread>
         <keepAliveTime>20</keepAliveTime>
         <ThreadQueueCapacity>1000</ThreadQueueCapacity>
         <LBHostPortPrefix>https://localhost:9443</LBHostPortPrefix>
         <enrollmentContextPath>/mdm/enrollment</enrollmentContextPath>
      </EmailClientConfiguration>

WSO2 EMM Jaggery apps configurations to enroll and manage devices

In WSO2 EMM, only Android and iOS platforms uses the agent to enroll devices with the EMM. The Windows platform uses the native workplace application to enroll devices with WSO2 EMM. Therefore, the following configurations steps are required only if you are registering or enrolling Android or iOS devices.

Follow the steps given below:

1. Open the config.json file that is in the <EMM_HOME>/repository/deployment/server/jaggeryapps/ emm-web-agent/config directory.

2. Configure the host attribute that is under generalConfig by providing the entire server address. 

   You are required to configure this file as it is used to handle device enrollments.

   • To download the EMM Android agent in a testing environment configure the host attribute using a HTTP URL, because the Android browser does not trust hosts with self signed certificates. 
   • To download the EMM Android agent in a production environment configure the host attribute using a HTTPS URL as the production server has a Certificate Authority (CA) installed with a valid SSL certificate. For more information on enabling HTTPS communication, see here.

   Example:

   "generalConfig" : {
           "host" : "http://localhost:9763",
           "companyName" : "WSO2 Enterprise Mobility Manager",
           "browserTitle" : "WSO2 EMM",
           "copyrightText" : "\u00A9 %date-year%, WSO2 Inc. (http://www.wso2.org) All Rights Reserved."
   }

3. Open the config.json file that is in the <EMM_HOME>/repository/deployment/server/jaggeryapps/emm/config directory.

4. Configure the host attribute that is under generalConfig by providing the entire server address.

   You are required to configure this file as it is used to manage the devices.

   In a clustered environment, configure the host attribute by providing the entire server address (by changing only the protocol to HTTPS and the port to the HTTPS port) that was given for the host attribute in the emm-web-agent's config.json file. This is required because the EMM configurations refer to the emm-web-agent app as it is used to handle device enrollments.

   Example:

   "generalConfig" : {
           "host" : "https://localhost:9443",
           "companyName" : "WSO2 Enterprise Mobility Manager",
           "browserTitle" : "WSO2 EMM",
           "copyrightText" : "\u00A9 %date-year%, WSO2 Inc. (http://www.wso2.org) All Rights Reserved."
   }

WSO2 App Manager configurations to mange applications in WSO2 EMM

Follow the steps given below to configure WSO2 App Manager for the EMM:

1. Open the carbon.xml file that is in the <EMM_HOME>/repository/conf directory.

2. Uncomment the HostName attribute and provide the server IP.
   Default: 

   <!--HostName>www.wso2.org</HostName-->

   An example after the configuration:

   <HostName>10.100.7.35</HostName>

3. Uncomment the MgtHostName attribute and provide the server IP.
   Default: 

   <!--MgtHostName>mgt.wso2.org</MgtHostName-->

   An example after the configuration:

   <MgtHostName>10.100.7.35</MgtHostName>

4. Comment the uncommented ServerURL and uncomment the ServerURL attribute that was commented by default.
   Configure the uncommented ServerURL as follows:
   
   1. Provide localhost as the value for {carbon.local.ip}.
   2. Provide the https port as the value for {carbon.management.port}.
      By default the port is 9443.
   3. Remove ${carbon.context}.

   By default:

   <ServerURL>local:/${carbon.context}/services/</ServerURL>
   <!--
   <ServerURL>https://${carbon.local.ip}:${carbon.management.port}${carbon.context}/services/</ServerURL>
   -->

   An example after the configuration:

   <!--ServerURL>local:/${carbon.context}/services/</ServerURL-->
   <ServerURL>https://localhost:9443/services/</ServerURL>

5. Restart the WSO2 EMM server.

6. Login to the WSO2 App Manager publisher to publish application or WSO2 App Manager store to install apps on mobile devices.

   • Access the WSO2 App Manager publisher:
     • http://localhost:9763/publisher
     • https://localhost:9443/publisher
   • Access WSO2 App Manager store
     • http://localhost:9763/store/
     • https://localhost:9443/store

SSO configurations

Follow the steps given below to configure single sign-on (SSO) for EMM:

1. Enable SSO in the following configuration files, under the ssoConfiguration section:

   • config.json file, which is in the <EMM_HOME>/repository/deployment/server/jaggeryapps/emm/config directory.

   • store.json file, which is in the <EMM_HOME>/repository/deployment/server/jaggeryapps/store/config directory.

   • publisher.json file, which is in the <EMM_HOME>/repository/deployment/server/jaggeryapps/publisher/config directory.

     "enabled" : true,

2. Configure the Identity Provider (IdP) in the following configuration files, under the ssoConfiguration section:

   For example, you can use the following steps to configure WSO2 Identity Server (IS) as an Identity Provider (IdP). For more information on configuring IS, see enabling SSO for WSO2 servers.

   • config.json file, which is in the <EMM_HOME>/repository/deployment/server/jaggeryapps/emm/config directory.

   • store.json file, which is in the <EMM_HOME>/repository/deployment/server/jaggeryapps/store/config directory.

   • publisher.json file, which is in the <EMM_HOME>/repository/deployment/server/jaggeryapps/publisher/config directory. 

    Click here for IdP related property definitions.

   The IdP related property definitions are as follows:

   • IdentityProviderURL - Provide the URL that defines where the user should navigate when signing in.

   • keyStorePassword - Provide the Key Store password.

   • identityAlias - Provide the Key Store identity alias or username.

   • keyStoreName - Provide the Identity Providers (e.g., WSO2 IS) public key value.

     The keyStorePassword and identityAlias are defined under <KeyStore> in the carbon.xml file, which is in the <EMM_HOME>/repository/conf directory.

      Click here for to view the KeyStore attributes.

     <KeyStore>
        <!-- Keystore file location-->
        <Location>${carbon.home}/repository/resources/security/wso2carbon.jks</Location>
        <!-- Keystore type (JKS/PKCS12 etc.)-->
        <Type>JKS</Type>
        <!-- Keystore password-->
        <Password>wso2carbon</Password>
        <!-- Private Key alias-->
        <KeyAlias>wso2carbon</KeyAlias>
        <!-- Private Key password-->
        <KeyPassword>wso2carbon</KeyPassword>
     </KeyStore>

   • storeAcs - Provide the Assertion Consumer URL, which is the redirecting URL, for the Store.

   • publisherAcs - Provide the Assertion Consumer URL, which is the redirecting URL, for the Publisher.

   By default, an Identity Provider (IdP) has been bundled with the EMM binary pack. If you wish to use this default IdP in EMM, modify the host/ip to the Server IP. If you wish to use your own IdP, modify the host/ip to your own IdP's host in the following files:

3. Update the SSO related IDP configurations in the sso-idp-config.xml  file, which is in the  <EMM_HOME>/repository/conf/identity  directory, by updating all the entries that state localhost to your IDP's IP address or domain.

    <ServiceProvider>
         <Issuer>mdm</Issuer>
         <AssertionConsumerServiceURLs>
            <AssertionConsumerServiceURL>https://localhost:9443/emm/sso/acs</AssertionConsumerServiceURL>
         </AssertionConsumerServiceURLs>
         <DefaultAssertionConsumerServiceURL>https://localhost:9443/emm/sso/acs</DefaultAssertionConsumerServiceURL>
         <SignAssertion>true</SignAssertion>
         <SignResponse>true</SignResponse>
         <EnableAttributeProfile>false</EnableAttributeProfile>
         <IncludeAttributeByDefault>false</IncludeAttributeByDefault>
         <Claims>
            <Claim>http://wso2.org/claims/role</Claim>
            <Claim>http://wso2.org/claims/emailaddress</Claim>
         </Claims>
         <EnableSingleLogout>false</EnableSingleLogout>
         <SingleLogoutUrl />
         <EnableAudienceRestriction>true</EnableAudienceRestriction>
         <EnableRecipients>true</EnableRecipients>
         <AudiencesList>
            <Audience>https://localhost:9443/oauth2/token</Audience>
         </AudiencesList>
         <RecipientList>
            <Recipient>https://localhost:9443/oauth2/token</Recipient>
         </RecipientList>
         <ConsumingServiceIndex />
      </ServiceProvider>
      <ServiceProvider>
         <Issuer>store</Issuer>
         <AssertionConsumerServiceURLs>
            <AssertionConsumerServiceURL>https://localhost:9443/store/acs</AssertionConsumerServiceURL>
         </AssertionConsumerServiceURLs>
         <DefaultAssertionConsumerServiceURL>https://localhost:9443/store/acs</DefaultAssertionConsumerServiceURL>
         <SignResponse>true</SignResponse>
         <CustomLoginPage>/store/login.jag</CustomLoginPage>
      </ServiceProvider>
      <ServiceProvider>
         <Issuer>social</Issuer>
         <AssertionConsumerServiceURLs>
            <AssertionConsumerServiceURL>https://localhost:9443/social/acs</AssertionConsumerServiceURL>
         </AssertionConsumerServiceURLs>
         <DefaultAssertionConsumerServiceURL>https://localhost:9443/social/acs</DefaultAssertionConsumerServiceURL>
         <SignResponse>true</SignResponse>
         <CustomLoginPage>/social/login</CustomLoginPage>
      </ServiceProvider>
      <ServiceProvider>
         <Issuer>publisher</Issuer>
         <AssertionConsumerServiceURLs>
            <AssertionConsumerServiceURL>https://localhost:9443/publisher/acs</AssertionConsumerServiceURL>
         </AssertionConsumerServiceURLs>
         <DefaultAssertionConsumerServiceURL>https://localhost:9443/publisher/acs</DefaultAssertionConsumerServiceURL>
         <SignResponse>true</SignResponse>
         <CustomLoginPage>/publisher/controllers/login.jag</CustomLoginPage>
      </ServiceProvider>

4. Enable authentication session persistence by uncommenting the following configuration in the <EMM_HOME>/repository/conf/identity.xml file, under the the Server and JDBCPersistenceManager elements.

   <SessionDataPersist>
       <Enable>true</Enable>
       <RememberMePeriod>20160</RememberMePeriod>
       <CleanUp>
           <Enable>true</Enable>
           <Period>1440</Period>
           <TimeOut>20160</TimeOut>
       </CleanUp>
       <Temporary>false</Temporary>
   </SessionDataPersist>

    Click here for more information on the configurations.

   Configuration element	Description
   Enable	This enables the persistence of session data. Therefore, this must be configured to true if you wish to enable session persistence.
   RememberMePeriod	This is the time period (in minutes) that the remember me option should be valid. After this time period, the users are logged out even if they enable the remember me option. The default value for this configuration element is 2 weeks.
   CleanUp	This section of the configuration is related to the cleaning up of session data. The cleanup task runs on a daily basis (once a day) by default unless otherwise configured in the Period tag. When this cleanup task is executed, it removes session data that is older than 2 weeks, unless otherwise specified in the TimeOut tag.
   Enable	Selecting true here enables the cleanup task and ensures that it starts running.
   Period	This is the time period (in minutes) that the cleanup task would run. The default value is 1 day.
   TimeOut	This is the timeout value (in minutes) of the session data that is removed by the cleanup task. The default value is 2 weeks.
   Temporary	Setting this to true enables persistence of temporary caches that are created within an authentication request.