Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

PB-1282: document the new authentication method. #504

Merged
merged 3 commits into from
Jan 28, 2025
Merged

PB-1282: document the new authentication method. #504

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
d3ef360
PB-1282: document the new authentication method.
adk-swisstopo Jan 20, 2025
23f4c82
Appease GitGuardian.
adk-swisstopo Jan 27, 2025
e2924a9
Remove references to old auth methods.
adk-swisstopo Jan 27, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
130 changes: 43 additions & 87 deletions spec/static/spec/v1/openapitransactional.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2937,26 +2937,32 @@ tags:
- [Example](#section/Example)
- name: Authentication
description: |
All write requests require authentication. There is currently three type of supported authentications:
All write requests require authentication. There are currently two types of supported authentications:

* [Session authentication](#section/Session-authentication)
* [Basic authentication](#section/Basic-authentication)
* [Token authentication](#section/Token-authentication)
* [JSON Web Token authentication](#section/JSON-Web-Token-authentication)

## Session authentication

When using the browsable API the user can simply use the admin interface for logging in.
Once logged in, the browsable API can be used to perform write requests.
The service issues a session cookie which the browser can use to authenticate itself
and perform write requests. This authentication method is only intended
for web browsers users of the admin interface. Non-browser clients and
API endpoints are not guaranteed to work with session authentication.

## Basic authentication
## JSON Web Token authentication

The username and password for authentication can be added to every write request the user wants to perform.
Here is an example of posting an asset using curl (_username_="MickeyMouse", _password_="I_love_Minnie_Mouse"):
The user authenticates with a JSON Web Token (JWT) passed in the
`Authorization` header with the `Bearer` HTTP authentication scheme as
described in
[RFC 6750](https://datatracker.ietf.org/doc/html/rfc6750#section-2.1).

Here is an example using curl, assuming the JWT is `123456`:

```
curl --request POST \
--user MickeyMouse:I_love_Minnie_Mouse \
--url https://data.geoadmin.ch/api/stac/v1/collections/ch.swisstopo.swisstlmregio/items/swisstlmregio-2020/assets \
--header 'Authorization: Bearer 123456' \
--header 'Content-Type: application/json' \
--data '{
"id": "fancy_unique_id",
Expand All @@ -2969,37 +2975,42 @@ tags:
}'
```

## Token authentication
Tokens are obtained by requesting them from the
[Amazon Cognito InitiateAuth API](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_InitiateAuth.html).

A user specific token for authentication can be added to every write request the user wants to perform.
Here is an example of posting an asset using curl:
Here is an example using curl and jq:

```
curl --request POST \
--url https://data.geoadmin.ch/api/stac/v1/collections/ch.swisstopo.swisstlmregio/items/swisstlmregio-2020/assets \
--header 'Authorization: Token ccecf40693bfc52ba090cd46eb7f19e723fe831f' \
--header 'Content-Type: application/json' \
--url https://cognito-idp.eu-central-1.amazonaws.com/ \
--header 'Content-Type: application/x-amz-json-1.1' \
--header 'X-Amz-Target: AWSCognitoIdentityProviderService.InitiateAuth' \
--data '{
"id": "fancy_unique_id",
"item": "swisstlmregio-2020",
"title": "My title",
"type": "application/x.filegdb+zip",
"description": "My description",
"proj:epsg": 2056,
"file:checksum": "12200ADEC47F803A8CF1055ED36750B3BA573C79A3AF7DA6D6F5A2AED03EA16AF3BC"
}'
"AuthFlow": "USER_PASSWORD_AUTH",
"AuthParameters": {
"PASSWORD": "I_love_Minnie_Mouse",
"USERNAME": "MickeyMouse"
},
"ClientId": "CLIENT_ID"
}' | jq -r .AuthenticationResult.AccessToken
```

Tokens can either be generated in the admin interface or existing users can perform a POST request
on the get-token endpoint to request a token (also see [Request token for token authentication](#operation/getToken)).
Here is an example using curl:

```
curl --request POST \
--url https://data.geoadmin.ch/api/stac/get-token \
--header 'Content-Type: application/json' \
--data '{"username": "MickeyMouse", "password": "I_love_Minnie_Mouse"}'
```
The `CLIENT_ID` value needs to be substituted for the correct client
identifier which you should receive along with your username and password.

Notice the response from `InitiateAuth` is a JSON document. The token used
to authenticate against the STAC API is the `AccessToken`. There are cases
where the response will not contain that token (e.g. if the password must
be updated or a second factor is required for authentication). It is the
responsibility of the client to handle these cases.
[AWS provides an SDK](https://aws.amazon.com/developer/tools/) which may
make this easier.

The access token is only valid for a certain duration (as per
the `AuthenticationResult.ExpiresIn` field in the response). You need to
refresh it periodically, either by obtaining a new JWT or by
[using the refresh token](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-the-refresh-token.html).
The refresh token is normally valid for a longer time period.
paths:
/:
get:
Expand Down Expand Up @@ -4477,58 +4488,3 @@ paths:
$ref: "#/components/responses/NotFound"
"500":
$ref: "#/components/responses/ServerError"
/get-token:
servers:
- url: http://data.geo.admin.ch/api/stac/
post:
tags:
- Authentication
summary: >-
Request token for token authentication.
operationId: getToken
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
username:
type: string
description: name of user for whom token is requested
password:
type: string
description: password of user for whom token is requested
required:
- username
- password
example:
username: "Mickey Mouse"
password: "I_love_Minnie_Mouse"
responses:
"200":
description: Returns the token for the specified user
content:
application/json:
schema:
type: object
properties:
token:
type: string
description: generated token for specified user
example:
token: ccecf40693bfc52ba090cd46eb7f19e723fe831f
"400":
description: Wrong credentials were provided.
content:
application/json:
schema:
type: object
properties:
code:
type: string
description:
type: string
example:
code: 400
description: "Unable to log in with provided credentials."
57 changes: 0 additions & 57 deletions spec/transaction/paths.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1223,60 +1223,3 @@ paths:
$ref: "../components/responses.yaml#/components/responses/NotFound"
"500":
$ref: "../components/responses.yaml#/components/responses/ServerError"


"/get-token":
servers:
- url: http://data.geo.admin.ch/api/stac/
post:
tags:
- Authentication
summary: >-
Request token for token authentication.
operationId: getToken
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
username:
type: string
description: name of user for whom token is requested
password:
type: string
description: password of user for whom token is requested
required:
- username
- password
example:
username: "Mickey Mouse"
password: "I_love_Minnie_Mouse"
responses:
"200":
description: Returns the token for the specified user
content:
application/json:
schema:
type: object
properties:
token:
type: string
description: generated token for specified user
example:
token: ccecf40693bfc52ba090cd46eb7f19e723fe831f
"400":
description: Wrong credentials were provided.
content:
application/json:
schema:
type: object
properties:
code:
type: string
description:
type: string
example:
code: 400
description: "Unable to log in with provided credentials."
75 changes: 43 additions & 32 deletions spec/transaction/tags.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -299,26 +299,32 @@ tags:

- name: Authentication
description: |
All write requests require authentication. There is currently three type of supported authentications:
All write requests require authentication. There are currently two types of supported authentications:

* [Session authentication](#section/Session-authentication)
* [Basic authentication](#section/Basic-authentication)
* [Token authentication](#section/Token-authentication)
* [JSON Web Token authentication](#section/JSON-Web-Token-authentication)

## Session authentication

When using the browsable API the user can simply use the admin interface for logging in.
Once logged in, the browsable API can be used to perform write requests.
The service issues a session cookie which the browser can use to authenticate itself
and perform write requests. This authentication method is only intended
for web browsers users of the admin interface. Non-browser clients and
API endpoints are not guaranteed to work with session authentication.

## Basic authentication
## JSON Web Token authentication

The username and password for authentication can be added to every write request the user wants to perform.
Here is an example of posting an asset using curl (_username_="MickeyMouse", _password_="I_love_Minnie_Mouse"):
The user authenticates with a JSON Web Token (JWT) passed in the
`Authorization` header with the `Bearer` HTTP authentication scheme as
described in
[RFC 6750](https://datatracker.ietf.org/doc/html/rfc6750#section-2.1).

Here is an example using curl, assuming the JWT is `123456`:

```
curl --request POST \
--user MickeyMouse:I_love_Minnie_Mouse \
--url https://data.geoadmin.ch/api/stac/v1/collections/ch.swisstopo.swisstlmregio/items/swisstlmregio-2020/assets \
--header 'Authorization: Bearer 123456' \
--header 'Content-Type: application/json' \
--data '{
"id": "fancy_unique_id",
Expand All @@ -331,34 +337,39 @@ tags:
}'
```

## Token authentication
Tokens are obtained by requesting them from the
[Amazon Cognito InitiateAuth API](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_InitiateAuth.html).

A user specific token for authentication can be added to every write request the user wants to perform.
Here is an example of posting an asset using curl:
Here is an example using curl and jq:

```
curl --request POST \
--url https://data.geoadmin.ch/api/stac/v1/collections/ch.swisstopo.swisstlmregio/items/swisstlmregio-2020/assets \
--header 'Authorization: Token ccecf40693bfc52ba090cd46eb7f19e723fe831f' \
--header 'Content-Type: application/json' \
--url https://cognito-idp.eu-central-1.amazonaws.com/ \
--header 'Content-Type: application/x-amz-json-1.1' \
--header 'X-Amz-Target: AWSCognitoIdentityProviderService.InitiateAuth' \
--data '{
"id": "fancy_unique_id",
"item": "swisstlmregio-2020",
"title": "My title",
"type": "application/x.filegdb+zip",
"description": "My description",
"proj:epsg": 2056,
"file:checksum": "12200ADEC47F803A8CF1055ED36750B3BA573C79A3AF7DA6D6F5A2AED03EA16AF3BC"
}'
"AuthFlow": "USER_PASSWORD_AUTH",
"AuthParameters": {
"PASSWORD": "I_love_Minnie_Mouse",
"USERNAME": "MickeyMouse"
},
"ClientId": "CLIENT_ID"
}' | jq -r .AuthenticationResult.AccessToken
```

Tokens can either be generated in the admin interface or existing users can perform a POST request
on the get-token endpoint to request a token (also see [Request token for token authentication](#operation/getToken)).
Here is an example using curl:

```
curl --request POST \
--url https://data.geoadmin.ch/api/stac/get-token \
--header 'Content-Type: application/json' \
--data '{"username": "MickeyMouse", "password": "I_love_Minnie_Mouse"}'
```
The `CLIENT_ID` value needs to be substituted for the correct client
identifier which you should receive along with your username and password.

Notice the response from `InitiateAuth` is a JSON document. The token used
to authenticate against the STAC API is the `AccessToken`. There are cases
where the response will not contain that token (e.g. if the password must
be updated or a second factor is required for authentication). It is the
responsibility of the client to handle these cases.
[AWS provides an SDK](https://aws.amazon.com/developer/tools/) which may
make this easier.

The access token is only valid for a certain duration (as per
the `AuthenticationResult.ExpiresIn` field in the response). You need to
refresh it periodically, either by obtaining a new JWT or by
[using the refresh token](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-the-refresh-token.html).
The refresh token is normally valid for a longer time period.
Loading