warrant

package module
v0.0.0-...-5aa0ff3 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 28, 2023 License: MIT Imports: 15 Imported by: 4

README

[DEPRECATED] A Client Library for UAA, written in Go

Deprecated in favor of https://github.com/cloudfoundry-community/go-uaa

Warrant provides a library of functionality for interacting with the UAA service. The library supports management of users, clients, groups and tokens.

GoDoc

Caveat Emptor

Warrant is still under development and the APIs shown herein are subject to change.

Example

Warrant can be used in a variety of ways. Here is a simple example to get you started:

package main

import (
	"log"

	"github.com/pivotal-cf-experimental/warrant"
)

func main() {
	w := warrant.New(warrant.Config{
		Host: "https://uaa.example.com",
	})

	clientToken, err := w.Clients.GetToken("admin", "admin-secret")
	if err != nil {
		log.Fatalf("Unable to fetch client token: %s", err)
	}

	user, err := w.Users.Create("my-user", "me@example.com", clientToken)
	if err != nil {
		log.Fatalf("Unable to create user: %s", err)
	}

	err = w.Users.SetPassword(user.ID, "my-password", clientToken)
	if err != nil {
		log.Fatalf("Unable to set user password: %s", err)
	}

	userToken, err := w.Users.GetToken("my-user", "my-password")
	if err != nil {
		log.Fatalf("Unable to fetch user token: %s", err)
	}

	decodedToken, err := w.Tokens.Decode(userToken)
	if err != nil {
		log.Fatalf("Unable to decode user token: %s", err)
	}

	log.Printf("%+v\n", decodedToken)
	// => {ClientID:cf, UserID:80d4fd0b-119f-4fc7-a800-eb186bc8e766, Scopes:[openid, cloud_controller.read]}
}

Documentation

Overview

Package warrant provides a library of functionality for interacting with the UAA service. The library supports management of users, clients, groups and tokens.

Example

Warrant can be used in a variety of ways. Here is a simple example to get you started:

import (
	"log"

	"github.com/pivotal-cf-experimental/warrant"
)

func main() {
	w := warrant.New(warrant.Config{
		Host: "https://uaa.example.com",
	})

	clientToken, err := w.Clients.GetToken("admin", "admin-secret")
	if err != nil {
		log.Fatalf("Unable to fetch client token: %s", err)
	}

	user, err := w.Users.Create("my-user", "me@example.com", clientToken)
	if err != nil {
		log.Fatalf("Unable to create user: %s", err)
	}

	err = w.Users.SetPassword(user.ID, "my-password", clientToken)
	if err != nil {
		log.Fatalf("Unable to set user password: %s", err)
	}

	userToken, err := w.Users.GetToken("my-user", "my-password")
	if err != nil {
		log.Fatalf("Unable to fetch user token: %s", err)
	}

	decodedToken, err := w.Tokens.Decode(userToken)
	if err != nil {
		log.Fatalf("Unable to decode user token: %s", err)
	}

	log.Printf("%+v\n", decodedToken)
	// => {ClientID:cf, UserID:80d4fd0b-119f-4fc7-a800-eb186bc8e766, Scopes:[openid, cloud_controller.read]}
}

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type BadRequestError

type BadRequestError struct {
	// contains filtered or unexported fields
}

BadRequestError indicates that the request sent to UAA is invalid. The specific issue can be found by inspecting the Error() output.

func (BadRequestError) Error

func (e BadRequestError) Error() string

Error returns a string representation of the BadRequestError.

type Client

type Client struct {
	// ID is the unique identifier for the client resource.
	ID string

	Name string

	// Scope contains a list of scope values describing the level of permissions for a
	// user token requested by this client.
	Scope []string

	// Authorities is a list of scope values describing the level of permissions granted
	// to this client in a token requested with the "client_credentials" grant type.
	Authorities []string

	// ResourceIDs is a white list of resource identifiers to be included in the decoded
	// tokens granted to this client. The UAA does not store any data here (it should be
	// "none" for all clients), but instead creates a list of resource identifiers
	// dynamically from the scope values when a token is granted.
	ResourceIDs []string

	// AuthorizedGrantTypes is a list of OAuth2 grant types, as defined in the spec.
	// Valid fields are:
	//   - client_credentials
	//   - password
	//   - implicit
	//   - refresh_token
	//   - authorization_code
	AuthorizedGrantTypes []string

	// AccessTokenValidity is the number of seconds before a token granted to this client
	// will expire.
	AccessTokenValidity time.Duration

	// RedirectURI is the location address to redirect the resource owner's user-agent
	// back to after completing its interaction with the resource owner.
	RedirectURI []string

	// Autoapprove is a list of scopes to automatically approve when making an implicit
	// grant for a user token.
	Autoapprove []string
}

Client is the representation of a client resource within UAA.

type ClientsService

type ClientsService struct {
	// contains filtered or unexported fields
}

ClientsService provides access to the common client actions. Using this service, you can create, delete, or fetch a client. You can also fetch a client token.

func NewClientsService

func NewClientsService(config Config) ClientsService

NewClientsService returns a ClientsService initialized with the given Config.

func (ClientsService) Create

func (cs ClientsService) Create(client Client, secret, token string) error

Create will make a request to UAA to register a client with the given client resource and A token with the "clients.write" or "clients.admin" scope is required.

func (ClientsService) Delete

func (cs ClientsService) Delete(id, token string) error

Delete will make a request to UAA to delete the client matching the given id. A token with the "clients.write" or "clients.admin" scope is required.

func (ClientsService) Get

func (cs ClientsService) Get(id, token string) (Client, error)

Get will make a request to UAA to fetch the client matching the given id. A token with the "clients.read" scope is required.

func (ClientsService) GetToken

func (cs ClientsService) GetToken(id, secret string) (string, error)

GetToken will make a request to UAA to retrieve a client token using the "client_credentials" grant type. A client id and secret are required.

func (ClientsService) List

func (cs ClientsService) List(query Query, token string) ([]Client, error)

List will make a request to UAA to retrieve all client resources matching the given query. A token with the "clients.read" or "clients.admin" scope is required.

func (ClientsService) Update

func (cs ClientsService) Update(client Client, token string) error

Update will make a request to UAA to update the matching client resource. A token with the "clients.write" or "clients.admin" scope is required.

type Config

type Config struct {
	// Host is a fully qualified url location for the UAA service (ie. https://uaa.example.com).
	Host string

	// SkipVerifySSL is a boolean value indicating whether the HTTP client will validate the SSL
	// certificate of the UAA service should those requests be communicated over HTTPS.
	SkipVerifySSL bool

	// TraceWriter is an io.Writer to which tracing information can be written. This information
	// includes the outgoing request and the incoming responses from UAA.
	TraceWriter io.Writer
}

Config contains the primary configuration values for library operation.

type DuplicateResourceError

type DuplicateResourceError struct {
	// contains filtered or unexported fields
}

DuplicateResourceError indicates that the action committed against the resource would result in a duplicate.

func (DuplicateResourceError) Error

func (e DuplicateResourceError) Error() string

Error returns a string representation of the DuplicateResourceError.

type ForbiddenError

type ForbiddenError struct {
	// contains filtered or unexported fields
}

ForbiddenError indicates that the requested action was unauthorized. This could mean that the provided token does not contain the required scope.

func (ForbiddenError) Error

func (e ForbiddenError) Error() string

Error returns a string representation of the UnauthorizedError.

type Group

type Group struct {
	// ID is the unique identifier for the group resource.
	ID string

	// DisplayName is the human-friendly name given to a group.
	DisplayName string

	// Description is the human readable description of the group.
	Description string

	// Version is an integer value indicating which revision this resource represents.
	Version int

	// CreatedAt is a timestamp value indicating when the group was created.
	CreatedAt time.Time

	// UpdatedAt is a timestamp value indicating when the group was last modified.
	UpdatedAt time.Time

	// Members is the list of members to be included in the group.
	Members []Member
}

Group is the representation of a group resource within UAA.

type GroupsService

type GroupsService struct {
	// contains filtered or unexported fields
}

GroupsService provides access to common group actions. Using this service, you can create, delete, fetch and list group resources.

func NewGroupsService

func NewGroupsService(config Config) GroupsService

NewGroupsService returns a GroupsService initialized with the given Config.

func (GroupsService) AddMember

func (gs GroupsService) AddMember(groupID, memberID, token string) (Member, error)

AddMember will make a request to UAA to add a member to the group resource with the matching id. A token with the "scim.write" scope is required.

func (GroupsService) CheckMembership

func (gs GroupsService) CheckMembership(groupID, memberID, token string) (Member, bool, error)

CheckMembership will make a request to UAA to fetch a member resource from a group resource. A token with the "scim.read" scope is required.

func (GroupsService) Create

func (gs GroupsService) Create(displayName, token string) (Group, error)

Create will make a request to UAA to create a new group resource with the given DisplayName. A token with the "scim.write" scope is required.

func (GroupsService) Delete

func (gs GroupsService) Delete(id, token string) error

Delete will make a request to UAA to delete the group resource with the matching id. A token with the "scim.write" scope is required.

func (GroupsService) Get

func (gs GroupsService) Get(id, token string) (Group, error)

Get will make a request to UAA to fetch the group resource with the matching id. A token with the "scim.read" scope is required.

func (GroupsService) List

func (gs GroupsService) List(query Query, token string) ([]Group, error)

List wil make a request to UAA to list the groups that match the given Query. A token with the "scim.read" scope is required.

func (GroupsService) ListMembers

func (gs GroupsService) ListMembers(groupID, token string) ([]Member, error)

ListMembers will make a request to UAA to fetch the members of a group resource with the matching id. A token with the "scim.read" scope is required.

func (GroupsService) RemoveMember

func (gs GroupsService) RemoveMember(groupID, memberID, token string) error

RemoveMember will make a request to UAA to remove a member from a group resource. A token with the "scim.write" scope is required.

func (GroupsService) Update

func (gs GroupsService) Update(group Group, token string) (Group, error)

Update will make a request to UAA to update the matching group resource. A token with the "scim.write" or "groups.update" scope is required.

type InvalidTokenError

type InvalidTokenError struct {
	// contains filtered or unexported fields
}

InvalidTokenError indicates that the provided token is invalid. The specific issue can be found by viewing the Error() return value.

func (InvalidTokenError) Error

func (e InvalidTokenError) Error() string

Error returns a string representation of the InvalidTokenError.

type MalformedResponseError

type MalformedResponseError struct {
	// contains filtered or unexported fields
}

MalformedResponseError indicates that the response received from UAA is malformed.

func (MalformedResponseError) Error

func (e MalformedResponseError) Error() string

Error returns a string representation of the MalformedResponseError.

type Member

type Member struct {
	// The alias of the identity provider that authenticated
	// this user. "uaa" is an internal UAA user.
	Origin string `json:"origin"`

	// Type is either "USER" or "GROUP".
	Type string `json:"type"`

	// Value is the globally-unique ID of the member entity,
	// either a user ID or another group ID.
	Value string `json:"value"`
}

Member is the representation of a group member resource within UAA. This is probably just a user.

type NotFoundError

type NotFoundError struct {
	// contains filtered or unexported fields
}

NotFoundError indicates that the resource could not be found.

func (NotFoundError) Error

func (e NotFoundError) Error() string

Error returns a string representation of the NotFoundError.

type Query

type Query struct {
	// Filter is a string representation of a filtering expression as specified in the SCIM spec.
	Filter string
	// SortBy is a string representation of what field to sort the users by.
	SortBy string
}

Query is a representation of a search query used to list resources.

type SigningKey

type SigningKey struct {
	// id for the signing key
	KeyId string

	// Algorithm indicates the kind of key used to sign tokens.
	// Keys can be either symmetric or asymmetric.
	Algorithm string

	// Value is a string representation of the key. In the case of a symmetric key,
	// this is the shared secret value. for asymmetric keys, this is the public key
	// of the keypair.
	Value string
}

SigningKey is the representation of the key used to validate a token.

type Token

type Token struct {
	// Algorithm is the method used to sign the token.
	Algorithm string

	// KeyID is the ID of the signing key used to sign this token.
	KeyID string

	// ClientID is the value given in the "client_id" field of the token claims.
	// This is the unique identifier of the client to whom this token was granted.
	ClientID string `json:"client_id"`

	// UserID is the value given in the "user_id" field of the token claims.
	// This is the unique identifier for the user.
	UserID string `json:"user_id"`

	// Scopes are the values given in the "scope" field of the token claims.
	// These values indicate the level of access granted by the user to this token.
	Scopes []string `json:"scope"`

	// Issuer is the UAA endpoint that generated the token.
	Issuer string `json:"iss"`

	// Segments contains the raw token segment strings.
	Segments TokenSegments
}

Token is the representation of a token within UAA.

func (Token) Verify

func (t Token) Verify(signingKeys []SigningKey) error

Verify will use the given signing keys to verify the authenticity of the token. Supports RSA and HMAC siging methods.

type TokenSegments

type TokenSegments struct {
	// Header is the raw token header segment.
	Header string

	// Claims is the raw token claims segment.
	Claims string

	// Signature is the raw token signature segment.
	Signature string
}

TokenSegments is the encoded token segments split into their named parts.

type TokensService

type TokensService struct {
	// contains filtered or unexported fields
}

TokensService provides access to common token actions. Using this service, you can decode a token and fetch the signing key to validate a token.

func NewTokensService

func NewTokensService(config Config) TokensService

NewTokensService returns a TokensService initialized with the given Config.

func (TokensService) Decode

func (ts TokensService) Decode(token string) (Token, error)

Decode returns a decoded token value. The returned value represents the token's claims section.

func (TokensService) GetSigningKey

func (ts TokensService) GetSigningKey() (SigningKey, error)

GetSigningKey makes a request to UAA to retrieve the SigningKey used to generate valid tokens.

func (TokensService) GetSigningKeys

func (ts TokensService) GetSigningKeys() ([]SigningKey, error)

GetSigningKeys makes a request to UAA to retrieve the SigningKeys used to generate valid tokens.

type UnauthorizedError

type UnauthorizedError struct {
	// contains filtered or unexported fields
}

UnauthorizedError indicates that the requested action was unauthorized. This could mean that the provided token is invalid, or does not contain the required scope.

func (UnauthorizedError) Error

func (e UnauthorizedError) Error() string

Error returns a string representation of the UnauthorizedError.

type UnexpectedStatusError

type UnexpectedStatusError struct {
	// contains filtered or unexported fields
}

UnexpectedStatusError indicates that UAA returned a status code that was unexpected. The error message should provide some information about the specific error.

func (UnexpectedStatusError) Error

func (e UnexpectedStatusError) Error() string

Error returns a string representation of the UnexpectedStatusError.

type UnknownError

type UnknownError struct {
	// contains filtered or unexported fields
}

UnknownError indicates that an error of unknown type has been encountered.

func (UnknownError) Error

func (e UnknownError) Error() string

Error returns a string representation of the UnknownError.

type User

type User struct {
	// ID is the unique identifier for the user.
	ID string

	// ExternalID is an identifier for the user as defined by the client that created it.
	ExternalID string

	// UserName is a human-friendly unique identifier for the user.
	UserName string

	// FormattedName is the full name, including middle names, of the user.
	FormattedName string

	// FamilyName is the family name, or last name, of the user.
	FamilyName string

	// GivenName is the given name, or first name, of the user.
	GivenName string

	// MiddleName is the middle name(s) of the user.
	MiddleName string

	// CreatedAt is a timestamp value indicating when the user was created.
	CreatedAt time.Time

	// UpdatedAt is a timestamp value indicating when the user was last modified.
	UpdatedAt time.Time

	// Version is an integer value indicating which revision this resource represents.
	Version int

	// Emails is a list of email addresses for this user.
	Emails []string

	// Groups is a list of groups to which this user is associated.
	Groups []Group

	// Active is a boolean value indicating the active status of the user.
	Active bool

	// Verified is a boolean value indicating whether this user has been verified.
	Verified bool

	// Origin is a value indicating where this user resource originated.
	Origin string
}

User is the representation of a user resource within UAA.

type UsersService

type UsersService struct {
	// contains filtered or unexported fields
}

UsersService provides access to common user actions. Using this service, you can create, fetch, update, delete, and list users. You can also change and set their passwords, and fetch their tokens.

func NewUsersService

func NewUsersService(config Config) UsersService

NewUsersService returns a UsersService initialized with the given Config.

func (UsersService) ChangePassword

func (us UsersService) ChangePassword(id, oldPassword, password, token string) error

ChangePassword will make a request to UAA to change the password for the user with the matching id to the given password value. The existing password for the user resource as well as a token for the user is required.

func (UsersService) Create

func (us UsersService) Create(username, email, token string) (User, error)

Create will make a request to UAA to create a new user resource with the given username and email. A token with the "scim.write" scope is required.

func (UsersService) Delete

func (us UsersService) Delete(id, token string) error

Delete will make a request to UAA to delete the user resource with the matching id. A token with the "scim.write" scope is required.

func (UsersService) Get

func (us UsersService) Get(id, token string) (User, error)

Get will make a request to UAA to fetch the user with the matching id. A token with the "scim.read" scope is required.

func (UsersService) GetToken

func (us UsersService) GetToken(username, password string, client Client) (string, error)

GetToken will make a request to UAA to retrieve the token for the user matching the given username. The user's password is required.

func (UsersService) List

func (us UsersService) List(query Query, token string) ([]User, error)

List will make a request to UAA to retrieve all user resources matching the given query. A token with the "scim.read" or "uaa.admin" scope is required.

func (UsersService) SetPassword

func (us UsersService) SetPassword(id, password, token string) error

SetPassword will make a request to UAA to set the password for the user with the matching id to the given password value. A token with the "password.write" scope is required.

func (UsersService) Update

func (us UsersService) Update(user User, token string) (User, error)

Update will make a request to UAA to update the matching user resource. A token with the "scim.write" or "uaa.admin" scope is required.

type Warrant

type Warrant struct {

	// Users is a UsersService providing access to the user resource actions.
	Users UsersService

	// Clients is a ClientsService providing access to the client resource actions.
	Clients ClientsService

	// Groups is a GroupsService providing access to the group resource actions.
	Groups GroupsService

	// Tokens is a TokensService providing access to the tokens actions.
	Tokens TokensService
	// contains filtered or unexported fields
}

Warrant provices access to the users, clients, groups, and tokens services provided by this library.

func New

func New(config Config) Warrant

New returns a Warrant initialized with the given Config. The member fields (Users, Clients, Groups, and Tokens) have also been initialized with the given Config.

Directories

Path Synopsis
internal
network
Package network provides an HTTP network abstraction that is bound to the request/response cycle of commands to the UAA service.
Package network provides an HTTP network abstraction that is bound to the request/response cycle of commands to the UAA service.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL