Securing the Management API

The Management API of WSO2 Micro Integrator is an internal REST API, which was introduced to substitute the admin services that were available in WSO2 EI 6.x.x.

The Micro Integrator CLI and the Micro Integrator dashboard communicates with this service to obtain administrative information of the server instance. If required, you can directly access the management API without using the dashboard or CLI.

The management API of the Micro Integrator is configured using the internal-apis.xml file (stored in the MI_HOME/conf/ directory).

User authentication

There are two handlers implemented for securing the management API of WSO2 Micro Integrator:

  1. JWT Authentication handler (default)
  2. Basic Authentication handler

Note that the above handlers only perform Authentication (no role based Authorization). If security is not required, user could simply remove the security handler from the management API.

JWT Authentication (default)

Note

The following settings have been improved by a product update. See TOML configurations for the Management API for details.

JWT-based authentication is enabled in the Micro Integrator by default. You can find the JWT security handler enabled in the internal-apis.xml file (stored in the MI_HOME/conf directory as shown below.

<?xml version="1.0" encoding="UTF-8"?>
<handler class="org.wso2.micro.integrator.management.apis.security.handler.JWTTokenSecurityHandler"
         name="JWTTokenSecurityHandler">
    <TokenStoreConfig>
        <MaxSize>200</MaxSize>
        <TokenCleanupTaskInterval>600</TokenCleanupTaskInterval><!--Seconds /-->
        <RemoveOldestTokenOnOverflow>true</RemoveOldestTokenOnOverflow>
    </TokenStoreConfig>
    <TokenConfig>
        <expiry>3600</expiry><!--Seconds /-->
        <size>2048</size>
    </TokenConfig>
    <UserStore>
        <users>
            <user>
                <username>admin</username>
                <password>admin</password>
            </user>
        </users>
    </UserStore>
</handler>

Token store configurations

This config section specifies the token store maintained inside the Micro Integrator.

  • MaxSize: Number of tokens stored in the in memory token store. User can increase or decrease this value accordingly.
  • TokenCleanupTaskInterval: Token cleanup will be handled through a seperate thread and the frequency of the token clean up can be configured from this setting. This will clean all the expired and revoked security tokens. The thread will run only when there are tokens in the store. If it is empty, the cleanup thread will automatically stop. Interval is specified in seconds.
  • RemoveOldestTokenOnOverflow: If set to true, this will remove the oldest accessed token when the token store is full. If it is set to false, the user should either wait until other tokens expire or increase the token store max size accordingly.

Token configurations

Settings for the JWT token issued.

  • expiry: This configures the expiry time of the token (specified in seconds).
  • size: Specifies the key size of the token.

User store

See the section on user store of the management API.

Basic Authentication (optional)

Warning

The Micro Integrator Dashboard and the Micro Integrator CLI will only work with JWT-based authentication. Basic authentication can only be used if you are directly invoking the management API.

If required, you can engage the basic auth handler as shown below. Note that only one security handler can be engaged. Once you have engaged the basic auth handler, you can configure the user store as well as CORS

<?xml version="1.0" encoding="UTF-8"?>
<handlers>
   <handler class="org.wso2.micro.integrator.management.apis.security.handler.BasicSecurityHandler" name="BasicSecurityHandler">
      <UserStore>
         <users>
            <user>
               <username>admin</username>
               <password>admin</password>
            </user>
         </users>
      </UserStore>
   </handler>
</handlers>

User store of Management API

Note

The following settings have been improved by a product update. See TOML configurations for the Management API for details.

A file-based user store is included for the authentication handler that is enabled for the Micro Integrator. Open the internal-apis.xml file (stored in the MI_HOME/conf directory and see that the <UserStore> section is configured as shown below. 

<UserStore>
    <users>
        <user>
            <username>admin</username>
            <password>admin</password>
        </user>
        <user>
            <username>admin2</username>
            <password>admin2Password@123</password>
        </user>
    </users>
</UserStore>

Update this configuration to add/remove users for the management API. You can encrypt the plain text passwords using secure vault.

To disable the file-based user store, remove this section from the internal-apis.xml file. When the file-based user store is disabled, the external user store that is configured for the Micro Integrator will function as the management API's user store.

CORS Configurations

Note

The following settings have been improved by a product update. See TOML configurations for the Management API for details.

CORS is enabled for the management API by default. Open the internal-apis.xml file (stored in the MI_HOME/conf directory and see that the <cors> section is configured for the authentication handler.

The default configuration allows all origins (denoted by the * symbol) as shown below. The Authorization header is also enabled by default to cater to the functionalities of the the Micro Integrator dashboard.

<cors>
       <enabled>true</enabled>
       <allowedOrigins>*</allowedOrigins>
       <allowedHeaders>Authorization</allowedHeaders>
 </cors>
If required, you can remove the wild card and add specific origins as a comma-separated list. You can also add more header values in a comma separated list (same as for origins).

<cors>
       <enabled>true</enabled>
       <allowedOrigins>https://127.0.0.1:9743</allowedOrigins>
       <allowedHeaders>Authorization</allowedHeaders>
 </cors>

Securing API login/logout

Tip

This section only applies when the default JWT authentication handler is engaged. If you have switched to basic authentication, you can secure the login by simply passing the base64 encoded user credentials when you send the invocation request.

JWT authentication introduces two additional resources to the management API to handle API login and logout:

  • /login: This resource is used to obtain a JWT token based on the user name and password and it is protected by basic auth. The credentials for this basic authentication is set here as the users. Please refer user store configs for more details.
  • /logout: This resource is used to revoke the JWT token.

When you access the management API directly, you must first acquire a JWT token with your valid username and password. To log out of the management API, this token must be revoked. See securely invoking the management API for more information.

When you use the Micro Integrator Dashboard or the Micro Integrator CLI, JWT token-based authentication is handled internally.

TOML configurations for the Management API

Note

This capability of configuring the management API using the deployment.toml file is released as a product update on the 26th March, 2020. You can get the latest updates using WSO2 Update Manager.

If your product instance has the latest updates, open the deployment.toml file (stored in the <MI_HOME>/conf directory) and configure the management API instead of using the internal-apis.xml file.

Changing the default authentication handler

By default JWT authentication is enabled. If you want to switch to basic authentication, use the following TOML configuration:

# The following disables the default JWT authentication handler.
[management_api_token_handler]
enable=false

# The following enables the basic authentication handler.
[management_api_basic_security_handler]
enable=true

Configuring the file-based user store

Use the following TOML configurations to enable and configure a user store for your authentication handler.

  • Disabling the default file-based user store:

    Note

    The following TOML configuration for disabling the file-based user store is released as a product update on 16th July, 2020. 

    [internal_apis.file_user_store]
enable=false

  • Adding new users:

    Tip

    These users will replace the default admin user.

    [[management_api.handler.user_store.users]]
user.name = "user-1"
user.password = "pwd-1"

[[management_api.handler.user_store.users]]
user.name = "user-2"
user.password = "pwd-2"

[[management_api.handler.user_store.users]]
user.name = "user-3"
user.password = "pwd-3"

Configuring JWT authentication

Use the following TOML configurations to change the default JWT authentication parameters.

  • Updating the token store:

    [management_api.handler.token_store_config]
max_size = "200"
clean_up_interval = "600"
remove_oldest_token_on_overflow = true

    Parameter Description
    MaxSize Number of tokens stored in the in memory token store. User can increase or decrease this value accordingly.
    TokenCleanupTaskInterval Token cleanup will be handled through a seperate thread and the frequency of the token clean up can be configured from this setting. This will clean all the expired and revoked security tokens. The thread will run only when there are tokens in the store. If it is empty, the cleanup thread will automatically stop. Interval is specified in seconds.
    RemoveOldestTokenOnOverflow If set to true, this will remove the oldest accessed token when the token store is full. If it is set to false, the user should either wait until other tokens expire or increase the token store max size accordingly.

  • Updating token configurations:

    [management_api.handler.token_config]
expiry = "3600"
size = "2048"

    Parameter Description
    expiry This configures the expiry time of the token (specified in seconds).
    size Specifies the key size of the token.

Configuring CORS for the management API

Use the following TOML configurations to enable and set up CORS for your authentication handler.

[management_api.cors]
enabled = true
allowed_origins = "https://127.0.0.1:9743,https://wso2.com:9743"
allowed_headers = "Authorization"
Top