Skip to content

Commit

Permalink
second draft jaf
Browse files Browse the repository at this point in the history
  • Loading branch information
@jamesfisher-geo
jamesfisher-geo committed Jul 20, 2023
1 parent 5bcb94d commit c7bd6e4
Show file tree
Hide file tree
Showing 4 changed files with 152 additions and 21 deletions.
107 changes: 103 additions & 4 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ The fields in the table below can be used in these parts of STAC documents:

| Field Name | Type | Description |
| -------------------- | ------------------------- | ----------- |
| sa:security | Map<string, [SecureAsset Object](#secure-asset-object)> | Keyword for asset security level. |
| security | Map<string, [SecureAsset Object](#secure-asset-object)> | Object that desribes the authenticated scheme and href |

### Additional Field Information

Expand All @@ -48,9 +48,108 @@ An Asset with the Secure Assets extension will have the following fields

| Field Name | Type | Description |
| ----------- | ------ | ----------- |
| href | string | **REQUIRED**. URI to the asset. Relative and abolsolute URI are both allowed |
| title | string | The displayed title for clients and users. |
| sa:security | string | Keyword for asset security level |
| scheme | string | **REQUIRED**. The authentification scheme used to access the data (`HttpClient` \| `S3Client` \| `PlanetaryComputerClient` \| `EarthdataClient` \| `SignedUrlClient`). |
| description | string | Additional instructions for authentification |

### Schemes

The authentification schemes align with the relevant clients included in the [stac-asset](https://github.com/stac-utils/stac-asset) library.

| Name | Description
| -- | -- |
| `HttpClient` | Simple HTTP client without any authentication |
| `S3Client` | Simple S3 client
| `PlanetaryComputerClient` | Signs URLs with the [Planetary Computer Authentication API](https://planetarycomputer.microsoft.com/docs/reference/sas/)
| `EarthdataClient` | Uses a token-based authentication to download data, from _some_ Earthdata providers, e.g. DAACs
| `SignedUrlClient` | Signs URLs with a user-defined Authentification API

### URL Signing

The `SignedUrlClient` scheme indicates that authentification will be handled by an API which generates and returns a signed URL. For example, a signed URL for assets in AWS S3 can be generated with the following Lambda function code.

```python
import boto3
from botocore.client import Config
import os
import json

def lambda_handler(event, context):
try:
s3Client = boto3.client("s3")
except Exception as e:
return {
"statusCode": 400,
"body": json.dumps({
"error": (e)
})
}

body = json.loads(event["body"])
key = body["key"]
bucketName = body["bucket"]

try:
URL = s3Client.generate_presigned_url(
"get_object",
Params = {"Bucket": bucketName, "Key":key},
ExpiresIn = 360
)

return ({
"statusCode": 200,
"body": json.dumps({
"signed_url": URL
}),
"headers":{
"Access-Control-Allow-Origin": "*",
"Access-Control-Allow-Headers": "*"
}

})
except Exception as e:
return {
"statusCode": 400,
"body": json.dumps({
"error": (e)
})
}
```
Where the response looks like

```json
{
"signed_url": "https://<bucket>.s3.<region>.amazonaws.com/<key>?AWSAccessKeyId=<aws access key>&Signature=<signature>&x-amz-security-token=<auth token>&Expires=<epoch expiration time>"
}
```

The authentication API can be called clientside using an AWS S3 href (`https://<bucket>.s3.<region>.amazonaws.com/<key>`) with the following code snippet.

```javascript
let signed_url
const auth_api = "";

function createSignedRequestBody(href) {
const bucket = href.split(".")[0].split("//")[1];
const key = href.split("/").slice(3).join("/").replace(/\+/g, " ");
return {
method: "POST",
headers: {
Accept: "application/json",
"Content-Type": "application/json",
},
body: JSON.stringify({ bucket: bucket, key: key }),
redirect: "follow",
};
};

Promise(
fetch(auth_api, createSignedRequestBody(href))
.then((resp) => resp.json())
.then((respJson) => {
signed_url = respJson.signed_url;
})
);
```

## Contributing

Expand Down
11 changes: 9 additions & 2 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://github.com/AtomicMaps/secure-assets/blob/main/json-schema/schema.json"
"https://stac-extensions.github.io/secure-assets/v1.1.0/schema.json"
],
"type": "Collection",
"id": "collection",
Expand Down Expand Up @@ -47,13 +47,20 @@
"roles": [
"data"
],
"sa:security": "private"
"security": {
"scheme": "SignedUrlClient",
"description": "Requires an authentification API"
}
}
},
"summaries": {
"datetime": {
"minimum": "2015-06-23T00:00:00Z",
"maximum": "2019-07-10T13:44:56Z"
},
"security": {
"scheme": ["SignedUrlClient"],
"description": ["Requires an authentification API"]
}
},
"links": [
Expand Down
7 changes: 5 additions & 2 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://github.com/AtomicMaps/secure-assets/blob/main/json-schema/schema.json"
"https://stac-extensions.github.io/secure-assets/v1.1.0/schema.json"
],
"type": "Feature",
"id": "item",
Expand Down Expand Up @@ -55,7 +55,10 @@
"roles": [
"data"
],
"sa:security": "private"
"security": {
"scheme": "EarthdataClient",
"description": "Requires a Personal Access Token"
}
}
}
}
48 changes: 35 additions & 13 deletions json-schema/schema.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://stac-extensions.github.io/secure-assets/v1.0.0/schema.json#",
"title": "Secure Assets Extension",
"description": "STAC Secure Assets Extension for STAC Items and STAC Collections.",
"description": "Secure Assets STAC Extension for STAC Items and STAC Collections.",
"oneOf": [
{
"$comment": "This is the schema for STAC Items.",
Expand All @@ -14,6 +14,7 @@
"type": "object",
"required": [
"type",
"properties",
"assets"
],
"properties": {
Expand All @@ -24,7 +25,7 @@
"$comment": "This validates the fields in Item Assets, but does not require them.",
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/fields"
"$ref": "#/definitions/secure_asset"
}
}
}
Expand Down Expand Up @@ -63,7 +64,10 @@
"not": {
"allOf": [
{
"$ref": "#/definitions/fields"
"$ref": "#/definitions/require_any_field"
},
{
"$ref": "#/definitions/secure_asset"
}
]
}
Expand All @@ -85,14 +89,28 @@
"not": {
"allOf": [
{
"$ref": "#/definitions/fields"
"$ref": "#/definitions/require_any_field"
},
{
"$ref": "#/definitions/secure_asset"
}
]
}
}
}
}
}
},
{
"$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"
}
}
}
]
}
Expand All @@ -115,21 +133,25 @@
"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": ["sa:security"]}
{"required": ["security", "secure_asset:scheme"]}
]
},
"fields": {
"secure_asset": {
"$comment": "Add your new fields here. Don't require them here, do that above in the corresponding schema.",
"type": "object",
"properties": {
"sa:security": {
"type": "string"
"security": {
"type": "object",
"properties": {
"scheme": {
"type": "string"
},
"description": {
"type": "string"
}
}
}
},
"patternProperties": {
"^(?!sa:)": {}
},
"additionalProperties": false
}
}
}
}

0 comments on commit c7bd6e4

Please sign in to comment.