API security

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 which 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 allow you access to a screen that lists users. To generate a list of users at the screen, you might also have to pass an authorization check for the getUserList API that lists the users.

Other examples of authorization checks include:

This security is implemented using the apisecurity specific 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.

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

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 the Organization and participant modeling concepts.