Skip to content

Commit 8b7eaa2

Browse files
author
Joe Reed
committed
added authentication tutorial
This includes the AWS SigV4 example.
1 parent 40e5908 commit 8b7eaa2

File tree

3 files changed

+153
-1
lines changed

3 files changed

+153
-1
lines changed

‎docs/tutorials.rst

+10
Original file line numberDiff line numberDiff line change
@@ -47,3 +47,13 @@ Calculating Coverage Percentage of the AOI by an Item
4747
This tutorial demonstrates the use of pystac-client to calculate the
4848
percentage an Item's geometry that intesects with the area of interest
4949
(AOI) specified in the search by the `intersects` parameter.
50+
51+
Authentication
52+
--------------
53+
54+
- :tutorial:`GitHub version <authentication.ipynb>`
55+
- :ref:`Docs version </tutorials/authentication.ipynb>`
56+
57+
This tutorial demontrates different ways the pystac-client can be
58+
used to access a private stac api, when protected with various
59+
authentication mechanisms.

‎docs/tutorials/authentication.ipynb

+141
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
{
2+
"cells": [
3+
{
4+
"attachments": {},
5+
"cell_type": "markdown",
6+
"metadata": {},
7+
"source": [
8+
"# Authentication\n",
9+
"\n",
10+
"While not integrated into this library directly, pystac-client provides a series of hooks that support a wide variety of authentication mechanisms. These can be used when interacting with stac API implementations behind various authorization walls."
11+
]
12+
},
13+
{
14+
"attachments": {},
15+
"cell_type": "markdown",
16+
"metadata": {},
17+
"source": [
18+
"## Basic auth\n",
19+
"\n",
20+
"Pystac-client supports HTTP basic authentication by simply exposing the ability to define headers to be used when sending requets. Simply encode the token and provide the header."
21+
]
22+
},
23+
{
24+
"cell_type": "code",
25+
"execution_count": null,
26+
"metadata": {},
27+
"outputs": [],
28+
"source": [
29+
"import base64\n",
30+
"import pystac_client\n",
31+
"\n",
32+
"# encode credentials\n",
33+
"user_name = \"yellowbeard\"\n",
34+
"password = \"yaarg\"\n",
35+
"userpass = f\"{user_name}:{password}\"\n",
36+
"b64_userpass = base64.b64encode(userpass.encode()).decode()\n",
37+
"\n",
38+
"# create the client\n",
39+
"client = pystac_client.Client.open(\n",
40+
" url=\"https://planetarycomputer.microsoft.com/api/stac/v1\",\n",
41+
" headers={\n",
42+
" 'Authorization': f\"Basic {b64_userpass}\"\n",
43+
" }\n",
44+
")"
45+
]
46+
},
47+
{
48+
"attachments": {},
49+
"cell_type": "markdown",
50+
"metadata": {},
51+
"source": [
52+
"## Token auth\n",
53+
"\n",
54+
"Providing a authentication token can be accomplished using the same mechanism as described above for [basic auth](#basic-auth). Simply provide the token in the `Authorization` header to the client in the same manner."
55+
]
56+
},
57+
{
58+
"attachments": {},
59+
"cell_type": "markdown",
60+
"metadata": {},
61+
"source": [
62+
"## AWS SigV4\n",
63+
"\n",
64+
"Accessing a stac api protected by AWS IAM often requires signing the request using [AWS SigV4](https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html). Unlike basic and token authentication, the entire request is part of the signing process. Thus the `Authorization` header cannot be added when the client is created, rather it must be generated and added after the request is fully formed.\n",
65+
"\n",
66+
"Pystac-client provides a lower-level hook, the `request_modifier` parameter, which can mutate the request, adding the necessary header after the request has been generated but before it is sent.\n",
67+
"\n",
68+
"The code cell below demonstrates this, using the `boto3` module."
69+
]
70+
},
71+
{
72+
"cell_type": "code",
73+
"execution_count": null,
74+
"metadata": {},
75+
"outputs": [],
76+
"source": [
77+
"import boto3\n",
78+
"import botocore.auth\n",
79+
"import botocore.awsrequest\n",
80+
"import pystac_client\n",
81+
"import requests\n",
82+
"\n",
83+
"# Details regarding the private stac api\n",
84+
"region = \"us-east-1\"\n",
85+
"service_name = \"execute-api\"\n",
86+
"endpoint_id = \"xxxxxxxx\"\n",
87+
"deployment_stage = \"dev\"\n",
88+
"stac_api_url = f\"https://{endpoint_id}.{service_name}.{region}.amazonaws.com/{deployment_stage}\"\n",
89+
"\n",
90+
"# load AWS credentials\n",
91+
"credentials = boto3.Session(region_name=region).get_credentials()\n",
92+
"signer = botocore.auth.SigV4Auth(credentials, service_name, region)\n",
93+
"\n",
94+
"def sign_request(request: requests.Request) -> requests.Request:\n",
95+
" \"\"\"Sign the request using AWS SigV4.\n",
96+
"\n",
97+
" Args:\n",
98+
" request (requests.Request): The fully populated request to sign.\n",
99+
"\n",
100+
" Returns:\n",
101+
" requests.Request: The provided request object, with auth header added.\n",
102+
" \"\"\"\n",
103+
" aws_request = botocore.awsrequest.AWSRequest(\n",
104+
" method=request.method,\n",
105+
" url=request.url,\n",
106+
" params=request.params,\n",
107+
" data=request.data,\n",
108+
" headers=request.headers\n",
109+
" )\n",
110+
" signer.add_auth(aws_request)\n",
111+
" request.headers = aws_request.headers\n",
112+
" return request\n",
113+
"\n",
114+
"# create the client\n",
115+
"client = pystac_client.Client.open(\n",
116+
" url=stac_api_url,\n",
117+
" request_modifier=sign_request\n",
118+
")"
119+
]
120+
}
121+
],
122+
"metadata": {
123+
"kernelspec": {
124+
"display_name": "Python 3.11.0 ('pystac-client')",
125+
"language": "python",
126+
"name": "python3"
127+
},
128+
"language_info": {
129+
"name": "python",
130+
"version": "3.11.0"
131+
},
132+
"orig_nbformat": 4,
133+
"vscode": {
134+
"interpreter": {
135+
"hash": "b62550f29e06d2208e428c097c27b298f772314506f572254f8375b095fcaf78"
136+
}
137+
}
138+
},
139+
"nbformat": 4,
140+
"nbformat_minor": 2
141+
}

‎requirements-docs.txt

+2-1
Original file line numberDiff line numberDiff line change
@@ -10,4 +10,5 @@ hvplot~=0.8.2
1010
matplotlib~=3.6.2
1111
geojson~=2.5.0
1212
pygeoif~=1.0
13-
pydata-sphinx-theme~=0.12
13+
pydata-sphinx-theme~=0.12
14+
boto3~=1.26.23

0 commit comments

Comments
 (0)