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 or Admin permission groups.

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

BORDER0_AUTH_TOKEN=_your_access_token_ go run main.go

Border0 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 sdk-socket-http
• 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") // border0 will set this header along with a few other identity related headers
		fmt.Fprintf(w, "Hello, %s! This is border0-go + standard library http.", name)
	})

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

Also see border0.Listen examples for gin, echo and fiber.

Documentation

Overview

Package border0 provides helper functions to:

1. create a Border API client to manage Border0 resources
2. create a Border listener to handle incoming HTTP connections

About Border0

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.

Index

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

Examples

• Listen
• NewAPIClient

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.

Explore examples folder for additional examples of how to use this Listen function with other HTTP libraries and frameworks.

Example

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") // border0 will set this header along with a few other identity related headers
	fmt.Fprintf(w, "Hello, %s! This is border0-go + standard library http.", name)
})

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

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.

Explore examples folder for additional examples of how to manage Border0 resources using this API client.

Example

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)