Configure API Registration

Administrators can configure two types of API registrations in BeyondInsight, allowing you to integrate part of the BeyondInsight and Password Safe functionality into your applications. One method uses an API key and the second method uses an Open Authorization (OAuth) authentication access policy for application users. Setting up each type of registration is detailed in the below sections.

Add an API Key Policy API Registration

To create an API key policy API registration:

1. Go to Configuration > General > API Registrations.
2. Click Create API Registration.

3. Select API Key Policy from the dropdown list. The Details screen is displayed. Fill out the new API registration details, as detailed below:
   • Select the Authentication Rule Options you wish to enable:
     • 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 bypasses 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.
   • An authentication rule must be included. 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).
     • 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 fails with a 401 Unauthorized error.
     • Click Create Rule.

4. Click Create Registration.

 

BeyondInsight generates 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 receives a "401 Unauthorized" error until the new key is used in its place. Read access and rotation of the key is audited.

Add OAuth Authentication for API Access for Application Users

OAuth is an open standard protocol that allows users to grant limited access to their resources on one website or application to another website or application without sharing their credentials, such as username or password. By enhancing Password Safe authentication to support OAuth, Password Safe application users can benefit from improved overall security and the ease of integration that this feature provides.

OAuth uses access tokens, which are short-lived secrets that grant access to specific resources or APIs on behalf of the application user. Users can revoke access to Password Safe for any connected application or service. This provides more robust control over access to sensitive information.

Application users are a user type that represent applications that interface with the public API. These users can’t log in to the web console. They can only authenticate and interact with the public API and they can only authenticate using the OAuth client credential flow for the public API. When creating an application user you must provide an API registration of the type API Access Policy, which is specifically used for application users. This API registration is used for processing IP rules instead of the API Key Policy registrations typically assigned to user groups.

Configure API Access Policy Registration

The API Access Policy registration is used specifically for OAuth. To create this in the BeyondInsight console:

1. Go to Configuration > General > API Registrations.
2. Click Create API Registration.
3. Select API Access Policy from the dropdown list. The Details screen is displayed.
4. Fill out the new API registration details, including the Access Token Duration. This field determines how long the OAuth token stays active.
5. Click Add Authentication Rule, enter the required information, and then click Create Rule.

Add an Application User

Application users represent applications that interface with the BeyondInsight public API. Application users cannot log in to the BeyondInsight console. They can only authenticate and interact with the public API, using Client ID and Client Secret for credentials within the OAuth client credential flow.

An API Registration type of API Access Policy must be assigned to an application user, and is used for processing IP rules. To create an application user:

1. Go to Configuration > Role Based Access > User Management > Users.
2. Click Create New User.
3. Select Add an Application User from the dropdown list. The Create New Application User screen is displayed.
4. Add a username.  
5. Under API Access Policy, select the policy.
6. Copy the information from the Client ID and Client Secret fields for later use.
7. Click Create User.
8. Assign the user to a group that has the required permissions to access BeyondInsight and Password Safe features.
   • Click the vertical ellipsis for the user, and then select View User Details.
   • From the User Details pane, click Groups.
   • Locate the group, select it, and click Assign Group above the grid.

Recycle the Client Secret for an Application User

When editing an application user, you have an option to recycle their secret. Once recycled, you can copy or view the new secret. When a secret is recycled and the user account is updated with this change, the previous client secret is no longer valid.

To recycle the secret for an application user:

1. Go to Configuration > Role Based Access > User Management > Users.
2. Locate the application user in the grid.
3. Click the ellipsis to the right of the user, and then select Edit User Details.
4. Click the Recycle icon to the right of the Client Secret.
5. Click Recycle on the confirmation message that displays.
6. Copy the new secret for later use.
7. Click Update User.

View and Update OAuth Secret Expiry

The user's secret will eventually expire. The Users grid has an OAuth Secret Expiry column, which you can use to view what is close to expiring. The default duration of a client secret is 365 days. You can adjust the lifetime of the secret from the Authentication Options configuration area in BeyondInsight. Updating this value only changes the secret expiry date for new application users and recycled client secrets. Older secrets cannot be updated.

To view the OAuth Secret Expiry for an application user:

1. Go to Configuration > Role Based Access > User Management > Users.
2. Locate the application user. The OAuth Secret Expiry column lists the date and time that a client secret for that user expires.

To update the duration for client secrets:

1. Go to Configuration > Authentication Management > Authentication Options.
2. Under Application User Authentication Settings, enter the new duration of the client secret in the Client Secret Expiry field.
3. Click Update Application User Authentications Settings.