API security

You can secure your APIs with two different levels that help you control who can call APIs and what authorization that person must have.

When calling an API, you must pass through the following two levels of security:

  1. Authentication with a user ID, a certificate, or both. The login API is called before any other API is called.
  2. Authorization, which verifies the API that you can access.

This security procedure is for every API call that is made through an application server process. By default, agent and integration servers always have full access to APIs.

Once you have passed the authentication check, an authorization check determines what APIs and resources you can access. This authorization check is in addition to the user interface (UI) security. For example, the UI security might help you access a screen that lists users. To generate a list of users at the screen, you might also need to pass an authorization check for the getUserList API that lists the users.

Other examples of authorization checks include:
  • If you use the getCommonCodeList API for display purposes, you should not be able to get user information that is explicitly restricted from the output of the API.
  • If you call the getUserList API before assigning an alert, you should not be able to get user passwords.
  • If you use the UserHierarchy API to change your password:
    • You must not be able to change your own IsSuperUser flag.
    • You must not be able to modify another user's information.
    • You must not be able to subscribe to more user groups, which would give you more system access.

This security is implemented by using the apisecurity template files. These apisecurity template files are XML files that documents the input and output elements to which (by default) all APIs are restricted. These files are automatically generated during XAPI deployment, even when document generation is turned off.

Note: Services do not use the apisecurity file.

Templates are used for the input and output authorization checks. These templates override the regular templates.

For example, an input template with the lines OrganizationCode=#PROHIBITED# and IsSuperUser=#PROHIBITED# would prevent you from subscribing to more user groups and gaining more permissions.

The output template supplements the filtering performed by the default documentation-based template. If an element is restricted because it is not configured in the apisecurity file, it will never be returned in the output, even if present in the documentation-based template.

Note: At certain points in the input and output, APIs like multiApi and getPage have authorization access for any element. But other APIs that are called by these APIs must go through the authorization check.

Access to API security and the permission level are controlled in the following properties in the yfs.properties file. All authorization failures are logged to a logging category named sci.apisecurity.

  • api.security.enabled
    • Y (default)—Enable API security
    • N—Do not enable API security
  • api.security.mode
    • STRICT—If any validation fails, throw an exception. This is appropriate for production systems, if all permissions are configured properly.
    • LAX—Filter out and log invalid input, but continue processing. The filtering allows the system to mostly work despite incorrect input or output, while the logging helps to identify places that need change.
      Note: The system may still throw an exception when the filtering produces an ambiguous behavior.
    • DEBUG—Log invalid input and output, but do not filter anything or throw exceptions. This is only appropriate during initial development to identify the permissions required by various processes.

If you do not specify a security mode, there is no filtering, thrown exceptions, or authorization checking. There is limited logging.

  • api.security.override.apiName.mode

    Use this setting to override permissions on individual APIs. This property uses the same values as api.security.mode.

  • api.security.smc.enabled
    • Y—Enable API security for the Applications Manager
    • N (default)—Do not enable API security for the Applications Manager
  • api.security.console.enabled
    • Y—Enable API security for the Application Console
    • N (default)—Do not enable API security for the Application Console

When upgrading, you should initially disable this feature and grant all access through properties. In an upgraded system, you can phase in this feature by enabling security one API at a time, as you define and test permissions. If enabled, only the system user group has grant permission to the APIs; for all other custom user groups, appropriate permission has to be given. For information about user group permissions, see About organization modeling.