5.1 Authentication

As mentioned earlier, all endpoints perform authentication and authorization checks. In order for these checks to succeed, a valid token should be presented in the Authorization header in the form of Bearer <JWT>.

Suggested application logic

If you plan to integrate MetaDefender for Secure Storage in your custom application or workflow, please consider the following scenarios for successfully making REST API requests:

Scenario

Possible use cases

Short-lived integration

You are building or enhancing an application that requires sporadic or on-demand access to MetaDefender for Secure Storage REST APIs.

The application is not expected to make more than a few REST API calls per hour.

The application does not need to preserve a session.

Long-lived integration

You are building or enhancing an application that requires continuous, uninterrupted, or hard to predict access to MetaDefender for Secure Storage REST APIs.

Requests are being triggered based on external factors and your application should maintain connectivity with MetaDefender for Secure Storage REST API.

Session preserving is necessary and authentication should happen without user-interaction.

Your application will make a significant number of REST API requests and you need increased performance.

Short-lived integration

  1. Obtain a signed accessToken by calling /api/authenticate API

  2. Use this token to call your desired REST API by providing it in the Authorization header

  3. Expire the token by calling /api/user/logout

  4. Repeat steps 1-3 the next time your application needs to call a REST API

Long-lived integration

  1. Obtain a signed token by calling /api/authenticate API

  2. Securely save the received accessToken and the refreshToken

  3. Use the accessToken to call your desired REST API by providing it in the Authorization header

  4. Add an exception handler in case you receive a 401 Unauthorized response because the JWT has expired

    1. call /api/user/refreshToken to obtain a new accessToken by providing the saved refreshToken.

    • The accessTokenexpires after an hour of creation; the expiry time is represented in UTC format by the accessTokenExpiryTime value.

    • The refreshTokenexpires after an hour of creation; the expiry time is represented in UTC format by the refreshTokenExpiryTime value.

    1. if the refreshToken has expired as well, obtain a signed token by calling /api/authenticate API

  5. Use the newly issued accessToken to call your desired REST API by providing it in the Authorization header

General considerations

The access token expiration date cannot be extended. By default, the access token is valid for an hour after calling /api/authenticate API to obtain it. The refresh token is also valid for an hour but can be extended by calling /api/user/refreshToken and it is also automatically extended with an hour with each non-GET request.

A refresh token is used to request a new access token when the current one expires without requiring re-authentication using a username and password.

The refresh token is used to forcibly expire any previously issued JWT when the refresh token expires or is removed by calling /api/user/logout.

A 3rd party application that needs persistent connectivity with MetaDefender for Secure Storage should implement a timeout mechanism to ensure that the refresh token is renewed before it expires by calling /api/user/refreshToken whenever the JWT (access token) is expired but before the refresh token expires as well.