Security

Service Permissions

Service Permissions apply to both Providers and Roles and relate to core functions of the Monarch platform. The figure below shows the panel of the admin console panel that controls services permissions.

For typical API development, only "Authenticate API requests" is necessary, but you should consider what permissions a provider should have based on the descriptions below.

  • Authenticate API requests - Authenticate incoming client requests and ensure that:

    1. The request contains valid API credentials or signature (e.g. HMAC, Hawk).
    2. The client has not exceeded their quota.
    3. The client is requesting an operation that it is authorized to invoke.

    Note: This must be enabled for all providers that are exposing API operations.

  • Create events - Events are a basic messaging system that allow you to signal actions (e.g. Record details of a transaction). Events are handled by event processors. Based on an event type, the event is routed to the appropriate event processor when the message is received. More on event processors can be found on the Custom Modules page.

  • Delegate access - Grant an application access to user-level permissions via a token (e.g. OAuth access token). Your OAuth application should use provider credentials with this permission enabled. You can find more details on the OAuth application on the OAuth page.

  • Revoke access - Revoke an access token. Typically initiated by the customer/user who no longer wants an application to act on their behalf.

Management Permissions

Management Permissions apply to both Providers and Roles and control access to the data entities stored in Monarch. The figure below shows the admin console panel that controls management permissions.

Access levels for each entity are:

  • No Access - No action is permitted
  • Redacted - Can query and view the entity fields, except for API Key and Shared Secret, if applicable (Client and Provider)
  • Read Only - Can query and view entities but not update or delete them
  • Read / Write - Can query, view, and update entities but not delete them
  • Full Access - Can query, view, update, and delete entities

Authenticators

Authenticators apply to both Providers and Clients and are modules that perform specialized authentication for incoming requests. Monarch comes with ready-made authenticators but developers can create custom authenticators by following these steps. Here are the provided authenticators:

Hawk V1

This validator implements the Hawk authentication scheme by Eran Hammer. It is a strong HMAC-based algorithm that is recommended for service-to-service integration. It does not require periodic generation of an access token, yet it signs the request differently each time and requests cannot be replayed after a few minutes.

Arguments:

  • Hash Algorithms: (MD5, SHA-1, SHA-256) Check all that you want to allow. The Service Drivers and API Gateway use SHA-256. You should enable this for Providers.

  • Require payload validation: (Recommended) This includes a hash of the request in the signature so that the request body cannot be tampered with. You should still utilize SSL for data privacy because it does not protect confidential information in the request body.

API Key / Bearer Token (Simple)

This validator simply looks for API Key and/or Access Token to be passed in the request without cryptographic protection. This entails:

  1. Finding the API Key in the query string (e.g. ?api_key=XXX) or a header (e.g. X-API-Key)

  2. If user authorization is required (access delegation, OAuth), then finding the access_token in the query string (e.g. ?access_token=YYY) or in a header (e.g. Authorization: Bearer YYY)

Passing these values in the request headers instead of the query string is recommended. Most web servers log the query string as part of the URI to the access logs, which may or may not be secure.

Important: With Default authentication, the shared secret is not used to sign the request; therefore, the API Key and token values must be protected from being compromised. SSL should be implemented if this authenticator is used.

Arguments:

  • Require API Key with Token for verification: If unchecked, it does not require the API Key to be passed. This is considered less secure because the token cannot be checked against the client/application that generated it.

Policies

Policies apply to both Providers and Clients. This allows for the request to be verified against a number of rules (e.g. Check that the request originated from a trusted IP address of a partner datacenter). Developers can create custom policies by following these steps. Here are the provided policies:

IPv4 Address Range

This policy is used to check the source IP address of the request to make sure it originated from a trusted department or partner datacenter.

Arguments:

  • IP Address Ranges: Comma-delimited list of singe IPs or IP ranges. e.g. (10.10.10.100, 10.10.10.150-10.10.10.200)

Claim Sources

Claim sources enable Monarch to determine a user's permissions and other information using Claims. In this case, the claims are available in Monarch's internal API context instead of in an issued token (e.g. SAML or JWT). Here are the provided claim sources:

Internal

Uses claims defined under Access -> Principals.

Arguments:

  • Profile: The claim profile name.