diff --git a/docs/asciidoc/front_matter.adoc b/docs/asciidoc/front_matter.adoc index dccbbd740..573ddf03a 100644 --- a/docs/asciidoc/front_matter.adoc +++ b/docs/asciidoc/front_matter.adoc @@ -34,8 +34,27 @@ For convenience, we define a recommended syntax for fully referencing DRS-access The DRS API specification is written in OpenAPI and embodies a RESTful service philosophy. It uses JSON in requests and responses and standard HTTP/HTTPS for information transport. -== Authorization & Authentication (WORK IN PROGRESS) - -Users must supply credentials that establish their identity and authorization in order to use a DRS endpoint. We recommend that DRS implementations use an OAuth2 https://oauth.net/2/bearer-tokens/[bearer token], although they can choose other mechanisms if appropriate. DRS callers can use the `auth_instructions_url` from the https://ga4gh.github.io/data-repository-service-schemas/#/DataRepositoryService/GetServiceInfo[service-info endpoint] to learn how to obtain and use a bearer token for a particular implementation. - -The DRS implementation is responsible for checking that a user is authorized to submit requests. The particular authorization policy is up to the DRS implementer. +== Authorization & Authentication + +=== Making DRS Requests + +The DRS implementation is responsible for defining and enforcing an authorization policy that determines which users are allowed to make which requests. We recommend that DRS implementations use an OAuth2 https://oauth.net/2/bearer-tokens/[bearer token], although they can choose other mechanisms if appropriate. DRS callers can use the `auth_instructions_url` from the https://ga4gh.github.io/data-repository-service-schemas/#/DataRepositoryService/GetServiceInfo[service-info endpoint] to learn how to obtain and use a bearer token for a particular implementation. + +=== Fetching DRS Objects + +The DRS API allows implementers to support a variety of different content access policies, depending on what `AccessMethod` s they return: + +* public content: +** server provides an `access_url` with a `url` and no `headers` +** caller fetches the object bytes without providing any auth info +* private content that requires the caller to have out-of-band auth knowledge (e.g. service account credentials): +** server provides an `access_url` with a `url` and no `headers` +** caller fetches the object bytes, passing the auth info they obtained out-of-band +* private content that requires the caller to pass an Authorization token: +** server provides an `access_url` with a `url` and `headers` +** caller fetches the object bytes, passing auth info via the specified header(s) +* private content that uses an expensive-to-generate auth mechanism (e.g. a signed URL): +** server provides an `access_id` +** caller passes the `access_id` to the `/access` endpoint +** server provides an `access_url` with the generated mechanism (e.g. a signed URL in the `url` field) +** caller fetches the object bytes from the `url` (passing auth info from the specified headers, if any) diff --git a/openapi/data_repository_service.swagger.yaml b/openapi/data_repository_service.swagger.yaml index da273d769..d5aec8c66 100644 --- a/openapi/data_repository_service.swagger.yaml +++ b/openapi/data_repository_service.swagger.yaml @@ -24,7 +24,9 @@ security: paths: '/service-info': get: - summary: Returns service version and other information + summary: Get information about this implementation. + description: >- + May return service version and other information. operationId: GetServiceInfo responses: '200': @@ -73,7 +75,9 @@ paths: x-swagger-router-controller: ga4gh.drs.server '/objects/{object_id}': get: - summary: Retrieve a Data Object + summary: Get info about a Data Object. + description: >- + Returns object metadata, and a list of access methods that can be used to fetch object bytes. operationId: GetObject responses: '200': @@ -110,7 +114,9 @@ paths: x-swagger-router-controller: ga4gh.drs.server '/objects/{object_id}/access/{access_id}': get: - summary: Returns a fully resolvable URL that can be used to fetch the actual object bytes. + summary: Get a URL for fetching bytes. + description: >- + Returns a fully resolvable URL that can be used to fetch the actual object bytes. operationId: GetAccessURL responses: '200': @@ -146,7 +152,7 @@ paths: in: path required: true type: string - description: An 'access_id' from 'access_methods' list of a Data Object + description: An `access_id` from the `access_methods` list of a Data Object tags: - DataRepositoryService x-swagger-router-controller: ga4gh.drs.server @@ -308,14 +314,22 @@ definitions: These aliases can be used to represent the Data Object's location in a directory (e.g. "bucket/folder/file.name") to make Data Objects more discoverable. They might also be used to represent - AccessURL: type: object - required: ['access_url'] + required: ['url'] properties: - access_url: + url: type: string - description: A fully resolvable access_url that can be used to fetch the actual object bytes. + description: A fully resolvable URL that can be used to fetch the actual object bytes. + headers: + type: array + items: + type: string + description: >- + An optional list of headers to include in the HTTP request to `url`. + These headers can be used to provide auth tokens required to fetch the object bytes. + example: + Authorization: Basic Z2E0Z2g6ZHJz AccessMethod: type: object required: @@ -338,20 +352,19 @@ definitions: description: >- Type of the access method. access_url: - type: string + $ref: '#/definitions/AccessURL' description: >- - A fully resolvable URL string that can be used to fetch the actual object bytes. - Note that at least one of access_url and access_id must be provided. + An `AccessURL` that can be used to fetch the actual object bytes. + Note that at least one of `access_url` and `access_id` must be provided. access_id: type: string description: >- - An arbitrary string to be passed to the /access path to fetch an access_url. + An arbitrary string to be passed to the /access path to get an `AccessURL`. This must be unique per object. - Note that at least one of access_url and access_id must be provided. + Note that at least one of `access_url` and `access_id` must be provided. region: type: string description: >- - OPTIONAL Name of the region in the cloud service provider that the object belongs to. example: us-east-1