ga4gh

package
v0.9.15 Latest Latest
Warning

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

 Go to latest Published: Mar 3, 2021 License: Apache-2.0 Imports: 16 Imported by: 0

README

The package ga4gh provides an implementation of GA4GH Passport v0.9.6 spec.

GA4GH Passport GitHub repository

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

Constants

This section is empty.

Variables

View Source 
var (
	// JWTEmptyJKU is for visa issuers who do not wish to set a "jku" header.
	// See https://tools.ietf.org/html/rfc7515#section-4.1.2 for details.
	JWTEmptyJKU = ""
)

Functions

func CheckCondition 

func CheckCondition(c Condition, a Assertion) error

CheckCondition checks if a Visa satisfies a Condition. We use Visa because we would also need to verify the Visa. https://bit.ly/ga4gh-passport-v1#conditions

func CheckConditions 

func CheckConditions(ctx context.Context, c Conditions, vs []*Visa, f JWTVerifier) error

CheckConditions checks if the given list of Assertions satisfies the given Conditions. Conditions is a DNF, an OR of Clauses, each Clause an AND of Literals, each Literal a Condition. A list of Assertions satisfies a Condition if at least one of Assertions makes the Condition true. Visas which cannot be verified will be ignored.

func CheckIdentityAllVisasLinked 

func CheckIdentityAllVisasLinked(ctx context.Context, i *Identity, f JWTVerifier) error

CheckIdentityAllVisasLinked checks if the Visas inside the identity are linked. Verifies all Visas of type LinkedIdentities. If JWTVerifier is not nil, will call f to verify LinkedIdentities Visas. If JWTVerifier is nil, verification is skipped.

func CheckLinkedIDs 

func CheckLinkedIDs(vs []*Visa) error

CheckLinkedIDs checks if there are sufficient LinkedIdentities Assertions to show that all IDs of the given list of Visas are the same.

func CustomType 

func CustomType(t Type) bool

CustomType checks if the Type of an Assertion is a custom. http://bit.ly/ga4gh-passport-v1#custom-passport-visa-types http://bit.ly/ga4gh-passport-v1#url-fields

func HasTrustedIssuer 

func HasTrustedIssuer(v *Visa, t TrustedIssuers) bool

HasTrustedIssuer checks if a given Visa has a trusted issuer.

func HasTrustedSource 

func HasTrustedSource(v *Visa, t TrustedSources) bool

HasTrustedSource checks if a Visa has a trusted source.

func HasUserinfoClaims added in v0.8.4 

func HasUserinfoClaims(id *Identity) bool

HasUserinfoClaims checks if /userinfo endpoint needs to be called to fetch additional claims for a particular identity.

func MatchPatterns 

func MatchPatterns(p Pattern, v string) error

MatchPatterns checks if a given string matches a Pattern.

func MatchRegExp 

func MatchRegExp(e RegExp, x Value) bool

MatchRegExp checks if a value matches one of the given list of RE2s.

func StandardType 

func StandardType(t Type) bool

StandardType checks if the Type of an Assertion is one of the standard ones. http://bit.ly/ga4gh-passport-v1#ga4gh-standard-passport-visa-type-definitions

func ToRejectedVisaProto added in v0.8.6 

func ToRejectedVisaProto(in *RejectedVisa) *cpb.RejectedVisa

ToRejectedVisaProto convert RejectedVisa to proto.

func TokenUserID added in v0.8.4 

func TokenUserID(token *Identity, maxLength int) string

TokenUserID returns an user identifier for a given token.

func ValidType 

func ValidType(t Type) bool

ValidType checks the Type of an Assertion is valid.

func VerifyTokenWithKey added in v0.8.4 

func VerifyTokenWithKey(publicKey *rsa.PublicKey, tok string) error

VerifyTokenWithKey verifies the signature of a token given a public key.

Types

type Access 

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

Access represents a GA4GH Access Token. http://bit.ly/ga4gh-passport-v1#overview

func NewAccessFromData 

func NewAccessFromData(ctx context.Context, d *AccessData, signer kms.Signer) (*Access, error)

NewAccessFromData creates a new Access.

keyID identifies the key used by issuer to sign the JWT. Visit the issuer's JWKS endpoint to obtain the keys and find the public key corresponding to the keyID. To find the issuer's JWKS endpoint, visit "[issuer]/.well-known/openid-configuration" "jku" in JWT header is not allowed for Access.

func NewAccessFromJWT 

func NewAccessFromJWT(j AccessJWT) (*Access, error)

NewAccessFromJWT creates a new Access from a given JWT. Returns error if the JWT is not the JWT of a Access. Does not verify the signature on the JWT.

func (*Access) Data 

func (p *Access) Data() *AccessData

Data returns the data of a Access.

func (*Access) JWT 

func (p *Access) JWT() AccessJWT

JWT returns the JWT of a Access.

type AccessData 

type AccessData struct {
	// StdClaims is embeded for standard JWT claims.
	StdClaims

	// Scope ...
	Scope string `json:"scope,omitempty"`

	// TODO: Replace identities with LinkedIdentities visas.
	Identities map[string][]string `json:"identities,omitempty"`

	Patient string `json:"patient,omitempty"`

	// FhirUser is the SMART-on-FHIR principal identity.
	FhirUser string `json:"fhirUser,omitempty"`
}

AccessData is used to create a new Access.

type AccessJWT 

type AccessJWT string

AccessJWT is a string containing a JWT Access object.

type Assertion 

type Assertion struct {
	// Type http://bit.ly/ga4gh-passport-v1#type
	Type Type `json:"type,omitempty"`

	// Value http://bit.ly/ga4gh-passport-v1#value
	Value Value `json:"value,omitempty"`

	// Source http://bit.ly/ga4gh-passport-v1#source
	Source Source `json:"source,omitempty"`

	// By http://bit.ly/ga4gh-passport-v1#by
	By By `json:"by,omitempty"`

	// Asserted http://bit.ly/ga4gh-passport-v1#asserted
	Asserted Timestamp `json:"asserted,omitempty"`

	// Conditions http://bit.ly/ga4gh-passport-v1#conditions
	Conditions Conditions `json:"conditions,omitempty"`
}

Assertion represents a GA4GH Passport Visa Object. http://bit.ly/ga4gh-passport-v1#passport-visa-object

type Audiences 

type Audiences []string

Audiences is "aud" field in jwt. In oidc spec, "aud" can be single string or array of string. https://tools.ietf.org/html/rfc7519#section-4.1.3

func NewAudience 

func NewAudience(aud string) Audiences

NewAudience returns Audiences based on a single string input.

func (*Audiences) UnmarshalJSON 

func (a *Audiences) UnmarshalJSON(bytes []byte) error

UnmarshalJSON unmarshal string or array of string in json to []string in go.

type By 

type By string

By is the By of an Assertion. http://bit.ly/ga4gh-passport-v1#by 

const (
	// Self is the Pasport Visa Identity for which the assertion is being made and the person who made the assertion is the same person.
	Self By = "self"

	// Peer is a person at the source organization has made this assertion on behalf of the Passport Visa Identity's person, and the person who is making the assertion has the same Passport Visa Type and value in that source organization. The source field represents the peer’s organization that is making the assertion, which is not necessarily the same organization as the Passport Visa Identity's organization.
	Peer By = "peer"

	// System is the source organization’s information system has made the assertion based on system data or metadata that it stores.
	System By = "system"

	// SO is a person (also known as "signing official") making the assertion within the source organization possesses direct authority (as part of their formal duties) to bind the organization to their assertion that the Passport Visa Identity, did possess such authority at the time the assertion was made.
	SO By = "so"

	// DAC is a Data Access Committee or other authority that is responsible as a grantee decision-maker for the given value and source field pair.)
	DAC By = "dac"
)

type Clause 

type Clause []Condition

Clause is an AND of Literals.

type Condition 

type Condition struct {
	// Type http://bit.ly/ga4gh-passport-v1#type
	Type Type `json:"type,omitempty"`

	// Value http://bit.ly/ga4gh-passport-v1#pattern-matching
	Value Pattern `json:"value,omitempty"`

	// Source http://bit.ly/ga4gh-passport-v1#source
	Source Pattern `json:"source,omitempty"`

	// By http://bit.ly/ga4gh-passport-v1#by
	By Pattern `json:"by,omitempty"`
}

Condition represnet a GA4GH Passport Visa Condition. http://bit.ly/ga4gh-passport-v1#conditions

type Conditions 

type Conditions [][]Condition

Conditions represent a GA4GH Passport Visa condition field sub-object. https://docs.google.com/document/d/1NySsYM1V9ssxk_k4RH37fU4tJK8x37YMmDxnn_45FvQ/

type ID 

type ID struct {
	Issuer  string
	Subject string
}

ID identifies a subject at an issuer.

func ExtractLinkedIDs 

func ExtractLinkedIDs(a Assertion) []ID

ExtractLinkedIDs extracts ids from a LinkedIdentities Assertion. Format is a semicolon separated list, each item in the list is of the form "subject,issuer" where subject and issuer are URI-encoded. http://bit.ly/ga4gh-passport-v1#linkedidentities

type Identity 

type Identity struct {
	Subject          string                 `json:"sub,omitempty"`
	Issuer           string                 `json:"iss,omitempty"`
	IssuedAt         int64                  `json:"iat,omitempty"`
	NotBefore        int64                  `json:"nbf,omitempty"`
	Expiry           int64                  `json:"exp,omitempty"`
	Scope            string                 `json:"scope,omitempty"`
	Scp              []string               `json:"scp,omitempty"`
	Audiences        Audiences              `json:"aud,omitempty"`
	AuthorizedParty  string                 `json:"azp,omitempty"`
	ID               string                 `json:"jti,omitempty"`
	TokenID          string                 `json:"tid,omitempty"`
	Nonce            string                 `json:"nonce,omitempty"`
	GA4GH            map[string][]OldClaim  `json:"-"` // do not emit
	RejectedVisas    []*RejectedVisa        `json:"-"` // do not emit
	IdentityProvider string                 `json:"idp,omitempty"`
	Identities       map[string][]string    `json:"identities,omitempty"`
	Username         string                 `json:"preferred_username,omitempty"`
	Email            string                 `json:"email,omitempty"`
	EmailVerified    bool                   `json:"email_verified,omitempty"`
	Name             string                 `json:"name,omitempty"`
	Nickname         string                 `json:"nickname,omitempty"`
	GivenName        string                 `json:"given_name,omitempty"`
	FamilyName       string                 `json:"family_name,omitempty"`
	MiddleName       string                 `json:"middle_name,omitempty"`
	ZoneInfo         string                 `json:"zoneinfo,omitempty"`
	Locale           string                 `json:"locale,omitempty"`
	Picture          string                 `json:"picture,omitempty"`
	Profile          string                 `json:"profile,omitempty"`
	Realm            string                 `json:"realm,omitempty"`
	VisaJWTs         []string               `json:"ga4gh_passport_v1,omitempty"`
	Extra            map[string]interface{} `json:"ext,omitempty"`
	Patient          string                 `json:"patient,omitempty"`  // SMART-on-FHIR
	FhirUser         string                 `json:"fhirUser,omitempty"` // SMART-on-FHIR
}

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

func ConvertTokenToIdentityUnsafe added in v0.8.4 

func ConvertTokenToIdentityUnsafe(tok string) (*Identity, error)

ConvertTokenToIdentityUnsafe unsafely converts a token to an identity.

func (*Identity) RejectVisa added in v0.8.4 

func (t *Identity) RejectVisa(visa *VisaData, format VisaFormat, reason, field, message string)

RejectVisa adds a new RejectedVisa report to the identity (up to a maximum number of reports).

type Issuer 

type Issuer string

Issuer is a Visa Issuer.

type JWTVerifier 

type JWTVerifier func(ctx context.Context, jwt, iss, jku string) error

JWTVerifier verifies the JWT token. It might make calls to external services, e.g. to obtain public key.

type Literal 

type Literal = Condition

Literal is a Condition.

type OldClaim 

type OldClaim struct {
	Value       string                       `json:"value"`
	Source      string                       `json:"source"`
	Asserted    float64                      `json:"asserted,omitempty"`
	Expires     float64                      `json:"expires,omitempty"`
	Condition   map[string]OldClaimCondition `json:"condition,omitempty"`
	By          string                       `json:"by,omitempty"`
	Issuer      string                       `json:"issuer,omitempty"`
	VisaData    *VisaData                    `json:"-"`
	TokenFormat VisaFormat                   `json:"-"`
}

OldClaim represents a claim object as defined by GA4GH.

type OldClaimCondition 

type OldClaimCondition struct {
	Value  []string `json:"value,omitempty"`
	Source []string `json:"source,omitempty"`
	By     []string `json:"by,omitempty"`
}

OldClaimCondition represents a condition object as defined by GA4GH.

type Passport 

type Passport struct {
	// Access is the Access Token for the Passport.
	Access *Access

	// Visas contains the list of Visas for the Passport.
	Visas []*Visa `json:"ga4gh_passport_v1,omitempty"`
}

Passport represents a GA4GH Passport. http://bit.ly/ga4gh-passport-v1#overview

type Pattern 

type Pattern string

Pattern for a string from Pattern Matching section of GA4GH Passport sepcification. Pattern should be of one of the following forms: prefix = "const:": the field should be equal to the suffix prefix = "pattern:": the field should match the suffix prefix = "split_pattern": the field should match one of the parts of suffix after splitting by ; The only wildchars for matching are ? and *. ? is interpreted as any single character, * is interpretted as any string. http://bit.ly/ga4gh-passport-v1#pattern-matching

type Policy 

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

Policy for a resource/view/role. Used in Passport Clearinghouse.

func NewPolicy 

func NewPolicy(i TrustedIssuers, s TrustedSources, allow Conditions, deny Conditions, f JWTVerifier) (*Policy, error)

NewPolicy creates a new Policy. A passport would satisfy the policy if, after filtering and restricting Visas to those from TrustedIssuers and TrustedSource, allow is true and deny is false, and Condtions inside the Visas are true. If no deny is unspecified (nil), it is ignored.

func (*Policy) Test 

func (p *Policy) Test(ctx context.Context, r *Passport) error

Test checks if the provided passport satisfies the policy. Presumes that the signatures on the Passport and its Visas have already been verified.

type RegExp 

type RegExp string

RegExp is a RE2 string. https://golang.org/s/re2syntax

type RejectedVisa added in v0.8.4 

type RejectedVisa struct {
	TokenFormat string        `json:"tokenFormat,omitempty"`
	Issuer      string        `json:"iss,omitempty"`
	Subject     string        `json:"sub,omitempty"`
	Assertion   Assertion     `json:"assertion,omitempty"`
	Rejection   VisaRejection `json:"rejection,omitempty"`
}

RejectedVisa provides insight into why a policy engine is not making use of visas that are present within the passport.

func NewRejectedVisa added in v0.8.4 

func NewRejectedVisa(visa *VisaData, format VisaFormat, reason, field, message string) *RejectedVisa

NewRejectedVisa creates a rejected visa information struct.

func VisasToOldClaims 

func VisasToOldClaims(ctx context.Context, visas []VisaJWT, f JWTVerifier) (map[string][]OldClaim, []*RejectedVisa, error)

VisasToOldClaims populates the GA4GH claim based on visas. Returns a map of visa types, each having a list of OldClaims for that type. TODO: use new policy engine instead when it becomes available.

type Scope 

type Scope string

Scope is the AAI Scope claim http://bit.ly/ga4gh-aai-profile#ga4gh-jwt-format

type Source 

type Source string

Source is the Source of an Assertion. http://bit.ly/ga4gh-passport-v1#source

type StdClaims 

type StdClaims struct {
	Audience        Audiences `json:"aud,omitempty"`
	AuthorizedParty string    `json:"azp,omitempty"`
	ExpiresAt       int64     `json:"exp,omitempty"`
	ID              string    `json:"jti,omitempty"`
	IssuedAt        int64     `json:"iat,omitempty"`
	Issuer          string    `json:"iss,omitempty"`
	NotBefore       int64     `json:"nbf,omitempty"`
	Subject         string    `json:"sub,omitempty"`
}

StdClaims contains the standard claims. We duplicate this instead of just using jwt.StandardClaims because Audience can be a string array.

func NewStdClaimsFromJWT 

func NewStdClaimsFromJWT(token string) (*StdClaims, error)

NewStdClaimsFromJWT extracts StdClaims from a serialized JWT token.

type Timestamp 

type Timestamp = int64

Timestamp is the number of seconds since epoch.

type TrustedIssuers 

type TrustedIssuers map[Issuer]map[Source]bool

TrustedIssuers contains the list of trusted Visa Issuers for each Source. Claims from issuers which are not trusted for the source must be ignored. If an issuer is trusted but no sources are listed then it is trusted for all.

type TrustedSources 

type TrustedSources map[Source]map[Type][]RegExp

TrustedSources contains the list of trusted Assertion Sources for each Assertion. Claims from sources which are not trusted for the Assertion must be ignored. E.g. Source "standford" can be trusted for "AffiliationAndRole" claims about "*@stanford.edu". If a source is trusted but no types are listed then it is trusted for all. If a source is trusted for a type but no RE are listed then it is ".*".

type Type 

type Type string

Type is known GA4GH Assertion types. http://bit.ly/ga4gh-passport-v1#type 

const (
	// AffiliationAndRole Assertion type.
	// http://bit.ly/ga4gh-passport-v1#affiliationandrole
	AffiliationAndRole Type = "AffiliationAndRole"

	// AcceptedTermsAndPolicies Assertion type.
	// http://bit.ly/ga4gh-passport-v1#acceptedtermsandpolicies
	AcceptedTermsAndPolicies Type = "AcceptedTermsAndPolicies"

	// ResearcherStatus Assertion type.
	// http://bit.ly/ga4gh-passport-v1#researcherstatus
	ResearcherStatus Type = "ResearcherStatus"

	// ControlledAccessGrants Assertion type.
	// http://bit.ly/ga4gh-passport-v1#controlledaccessgrants
	ControlledAccessGrants Type = "ControlledAccessGrants"

	// LinkedIdentities Assertion type.
	// http://bit.ly/ga4gh-passport-v1#linkedidentities
	LinkedIdentities Type = "LinkedIdentities"
)

type Value 

type Value string

Value is the value of an Assertion. http://bit.ly/ga4gh-passport-v1#value

func LinkedIDValue 

func LinkedIDValue(neighbors []ID) Value

LinkedIDValue creates a LinkedIdentities Assertion Value from a given list of IDs.

type Visa 

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

Visa represents a GA4GH Passport Visa. A Visa is a "Signed Assertion".

func NewVisaFromData 

func NewVisaFromData(ctx context.Context, d *VisaData, jku string, signer kms.Signer) (*Visa, error)

NewVisaFromData creates a new Visa.

keyID identifies the key used by issuer to sign the JWT. Visit the issuer's JWKS endpoint to obtain the keys and find the public key corresponding to the keyID. To find the issuer's JWKS endpoint: 

If openid scope exists in the Visa, visit "[issuer]/.well-known/openid-configuration"
Else if "jku" exists in JWT header, use the "jku" value.
Otherwise, the Visa cannot be verified.

See https://bit.ly/ga4gh-aai-profile#embedded-token-issued-by-embedded-token-issuer

func NewVisaFromJWT 

func NewVisaFromJWT(j VisaJWT) (*Visa, error)

NewVisaFromJWT creates a new Visa from a given JWT. Returns error if the JWT is not the JWT of a Visa. Does not verify the signature on the JWT.

func (*Visa) AssertionProto 

func (v *Visa) AssertionProto() *cpb.Assertion

AssertionProto returns the visa assertion in common proto (cpb.Assertion) format.

func (*Visa) Data 

func (v *Visa) Data() *VisaData

Data returns the data of a Visa.

func (*Visa) Format added in v0.8.4 

func (v *Visa) Format() VisaFormat

Format returns the VisaFormat (i.e. embedded token format) for the visa.

func (*Visa) JKU added in v0.8.4 

func (v *Visa) JKU() string

JKU returns the JKU header of a Visa.

func (*Visa) JWT 

func (v *Visa) JWT() VisaJWT

JWT returns the JWT of a Visa.

type VisaData 

type VisaData struct {
	// StdClaims is embeded for standard JWT claims.
	StdClaims

	// Scope for the Visa.
	// http://bit.ly/ga4gh-aai-profile#ga4gh-jwt-format
	Scope Scope `json:"scope,omitempty"`

	// Assertion contains the Visa Assertion.
	Assertion Assertion `json:"ga4gh_visa_v1,omitempty"`
}

VisaData is used for creating a new visa.

func MustVisaDataFromJWT 

func MustVisaDataFromJWT(j VisaJWT) *VisaData

MustVisaDataFromJWT converts a VisaJWT to VisaData. Crashes if VisaJWT cannot be parsed. Useful for writing tests: cmp.Transformer("", ga4gh.VisaJWTTransform) DO NOT use in non-test code. TODO: move to a testutil package.

type VisaFormat added in v0.8.4 

type VisaFormat string

VisaFormat indicates what GA4GH embedded token format is used for a visa. See https://bit.ly/ga4gh-aai-profile#embedded-token-issued-by-embedded-token-issuer. 

const (
	// AccessTokenVisaFormat represents an "Embedded Access Token" visa format.
	// See https://bit.ly/ga4gh-aai-profile#term-embedded-access-token.
	AccessTokenVisaFormat VisaFormat = "access_token"

	// DocumentVisaFormat represents an "Embedded Document Token" visa format.
	// See https://bit.ly/ga4gh-aai-profile#term-embedded-document-token.
	DocumentVisaFormat VisaFormat = "document"

	// UnspecifiedVisaFormat is used when the token cannot be read or is not available.
	UnspecifiedVisaFormat VisaFormat = ""
)

type VisaJWT 

type VisaJWT string

VisaJWT is a JWT object containing a GA4GH Visa.

type VisaRejection added in v0.8.4 

type VisaRejection struct {
	Reason      string `json:"reason,omitempty"`
	Field       string `json:"field,omitempty"`
	Description string `json:"msg,omitempty"`
}

VisaRejection is filled in by a policy engine to understand why a visa was rejected. Visas unrelated to the policy are not considered rejected unless they are not trusted.

Source Files

View all Source files

Directories

Path Synopsis
example is an example of how to use ga4gh package.
 example is an example of how to use ga4gh package.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.