Skip to content

Latest commit

 

History

History
383 lines (318 loc) · 16 KB

README.md

File metadata and controls

383 lines (318 loc) · 16 KB
Raw

Authentication Extension Specification

The Authentication extension to the STAC specification provides a standard set of fields to describe authentication and authorization schemes, flows, and scopes required to access Assets and Links that align with the OpenAPI security spec

The Authentication extension also includes support for other authentication schemes specified in stac-asset library. A signedUrl scheme type can be specified that describes authentication via signed URLs returned from a user-defined API. See the Signed URL section for a Lambda function example.

Fields

The fields in the table below can be used in these parts of STAC documents:

  • Catalogs
  • Collections
  • Item Properties (incl. Summaries in Collections)
  • Assets (for both Collections and Items, incl. Item Asset Definitions in Collections)
  • Links
Field Name Type Description
auth:schemes Map<string, Authentication Scheme Object> A property that contains all of the scheme definitions used by Assets and Links in the STAC Item or Collection.

The fields in the table below can be used in these parts of STAC documents:

  • Catalogs
  • Collections
  • Item Properties (incl. Summaries in Collections)
  • Assets (for both Collections and Items, incl. Item Asset Definitions in Collections)
  • Links
Field Name Type Description
auth:refs [string] A property that specifies which schemes in auth:schemes may be used to access an Asset or Link.

Scheme Types

The type value is not restricted to the following values, so a practitioner may define a custom authentication or authorization scheme not included in the scheme type standards below.

Name Description
http Simple HTTP authentication mechanisms (Basic, Bearer, Digest, etc.).
s3 Simple S3 authentication.
signedUrl Signs URLs with a user-defined authentication API.
oauth2 Open Authentication (OAuth) 2.0 configuration
apiKey Description of API key authentication included in request headers, query parameters, or cookies.
openIdConnect Description of OpenID Connect authentication

Authentication Scheme Object

The Authentication Scheme extends the OpenAPI security spec for support of OAuth2.0, API Key, and OpenID Connect authentication. All the authentication clients included in the 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 | signedUrl | oauth2 | apiKey | openIdConnect | a custom scheme type ).
description string All Additional instructions for authentication. CommonMark 0.29 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. The values used SHOULD be registered in the IANA Authentication Scheme registry. (basic | bearer | digest | dpop | hoba | mutual | negotiate | oauth (1.0) | privatetoken | scram-sha-1 | scram-sha-256 | vapid)
flows Map<string, (OAuth2 Flow 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. 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 this 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

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 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.

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

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

"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": {}
    }
  }
}

Links reference

"links": [
  {
    "href": "https://example.com/examples/collection.json",
    "rel": "self"
  },
  {
    "href": "https://example.com/examples/item.json",
    "rel": "item",
    "auth:refs": [
      "oauth"
    ]
  }
]

Asset reference

"assets": {
  "data": {
    "href": "https://example.com/examples/file.xyz",
    "title": "Secure Asset Example",
    "type": "application/vnd.example",
    "roles": [
      "data"
    ],
    "auth:refs": [
      "oauth"
    ]
  }
}

URL Signing

The signedUrl scheme type indicates that authentication will be handled by an API which generates and returns a signed URL. A signed URL authentication scheme can be defined with

"auth:schemes": {
  "signed_url_auth": {
    "type": "signedUrl",
    "description": "Requires an authentication API",
    "flows": {
      "authorizationCode": {
        "authorizationApi": "https://example.com/signed_url/authorize",
        "method": "POST",
        "parameters": {
          "bucket": {
            "in": "body",
            "required": true,
            "description": "asset bucket",
            "schema": {
              "type": "string",
              "examples": "example-bucket"
            }
          },
          "key": {
            "in": "body",
            "required": true,
            "description": "asset key",
            "schema": {
              "type": "string",
              "examples": "path/to/example/asset.xyz"
            }
          }
        },
        "responseField": "signed_url"
      }
    }
  }
}

and generated via a Gateway API and the following Lambda function.

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

{
  "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 on the client side based on an AWS S3 href (https://<bucket>.s3.<region>.amazonaws.com/<key>) with the following code snippet.

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;
    })
);

Planetary Computer URL Signing

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

"auth:schemes": {
  "plantetary_computer_auth": {
    "type": "signedUrl",
    "description": "Requires authorization from Planetary Computer",
    "flows": {
      "authorizationCode": {
        "authorizationApi": "https://planetarycomputer.microsoft.com/api/sas/v1/sign",
        "method": "GET",
        "parameters": {
          "href": {
            "in": "query",
            "required": true,
            "description": "HREF (URL) to sign",
            "schema": {
              "type": "string",
            }
          },
          "duration": {
            "in": "query",
            "required": false,
            "description": "The duration, in minutes, that the SAS token will be valid. Only valid for approved users.",
            "schema": {
              "type": "integer",
            }
          },
          "_id": {
            "in": "query",
            "required": false,
            "description": "Third party user identifier for metrics tracking.",
            "schema": {
              "type": "string"
            }
          }
        },
        "responseField": "href"
      }
    }
  }
}

Contributing

All contributions are subject to the STAC Specification Code of Conduct. For contributions, please follow the STAC specification contributing guide Instructions for running tests are copied here for convenience.

Running tests

The same checks that run as checks on PR's are part of the repository and can be run locally to verify that changes are valid. To run tests locally, you'll need npm, which is a standard part of any node.js installation.

First you'll need to install everything with npm once. Just navigate to the root of this repository and on your command line run:

npm install

Then to check markdown formatting and test the examples against the JSON schema, you can run:

npm test

This will spit out the same texts that you see online, and you can then go and fix your markdown or examples.

If the tests reveal formatting problems with the examples, you can fix them with:

npm run format-examples