Configure API Registration

BeyondInsight provides a way to integrate part of the BeyondInsight and Password Safe functionality into your applications, using an API key. The API Registrations page is only available to Password Safe administrators.

To create an API Registration:

  1. In the BeyondInsight console, go to Configuration > General > API Registrations.
  2. Click Create API New API Registration.
  3. Enter a name for the new registration and then click Create API Regisration.

    BeyondInsight will generate a unique identifier (API key) that the calling application provides in the Authorization header of the web request. The API key is masked and can be shown in plain text by clicking the Show Key icon next to the Key field. The API key can also be manually rotated, or changed, by clicking the circular arrow.

Once the key has been changed, any script using the old key will receive a "401 Unauthorized" error until the new key is used in its place. Read access and rotation of the key is audited.

  1. To configure the new registration or modify an existing one, select the registration and then set the Authentication Rule Options in the registration's Details pane.
    • Enforce multi-factor authentication: This setting is enabled by default. When enabled, requires users to abide by multi-factor authentication settings configured for Password Safe. Disabling this setting will bypass multi-factor authentication when accessing user accounts through API. This allows applications integrated with Password Safe using an API key to abide by multi-factor authentication settings configured for the application, as opposed to using the Password Safe settings.
    • Client Certificate Required: When enabled, a client certificate is required with the web request, and if not enabled, client certificates are ignored and do not need to be present. A valid client certificate is any client certificate that is signed by a Certificate Authority trusted by the server on which BeyondInsight resides.
    • User Password Required: When enabled, an additional Authorization header value containing the RunAs user password is required with the web request. If not enabled, this header value does not need to be present and is ignored if provided.

      Square brackets surround the password in the header. For example, the Authorization header might look like:

      Authorization=PS-Auth key=c479a66f…c9484d; runas=doe-main\johndoe; pwd=[un1qu3];
    • Verify PSRUN Signature: The PSRUN signature is an extra level of authentication. It’s computed from the factors using a shared secret between the client and server. PSRUN sends the signature as part of the header during its API request. If enabled, the server recomputes the signature during factor validation and compares it against the one sent by the client. If the signatures match, the client’s identity is considered verified. The signature effectively keeps the client in sync with the server. Changing the secret on the server requires the client to be rebuilt and guarantees that out-of-date clients cannot authenticate.

    Add Authentication Rule on the API Registration Details page.

  2. From the registration's Details pane, click Add Authentication Rule. At least one IP rule or PSRUN rule is required, providing a valid source IP address (IPv4 or IPv6), an IP range, or CIDR from which requests can be sent for this API key (one IP address, IP range, or CIDR per line).

     

    Create New Authentication Rule for an API Registration.

    X-Forwarded-For rules can also be created, providing a valid source IP address (IPv4 or IPv6), an IP range, or CIDR from which requests can be sent for this API key. In a load-balanced scenario, IP authentication rules are used to validate the load balancer IPs, and the X-Forwarded-For header is used to validate the originating client IP. Existing rules cannot be changed from an IP rule to a X-Forwarded-For rule, or vice-versa.

    If an X-Forwarded-For rule is configured, it is required on the HTTP request (only a single header is allowed on the request). If the X-Forwarded-For header is missing, the request will fail with a 401 Unauthorized error.

  3. In the Create New Authentication Rule pane, click Create Rule.
  4. In the Details pane, click Save Changes.

 

For more information, please see the following: