secure api

Securing Management API

Version: 17.07


Management API provided by the UltraESB can be secured through user authentication and by enabling SSL over the REST endpoints.

Enable User Authentication

Current implementation of the Management Server supports user authentication with a simple permission model. A JWT token is used exchange the authentication details for each subsequent API call between a client and the Management Server.

In order to enable user authentication, you need to modify few files under $ULTRA_HOME/conf/management directory file

[ cols="20a,80a"]

Property Name



Set this value to true in-order enable user authentication and false for otherwise


Name of the JWT token issuer. Default value is adroitlogic - projectX - management_server


Lifetime of a JWT token. Default value is 3600000 milliseconds. It should be noted that once the server is restarted all the previously issued tokens will be invalidated even though the lifetime has not expired


Secret key to be used in-order to encrypt the JWT token. The secret key can be encrypted itself instead of specifying it in plain text. For securing secret ker refer encrypting properties


Secret key to be used to sign the JWT token. This key is used to validate the integrity of the JWT token. Specifying this value is similar to the jwt.encryption.key


The authentication endpoint of the management server. By default it is /management/auth resource path.


The endpoint where the user should be re-directed in-case of an invalid or an unauthorized authentication attempt. The default value is /management/auth/unauthorized


List of users and their respective encrypted passwords


List of users with their assigned permissions

Obtaining Authenticated JWT Token

After specifying true`for the `console.auth.jwt.on property in file, user authentication will be enabled and the user needs to obtain a valid JWT token by sending a request to the console.auth.url endpoint

[ cols="20a,80a"]

Authentication Endpoint


HTTP Method


Transport Headers

Content-Type: application/json

Sample POST body data

[source,json] ---- {"username":"admin","password":"password"} ----

Sample Success Response

[source,json] ---- { "msg": "QUYxOGVJd1ZoZTRCZElxbjJjTngxd05BL" } ----

Erroneous Response

[source,json] ---- { "msg": "Invalid login credentials" } ---- With 401 response code for authentication failure

Upon successful authentication, user will be issued a JWT token and this token should be sent to the management server as the value for Authorization transport header for each and every request.

Enable SSL Encryption

In order to enable SSL connection to the management server, you need to modify the $ULTRA_HOME/conf/management/jetty.xml file.

First you need to uncomment below configurations

<New id="sslHttpConfig" class="org.eclipse.jetty.server.HttpConfiguration">
      <Ref refid="httpConfig"/>
  <Call name="addCustomizer">
          <New class="org.eclipse.jetty.server.SecureRequestCustomizer">

<New id="sslContextFactory" class="org.eclipse.jetty.util.ssl.SslContextFactory">
    <Set name="KeyStorePath">
        <Property name="jetty.sslContext.keyStorePath" deprecated="jetty.keystore"
    <Set name="KeyStorePassword">
        <Property name="jetty.sslContext.keyStorePassword" deprecated="jetty.keystore.password"
    <Set name="KeyManagerPassword">
        <Property name="jetty.sslContext.keyManagerPassword" deprecated="jetty.keymanager.password"
    <Set name="TrustStorePath">
        <Property name="jetty.sslContext.trustStorePath" deprecated="jetty.truststore"
    <Set name="TrustStorePassword">
        <Property name="jetty.sslContext.trustStorePassword" deprecated="jetty.truststore.password"
    <Set name="ExcludeCipherSuites">
        <Array type="String">

<Call name="addConnector">
        <New id="sslConnector" class="org.eclipse.jetty.server.ServerConnector">
            <Arg name="server">
                <Ref refid="Server"/>
            <Arg name="acceptors" type="int">
                <Property name="jetty.ssl.acceptors" deprecated="ssl.acceptors" default="-1"/>
            <Arg name="selectors" type="int">
                <Property name="jetty.ssl.selectors" deprecated="ssl.selectors" default="-1"/>
            <Arg name="factories">
                <Array type="org.eclipse.jetty.server.ConnectionFactory">
                        <New class="org.eclipse.jetty.server.SslConnectionFactory">
                            <Arg name="sslContextFactory">
                                <Ref refid="sslContextFactory"/>
                            <Arg name="next">http/1.1</Arg>
                        <New class="org.eclipse.jetty.server.HttpConnectionFactory">
                            <Arg name="config">
                                <Ref refid="sslHttpConfig"/>

            <Set name="host">
                <Property name="" deprecated="" default="localhost"/>
            <Set name="port">
                <Property name="jetty.ssl.port" deprecated="ssl.port" default="8445"/>
            <Set name="idleTimeout">
                <Property name="jetty.ssl.idleTimeout" deprecated="ssl.timeout" default="30000"/>

Note that following default property values in the above configurations should be changed to match your environment

[ cols="20a,80a"]


Absolute path of the Identity Store


Password of the Identity Store


Password of the Identity Store key manager


Absolute path of the Trust Store


Password of the Trust Store


Cipher suites which should be excluded when performing SSL handshake

Host name of the Management Server


SSL port for Management Server

Note: If you want to disable the HTTP endpoint, comment the connector with below setting <New id="httpConnector" class="org.eclipse.jetty.server.ServerConnector">

In this topic
In this topic
Contact Us