Skip to content

Commit 9fa7094

Browse files
m-mohrm-mohr
authoredApr 28, 2024
Merge pull request #31 from stac-extensions/v1.1.0
Fix schema, clarify spec (v1.1.0)
2 parents 3cb217b + 75c0e51 commit 9fa7094

File tree

6 files changed

+481
-378
lines changed

6 files changed

+481
-378
lines changed
 

‎CHANGELOG.md

+15-3
Original file line numberDiff line numberDiff line change
@@ -6,16 +6,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
66

77
## [Unreleased]
88

9-
### Added
9+
## [v1.1.0] - 2023-04-30
1010

1111
### Changed
1212

1313
- Clarify http and extend http authorization methods [#27](https://github.com/stac-extensions/authentication/pull/27)
14+
- Split Authentication Flows Object into OAuth2 Flow Object and Signed URL Object
15+
- The JSON Schema is much stricter compared to before, actually enforcing many restrictions documented in the written spec
16+
- The Parameter Schemas must comply to JSON Schema draft-07 instead of OpenAPI Schema [#21](https://github.com/stac-extensions/authentication/issues/21)
1417

15-
### Deprecated
18+
### Fixed
19+
20+
- JSON Schema supports Catalogs
21+
- Fixed various other issues in the JSON Schema
22+
- Clarified which fields apply to which schema type
23+
- Clarified required fields
24+
- Fixed examples
1625

1726
### Removed
1827

28+
- Removed the provider-specific `planetaryComputer` and `earthdata` scheme types [#32](https://github.com/stac-extensions/authentication/pull/32)
29+
1930
## [v1.0.0] - 2023-11-07
2031

2132
### Added
@@ -58,5 +69,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
5869

5970
### Fixed
6071

61-
[Unreleased]: <https://github.com/stac-extensions/authentication/compare/v1.0.0...HEAD>
72+
[Unreleased]: <https://github.com/stac-extensions/authentication/compare/v1.1.0...HEAD>
73+
[v1.1.0]: <https://github.com/stac-extensions/authentication/compare/v1.0.0...v1.1.0>
6274
[v1.0.0]: <https://github.com/stac-extensions/authentication/tree/v1.0.0>

‎README.md

+64-56
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
# Authentication Extension Specification
22

33
- **Title:** Authentication
4-
- **Identifier:** <https://stac-extensions.github.io/authentication/v1.0.0/schema.json>
4+
- **Identifier:** <https://stac-extensions.github.io/authentication/v1.1.0/schema.json>
55
- **Field Name Prefix:** auth
66
- **Scope:** Catalog, Collection, Item, Asset, Links
77
- **Extension [Maturity Classification](https://github.com/radiantearth/stac-spec/tree/master/extensions/README.md#extension-maturity):** Proposal
@@ -58,80 +58,89 @@ included in the scheme type standards below.
5858
| ------------------- | ----------- |
5959
| `http` | Simple HTTP authentication mechanisms (Basic, Bearer, Digest, etc.). |
6060
| `s3` | Simple S3 authentication. |
61-
| `planetaryComputer` | Signs URLs with the [Planetary Computer Authentication API](https://planetarycomputer.microsoft.com/docs/reference/sas/) |
62-
| `earthdata` | Uses a token-based authentication to download data, from *some* Earthdata providers, e.g. DAACs |
6361
| `signedUrl` | Signs URLs with a user-defined authentication API. |
6462
| `oauth2` | [Open Authentication 2.0](https://swagger.io/docs/specification/authentication/oauth2/) configuration |
6563
| `apiKey` | Description of [API key](https://swagger.io/docs/specification/authentication/api-keys/) authentication included in request headers, query parameters, or cookies. |
6664
| `openIdConnect` | Description of [OpenID Connect Discovery](https://swagger.io/docs/specification/authentication/openid-connect-discovery/) authentication |
6765

6866
### Authentication Scheme Object
6967

70-
The Authentication Scheme aligns with the
71-
[OpenAPI security spec](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#security-scheme-object) for support of OAuth2.0,
72-
API Key, and OpenID authentication. All the [authentication clients](https://github.com/stac-utils/stac-asset#clients) included in the
73-
[stac-asset](https://github.com/stac-utils/stac-asset) library can be described, as well as a custom signed URL authentication scheme.
74-
75-
| Field Name | Type | Description |
76-
| ------------------ | ------------------------------------------------------------ | ----------- |
77-
| `type` | string | **REQUIRED**. The authentication scheme type used to access the data (`http` \| `s3` \| `planetaryComputer` \| `earthdata` \| `signedUrl` \| `oauth2` \| `apiKey` \| `openIdConnect` \| a custom scheme type ). |
78-
| `description` | string | Additional instructions for authentication. [CommonMark 0.29](https://commonmark.org/) syntax MAY be used for rich text representation. |
79-
| `name` | string | Required for `type: apiKey`. The name of the header, query, or cookie parameter to be used. |
80-
| `in` | string | Required for `type: apiKey`. The location of the API key (`query` \| `header` \| `cookie`). |
81-
| `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`) |
82-
| `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`) |
83-
| `openIdConnectUrl` | string | Required for `type: openIdConnectUrl`. OpenID Connect URL to discover OAuth2 configuration values. This MUST be in the form of a URL. |
84-
85-
### Authentication Flow Object
86-
87-
[OpenAPI OAuth Flow Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#oauth-flows-object). Allows configuration of
88-
the supported OAuth Flows.
89-
90-
Configuration details for a supported OAuth Flow
91-
92-
| Field Name | Type | Description |
93-
| ------------------ | -------------------------------------------------- | ----------- |
94-
| `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. |
95-
| `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. |
96-
| `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. |
97-
| `refreshUrl` | `string` | Optional for `oauth2`. The URL to be used for obtaining refresh tokens. This MUST be in the form of a URL. |
98-
| `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. |
99-
| `method` | `string` | Required for `signedUrl`. The method to be used for requests |
100-
| `parameters` | Map<string, [Parameter Object](#parameter-object)> | Optional for `signedUrl`. Parameter definition for requests to the `authorizationApi` |
101-
| `responseField` | string | Optional for `signedUrl`. Key name for the signed URL field in an authorizationApi response |
68+
The Authentication Scheme extends the
69+
[OpenAPI security spec](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#security-scheme-object)
70+
for support of OAuth2.0, API Key, and OpenID Connect authentication.
71+
All the [authentication clients](https://github.com/stac-utils/stac-asset#clients) included in the
72+
[stac-asset](https://github.com/stac-utils/stac-asset)
73+
library can be described, as well as a custom signed URL authentication scheme.
74+
75+
| Field Name | Type | Applies to | Description |
76+
| ------------------ | ------------------------------------------------------------ | --------------------- | ------------------------------------------------------------ |
77+
| `type` | string | *All* | **REQUIRED**. The authentication scheme type used to access the data (`http` \| `s3` \| `signedUrl` \| `oauth2` \| `apiKey` \| `openIdConnect` \| a custom scheme type ). |
78+
| `description` | string | *All* | Additional instructions for authentication. [CommonMark 0.29](https://commonmark.org/) syntax MAY be used for rich text representation. |
79+
| `name` | string | `apiKey` | **REQUIRED.** The name of the header, query, or cookie parameter to be used. |
80+
| `in` | string | `apiKey` | **REQUIRED.** The location of the API key (`query` \| `header` \| `cookie`). |
81+
| `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`) |
82+
| `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`. |
83+
| `openIdConnectUrl` | string | `openIdConnect` | **REQUIRED.** OpenID Connect URL to discover OpenID configuration values. This MUST be in the form of a URL. |
84+
85+
The column "Applies to" specifies for which values of `type` the fields only apply.
86+
They are also only required in this context.
87+
88+
### OAuth2 Flow Object
89+
90+
Based on the [OpenAPI OAuth Flow Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#oauth-flows-object).
91+
Allows configuration of the supported OAuth Flows.
92+
93+
| Field Name | Type | Description |
94+
| ------------------ | ----------------------- | ------------------------------------------------------------ |
95+
| `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. |
96+
| `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. |
97+
| `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. |
98+
| `refreshUrl` | `string` | The URL to be used for obtaining refresh tokens. This MUST be in the form of a URL. |
99+
100+
### Signed URL Object
101+
102+
Based on the [OpenAPI OAuth Flow Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#oauth-flows-object).
103+
Allows configuration of the supported OAuth Flows.
104+
105+
| Field Name | Type | Description |
106+
| ------------------ | -------------------------------------------------- | ------------------------------------------------------------ |
107+
| `method` | `string` | **REQUIRED.** The method to be used for requests |
108+
| `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. |
109+
| `parameters` | Map<string, [Parameter Object](#parameter-object)> | Parameter definition for requests to the `authorizationApi` |
110+
| `responseField` | string | Key name for the signed URL field in an `authorizationApi` response |
102111

103112
### Parameter Object
104113

105-
Definition for a request parameter
114+
Definition for a request parameter.
106115

107-
| Field Name | Type | Description |
108-
| ------------- | --------- | ----------- |
109-
| `in` | `string` | The location of the parameter (`query` \| `header` \| `body`). |
110-
| `required` | `boolean` | Setting for optional or required parameter |
111-
| `description` | `string` | Optional. Plain language description of the parameter |
112-
| `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/) |
116+
| Field Name | Type | Description |
117+
| ------------- | --------- | ------------------------------------------------------------ |
118+
| `in` | `string` | **REQUIRED.** The location of the parameter (`query` \| `header` \| `body`). |
119+
| `required` | `boolean` | **REQUIRED.** Setting for optional or required parameter. |
120+
| `description` | `string` | Plain language description of the parameter |
121+
| `schema` | `object` | Schema object following the [JSON Schema draft-07](https://json-schema.org/) |
113122

114-
### Examples
123+
## Examples
115124

116125
`auth:schemes` may be referenced identically in a STAC Asset or Link objects. Examples of these two use-cases are provided below.
117126

118-
#### Schema definitions
127+
### Schema definitions
119128

120129
```json
121130
"auth:schemes": {
122-
"oauth": {
123-
"type": "oauth2",
124-
"description": "requires a login and user token",
125-
"flows": {
126-
"authorizationUrl": "https://example.com/oauth/authorize",
127-
"tokenUrl": "https://example.com/oauth/token",
128-
"scopes": {}
129-
}
131+
"oauth": {
132+
"type": "oauth2",
133+
"description": "requires a login and user token",
134+
"flows": {
135+
"authorizationUrl": "https://example.com/oauth/authorize",
136+
"tokenUrl": "https://example.com/oauth/token",
137+
"scopes": {}
130138
}
131139
}
140+
}
132141
```
133142

134-
#### Links reference
143+
### Links reference
135144

136145
```json
137146
"links": [
@@ -149,7 +158,7 @@ Definition for a request parameter
149158
]
150159
```
151160

152-
#### Asset reference
161+
### Asset reference
153162

154163
```json
155164
"assets": {
@@ -299,8 +308,7 @@ Promise(
299308

300309
### Planetary Computer URL Signing
301310

302-
Planetary Computer uses the same signed URL pattern described above. Here is an example of how to configure an `auth:scheme` with instructions on
303-
how to sign URLs with the [Planetary Computer Data Authentication API](https://planetarycomputer.microsoft.com/docs/reference/sas/)
311+
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/)
304312

305313
```json
306314
"auth:schemes": {

‎examples/collection.json

+9-11
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
"stac_version": "1.0.0",
33
"stac_extensions": [
44
"https://stac-extensions.github.io/item-assets/v1.0.0/schema.json",
5-
"https://stac-extensions.github.io/authentication/v1.0.0/schema.json"
5+
"https://stac-extensions.github.io/authentication/v1.1.0/schema.json"
66
],
77
"type": "Collection",
88
"id": "collection",
@@ -49,7 +49,7 @@
4949
"type": "signedUrl",
5050
"description": "Requires an authentication API",
5151
"flows": {
52-
"authorizationCode": {
52+
"auth": {
5353
"authorizationApi": "https://example.com/signed_url/authorize",
5454
"method": "POST",
5555
"parameters": {
@@ -59,7 +59,9 @@
5959
"description": "asset-bucket",
6060
"schema": {
6161
"type": "string",
62-
"examples": "example-bucket"
62+
"examples": [
63+
"example-bucket"
64+
]
6365
}
6466
},
6567
"key": {
@@ -68,7 +70,9 @@
6870
"description": "asset key",
6971
"schema": {
7072
"type": "string",
71-
"examples": "path/to/example/asset.xyz"
73+
"examples": [
74+
"path/to/example/asset.xyz"
75+
]
7276
}
7377
}
7478
},
@@ -106,13 +110,7 @@
106110
"datetime": {
107111
"minimum": "2015-06-23T00:00:00Z",
108112
"maximum": "2019-07-10T13:44:56Z"
109-
},
110-
"auth:schemes": [
111-
"none",
112-
"oauth",
113-
"s3",
114-
"signedUrl"
115-
]
113+
}
116114
},
117115
"links": [
118116
{

‎examples/item.json

+2-3
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
{
22
"stac_version": "1.0.0",
33
"stac_extensions": [
4-
"https://stac-extensions.github.io/authentication/v1.0.0/schema.json"
4+
"https://stac-extensions.github.io/authentication/v1.1.0/schema.json"
55
],
66
"type": "Feature",
77
"id": "item",
@@ -59,8 +59,7 @@
5959
"none": {
6060
"type": "http",
6161
"scheme": "basic",
62-
"description": "Free access without restrictions",
63-
"flows": {}
62+
"description": "Free access without restrictions"
6463
}
6564
}
6665
},

0 commit comments

Comments
 (0)
Please sign in to comment.