Service accounts are machine identities that enable automated machine-to-machine access to resources (Sockets) through Border0, allowing scripts and applications to securely interact with our platform without human intervention. Essentially, they are machine accounts that can be used for automation, providing a secure and audited way to access resources. By using service accounts, you can streamline your workflows, improve efficiency, and reduce the risk of human error.

The service identities can have a role just like your human users. Based on the role, the service account will have access to sockets, and/or the Border0 admin API, which will allow it to manage your Border0 resources. Just like your human account, a service account can be added to a Border0 Policy, which will allow you to control to what Sockets the account will have access.

Creating a Service Account

To create a Service Account using the portal, navigate to "Team > Service Accounts" on the left menu panel. Note that every service account will need a Token too. So after creating a service account, select "Access Tokens" and then click the "New" button on the top of the Access Tokens page.

All tokens must be given a role at creation-time. You can learn more about available roles in the Role Based Access Control (RBAC) page. The TL;DR; is:

• If you want your service account to be able to manage Border0 itself, choose between the Admin, Member, or Read Only roles
• If you only want to use your service account as a socket client, choose the Client Access Only role

Once we have our Service Account created we can proceed to creating Tokens and including it in access policies

Tokens and Service Accounts

To create a token using the portal, navigate to "Team > Service Accounts" on the left menu panel.
After that, select the Service Account you wish to create a token for.

Once in the Details panel for your selected Service Account click the "Actions" button on the top of the page and select "Create token"

🚧

Remember to copy the token to your clipboard

You will not be able to retrieve it again

📘

Your token will look something like this

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJvcmdfaWQiOiJteS1hd2Vzb21lLW9yZy1pZCIsInR5cGUiOiJ0b2tlbiIsInVzZXJfaWQiOiJ0aGlzLWlzLW15LXVzZXItaWQifQ.m6sk5616to2_y_Y4hA2BbjCD_a_h64A7Rs6hWbUWS4k

🚧

Tokens are secrets!

Make sure you handle and store tokens with appropriate security tools and protocols. Token privilege level is inherited from the Service Account Role.

Policy Access

If you use your newly created service account to access Sockets (your servers) in an automated way, then the next step is to make sure your service account is added to the appropriate policy.

Add Service-Account to a policy

We can create a new policy for our service account or update an existing policy to grant access to our new Service Account.

To update any policy using the portal, navigate to "Policies" on the left menu panel, then select the policy you want to modify or use "New Policy" button to create a new policy.

In the example below, we'll be adding our new Service Account to existing "org-default-policy"

Once the Service Account is added to an access policy, any Token for that Service account can be used to access socket content, provided the policy allows it.

Using Your Service Account

To use your newly created service account token with the border0 cli you need to make the token available as an environment variable.

There are 2 variations depending on the use case, admin or client (Socket) access

Admin Access

You can use your new service account to perform administrative actions to your Border0 account. For example, listing and creating Sockets, users, policies and more.

BORDER0_ADMIN_TOKEN is used to interact with the administrative functions, creating resources or updating them etc.

For examples:

export BORDER0_ADMIN_TOKEN=<TOKEN>
border0 socket ls

or

export BORDER0_ADMIN_TOKEN=<TOKEN>

curl -X "GET" \
 https://api.border0.com/api/v1/sockets \
 -H "accept: application/json" \
 -H "Authorization: $BORDER0_ADMIN_TOKEN" 

Client Access

Service accounts can be used to access Sockets (your servers) through the Border0 platform. A typical example is machine-to-machine access.

BORDER0_CLIENT_TOKEN will only apply to client features while accessing sockets

For examples:

export BORDER0_CLIENT_TOKEN=<TOKEN>
border0 client ssh my-ssh-socket-demo.border0.io

or

export BORDER0_CLIENT_TOKEN=<TOKEN>

curl -X "GET" \
 https://api.border0.com/api/v1/client/resources \
 -H "accept: application/json" \
 -H "Authorization: $BORDER0_CLIENT_TOKEN" 

👍

Machine to Machine Access

Using client service accounts and their tokens enables programmatic use of Border0 and other M2M applications

Client Service Account Tokens can be used across all socket types. This means that HTTP sockets can be accessed like so:

export BORDER0_CLIENT_TOKEN=<TOKEN>

curl -X 'GET'  https://nginx1-demo.border0.io \
 -H "Border0-Token: $BORDER0_CLIENT_TOKEN"

Note: make sure your service account is added to the correct Policy to ensure your service account can access the socket.

👍

Automation with Ansible and AWX

Border0 released Ansible Tower/AWX integration, for details you can go to our knowledge base article: Ansible AWX

Working with Docker

We publish docker image alongside our binary toolkit release, you can pull it from GitHub registry. Below an example demonstrating how to access an ssh socket using a service account.

docker pull ghcr.io/borderzero/border0

docker run --rm -ti --env BORDER0_CLIENT_TOKEN=$BORDER0_CLIENT_TOKEN \
 ghcr.io/borderzero/border0 client ssh my-ssh-socket-demo.border0.io