border0

README

Border0 Go SDK

Border0 enables users to log into various services, including web, SSH, database, and generic TCP, using their existing Single Sign-On (SSO) credentials. If you haven't yet registered, create a new account and explore our informative blog posts and comprehensive documentation.

This SDK contains 2 major components:

• Border0 API Client: provides API client methods that interact with our API to manage Border0 resources. See examples folder for a basic example of how to manage Border0 resources using this API client.
• Border0 Listen: border0.Listen creates a Go net.listener, that can be used to accept incoming connections. When the listener is passed to http.Serve, the server will accept HTTP requests sent by Border0 and forward them to an HTTP handler. The handler's response will be sent back to Border0. See examples folder for a simple and advanced examples of how to use the border0.Listen function.

Installation

go get github.com/borderzero/border0-go

Quickstart

Explore the examples folder for additional use cases and examples. To run these examples, you'll need a Border0 access token. You can generate one by going to Border0 Admin Portal -> Organization Settings -> Access Tokens, create a token in Member permission group.

Once you have the token, you can proceed to run the example code with:

BORDER0_AUTH_TOKEN=_your_access_token_ go run main.go

Border API Client

Create an HTTP socket using border0-go:

package main

import (
	"context"
	"log"
	"os"

	"github.com/borderzero/border0-go"
	"github.com/borderzero/border0-go/client"
)

func main() {
	api := border0.NewAPIClient(
		client.WithAuthToken(os.Getenv("BORDER0_AUTH_TOKEN")), // optional, if not provided, Border0 SDK will use BORDER0_AUTH_TOKEN env var
		client.WithRetryMax(2),                                // 1 initial + 2 retries = 3 attempts
	)
	ctx := context.Background()

	// create socket
	socket := client.Socket{
		Name:       "sdk-socket-http",
		SocketType: "http",
	}
	created, err := api.CreateSocket(ctx, &socket)
	if err != nil {
		log.Fatalln("failed to create socket using border0 api client sdk:", err)
	}

	log.Printf("created socket: %+v", created)
}

border0.Listen

The following example will:

• Automatically create an HTTP socket with name border0-go-http-listener
• Connect to Border0 and return a Border0 net.Listener
• Serve HTTP requests that are sent by Border0 right from your local machine

package main

import (
	"fmt"
	"log"
	"net/http"
	"os"

	"github.com/borderzero/border0-go"
	"github.com/borderzero/border0-go/listen"
)

func main() {
	listener, err := border0.Listen(
		listen.WithSocketName("sdk-socket-http"),              // http socket name the listener will be bound to, socket will be created if not exists
		listen.WithAuthToken(os.Getenv("BORDER0_AUTH_TOKEN")), // optional, if not provided, Border0 SDK will use BORDER0_AUTH_TOKEN env var
	)
	if err != nil {
		log.Fatalln("failed to start listener:", err)
	}

	handler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		name := r.Header.Get("X-Auth-Name")
		fmt.Fprintf(w, "Hello, %s! This is border0-go + standard library http.", name)
	})

	log.Fatalln(http.Serve(listener, handler))
}

Documentation

Index

• func Listen(options ...listen.Option) (net.Listener, error)
• func NewAPIClient(options ...client.Option) client.Requester

Functions

func Listen

func Listen(options ...listen.Option) (net.Listener, error)

Listen creates a new Border0 listener with the given options. It returns a net.Listener that can be used to accept incoming connections. When the listener is passed to http.Serve, the server will accept HTTP requests sent by Border0 and forward them to the handler. The handler's response will be sent back to Border0. If no options are provided, some default values will be used. See the listen.Option type for more details.

Also see examples folder for a simple and advanced examples of how to use this Listen function.

func NewAPIClient

func NewAPIClient(options ...client.Option) client.Requester

NewAPIClient creates a new Border0 API client with the given options. If no options are provided, some default values will be used. See the client.Option type for more details.

Also see examples folder for a basic example of how to manage Border0 resources using this API client.