From f2f9a621178a9dcd8127647c3c0e538b7ad9323a Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Sat, 27 Apr 2024 12:48:48 +0200 Subject: [PATCH 1/2] Fix schema, clarify spec --- CHANGELOG.md | 16 +- README.md | 115 ++++--- examples/collection.json | 20 +- examples/item.json | 5 +- json-schema/schema.json | 692 ++++++++++++++++++++++----------------- package.json | 6 +- 6 files changed, 479 insertions(+), 375 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 8e34ff8..03b2a7f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,15 +6,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] -### Added +## [v1.1.0] - 2023-04-30 ### Changed - Clarify http and extend http authorization methods [#27](https://github.com/stac-extensions/authentication/pull/27) +- Split Authentication Flows Object into OAuth2 Flow Object and Signed URL Object +- The JSON Schema is much stricter compared to before, actually enforcing many restrictions documented in the written spec +- The Parameter Schemas must comply to JSON Schema draft-07 instead of OpenAPI Schema [#21](https://github.com/stac-extensions/authentication/issues/21) -### Deprecated +### Fixed -### Removed +- JSON Schema supports Catalogs +- Fixed various other issues in the JSON Schema +- Clarified which fields apply to which schema type +- Clarified required fields +- Fixed examples ## [v1.0.0] - 2023-11-07 @@ -58,5 +65,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Fixed -[Unreleased]: +[Unreleased]: +[v1.1.0]: [v1.0.0]: diff --git a/README.md b/README.md index 183d00a..c33eab5 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ # Authentication Extension Specification - **Title:** Authentication -- **Identifier:** +- **Identifier:** - **Field Name Prefix:** auth - **Scope:** Catalog, Collection, Item, Asset, Links - **Extension [Maturity Classification](https://github.com/radiantearth/stac-spec/tree/master/extensions/README.md#extension-maturity):** Proposal @@ -67,71 +67,82 @@ included in the scheme type standards below. ### Authentication Scheme Object -The Authentication Scheme aligns with the -[OpenAPI security spec](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#security-scheme-object) for support of OAuth2.0, -API Key, and OpenID authentication. All the [authentication clients](https://github.com/stac-utils/stac-asset#clients) included in the -[stac-asset](https://github.com/stac-utils/stac-asset) library can be described, as well as a custom signed URL authentication scheme. - -| Field Name | Type | Description | -| ------------------ | ------------------------------------------------------------ | ----------- | -| `type` | string | **REQUIRED**. The authentication scheme type used to access the data (`http` \| `s3` \| `planetaryComputer` \| `earthdata` \| `signedUrl` \| `oauth2` \| `apiKey` \| `openIdConnect` \| a custom scheme type ). | -| `description` | string | Additional instructions for authentication. [CommonMark 0.29](https://commonmark.org/) syntax MAY be used for rich text representation. | -| `name` | string | Required for `type: apiKey`. The name of the header, query, or cookie parameter to be used. | -| `in` | string | Required for `type: apiKey`. The location of the API key (`query` \| `header` \| `cookie`). | -| `scheme` | string | Required for `type: http`. The name of the HTTP Authorization scheme to be used in the [Authorization header as defined in RFC7235](https://tools.ietf.org/html/rfc7235#section-5.1). The values used SHOULD be registered in the [IANA Authentication Scheme registry](https://www.iana.org/assignments/http-authschemes/http-authschemes.xhtml). (`basic` \| `bearer` \| `digest` \| `dpop` \| `hoba` \| `mutual` \| `negotiate` \| `oauth` (1.0) \| `privatetoken` \| `scram-sha-1` \| `scram-sha-256` \| `vapid`) | -| `flows` | Map | Required for `type: oauth2` and `type: signedUrl`. Scenarios an API client performs to get an access token from the authorization server (`authorizationCode` \| `implicit` \| `password ` \| `clientCredentials`) | -| `openIdConnectUrl` | string | Required for `type: openIdConnectUrl`. OpenID Connect URL to discover OAuth2 configuration values. This MUST be in the form of a URL. | - -### Authentication Flow Object - -[OpenAPI OAuth Flow Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#oauth-flows-object). Allows configuration of -the supported OAuth Flows. - -Configuration details for a supported OAuth Flow - -| Field Name | Type | Description | -| ------------------ | -------------------------------------------------- | ----------- | -| `authorizationUrl` | `string` | Required for `oauth2` (`"implicit"`, `"authorizationCode"`). The authorization URL to be used for this flow. This MUST be in the form of a URL. | -| `tokenUrl` | `string` | Required for `oauth2` (`"password"`, `"clientCredentials"`, `"authorizationCode"`). The token URL to be used for this flow. This MUST be in the form of a URL. | -| `authorizationApi` | `string` | Optional for `signedUrl`. The signed URL API endpoint to be used for this flow. If not enferred from the client environment, this must be defined in the authentication flow. | -| `refreshUrl` | `string` | Optional for `oauth2`. The URL to be used for obtaining refresh tokens. This MUST be in the form of a URL. | -| `scopes` | Map<`string`, `string`> | Required for `oauth2`. The available scopes for the authentication scheme. A map between the scope name and a short description for it. The map MAY be empty. | -| `method` | `string` | Required for `signedUrl`. The method to be used for requests | -| `parameters` | Map | Optional for `signedUrl`. Parameter definition for requests to the `authorizationApi` | -| `responseField` | string | Optional for `signedUrl`. Key name for the signed URL field in an authorizationApi response | +The Authentication Scheme extends the +[OpenAPI security spec](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#security-scheme-object) +for support of OAuth2.0, API Key, and OpenID Connect authentication. +All the [authentication clients](https://github.com/stac-utils/stac-asset#clients) included in the +[stac-asset](https://github.com/stac-utils/stac-asset) +library can be described, as well as a custom signed URL authentication scheme. + +| Field Name | Type | Applies to | Description | +| ------------------ | ------------------------------------------------------------ | --------------------- | ------------------------------------------------------------ | +| `type` | string | *All* | **REQUIRED**. The authentication scheme type used to access the data (`http` \| `s3` \| `planetaryComputer` \| `earthdata` \| `signedUrl` \| `oauth2` \| `apiKey` \| `openIdConnect` \| a custom scheme type ). | +| `description` | string | *All* | Additional instructions for authentication. [CommonMark 0.29](https://commonmark.org/) syntax MAY be used for rich text representation. | +| `name` | string | `apiKey` | **REQUIRED.** The name of the header, query, or cookie parameter to be used. | +| `in` | string | `apiKey` | **REQUIRED.** The location of the API key (`query` \| `header` \| `cookie`). | +| `scheme` | string | `http` | **REQUIRED.** The name of the HTTP Authorization scheme to be used in the [Authorization header as defined in RFC7235](https://tools.ietf.org/html/rfc7235#section-5.1). The values used SHOULD be registered in the [IANA Authentication Scheme registry](https://www.iana.org/assignments/http-authschemes/http-authschemes.xhtml). (`basic` \| `bearer` \| `digest` \| `dpop` \| `hoba` \| `mutual` \| `negotiate` \| `oauth` (1.0) \| `privatetoken` \| `scram-sha-1` \| `scram-sha-256` \| `vapid`) | +| `flows` | Map> | `oauth2`, `signedUrl` | **REQUIRED.** Scenarios an API client performs to get an access token from the authorization server. For `oauth2` the following keys are pre-defined for the corresponding OAuth flows: `authorizationCode` \| `implicit` \| `password ` \| `clientCredentials`. The OAuth2 Flow Object applies for `oauth2`, the Signed URL Object applies to `signedUrl`. | +| `openIdConnectUrl` | string | `openIdConnect` | **REQUIRED.** OpenID Connect URL to discover OpenID configuration values. This MUST be in the form of a URL. | + +The column "Applies to" specifies for which values of `type` the fields only apply. +They are also only required in this context. + +### OAuth2 Flow Object + +Based on the [OpenAPI OAuth Flow Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#oauth-flows-object). +Allows configuration of the supported OAuth Flows. + +| Field Name | Type | Description | +| ------------------ | ----------------------- | ------------------------------------------------------------ | +| `authorizationUrl` | `string` | **REQUIRED** for parent keys: `"implicit"`, `"authorizationCode"`. The authorization URL to be used for this flow. This MUST be in the form of a URL. | +| `tokenUrl` | `string` | **REQUIRED** for parent keys: `"password"`, `"clientCredentials"`, `"authorizationCode"`. The token URL to be used for sthis flow. This MUST be in the form of a URL. | +| `scopes` | Map<`string`, `string`> | **REQUIRED.** The available scopes for the authentication scheme. A map between the scope name and a short description for it. The map MAY be empty. | +| `refreshUrl` | `string` | The URL to be used for obtaining refresh tokens. This MUST be in the form of a URL. | + +### Signed URL Object + +Based on the [OpenAPI OAuth Flow Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#oauth-flows-object). +Allows configuration of the supported OAuth Flows. + +| Field Name | Type | Description | +| ------------------ | -------------------------------------------------- | ------------------------------------------------------------ | +| `method` | `string` | **REQUIRED.** The method to be used for requests | +| `authorizationApi` | `string` | **REQUIRED.** The signed URL API endpoint to be used for this flow. If not inferred from the client environment, this must be defined in the authentication flow. | +| `parameters` | Map | Parameter definition for requests to the `authorizationApi` | +| `responseField` | string | Key name for the signed URL field in an `authorizationApi` response | ### Parameter Object -Definition for a request parameter +Definition for a request parameter. -| Field Name | Type | Description | -| ------------- | --------- | ----------- | -| `in` | `string` | The location of the parameter (`query` \| `header` \| `body`). | -| `required` | `boolean` | Setting for optional or required parameter | -| `description` | `string` | Optional. Plain language description of the parameter | -| `schema` | `object` | Optional. Schema object following the [OpenAPI extended subset](https://swagger.io/docs/specification/data-models/) of the [JSON Schema spec](https://json-schema.org/) | +| Field Name | Type | Description | +| ------------- | --------- | ------------------------------------------------------------ | +| `in` | `string` | **REQUIRED.** The location of the parameter (`query` \| `header` \| `body`). | +| `required` | `boolean` | **REQUIRED.** Setting for optional or required parameter. | +| `description` | `string` | Plain language description of the parameter | +| `schema` | `object` | Schema object following the [JSON Schema draft-07](https://json-schema.org/) | -### Examples +## Examples `auth:schemes` may be referenced identically in a STAC Asset or Link objects. Examples of these two use-cases are provided below. -#### Schema definitions +### Schema definitions ```json "auth:schemes": { - "oauth": { - "type": "oauth2", - "description": "requires a login and user token", - "flows": { - "authorizationUrl": "https://example.com/oauth/authorize", - "tokenUrl": "https://example.com/oauth/token", - "scopes": {} - } + "oauth": { + "type": "oauth2", + "description": "requires a login and user token", + "flows": { + "authorizationUrl": "https://example.com/oauth/authorize", + "tokenUrl": "https://example.com/oauth/token", + "scopes": {} } } +} ``` -#### Links reference +### Links reference ```json "links": [ @@ -149,7 +160,7 @@ Definition for a request parameter ] ``` -#### Asset reference +### Asset reference ```json "assets": { diff --git a/examples/collection.json b/examples/collection.json index 6f11bd9..42d8352 100644 --- a/examples/collection.json +++ b/examples/collection.json @@ -2,7 +2,7 @@ "stac_version": "1.0.0", "stac_extensions": [ "https://stac-extensions.github.io/item-assets/v1.0.0/schema.json", - "https://stac-extensions.github.io/authentication/v1.0.0/schema.json" + "https://stac-extensions.github.io/authentication/v1.1.0/schema.json" ], "type": "Collection", "id": "collection", @@ -49,7 +49,7 @@ "type": "signedUrl", "description": "Requires an authentication API", "flows": { - "authorizationCode": { + "auth": { "authorizationApi": "https://example.com/signed_url/authorize", "method": "POST", "parameters": { @@ -59,7 +59,9 @@ "description": "asset-bucket", "schema": { "type": "string", - "examples": "example-bucket" + "examples": [ + "example-bucket" + ] } }, "key": { @@ -68,7 +70,9 @@ "description": "asset key", "schema": { "type": "string", - "examples": "path/to/example/asset.xyz" + "examples": [ + "path/to/example/asset.xyz" + ] } } }, @@ -106,13 +110,7 @@ "datetime": { "minimum": "2015-06-23T00:00:00Z", "maximum": "2019-07-10T13:44:56Z" - }, - "auth:schemes": [ - "none", - "oauth", - "s3", - "signedUrl" - ] + } }, "links": [ { diff --git a/examples/item.json b/examples/item.json index e42b908..5e189e1 100644 --- a/examples/item.json +++ b/examples/item.json @@ -1,7 +1,7 @@ { "stac_version": "1.0.0", "stac_extensions": [ - "https://stac-extensions.github.io/authentication/v1.0.0/schema.json" + "https://stac-extensions.github.io/authentication/v1.1.0/schema.json" ], "type": "Feature", "id": "item", @@ -59,8 +59,7 @@ "none": { "type": "http", "scheme": "basic", - "description": "Free access without restrictions", - "flows": {} + "description": "Free access without restrictions" } } }, diff --git a/json-schema/schema.json b/json-schema/schema.json index df21bf0..4908942 100644 --- a/json-schema/schema.json +++ b/json-schema/schema.json @@ -1,365 +1,453 @@ { "$schema": "http://json-schema.org/draft-07/schema#", - "$id": "https://stac-extensions.github.io/authentication/v1.0.0/schema.json#", + "$id": "https://stac-extensions.github.io/authentication/v1.1.0/schema.json", "title": "Authentication Extension", "description": "STAC Authentication Extension for STAC Catalogs, STAC Collections, STAC Items, STAC Assets, and STAC Links.", + "type": "object", + "required": [ + "stac_extensions" + ], + "properties": { + "stac_extensions": { + "type": "array", + "contains": { + "const": "https://stac-extensions.github.io/authentication/v1.1.0/schema.json" + } + } + }, "oneOf": [ { "$comment": "This is the schema for STAC Items.", + "type": "object", + "required": [ + "type", + "properties" + ], + "properties": { + "type": { + "const": "Feature" + }, + "properties": { + "$ref": "#/definitions/schemes_field" + }, + "assets": { + "$ref": "#/definitions/assets" + }, + "links": { + "$ref": "#/definitions/links" + } + } + }, + { + "$comment": "This is the schema for STAC Collections", + "type": "object", + "required": [ + "type" + ], + "properties": { + "type": { + "const": "Collection" + }, + "assets": { + "$ref": "#/definitions/assets" + }, + "item_assets": { + "$ref": "#/definitions/assets" + }, + "links": { + "$ref": "#/definitions/links" + } + }, "allOf": [ { - "$ref": "#/definitions/stac_extensions" + "$ref": "#/definitions/schemes_field" + } + ] + }, + { + "$comment": "This is the schema for STAC Catalogs", + "type": "object", + "required": [ + "type" + ], + "properties": { + "type": { + "const": "Catalog" }, + "links": { + "$ref": "#/definitions/links" + } + }, + "allOf": [ { + "$ref": "#/definitions/schemes_field" + } + ] + } + ], + "definitions": { + "schemes_field": { + "type": "object", + "required": [ + "auth:schemes" + ], + "properties": { + "auth:schemes": { "type": "object", - "required": [ - "type", - "properties", - "assets", - "links" - ], - "properties": { - "type": { - "const": "Feature" - }, - "properties": { - "allOf": [ - { - "$comment": "Require fields here for Item Properties.", - "required": [ - "auth:schemes" - ] - }, - { - "$ref": "#/definitions/fields" - } - ] - }, - "assets": { - "$comment": "This validates the fields in Item Assets, but does not require them.", - "type": "object", - "additionalProperties": { - "$ref": "#/definitions/fields" - } + "patternProperties": { + "^.*$": { + "$ref": "#/definitions/auth_scheme" } }, - "links": { - "type": "array", - "items": { - "if": { - "$ref": "#/definitions/authLink" - }, - "then": { - "properties": { - "auth:refs": { - "$ref": "#/definitions/fields/properties/auth:refs" - } - } - }, - "else": { - } - } - }, - "contains": { - "$ref": "#/definitions/authLink" - } + "additionalProperties": false } - ] + }, + "patternProperties": { + "^(?!auth:)": {} + }, + "additionalProperties": false }, - { - "$comment": "This is the schema for STAC Collections.", + "refs_field": { "type": "object", - "allOf": [ - { - "required": [ - "type" - ], - "properties": { - "type": { - "const": "Collection" + "properties": { + "auth:refs": { + "type": "array", + "items": { + "type": "string" + } + } + }, + "patternProperties": { + "^(?!auth:)": {} + }, + "additionalProperties": false + }, + "assets": { + "type": "object", + "additionalProperties": { + "allOf": [ + { + "$ref": "#/definitions/refs_field" + }, + { + "type": "object", + "properties": { + "alternate": { + "$ref": "#/definitions/refs_field" + } } } + ] + } + }, + "links": { + "type": "array", + "items": { + "$ref": "#/definitions/refs_field" + } + }, + "auth_scheme": { + "required": [ + "type" + ], + "properties": { + "type": { + "title": "Scheme keyword", + "type": "string", + "examples": [ + "http", + "s3", + "planetaryComputer", + "earthdata", + "signedUrl", + "oauth2", + "apiKey", + "openIdConnect" + ] }, - { - "$ref": "#/definitions/stac_extensions" + "description": { + "title": "Authentication scheme description", + "type": "string" } - ], - "anyOf": [ + }, + "allOf": [ { - "$comment": "This is the schema for the top-level fields in a Collection.", - "allOf": [ - { - "$comment": "Require fields here for Collections (top-level).", - "required": [ - "auth:schemes" - ] - }, - { - "$ref": "#/definitions/fields" + "if": { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "apiKey" + } } - ] + }, + "then": { + "type": "object", + "required": [ + "name", + "in" + ], + "properties": { + "name": { + "title": "API Key header, query, or cookie parameter name", + "type": "string", + "examples": [ + "x-api-key" + ] + }, + "in": { + "title": "Location of the API Key", + "type": "string", + "examples": [ + "query", + "header", + "cookie" + ] + } + } + }, + "else": { + "type": "object", + "properties": { + "name": false, + "in": false + } + } }, { - "$comment": "This validates the fields in Collection Assets, but does not require them.", - "required": [ - "assets" - ], - "properties": { - "assets": { - "type": "object", - "not": { - "additionalProperties": { - "not": { - "allOf": [ - { - "$ref": "#/definitions/require_any_field" - }, - { - "$ref": "#/definitions/fields" - } - ] - } - } + "if": { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "http" } - }, - "links": { - "type": "array", - "items": { - "if": { - "$ref": "#/definitions/authLink" - }, - "then": { - "properties": { - "auth:refs": { - "$ref": "#/definitions/fields/properties/auth:refs" - } - } - }, - "else": { - } - }, - "contains": { - "$ref": "#/definitions/authLink" + } + }, + "then": { + "type": "object", + "required": [ + "scheme" + ], + "properties": { + "scheme": { + "title": "Name of the http authentication scheme", + "type": "string", + "examples": [ + "basic", + "bearer", + "digest", + "dpop", + "hoba", + "mutual", + "negotiate", + "oauth", + "privatetoken", + "scram-sha-1", + "scram-sha-256", + "vapid" + ] } } + }, + "else": { + "type": "object", + "properties": { + "scheme": false + } } }, { - "$comment": "This is the schema for the fields in Item Asset Definitions. It doesn't require any fields.", - "required": [ - "item_assets" - ], - "properties": { - "item_assets": { + "if": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "oauth2", + "signedUrl" + ] + } + } + }, + "then": { + "type": "object", + "required": [ + "flows" + ], + "if": { "type": "object", - "not": { - "additionalProperties": { - "not": { - "allOf": [ - { - "$ref": "#/definitions/require_any_field" - }, - { - "$ref": "#/definitions/fields" + "properties": { + "type": { + "type": "string", + "const": "oauth2" + } + } + }, + "then": { + "type": "object", + "title": "OAuth2 Flows", + "properties": { + "flows": { + "additionalProperties": { + "$ref": "#/definitions/oauth2_flow" + }, + "allOf": [ + { + "patternProperties": { + "^(implicit|authorizationCode)*$": { + "required": [ + "authorizationUrl" + ] + }, + "^(password|clientCredentials|authorizationCode)*$": { + "required": [ + "tokenUrl" + ] + } } - ] + } + ] + } + } + }, + "else": { + "type": "object", + "title": "Signed URL", + "properties": { + "flows": { + "additionalProperties": { + "$ref": "#/definitions/signed_url_flow" } } } } + }, + "else": { + "type": "object", + "properties": { + "flows": false + } } }, { - "$comment": "This is the schema for the fields in Summaries. By default, only checks the existence of the properties, but not the schema of the summaries.", - "required": [ - "summaries" - ], - "properties": { - "summaries": { - "$ref": "#/definitions/require_any_field" + "if": { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "openIdConnectUrl" + } + } + }, + "then": { + "type": "object", + "required": [ + "openIdConnectUrl" + ], + "properties": { + "openIdConnectUrl": { + "title": "This URL returns a JSON listing of the OpenID/OAuth endpoints, supported scopes and claims, public keys used to sign the tokens, and other details", + "type": "string" + } + } + }, + "else": { + "type": "object", + "properties": { + "openIdConnectUrl": false } } } ] - } - ], - "definitions": { - "stac_extensions": { + }, + "oauth2_flow": { "type": "object", "required": [ - "stac_extensions" + "scopes" ], "properties": { - "stac_extensions": { - "type": "array", - "contains": { - "const": "https://stac-extensions.github.io/authentication/v1.0.0/schema.json" + "authorizationUrl": { + "title": "The authorization URL to be used", + "type": "string", + "format": "uri" + }, + "tokenUrl": { + "title": "The token URL to be used", + "type": "string", + "format": "uri" + }, + "refreshUrl": { + "title": "The URL to be used for obtaining refresh tokens", + "type": "string", + "format": "uri" + }, + "scopes": { + "title": "The available scopes for the authentication scheme", + "type": "object", + "additionalProperties": { + "type": "string" } } } }, - "require_any_field": { - "$comment": "Please list all fields here so that we can force the existence of one of them in other parts of the schemas.", - "anyOf": [ - { - "required": [ - "auth:schemes" - ] - } - ] - }, - "authLink": { + "signed_url_flow": { "type": "object", "required": [ - "rel" + "method", + "authorizationApi" ], "properties": { - "rel": { - "const": "auth" - } - } - }, - "fields": { - "$comment": "Add your new fields here. Don't require them here, do that above in the corresponding schema.", - "type": "object", - "properties": { - "auth:refs": { - "type": "array", - "items": { - "type": "string" - } + "authorizationApi": { + "title": "The signed URL API endpoint to be used", + "type": "string", + "format": "uri" }, - "auth:schemes": { - "type": "object", - "properties": { - "type": { - "title": "Scheme keyword", - "type": "string", - "examples": [ - "http", - "s3", - "planetaryComputer", - "earthdata", - "signedUrl", - "oauth2", - "apiKey", - "openIdConnect" - ] - }, - "description": { - "title": "Authentication scheme description", - "type": "string" - }, - "name": { - "title": "API Key header, query, or cookie parameter name", - "type": "string", - "examples": [ - "x-api-key" - ] - }, - "in": { - "title": "Location of the API Key", - "type": "string", - "examples": [ - "query", - "header", - "cookie" - ] - }, - "scheme": { - "title": "Name of the http authentication scheme", - "type": "string", - "examples": [ - "basic", - "bearer", - "digest", - "dpop", - "hoba", - "mutual", - "negotiate", - "oauth", - "privatetoken", - "scram-sha-1", - "scram-sha-256", - "vapid" - ] - }, - "openConnectUrl": { - "title": "This URL returns a JSON listing of the OpenID/OAuth endpoints, supported scopes and claims, public keys used to sign the tokens, and other details", - "type": "string" - }, - "flows": { - "title": "Scenarios an API client performs to get an access token from the authorization server", - "type": "object", - "properties": { - "authorizationUrl": { - "title": "The authorization URL to be used", - "type": "string" - }, - "tokenUrl": { - "title": "The token URL to be used", - "type": "string" - }, - "authorizationApi": { - "title": "The signed URL API endpoint to be used", - "type": "string" - }, - "refreshUrl": { - "title": "The URL to be used for obtaining refresh tokens", - "type": "string" - }, - "scopes": { - "title": "The available scopes for the authentication scheme", - "type": "object" - }, - "method": { - "title": "HTTP request method", - "type": "string", - "examples": [ - "POST", - "GET" - ] - }, - "responseField": { - "title": "Key name for the signed URL field in an authorizationApi response", - "type": "string" - }, - "parameters": { - "title": "Parameter definitions for requests to the authorizationApi", - "type": "object", - "properties": { - "in": { - "title": "Location of the parameter", - "type": "string", - "examples": [ - "query", - "header", - "body" - ] - }, - "required": { - "title": "Setting for optional or required parameter", - "type": "boolean" - }, - "description": { - "title": "Plain language description of the parameter", - "type": "string" - }, - "schema": { - "title": "Schema object following the OpenAPI extended subset of the JSON Schema spec", - "type": "object" - } - } - } + "method": { + "title": "HTTP request method", + "type": "string", + "examples": [ + "POST", + "GET" + ] + }, + "responseField": { + "title": "Key name for the signed URL field in an authorizationApi response", + "type": "string" + }, + "parameters": { + "title": "Parameter definitions for requests to the authorizationApi", + "additionalProperties": { + "type": "object", + "required": [ + "in", + "required" + ], + "properties": { + "in": { + "title": "Location of the parameter", + "type": "string", + "examples": [ + "query", + "header", + "body" + ] + }, + "required": { + "title": "Setting for optional or required parameter", + "type": "boolean" + }, + "description": { + "title": "Plain language description of the parameter", + "type": "string" + }, + "schema": { + "$ref": "http://json-schema.org/draft-07/schema" } } } } - }, - "patternProperties": { - "^(?!auth:)": {} - }, - "additionalProperties": false + } } } -} \ No newline at end of file +} diff --git a/package.json b/package.json index b20d5db..953cee9 100644 --- a/package.json +++ b/package.json @@ -1,11 +1,11 @@ { "name": "stac-extensions", - "version": "1.0.0", + "version": "1.1.0", "scripts": { "test": "npm run check-markdown && npm run check-examples", "check-markdown": "remark . -f -r .github/remark.yaml", - "check-examples": "stac-node-validator . --lint --verbose --schemaMap https://stac-extensions.github.io/authentication/v1.0.0/schema.json=./json-schema/schema.json", - "format-examples": "stac-node-validator . --format --schemaMap https://stac-extensions.github.io/authentication/v1.0.0/schema.json=./json-schema/schema.json" + "check-examples": "stac-node-validator . --lint --verbose --schemaMap https://stac-extensions.github.io/authentication/v1.1.0/schema.json=./json-schema/schema.json", + "format-examples": "stac-node-validator . --format --schemaMap https://stac-extensions.github.io/authentication/v1.1.0/schema.json=./json-schema/schema.json" }, "dependencies": { "remark-cli": "^8.0.0", From 75c0e51e54f10685e2931eed00f170658ae6f227 Mon Sep 17 00:00:00 2001 From: James Fisher <85769594+jamesfisher-gis@users.noreply.github.com> Date: Sun, 28 Apr 2024 17:21:20 -0400 Subject: [PATCH 2/2] Remove PlanetaryComputer and earthdata types (#32) --- CHANGELOG.md | 4 ++++ README.md | 7 ++----- json-schema/schema.json | 2 -- 3 files changed, 6 insertions(+), 7 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 03b2a7f..963b9f3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -23,6 +23,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Clarified required fields - Fixed examples +### Removed + +- Removed the provider-specific `planetaryComputer` and `earthdata` scheme types [#32](https://github.com/stac-extensions/authentication/pull/32) + ## [v1.0.0] - 2023-11-07 ### Added diff --git a/README.md b/README.md index c33eab5..12431a7 100644 --- a/README.md +++ b/README.md @@ -58,8 +58,6 @@ included in the scheme type standards below. | ------------------- | ----------- | | `http` | Simple HTTP authentication mechanisms (Basic, Bearer, Digest, etc.). | | `s3` | Simple S3 authentication. | -| `planetaryComputer` | Signs URLs with the [Planetary Computer Authentication API](https://planetarycomputer.microsoft.com/docs/reference/sas/) | -| `earthdata` | Uses a token-based authentication to download data, from *some* Earthdata providers, e.g. DAACs | | `signedUrl` | Signs URLs with a user-defined authentication API. | | `oauth2` | [Open Authentication 2.0](https://swagger.io/docs/specification/authentication/oauth2/) configuration | | `apiKey` | Description of [API key](https://swagger.io/docs/specification/authentication/api-keys/) authentication included in request headers, query parameters, or cookies. | @@ -76,7 +74,7 @@ library can be described, as well as a custom signed URL authentication scheme. | Field Name | Type | Applies to | Description | | ------------------ | ------------------------------------------------------------ | --------------------- | ------------------------------------------------------------ | -| `type` | string | *All* | **REQUIRED**. The authentication scheme type used to access the data (`http` \| `s3` \| `planetaryComputer` \| `earthdata` \| `signedUrl` \| `oauth2` \| `apiKey` \| `openIdConnect` \| a custom scheme type ). | +| `type` | string | *All* | **REQUIRED**. The authentication scheme type used to access the data (`http` \| `s3` \| `signedUrl` \| `oauth2` \| `apiKey` \| `openIdConnect` \| a custom scheme type ). | | `description` | string | *All* | Additional instructions for authentication. [CommonMark 0.29](https://commonmark.org/) syntax MAY be used for rich text representation. | | `name` | string | `apiKey` | **REQUIRED.** The name of the header, query, or cookie parameter to be used. | | `in` | string | `apiKey` | **REQUIRED.** The location of the API key (`query` \| `header` \| `cookie`). | @@ -310,8 +308,7 @@ Promise( ### Planetary Computer URL Signing -Planetary Computer uses the same signed URL pattern described above. Here is an example of how to configure an `auth:scheme` with instructions on -how to sign URLs with the [Planetary Computer Data Authentication API](https://planetarycomputer.microsoft.com/docs/reference/sas/) +Planetary Computer uses the same signed URL pattern described above. Here is an example of how to configure a `signedUrl` `auth:scheme` for the [Planetary Computer Data Authentication API](https://planetarycomputer.microsoft.com/docs/reference/sas/) ```json "auth:schemes": { diff --git a/json-schema/schema.json b/json-schema/schema.json index 4908942..395f1a7 100644 --- a/json-schema/schema.json +++ b/json-schema/schema.json @@ -157,8 +157,6 @@ "examples": [ "http", "s3", - "planetaryComputer", - "earthdata", "signedUrl", "oauth2", "apiKey",