oauth

Documentation

Index

• type AuthData
• type Bearer
• type ForgeAuthenticator
• type Information
  • func NewInformationQuerier() Information
  • func (a Information) AboutMe(token string) (profile UserProfile, err error)
• type ThreeLeggedAuth
  • func NewThreeLeggedClient(clientID, clientSecret, redirectURI string) ThreeLeggedAuth
  • func (a ThreeLeggedAuth) Authorize(scope string, state string) (string, error)
  • func (a ThreeLeggedAuth) GetToken(code string) (bearer Bearer, err error)
  • func (a ThreeLeggedAuth) RefreshToken(refreshToken string, scope string) (bearer Bearer, err error)
• type ThreeLeggedAuthenticator
• type TwoLeggedAuth
  • func NewTwoLeggedClient(clientID, clientSecret string) TwoLeggedAuth
  • func (a TwoLeggedAuth) Authenticate(scope string) (bearer Bearer, err error)
• type TwoLeggedAuthenticator
• type UserProfile

Examples

• Information.AboutMe
• TwoLeggedAuth.Authenticate

Types

type AuthData

type AuthData struct {
	ClientID     string `json:"client_id,omitempty"`
	ClientSecret string `json:"client_secret,omitempty"`
	Host         string `json:"host,omitempty"`
	AuthPath     string `json:"auth_path"`
}

AuthData reflects the data common to 2-legged and 3-legged api calls

type Bearer

type Bearer struct {
	TokenType    string `json:"token_type"`              // Will always be Bearer
	ExpiresIn    int32  `json:"expires_in"`              // Access token expiration time (in seconds)
	AccessToken  string `json:"access_token"`            // The access token
	RefreshToken string `json:"refresh_token,omitempty"` // The refresh token used in 3-legged oauth
}

Bearer reflects the response when acquiring a 2-legged token or in 3-legged context for exchanging the authorization code for a token + refresh token and when exchanging the refresh token for a new token

type ForgeAuthenticator

type ForgeAuthenticator interface {
	GetTokenWithScope(scope string) (Bearer, error)
}

ForgeAuthenticator defines an interface that allows abstraction from a 2-legged and a 3-legged context.

This provides useful when an API accepts both 2-legged and 3-legged context tokens

type Information

type Information struct {
	Host        string `json:"host,omitempty"`
	ProfilePath string `json:"profile_path"`
}

Information struct is holding the host and path used when making queries for profile of an authorizing end user in a 3-legged context

func NewInformationQuerier

func NewInformationQuerier() Information

NewInformationQuerier returns an Informational API accessor with default host and profilePath

func (Information) AboutMe

func (a Information) AboutMe(token string) (profile UserProfile, err error)

AboutMe is used to get the profile of an authorizing end user, given the token obtained via 3-legged OAuth flow

Example

package main

import (
	"fmt"
	"github.com/apprentice3d/forge-api-go-client/oauth"
)

func main() {

	aThreeLeggedToken := "put a valid 3-legged token here"

	info := oauth.NewInformationQuerier()

	profile, err := info.AboutMe(aThreeLeggedToken)

	if err != nil {
		fmt.Printf("[ERROR] Could not retrieve profile, got %s\n", err.Error())
		return
	}

	fmt.Printf("Received profile:\n"+
		"UserId: %s\n"+
		"UserName: %s\n"+
		"EmailId: %s\n"+
		"FirstName: %s\n"+
		"LastName: %s\n"+
		"EmailVerified: %t\n"+
		"Var2FaEnabled: %t\n"+
		"ProfileImages: %v",
		profile.UserID,
		profile.UserName,
		profile.EmailID,
		profile.FirstName,
		profile.LastName,
		profile.EmailVerified,
		profile.Var2FaEnabled,
		profile.ProfileImages)
}

type ThreeLeggedAuth

type ThreeLeggedAuth struct {
	AuthData
	RedirectURI string `json:"redirect_uri,omitempty"`
}

ThreeLeggedAuth struct holds data necessary for making requests in 3-legged context

func NewThreeLeggedClient

func NewThreeLeggedClient(clientID, clientSecret, redirectURI string) ThreeLeggedAuth

NewThreeLeggedClient returns a 3-legged authenticator with default host and authPath

func (ThreeLeggedAuth) Authorize

func (a ThreeLeggedAuth) Authorize(scope string, state string) (string, error)

Authorize method returns an URL to redirect an end user, where it will be asked to give his consent for app to access the specified resources.

The resources for which the permission is asked are specified as a space-separated list of required scopes. State can be used to specify, as URL-encoded payload, some arbitrary data that the authentication flow will pass back verbatim in a state query parameter to the callback URL.

Note: You do not call this URL directly in your server code.
See the Get a 3-Legged Token tutorial for more information on how to use this endpoint.

func (ThreeLeggedAuth) GetToken

func (a ThreeLeggedAuth) GetToken(code string) (bearer Bearer, err error)

GetToken is used to exchange the authorization code for a token and an exchange token

func (ThreeLeggedAuth) RefreshToken

func (a ThreeLeggedAuth) RefreshToken(refreshToken string, scope string) (bearer Bearer, err error)

RefreshToken is used to get a new access token by using the refresh token provided by GetToken

type ThreeLeggedAuthenticator

type ThreeLeggedAuthenticator interface {
	Authorize(scope string, state string) (string, error)
	GetToken(code string) (Bearer, error)
	RefreshToken(refreshToken string, scope string) (Bearer, error)
}

ThreeLeggedAuthenticator interface defines the method necessary to qualify as 3-legged authenticator

type TwoLeggedAuth

type TwoLeggedAuth struct {
	AuthData
}

TwoLeggedAuth struct holds data necessary for making requests in 2-legged context

func NewTwoLeggedClient

func NewTwoLeggedClient(clientID, clientSecret string) TwoLeggedAuth

NewTwoLeggedClient returns a 2-legged authenticator with default host and authPath

func (TwoLeggedAuth) Authenticate

func (a TwoLeggedAuth) Authenticate(scope string) (bearer Bearer, err error)

Authenticate allows getting a token with a given scope

Example

package main

import (
	"fmt"
	"github.com/apprentice3d/forge-api-go-client/oauth"
	"log"
	"os"
)

func main() {

	// aquire Forge secrets from environment
	clientID := os.Getenv("FORGE_CLIENT_ID")
	clientSecret := os.Getenv("FORGE_CLIENT_SECRET")

	if len(clientID) == 0 || len(clientSecret) == 0 {
		log.Fatalf("Could not get from env the Forge secrets")
	}

	// create oauth client
	authenticator := oauth.NewTwoLeggedClient(clientID, clientSecret)

	// request a token with needed scopes, separated by spaces
	bearer, err := authenticator.Authenticate("data:read data:write")

	if err != nil || len(bearer.AccessToken) == 0 {
		log.Fatalf("Could not get from env the Forge secrets")
	}

	// at this point, the bearer should contain the needed data. Check Bearer struct for more info
	fmt.Printf("Bearer now contains:\n"+
		"AccessToken: %s\n"+
		"TokenType: %s\n"+
		"Expires in: %d\n",
		bearer.AccessToken,
		bearer.TokenType,
		bearer.ExpiresIn)

}

type TwoLeggedAuthenticator

type TwoLeggedAuthenticator interface {
	Authenticate(scope string) (Bearer, error)
}

TwoLeggedAuthenticator interface defines the method necessary to qualify as 2-legged authenticator

type UserProfile

type UserProfile struct {
	UserID    string `json:"userId"`    // The backend user ID of the profile
	UserName  string `json:"userName"`  // The username chosen by the user
	EmailID   string `json:"emailId"`   // The user’s email address
	FirstName string `json:"firstName"` // The user’s first name
	LastName  string `json:"lastName"`  // The user’s last name
	// true if the user’s email address has been verified false if the user’s email address has not been verified
	EmailVerified bool `json:"emailVerified"`
	// true if the user has enabled two-factor authentication false if the user has not enabled two-factor authentication
	Var2FaEnabled bool `json:"2FaEnabled"`
	// A flat JSON object of attribute-value pairs in which the attributes specify available profile image sizes in the
	// format sizeX<pixels> (where <pixels> is an integer that represents both height and width in pixels of square
	// profile images) and the values are URLs for downloading the images via HTTP
	ProfileImages interface{} `json:"profileImages"`
}

UserProfile reflects the response received when query the profile of an authorizing end user in a 3-legged context