Authentication and Access Permissions

Download this manual as a PDF file

This section describes the authentication and access permissions needed to use the ScienceLogic API.

Use the following menu options to navigate the SL1 user interface:

  • To view a pop-out list of menu options, click the menu icon ().
  • To view a page containing all the menu options, click the Advanced menu icon ().

This section includes the following topics:

User Access to the API

User access to the API is controlled in the same way user access to the Administration Portal is controlled:

  • A user can interact only with entities associated with their organizations. Entities are either explicitly aligned with organizations, aligned with organizations based on the user that created the entity, or are not aligned with an organization.
  • Users of type "Administrator" can perform all actions on all resources, regardless of organization membership.
  • Device groups and dashboards can be configured so that a user must be granted a specific access key to use that device group or dashboard.

NOTE: The new user interface architecture requires API access for all users; API access is automatically granted to users. The following API-specific access hooks have been deprecated and removed from SL1: API: Resource Indexes, API: Server Access, API: Virtual Device.

The following sections describe how the access permissions system applies to the API. For more information on the access permissions system in SL1, see the Access Permissions section.

User accounts that use a SAML provider for authentication cannot perform API requests unless the authentication profile for that user also includes an EM7 Internal or AD/LDAP authentication resource.

Account Lockouts

The account lockout functionality applies to API requests (i.e., if an incorrect password is specified in multiple, sequential API requests for a valid user account, the user account will be locked out). The following settings in the Behavior Settings page (System > Settings > Behavior) control account lockouts:

  • Account Lockout Attempts. Number of times a user can supply incorrect login information (i.e., the number of consecutive API requests with an incorrect password before a lockout occurs). Choices are 1 time through 10 times.
  • Account Lockout Type. If a user enters incorrect login information multiple times in a row, that user will be locked out of the user interface. In this field, you can select how the lockout will be applied. Choices are:
  • Lockout by IP Address. All login attempts from the IP address will be denied.
  • Lockout by Username and IP Address. All login attempts by the username from the IP address will be denied.
  • Lockout by Username (default). All login attempts by the username will be denied.
  • Disabled. Lockouts are disabled.
  • Account Lockout Duration. Specifies how long a user will be locked out of the user interface. Choices are 1 hour through 24 hours, in one-hour increments.

While a user account is locked out, API requests specifying that user will return an HTTP 403 status code with the following ScienceLogic-specific header values:

X-EM7-status-message: Authentication failed due to lock

X-EM7-status-code: LOCKED

X-EM7-info-message: Authentication temporarily locked due to too many failed authentication attempts

Account lockouts can be removed via the API using the /access_lock resource. The /access_lock resource supports the following methods:

Action URI Method
View a list of locked-out user accounts. /access_lock GET
View details about a locked-out user account. /access_lock/X GET
Clear a lock on a user account. /access_lock/X DELETE

The _self Resource

User accounts are granted access to their own user account information through the following resource:

/account/_self

This resource returns the equivalent of the standard /account resource for the user that authenticated the request, even if that user account has not been granted permission to access other /account resources.

Audit Logging

All requests that use a PUT, POST, or DELETE method are included in the audit logs for the user's primary organization. Organizational audit logs are accessible through the Logs tab in the Organizational Summary page; a log for all organizations is displayed on the Audit Logs page (System > Monitor > Audit Logs). Each log message generated by an API request includes the following information:

  • The date when the request was made.
  • The user account that was used to authenticate the request.
  • The method used in the request.
  • The resource URI the request was made on.
  • The result of the request.

All API audit logs have a Source of "API Server".

Authenticating Requests as Other Users

If you are authenticating an API request using an administrator account, you can optionally specify a "run-as" user account that the API should use when applying multi-tenancy rules for that request. When you specify a "run-as" user account, the response is the same as if the request was authenticated by that "run-as" user account, i.e. the response will include only entities associated with the run-as user's organizations. This feature is useful if you want to use only one set of credentials to authenticate API requests but want to use the multi-tenancy features of SL1.

To specify a "run-as" user in a request, you must:

  • Supply the URI of the "run-as" user account in the "x-em7-run-as" header. For example, to specify the user account with ID 2 as the "run-as" user, you would include "x-em7-run-as:/api/account/2" as a header in your request.
  • Authenticate using an administrator account.

The Internal API User

If you are developing content for SL1, such as Dynamic Applications or Run Book Automation Actions, you can optionally perform API requests without supplying a password. To use this feature, you must select a user account that will be used to perform these requests in the API Internal Req Account field in the REST API Settings page (System > Settings > API).

SL1 will authenticate an API request without a password if:

  • The request originates from an IP address of an appliance in the system.
  • The username supplied with the request is a comma-delimited list that includes the following three items:
    • The user ID of the account selected in the API Internal Req Account field in the REST API Settings page (System > Settings > API).
    • The appliance ID of the appliance from which the request originates.
    • An SHA256 hash of the following string:

      • <user ID>_SILO_API_INTERNAL_<appliance ID>

NOTE: If SL1 is not running in FIPS-compliant mode, you can create the hash with MD5.

For example, suppose you want to perform an API request from a Data Collector. You would:

  1. Go to the Appliance Manager page (System > Settings > Appliances) and note the ID value for the Data Collector. For this example, suppose the ID is "2".
  2. Go to the REST API Settings page (System > Settings > API) and note the API Internal Req Account. For this example, suppose the user is "em7admin"
  3. Go to the User Accounts page (Registry > Accounts > User Accounts) and note the User ID value for the API Internal Req Account. For this example, suppose the ID is "1".

  1. Calculate the SHA256 hash (or MD5 hash) of the following string:

    2. <user ID>_SILO_API_INTERNAL_<appliance ID>

    For this example the string is:

    1_SILO_API_INTERNAL_2

  1. Supply the user ID, appliance ID, and SHA256 hash (or MD5 hash) in a comma-delimited list as the username for the request. For this example, the username for the request is:

    2. 1,2,9ec1df2f13d940c80597b9e5a09bf001

  2. Supply an empty-string as the password in the request.