Skip to content

Commit

Permalink
Fix schema, clarify spec
Browse files Browse the repository at this point in the history
  • Loading branch information
@m-mohr
m-mohr committed Apr 27, 2024
1 parent 3cb217b commit f2f9a62
Show file tree
Hide file tree
Showing 6 changed files with 479 additions and 375 deletions.
16 changes: 12 additions & 4 deletions CHANGELOG.md
View file
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
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
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
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

0 comments on commit f2f9a62

Please sign in to comment.