Skip to content

Commit f2f9a62

Browse files
m-mohrm-mohr
committed
Fix schema, clarify spec
1 parent 3cb217b commit f2f9a62

File tree

6 files changed

+479
-375
lines changed

6 files changed

+479
-375
lines changed

‎CHANGELOG.md

+12-4
Original file line numberDiff line numberDiff line change
@@ -6,15 +6,22 @@ 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
1619

17-
### Removed
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
1825

1926
## [v1.0.0] - 2023-11-07
2027

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

5966
### Fixed
6067

61-
[Unreleased]: <https://github.com/stac-extensions/authentication/compare/v1.0.0...HEAD>
68+
[Unreleased]: <https://github.com/stac-extensions/authentication/compare/v1.1.0...HEAD>
69+
[v1.1.0]: <https://github.com/stac-extensions/authentication/compare/v1.0.0...v1.1.0>
6270
[v1.0.0]: <https://github.com/stac-extensions/authentication/tree/v1.0.0>

‎README.md

+63-52
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
@@ -67,71 +67,82 @@ included in the scheme type standards below.
6767

6868
### Authentication Scheme Object
6969

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

103114
### Parameter Object
104115

105-
Definition for a request parameter
116+
Definition for a request parameter.
106117

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

114-
### Examples
125+
## Examples
115126

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

118-
#### Schema definitions
129+
### Schema definitions
119130

120131
```json
121132
"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-
}
133+
"oauth": {
134+
"type": "oauth2",
135+
"description": "requires a login and user token",
136+
"flows": {
137+
"authorizationUrl": "https://example.com/oauth/authorize",
138+
"tokenUrl": "https://example.com/oauth/token",
139+
"scopes": {}
130140
}
131141
}
142+
}
132143
```
133144

134-
#### Links reference
145+
### Links reference
135146

136147
```json
137148
"links": [
@@ -149,7 +160,7 @@ Definition for a request parameter
149160
]
150161
```
151162

152-
#### Asset reference
163+
### Asset reference
153164

154165
```json
155166
"assets": {

‎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)