...
GA4GH supports multiple types of visa claims, each with varying degrees of complexity. In addition, each claim contains temporal data used for validation. Some visas have conditions such that they are only valid if one or more other visas are also present. Deciding if a visa matches the access requirement conditions will often require more than a simple “equals” check.
...
| Code Block | ||
|---|---|---|
| ||
{
"description": "This is an ACT managed access requirement used to require that a user has obtained one or more GA4GH Passport Visa Claims in order to access the associated subjects.",
"extends": {
"$ref": "org.sagebionetworks.repo.model.ManagedACTAccessRequirement"
},
"properties": {
"visaConditions": {
"description": "The conditions define how this access requirement matches to each required GA4GH passport visa. Each condition group can contain one or more VisaContions. Conditions within each group are delimited with an 'AND' while each groups are delimited with an 'OR'",
"type": "array",
"items": {
"$ref": "org.sagebionetworks.repo.model.ar.ConditionGroup"
}
}
}
} |
...
| Code Block | ||
|---|---|---|
| ||
{
"description": "A group of one or more VisaConditions.",
"properties": {
"andConditions": {
"description": "A group of one or more visa conditions. Each condition within the group is delimited with an 'AND'.",
"type": "array",
"items": {
"$ref": "org.sagebionetworks.repo.model.ar.VisaCondition"
}
}
}
} |
VisaType.json
| Code Block | ||
|---|---|---|
| ||
{
"description": "Required. The visa type to be matched. Note: Custom types are not supported.",
"type": "string",
"enum": [
{
"name": "AffiliationAndRole"
},
{
"name": "AcceptedTermsAndPolicies"
},
{
"name": "ResearcherStatus"
},
{
"name": "ControlledAccessGrants"
},
{
"name": "LinkedIdentities"
}
]
} |
...
VisaCondition.json
| Code Block | ||
|---|---|---|
| ||
{
"description": "Defines a match to a single GA4GH passport visa. See: <a href=\"https://github.com/ga4gh-duri/ga4gh-duri.github.io/blob/master/researcher_ids/ga4gh_passport_v1.md#conditions\">GA4GH passport conditions</a>",
"properties": {
"type": {
"description": "Required. The visa type to be matched. Note: Custom types are not supported.",
"$ref": "org.sagebionetworks.repo.model.ar.VisaType"
},
"value": {
"description": "Optional. When provided defines an expected 'value' claim.",
"$ref": "org.sagebionetworks.repo.model.ar.MatchTypeValue"
},
"source": {
"description": "Optional. When provided defines an expected 'source' claim.",
"$ref": "org.sagebionetworks.repo.model.ar.MatchTypeValue"
},
"by": {
"description": "Optional. When provided defines an expected 'by' claim.",
"$ref": "org.sagebionetworks.repo.model.ar.MatchTypeValue"
},
"brokerRedirectUrl": {
"description": "The redirect URL of the passport broker that will provide this GA4GH passport visa for an authenticated caller.",
"type": "string"
},
"visaName": {
"description": "The name of the visa to request from the passport broker.",
"type": "string"
}
}
} |
...
MatchTypeValue.json
| Code Block | ||
|---|---|---|
| ||
{
"description": "Defines both the operation and value for matching a single visa claim.",
"properties": {
"type": {
"description": "Required. The type defines how value should be matched to a claim.",
"name": "MatchType",
"type": "string",
"enum": [
{
"name": "const",
"description": "A case sensitive full string match."
},
{
"name": "pattern",
"description": "Supports special meaning characters for matching values. Use '?' to match any single character, and '*' to match multiple characters"
},
{
"name": "split_pattern",
"description": "A pattern match on part of a ';' delimited value."
}
]
},
"value": {
"description": "The value depends on match type. For 'const' a match requires a case sensitive full string match of this value. For 'patterns', use a '?' to match any single character, and '*' to match multiple characters including the empty string and null string.",
"type": "string"
}
}
} |
...
With the new passport AR, a caller will need to acquire one or more GA4GH passport visas from one or more passport broker before they will be permitted to download any file that is the subject of the passport AR.
Note: The caller might have many visas available to them from a passport broker. A broker might ask the caller which visa should be sent to Synapse. For such a case, we need to provide the user with the names of the visas to request from the broker.
...
The GA4GH ‘Data Passports' specification extends the basic OIDC process to enable a passport broker to provide a passport clearinghouse with a passport containing one or more visa claims. See also: ‘AAI OIDC Profile’. Specifically, the access token (also a JWT) provided by the broker, to clearinghouse will include an entry for the caller’s passportpassports.
We propose extending the Synapse OIDC support to not only “login” via a broker but to also capture the broker provided passport in the resulting Synapse access token.
...
Currently, the primary job of the Synapse AuthenticationFilter is to validate a user provided access token in order identify the caller. The filter also passes along the access token as a header that can be read accessed by downstream code such as the OAuthScopeInterceptor. We propose adding a new interceptor for processing visa claims found in the access token. The per-processing would include the following:
Validate signature and expiration of each visa.
Validate the conditional relationship between visas. For example, a via might include a condition such that it is only valid if another visa also exists. For such a case, the dependent visa would be invalid if its dependency were missing.
FinallyAfter validation, the passport visa interceptor would bind the remaining list of valid claims will bind all valid visas to the thread local. The thread local list would be of type:
...
| Code Block |
|---|
DENY_IF_DOES_NOT_EXIST, DENY_IF_IN_TRASH, GRANT_IF_ADMIN, DENY_IF_HAS_UNMET_ACCESS_RESTRICTIONS, DENY_IF_TWO_FA_REQUIREMENT_NOT_MET, GRANT_IF_OPEN_DATA_WITH_READ, DENY_IF_ANONYMOUS, DENY_IF_HAS_NOT_ACCEPTED_TERMS_OF_USE, GRANT_IF_HAS_DOWNLOAD, DENY |
Currently the step at , line:4 DENY_IF_HAS_UNMET_ACCESS_RESTRICTIONS is based on managed AR where the principal must be approved by ACT. This typically involves, checking if the principal has been granted approval for all ARs that have the given file as a subject.
We will need to extend the unmet AR check to look for the new passport AR type. The conditions of each passport AR must then be matched against the passport visa list from principal’s passport visas bound to the thread local. The AR would be treated as ‘met’ if all visas match, and ‘unmet’ if one or more do not match. Note: The visa condition matching system should be the same as the system used to validate visas with conditions in the interceptor layer.