ga4gh

README

ga4gh-identity

This repository contains an implementation of the GA4GH Data Use and Researcher Identity and Authentication Profile specifications. It also contains a Google Cloud Platform specific implementation of an identity proxy capable of turning GA4GH identities into Google Cloud Platform identities.

Contributing

See the contributing document for information about how to contribute to this repository.

Notice

This is not an officially supported Google product.

Documentation

Overview

Package ga4gh provides primitives for dealing with identities as described by the Global Alliance for Genomics and Healthcare's Data Use and Researcher Identity workstream.

Index

• func NewIdentityContext(ctx context.Context, identity *Identity) context.Context
• type BoolValue
• type Evaluator
  • func (ev *Evaluator) Evaluate(ctx context.Context, auth string) (*Identity, error)
• type Handler
  • func (h *Handler) ServeHTTP(w http.ResponseWriter, req *http.Request)
• type Identity
  • func IdentityFromContext(ctx context.Context) (*Identity, bool)
• type Parser
  • func NewParser(ctx context.Context, shims []Shim, issuers map[string]string) (*Parser, error)
  • func (p *Parser) Parse(ctx context.Context, auth string) (*Identity, error)
• type Shim
• type StringValue
• type Validator

Functions

func NewIdentityContext

func NewIdentityContext(ctx context.Context, identity *Identity) context.Context

NewIdentityContext creates a new context.Conext from ctx that carries identity.

Types

type BoolValue

type BoolValue struct {
	Value  bool   `json:"value"`
	Source string `json:"source"`
}

BoolValue represents a boolean value and claim source.

type Evaluator

type Evaluator struct {
	Parser    *Parser
	Validator Validator
}

Evaluator combines both parsing and validation of authorization tokens.

func (*Evaluator) Evaluate

func (ev *Evaluator) Evaluate(ctx context.Context, auth string) (*Identity, error)

Evaluate attempts to parse auth using ev.Parser, and then validate it using ev.Validator. It will only return a non-error result if the identity both parses and validates.

type Handler

type Handler struct {
	// Evaluator is used to provide the parsing and validation logic.
	Evaluator *Evaluator

	// Handler is invoked only if the incoming identity could be parsed and
	// validated.  The http.Request will have a ga4gh.Identity associated with it
	// via NewIdentityContext.
	Handler http.Handler
}

Handler implements an http.Handler that parses an incoming identity, validates it, and then passes it to an underlying http.Handler. The http.Request passed to the underlying handler has an identity associated with it via NewIdentityContext.

func (*Handler) ServeHTTP

func (h *Handler) ServeHTTP(w http.ResponseWriter, req *http.Request)

ServeHTTP implements the http.Handler interface.

type Identity

type Identity struct {
	Subject string `json:"sub,omitempty"`
	Issuer  string `json:"iss,omitempty"`

	OriginOrganization              []StringValue `json:"ga4gh.IdentityOriginOrganization"`
	AcademicInstitutionAffiliations []StringValue `json:"ga4gh.AcademicInstitutionAffiliations"`
	Role                            []StringValue `json:"ga4gh.Role"`
	HasAcknowledgedEthicsTerms      []StringValue `json:"ga4gh.HasAcknowledgedEthicsTerms"`
	BonaFide                        []BoolValue   `json:"ga4gh.ResearcherStatus.BonaFide"`
}

Identity is a GA4GH identity as described by the Data Use and Researcher Identity stream.

func IdentityFromContext

func IdentityFromContext(ctx context.Context) (*Identity, bool)

IdentityFromContext returns the identity associated with ctx. If there is no associated identity then it returns (nil, false).

type Parser

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

Parser parses OIDC bearer tokens into Identity structs.

func NewParser

func NewParser(ctx context.Context, shims []Shim, issuers map[string]string) (*Parser, error)

NewParser constructs a new Parser using shims for translating external identities and issuers as a map of OAuth 2.0 base URLs to client IDs. When parsing an identity token it first tries to use each of the shims in order to perform the conversion. If none of the shims succeed it then checks if the token was issued by any of the OAuth 2.0 providers in issuers, and directly accepting the claims present if it is.

func (*Parser) Parse

func (p *Parser) Parse(ctx context.Context, auth string) (*Identity, error)

Parse takes an authorization string (usually an HTTP authorization bearer token) and converts it into an Identity.

type Shim

type Shim interface {
	Shim(ctx context.Context, auth string) (*Identity, error)
}

Shim is used to convert an HTTP bearer authorization string that is _not_ in the normal Identity format into an Identity. This is useful when interoperating with systems that do not yet provide a GA4GH identity.

type StringValue

type StringValue struct {
	Value  string `json:"value"`
	Source string `json:"source"`
}

StringValue represents a string value and claim source.

type Validator

type Validator interface {
	Validate(ctx context.Context, identity *Identity) (bool, error)
}

Validator is used to determine whether a given Identity is "valid" in a given context.