sso

README

sso

A go package to request WorkOS SSO API.

Install

go get -u github.com/workos-inc/workos-go/pkg/sso

How it works

You first need to setup an SSO connection on workos.com.

Then implement the /login and /callback handlers on your server:

import (
    "context"
    "fmt"
    "net/http"

    "github.com/workos-inc/workos-go/pkg/sso"
)

func main() {
    sso.Configure(
        "xxxxx",                            // WorkOS api key
        "project_xxxxx",                    // WorkOS project id
        "https://mydomain.com/callback",    // Redirect URI
    )

    http.Handle("/login", sso.Login(sso.GetAuthorizationURLOptions{
        Domain: "mydomain.com",
    }))

    http.HandleFunc("/callback", func(w http.ResponseWriter, r *http.Request) {
        profile, err := sso.GetProfile(context.Background(), sso.GetProfileOptions{
            Code:   r.URL.Query().Get("code"),
        })
        if err != nil {
            // Handle the error ...
            return
        }

        // Handle the profile ...
        fmt.Println(profile)
    })

    if err := http.ListenAndServe("your_server_addr", nil); err != nil {
        panic(err)
    }
}

Documentation

Overview

Package sso provide functions and client to communicate with WorkOS SSO API.

You first need to setup an SSO connection on https://dashboard.workos.com/sso/connections.

Then implement the `/login` and `/callback` handlers on your server:

  func main() {
      sso.Configure(
          "xxxxx",                         // WorkOS api key
          "project_xxxxx",                 // WorkOS project id
          "https://mydomain.com/callback", // Redirect URI
      )

      http.Handle("/login", sso.Login(sso.GetAuthorizationURLOptions{
	         Domain:	"mydomain.com",
      }))

	     http.HandleFunc("/callback", func(w http.ResponseWriter, r *http.Request) {
	         profile, err := sso.GetProfile(context.Background(), sso.GetProfileOptions{
	             Code:	r.URL.Query().Get("code"),
	         })
	         if err != nil {
	             // Handle the error ...
	             return
	         }

	         // Handle the profile ...
	         fmt.Println(profile)
      })

      if err := http.ListenAndServe("your_server_addr", nil); err != nil {
          panic(err)
      }
  }

Index

• Variables
• func Configure(apiKey, projectID, redirectURI string)
• func GetAuthorizationURL(opts GetAuthorizationURLOptions) (*url.URL, error)
• func Login(opts GetAuthorizationURLOptions) http.Handler
• type Client
  • func (c *Client) GetAuthorizationURL(opts GetAuthorizationURLOptions) (*url.URL, error)
  • func (c *Client) GetProfile(ctx context.Context, opts GetProfileOptions) (Profile, error)
• type ConnectionType
• type GetAuthorizationURLOptions
• type GetProfileOptions
• type Profile
  • func GetProfile(ctx context.Context, opts GetProfileOptions) (Profile, error)

Variables

var (
	// DefaultClient is the client used by GetAuthorizationURL, GetProfile and
	// Login functions.
	DefaultClient = &Client{}
)

Functions

func Configure

func Configure(apiKey, projectID, redirectURI string)

Configure configures the default client that is used by GetAuthorizationURL, GetProfile and Login. It must be called before using those functions.

func GetAuthorizationURL

func GetAuthorizationURL(opts GetAuthorizationURLOptions) (*url.URL, error)

GetAuthorizationURL returns an authorization url generated with the given options.

func Login

func Login(opts GetAuthorizationURLOptions) http.Handler

Login return a http.Handler that redirects client to the appropriate login provider.

Types

type Client

type Client struct {
	// The WorkOS api key. It can be found in
	// https://dashboard.workos.com/api-keys.
	//
	// REQUIRED.
	APIKey string

	// The WorkOS Project ID (eg. project_01JG3BCPTRTSTTWQR4VSHXGWCQ).
	//
	// REQUIRED.
	ProjectID string

	// The callback URL where your app redirects the user-agent after an
	// authorization code is granted (eg. https://foo.com/callback).
	//
	// REQUIRED.
	RedirectURI string

	// The endpoint to WorkOS API.
	//
	// Defaults to https://api.workos.com.
	Endpoint string

	// The http.Client that is used to send request to WorkOS.
	//
	// Defaults to http.Client.
	HTTPClient *http.Client
	// contains filtered or unexported fields
}

Client represents a client that fetch SSO data from WorkOS API.

func (*Client) GetAuthorizationURL

func (c *Client) GetAuthorizationURL(opts GetAuthorizationURLOptions) (*url.URL, error)

GetAuthorizationURL returns an authorization url generated with the given options.

func (*Client) GetProfile

func (c *Client) GetProfile(ctx context.Context, opts GetProfileOptions) (Profile, error)

GetProfile returns a profile describing the user that authenticated with WorkOS SSO.

type ConnectionType

type ConnectionType string

ConnectionType represents a connection type.

const (
	ADFSSAML    ConnectionType = "ADFSSAML"
	AzureSAML   ConnectionType = "AzureSAML"
	GoogleOAuth ConnectionType = "GoogleOAuth"
	OktaSAML    ConnectionType = "OktaSAML"
)

Constants that enumerate the available connection types.

type GetAuthorizationURLOptions

type GetAuthorizationURLOptions struct {
	// The app/company domain without without protocol (eg. example.com).
	Domain string

	// Authentication service provider descriptor.
	// Provider is currently only used when the connection type is GoogleOAuth.
	Provider ConnectionType

	// A unique identifier used to manage state across authorization
	// transactions (eg. 1234zyx).
	//
	// OPTIONAL.
	State string
}

GetAuthorizationURLOptions contains the options to pass in order to generate an authorization url.

type GetProfileOptions

type GetProfileOptions struct {
	// An opaque string provided by the authorization server. It will be
	// exchanged for an Access Token when the user’s profile is sent.
	Code string
}

GetProfileOptions contains the options to pass in order to get a user profile.

type Profile

type Profile struct {
	// The user ID.
	ID string `json:"id"`

	// An unique alphanumeric identifier for a Profile’s identity provider.
	IdpID string `json:"idp_id"`

	// The connection type.
	ConnectionType ConnectionType `json:"connection_type"`

	// The user email.
	Email string `json:"email"`

	// The user first name. Can be empty.
	FirstName string `json:"first_name"`

	// The user last name. Can be empty.
	LastName string `json:"last_name"`
}

Profile contains information about a user authentication.

func GetProfile

func GetProfile(ctx context.Context, opts GetProfileOptions) (Profile, error)

GetProfile returns a profile describing the user that authenticated with WorkOS SSO.