secure api

Securing Management API

Version: latest

Overview

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

management.properties file

[ cols="20a,80a"]

Property Name

Description

console.auth.jwt.on

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

jwt.issuer

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

jwt.lifetime

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

jwt.encryption.key

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

jwt.shared.key

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

console.auth.url

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

console.auth.unauthorized

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

shiro.users

List of users and their respective encrypted passwords

shiro.permissions

List of users with their assigned permissions

Obtaining Authenticated JWT Token

After specifying true`for the `console.auth.jwt.on property in management.properties 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

management/auth

HTTP Method

POST

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">
  <Arg>
      <Ref refid="httpConfig"/>
  </Arg>
  <Call name="addCustomizer">
      <Arg>
          <New class="org.eclipse.jetty.server.SecureRequestCustomizer">
          </New>
      </Arg>
  </Call>
</New>


<New id="sslContextFactory" class="org.eclipse.jetty.util.ssl.SslContextFactory">
    <Set name="KeyStorePath">
        <Property name="jetty.sslContext.keyStorePath" deprecated="jetty.keystore"
                  default="/tmp/identity.jks"/>
    </Set>
    <Set name="KeyStorePassword">
        <Property name="jetty.sslContext.keyStorePassword" deprecated="jetty.keystore.password"
                  default="password"/>
    </Set>
    <Set name="KeyManagerPassword">
        <Property name="jetty.sslContext.keyManagerPassword" deprecated="jetty.keymanager.password"
                  default="password"/>
    </Set>
    <Set name="TrustStorePath">
        <Property name="jetty.sslContext.trustStorePath" deprecated="jetty.truststore"
                  default="/tmp/trust.jks"/>
    </Set>
    <Set name="TrustStorePassword">
        <Property name="jetty.sslContext.trustStorePassword" deprecated="jetty.truststore.password"
                  default="password"/>
    </Set>
    <Set name="ExcludeCipherSuites">
        <Array type="String">
            <Item>SSL_RSA_WITH_DES_CBC_SHA</Item>
            <Item>SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA</Item>
            <Item>SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA</Item>
            <Item>TLS_DHE_RSA_WITH_AES_256_CBC_SHA256</Item>
            <Item>TLS_DHE_DSS_WITH_AES_256_CBC_SHA256</Item>
            <Item>TLS_DHE_RSA_WITH_AES_256_CBC_SHA</Item>
            <Item>TLS_DHE_DSS_WITH_AES_256_CBC_SHA</Item>
            <Item>TLS_DHE_RSA_WITH_AES_128_CBC_SHA256</Item>
            <Item>TLS_DHE_DSS_WITH_AES_128_CBC_SHA256</Item>
            <Item>TLS_DHE_RSA_WITH_AES_128_CBC_SHA</Item>
            <Item>TLS_DHE_DSS_WITH_AES_128_CBC_SHA</Item>
            <Item>SSL_RSA_WITH_RC4_128_SHA</Item>
            <Item>SSL_RSA_WITH_RC4_128_MD5</Item>
            <Item>TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA</Item>
            <Item>SSL_RSA_WITH_3DES_EDE_CBC_SHA</Item>
            <Item>TLS_ECDHE_RSA_WITH_RC4_128_SHA</Item>
        </Array>
    </Set>
</New>


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

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

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

[ cols="20a,80a"]

jetty.sslContext.keyStorePath

Absolute path of the Identity Store

jetty.sslContext.keyStorePassword

Password of the Identity Store

jetty.sslContext.keyManagerPassword

Password of the Identity Store key manager

jetty.sslContext.trustStorePath

Absolute path of the Trust Store

jetty.sslContext.trustStorePassword

Password of the Trust Store

ExcludeCipherSuites

Cipher suites which should be excluded when performing SSL handshake

jetty.ssl.host

Host name of the Management Server

jetty.ssl.port

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
(c) Copyright 2016-2017 AdroitLogic. All rights reserved.
Terms of Use
Contact Us