Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix schema, clarify spec (v1.1.0) #31

Merged
merged 2 commits into from
Apr 28, 2024
+481 −378
Merged

Fix schema, clarify spec (v1.1.0) #31

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f2f9a62
Fix schema, clarify spec
m-mohr Apr 27, 2024
75c0e51
Remove PlanetaryComputer and earthdata types (#32)
jamesfisher-geo Apr 28, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 12 additions & 4 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -58,5 +65,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

### Fixed

[Unreleased]: <https://github.com/stac-extensions/authentication/compare/v1.0.0...HEAD>
[Unreleased]: <https://github.com/stac-extensions/authentication/compare/v1.1.0...HEAD>
[v1.1.0]: <https://github.com/stac-extensions/authentication/compare/v1.0.0...v1.1.0>
[v1.0.0]: <https://github.com/stac-extensions/authentication/tree/v1.0.0>
115 changes: 63 additions & 52 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Authentication Extension Specification

- **Title:** Authentication
- **Identifier:** <https://stac-extensions.github.io/authentication/v1.0.0/schema.json>
- **Identifier:** <https://stac-extensions.github.io/authentication/v1.1.0/schema.json>
- **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
Expand Down Expand Up @@ -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<string, [Authentication Flows Object](#authentication-flow-object)> | 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<string, [Parameter Object](#parameter-object)> | 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<string, [OAuth2 Flow Object](#oauth2-flow-object) \| [Signed URL Object](#signed-url-object)>> | `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<string, [Parameter Object](#parameter-object)> | 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": [
Expand All @@ -149,7 +160,7 @@ Definition for a request parameter
]
```

#### Asset reference
### Asset reference

```json
"assets": {
Expand Down
20 changes: 9 additions & 11 deletions examples/collection.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down Expand Up @@ -49,7 +49,7 @@
"type": "signedUrl",
"description": "Requires an authentication API",
"flows": {
"authorizationCode": {
"auth": {
"authorizationApi": "https://example.com/signed_url/authorize",
"method": "POST",
"parameters": {
Expand All @@ -59,7 +59,9 @@
"description": "asset-bucket",
"schema": {
"type": "string",
"examples": "example-bucket"
"examples": [
"example-bucket"
]
}
},
"key": {
Expand All @@ -68,7 +70,9 @@
"description": "asset key",
"schema": {
"type": "string",
"examples": "path/to/example/asset.xyz"
"examples": [
"path/to/example/asset.xyz"
]
}
}
},
Expand Down Expand Up @@ -106,13 +110,7 @@
"datetime": {
"minimum": "2015-06-23T00:00:00Z",
"maximum": "2019-07-10T13:44:56Z"
},
"auth:schemes": [
"none",
"oauth",
"s3",
"signedUrl"
]
}
},
"links": [
{
Expand Down
5 changes: 2 additions & 3 deletions examples/item.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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",
Expand Down Expand Up @@ -59,8 +59,7 @@
"none": {
"type": "http",
"scheme": "basic",
"description": "Free access without restrictions",
"flows": {}
"description": "Free access without restrictions"
}
}
},
Expand Down
Loading
Loading