Programmatic Access for Hosted Websites
Provide programmatic access to third-party applications accessing Cloud Secure Edge (CSE) hosted websites
- Updated on May 20, 2024
- 12 minutes to read
-
Contributors
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 Cloud Secure Edge (CSE) can access protected services. Often, however, third-party apps will need to access your CSE-protected services, without a physical user to authenticate or the app running (e.g., when Slack needs access to GitLab).
Instead of bypassing authentication, admins can create Service Accounts in CSE. This way, you can authenticate third-party applications to your CSE-protected services via an API key or JWT token.
Steps
Step 1: Create a CSE Service Account
1.1 Navigate from Directory > Service Accounts, and select + Add Service Account.
1.2 Select a Service Account Type.
CSE supports three Service Account types:
(a) CSE Generated - a CSE-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 Service Account you created in 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 CSE 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 CSE-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 Home > 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).
