Programmatic Access for Hosted Websites

Provide programmatic access to third-party applications accessing Banyan hosted websites

  • Updated on Apr 26, 2022
  • 12 minutes to read
  • Contributors

In order to use service accounts, you need will need: Netagent version 1.43 or later

Currently, we only support Service Accounts for Hosted Websites. Support for Service Accounts in Infrastructure Services is planned.

Overview

Users who authenticate with their org’s identity provider and have trusted devices registered with Banyan can access protected services. Often, however, third-party apps will need to access your Banyan protected services, without a physical user to authenticate or the Banyan app running (e.g., when Slack needs access to GitLab).

Instead of bypassing authentication, admins can create Service Accounts in Banyan. This way, you can authenticate third-party applications to your Banyan protected services via an API key or JWT token.

Steps

Step 1: Create a Banyan Service Account

1.1 Navigate from Directory & Infrastructure > Service Accounts, and select Add Service Account.

1.2 Select a Service Account Type.

Banyan supports three Service Account types:

(a) Banyan Generated - a Banyan-generated key that can be sent from the third-party application

(b) External API Key - allows entering an External API Key generated by the third-party application

(c) External JSON Web Token (JWT) - allows for validating parameters in an external JWT token (such as issuer, subject, and audience)

Only GCP External JSON Web Tokens are currently supported. Support for standard OIDC JSON Web Tokens is planned.

Note: You can add multiple Subjects to a single External JWT Service Account.

Step 2: Add a Service Account to a Role and a Policy

2.1 Create a Role.

2.2 Add a Role Attribute to your Service Account, and select the account from Step 1.

Note: You can add multiple Service Accounts to a single role.

2.3 Add the Role to a Policy.

Service Accounts will not adhere to any Trust Scoring requirements within a policy.

Step 3: Allow the Service Account to access your Banyan Service

3.1 Create or Edit an existing Hosted Website.

3.2 Under Advanced Configuration, enable Service Account Access.

3.3 Set how the service accounts credentials will be sent.

The third-party app accessing a Banyan-protected hosted website can send service account credentials in the following ways:

Token Location Type Description Example
Authorized Header String The Authorization request header is a standard HTTP header used to provide credentials that authenticate a user agent with a server curl --header "Authorization: Bearer <Your_API_Secret>" "https://gitlab.example.com/api/v4/projects"
Custom Header String A Custom HTTP header that can be used to provide credentials that authenticate a user agent with a server. Enter the header name curl --header "X-BNN-SVCACNT: <Your_API_Secret>" "https://gitlab.example.com/api/v4/projects"
Query Parameter String Query Parameters are attached to the end of a URL. Enter the parameter name. curl "https://gitlab.example.com/api/v4/projects?service_account=<Your_API_Secret>"

3.4 Ensure the Policy from Step 2 is attached.

Test the Connection

To test whether your service account works, try sending the credentials. In your CLI, enter the following:

curl https://clara.farazorg.bnndemo.com -H "Authorization: Bearer xbdbxiC3IucFCgfK11xVFfc-6EbbxOdLrrZupz__FgId"

Note: This is an example using the Authorization request header, our own mock API key secret, and our own hosted website.

The output returned in your CLI should be the web page you’re attempting to access.

In the console, navigate from Monitor > Events. You should see your latest Service Account access activity, and you can view further details in the JSON log of the Events Log Viewer (example below).

Can’t find what you’re looking for?

We’re happy to help. Contact our team.