cloudfoundry / go-uaa

API for UAA written in Go

go-uaa

Overview

go-uaa is a client library for the UAA API. It is a go module.

Usage

Step 1: Add go-uaa As A Dependency

$ go mod init # optional
$ go get -u github.com/cloudfoundry-community/go-uaa
$ cat go.mod

module github.com/cloudfoundry-community/go-uaa/cmd/test

go 1.13

require github.com/cloudfoundry-community/go-uaa latest

Step 2: Construct and Use uaa.API

Construct a uaa.API by using uaa.New(target string, authOpt AuthenticationOption, opts ...Option):

• The target is the URL of your UAA API (for example, https://uaa.run.pivotal.io); do not include /oauth/token suffix
• You must choose one authentication method and supply it as the third argument. There are a number of authentication methods available:
  • uaa.WithClientCredentials(clientID string, clientSecret string, tokenFormat TokenFormat)
  • uaa.WithPasswordCredentials(clientID string, clientSecret string, username string, password string, tokenFormat TokenFormat)
  • uaa.WithAuthorizationCode(clientID string, clientSecret string, authorizationCode string, tokenFormat TokenFormat, redirectURL *url.URL)
  • uaa.WithRefreshToken(clientID string, clientSecret string, refreshToken string, tokenFormat TokenFormat)
  • uaa.WithToken(token *oauth2.Token) (this is the only authentication methods that cannot automatically refresh the token when it expires)
• You can optionally supply one or more options:
  • uaa.WithZoneID(zoneID string) if you want to specify your own zone ID
  • uaa.WithClient(client *http.Client) if you want to specify your own http.Client
  • uaa.WithSkipSSLValidation(skipSSLValidation bool) if you want to ignore SSL validation issues; this is not recommended, and you should instead ensure you trust the certificate authority that issues the certificates used by UAA
    • uaa.WithUserAgent(userAgent string) if you want to supply your own user agent for requests to the UAA API
    • uaa.WithVerbosity(verbose bool) if you want to enable verbose logging

$ cat main.go

package main

import (
	"log"

	uaa "github.com/cloudfoundry-community/go-uaa"
)

func main() {
	// construct the API
	api, err := uaa.New(
		"https://uaa.example.net",
		uaa.WithClientCredentials("client-id", "client-secret", uaa.JSONWebToken),
	)
	if err != nil {
		log.Fatal(err)
	}

	// use the API to fetch a user
	user, err := api.GetUserByUsername("[e-mail]", "uaa", "")
	if err != nil {
		log.Fatal(err)
	}
	log.Printf("Hello, %s\n", user.Name.GivenName)
}

Experimental

• For the foreseeable future, releases will be in the v0.x.y range
• You should expect breaking changes until v1.x.y releases occur
• Notifications of breaking changes will be made via release notes associated with each tag
• You should use go modules with this package

Contributing

Pull requests welcome.