Skip to content

Commit

Permalink
Merge pull request #470 from GeoLabs/feature/fix-issue-458
Browse files Browse the repository at this point in the history 
Remove security example
  • Loading branch information
@gfenoy
gfenoy authored Oct 31, 2024
2 parents ba7ef93 + 644ad88 commit e87fd2e
Showing 1 changed file with 2 additions and 108 deletions.
110 changes: 2 additions & 108 deletions extensions/job_management/standard/sections/clause_12_security_considerations.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,116 +4,10 @@ See <<OAProc-1,OGC API - Processes - Part 1: Core>>, Clause 10.4.

Since creating and updating jobs will change the jobs available to a client, servers will - in almost all cases - restrict the access to these operations.

Users making modifications to process resources need to:
Users making modifications to job resources need to:

. Be authenticated,
. Have "modification privileges" on the jobs offered through the API,
. Have access to one or more of the POST and/or PUT methods on the jobs /jobs/{jobId} endpoints.
. Have access to one or more of the POST and/or PATCH methods on the jobs /job and /jobs/{jobId} endpoints.

The API definition, as defined in Clause 7.3 from <<OAProc-1>>, must reflect this in the resource paths and their available methods.

Examples in the Clauses specifying the requirements classes focus on the mechanics of the POST, PUT, and DELETE methods and exclude authentication. Since authentication will typically be required for all DRU requests, this section provides some examples/guidance:

The OpenAPI definition exposed by the serve will declare the authentication schemes that an implementation of the Processes - Part 4 (JM) supports for each operation (or for all operations in the API implementation).

A member "security" in the OpenAPI definition object can be provided to list the default security schemes supported by all operations. Individual DRU operations can override this default by providing a "security" member for the individual operation.

[#auth-example-1,reftext=`Example OpenAPI definition with security requirements`]
.Example OpenAPI definition with security requirements
====
The following OpenAPI definition declares that the API accepts either api keys in an "X-API-Key" header or Json Web Token (JWT) bearer tokens to authenticate the requestor. X-API-KEY is a custom HTTP header that can be used to secure APIs. The API implementation will decide, if an authenticated request is rejected or executed based on the privileges of the authenticated user.

[source,JSON]
----
{
"openapi" : "3.0.3",
"info" : {
"title" : "My API",
"description" : "This API ...",
"version" : "1.0.0"
},
"servers" : [ {
"url" : "https://example.com/api/v1"
} ],
"security" : [ {
"JWT" : [ ],
"api_key": [ ]
} ],
"paths" : { },
"components" : {
"securitySchemes": {
"JWT" : {
"type" : "http",
"scheme" : "bearer",
"bearerFormat" : "JWT"
},
"api_key" : {
"type": "apiKey",
"name": "X-API-Key",
"in": "header"
}
}
}
}
----
====
If the authentication of a secured request fails or if the user does not have sufficient privileges, the API endpoint will return an error.
In case the request does not include information to authenticate the user, the server will respond with a 401 response ("Unauthorized"). The response will include a "WWW-Authenticate" header with hints as to how authentication credentials are provided.
[#auth-example-2,reftext=`Unauthorized request`]
.Unauthorized request
----
Client Server
| |
| POST /jobs/xxxx-xxx-xxx-xxxxx HTTP/1.1 |
| ----------------------------------------------------------->|
| |
| HTTP/1.1 401 Unauthorized |
| Date: Mon, 23 May 2022 11:18:45 GMT |
| WWW-Authenticate: Bearer realm="my-realm" |
| WWW-Authenticate: ApiKey header="X-API-Key" |
| Content-Type: application/problem+json |
| Vary: Accept |
| Content-Length: 86 |
| |
| { |
| "status": 401, |
| "title": "Unauthorized", |
| "detail": "HTTP 401 Unauthorized" |
| } |
| <-----------------------------------------------------------|
----
NOTE: HTTP WWW-Authenticate header is a response-type header. It serves as a support for various authentication mechanisms which are important to control access to pages and other resources as well. All of these mechanisms are based on the use of the 401 status code. The HTTP WWW-Authenticate response header defines the authentication method that ought to be wont to gain access to a resource. As discussed earlier, the WWW-Authenticate header is sent along with a 401 Unauthorized response. (GeeksforGeeks.org, 2023)
If valid authentication credentials have been provided, but the API refuses to execute the operation, because the user has insufficient privileges, the server will typically return a 403 response ("Forbidden").
[#auth-example-3,reftext=`Forbidden request`]
.Forbidden request
```
Client Server
| |
| POST /jobs/xxxx-xxx-xxx-xxxxx HTTP/1.1 |
| Host: example.com |
| Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ97HgQ |
|------------------------------------------------------------------>|
| |
| HTTP/1.1 403 Forbidden |
| Date: Mon, 23 May 2022 11:18:55 GMT |
| Content-Type: application/problem+json |
| Vary: Accept |
| Content-Length: 80 |
| |
| { |
| "status" : 403, |
| "title" : "Forbidden", |
| "detail" : "HTTP 403 Forbidden" |
| } |
|<------------------------------------------------------------------|
```
However, for security reasons, the server may also decide to return other status codes to hide information from a potential attacker. For example, the server may decide to return a 401 response even for a valid, but un-privileged user. Or the server may return a 404 response ("Not Found") to hide the fact that the resource exists in the first place, typically if the user would also not be privileged to fetch the resource with a GET operation.

0 comments on commit e87fd2e

Please sign in to comment.