Skip to content

Commit 18d362b

Browse files
schnuerleschnuerle
authored
Merge pull request #835 from openmobilityfoundation/feature-authorization
Consolidating authorization across APIs
2 parents 9066711 + e86e4e1 commit 18d362b

8 files changed

Lines changed: 121 additions & 96 deletions

File tree

‎agency/README.md‎

Lines changed: 9 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -9,10 +9,10 @@ This specification contains a collection of RESTful APIs used to specify the dig
99
## Table of Contents
1010

1111
* [General Information](#general-information)
12+
* [Authorization](#authorization)
1213
* [Versioning](#versioning)
1314
* [Modes](#modes)
1415
* [Responses and Error Messages](#responses-and-error-messages)
15-
* [Authorization](#authorization)
1616
* [GBFS](#gbfs)
1717
* [Vehicles](#vehicles)
1818
* [Vehicle - Status](#vehicle---status)
@@ -34,6 +34,14 @@ This specification uses data types including timestamps, UUIDs, and vehicle stat
3434

3535
[Top][toc]
3636

37+
### Authorization
38+
39+
MDS Agency endpoint producers **SHALL** provide authorization for API endpoints via a bearer token based auth system. When making requests, the endpoints expect `provider_id` to be part of the claims in a [JSON Web Token](https://jwt.io/) (JWT) `access_token` in the `Authorization` header, in the form `Authorization: Bearer <access_token>`. The token issuance, expiration and revocation policies are at the discretion of the agency. [JSON Web Token](/general-information.md#json-web-tokens) is the recommended format.
40+
41+
General authorization details are specified in the [Authorization section](/general-information.md#authorization) in MDS General Information.
42+
43+
[Top][toc]
44+
3745
### Versioning
3846

3947
`Agency` APIs must handle requests for specific versions of the specification from clients.
@@ -54,12 +62,6 @@ See the [Responses][responses] and [Error Messages][error-messages] sections.
5462

5563
[Top][toc]
5664

57-
### Authorization
58-
59-
When making requests, the Agency API expects `provider_id` to be part of the claims in a [JWT](https://jwt.io/) `access_token` in the `Authorization` header, in the form `Authorization: Bearer <access_token>`. The token issuance, expiration and revocation policies are at the discretion of the Agency.
60-
61-
[Top][toc]
62-
6365
### GBFS
6466

6567
See the [GBFS Requirement](/README.md#gbfs-requirement) language for more details.

‎general-information.md‎

Lines changed: 41 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ This document contains specifications that are shared between the various MDS [A
44

55
## Table of Contents
66

7-
- [Authentication](#authentication)
7+
- [Authorization](#authorization)
88
- [Beta Features](#beta-features)
99
- [Costs and Currencies](#costs-and-currencies)
1010
- [Data Types](#data-types)
@@ -25,11 +25,49 @@ This document contains specifications that are shared between the various MDS [A
2525
- [Vehicle States](#vehicle-states)
2626
- [Versioning](#versioning)
2727

28-
## Authentication
28+
## Authorization
29+
30+
Outlines shared authorization details and methods across all MDS APIs.
31+
32+
### Endpoint Requirements
33+
34+
All MDS Provider, Agency, and Metrics APIs require authentication, as outlined.
2935

3036
If implementing MDS Policy, Geography, and/or Jurisdiction APIs and endpoints, an agency must make them unauthenticated and public. This allows transparency for the public to see how the city is regulating, holds the city accountable for their policy decisions, and reduces the technical burden on providers to use these endpoints. A side benefit is that this allows third parties to ingest this information into their applications and services for public benefit.
3137

32-
All other MDS APIs require authentication, as outlined.
38+
As of MDS 0.3.0, `gbfs.json` is required. The required GBFS endpoints should be made available publicly. See Provider [#realtime-data](https://github.com/openmobilityfoundation/mobility-data-specification/tree/main/provider#realtime-data) for more information about how to implement GBFS for dockless systems.
39+
40+
### Header
41+
42+
The `Authorization` header is sent as part of an HTTP request. Example:
43+
44+
```
45+
GET /trips HTTP/1.1
46+
Host: api.provider.co
47+
Authorization: Bearer <token>
48+
```
49+
50+
More info on how to document [Bearer Auth in swagger](https://swagger.io/docs/specification/authentication/bearer-authentication/).
51+
52+
### JSON Web Tokens
53+
54+
JSON Web Token ([JWT](https://jwt.io/introduction/)) is **RECOMMENDED** as the token format.
55+
56+
JWTs provide a safe, secure way to verify the identity of an agency and provide access to MDS resources without providing access to other, potentially sensitive data.
57+
58+
> JSON Web Token (JWT) is an open standard ([RFC 7519](https://tools.ietf.org/html/rfc7519)) that defines a compact and self-contained way for securely transmitting information between parties as a JSON object. This information can be verified and trusted because it is digitally signed. JWTs can be signed using a secret (with the HMAC algorithm) or a public/private key pair using RSA or ECDSA.
59+
60+
MDS API producers **MAY** include any metadata in the JWT they wish that helps to route, log, permission, or debug agency requests, leaving their internal implementation flexible.
61+
62+
JWT provides a helpful [debugger](https://jwt.io/#debugger) for testing your token and verifying security.
63+
64+
### OAuth 2.0
65+
66+
OAuth 2.0's `client_credentials` grant type (outlined in [RFC6749](https://tools.ietf.org/html/rfc6749#section-4.4)) is **RECOMMENDED** as the authentication and authorization scheme.
67+
68+
OAuth 2.0 is an industry standard authorization framework with a variety of existing tooling. The `client_credentials` grant type facilitates generation of tokens that can be used for access by agencies and distributed to data partners.
69+
70+
If an MDS endpoint producer implements this auth scheme, it **MAY** choose to specify token scopes that define access parameters like allowable time ranges. These guidelines **SHOULD** be encoded into the returned token in a parsable way.
3371

3472
[Top][toc]
3573

‎geography/README.md‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -11,11 +11,11 @@ Geographical data will be stored as GeoJSON and read from either `geographies.js
1111
## Table of Contents
1212

1313
* [General Information](#general-information)
14+
* [Authorization](#authorization)
1415
* [Versioning](#versioning)
1516
* [Distribution](#distribution)
1617
* [Flat Files](#flat-files)
1718
* [Response Format](#response-format)
18-
* [Authorization](#authorization)
1919
* [Schema](#schema)
2020
* [Geography Fields](#geography-fields)
2121
* [Previous Geographies](#previous-geographies)
@@ -32,6 +32,12 @@ The following information applies to all `geography` API endpoints.
3232

3333
[Top][toc]
3434

35+
### Authorization
36+
37+
This endpoint should be made public. Authorization is not required.
38+
39+
[Top][toc]
40+
3541
### Versioning
3642

3743
MDS APIs must handle requests for specific versions of the specification from clients.
@@ -72,12 +78,6 @@ See the [Responses][responses] and [Error Messages][error-messages] sections.
7278

7379
[Top][toc]
7480

75-
### Authorization
76-
77-
This endpoint should be made public. Authorization is not required.
78-
79-
[Top][toc]
80-
8181
## Schema
8282

8383
See the [Endpoints](#endpoints) below for links to their specific JSON Schema documents.

‎jurisdiction/README.md‎

Lines changed: 32 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -8,9 +8,9 @@ This specification details the purpose, use cases, and schema for Jurisdictions.
88

99
- [Background](#background)
1010
- [Beta Feature](#beta-feature)
11+
- [Authorization](#authorization)
1112
- [Use Cases](#use-cases)
1213
- [Distribution](#distribution)
13-
- [REST](#rest)
1414
- [Schema](#schema)
1515
- [REST Endpoints](#rest-endpoints)
1616
- [Flat Files](#flat-files)
@@ -33,12 +33,22 @@ A jurisdiction is:
3333
- Purview to make rules over physical boundaries and modal boundaries (e.g. a jurisdiction could be for taxis only)
3434
- A way of tracking revisions in an agency's authority
3535

36+
[Top][toc]
37+
3638
## Beta Feature
3739

3840
The Jurisdictions API and all of its endpoints are marked as a [beta feature](https://github.com/openmobilityfoundation/mobility-data-specification/blob/feature-metrics/general-information.md#beta-features) starting in the 1.1.0 release. It has not been tested in real world scenarios, and may be adjusted in future releases.
3941

4042
**[Beta feature](https://github.com/openmobilityfoundation/mobility-data-specification/blob/feature-metrics/general-information.md#beta-features)**: _Yes (as of 1.1.0)_. [Leave feedback](https://github.com/openmobilityfoundation/mobility-data-specification/issues/673)
4143

44+
[Top][toc]
45+
46+
### Authorization
47+
48+
This endpoint should be made public. Authorization is not required.
49+
50+
[Top][toc]
51+
4252
## Use Cases
4353

4454
### 1. Defining boundaries and what the vehicle state `elsewhere` means
@@ -64,25 +74,13 @@ Example: A SaaS company contracts with Miami-Dade County to provide MDS. There a
6474
Example: The City of Miami has different data visualization tools from the city of Coral Gables
6575
Those tools can be granted data access from the SaaS tool based on the jurisdiction's stable identifier.
6676

67-
[Top](#table-of-contents)
77+
[Top][toc]
6878

6979
## Distribution
7080

71-
Jurisdictions can be served by agencies through the following REST API, or via [flat-files](#flat-files). Agencies should make the endpoints public and non-authenticated.
72-
73-
### REST
74-
75-
All response fields must use `lower_case_with_underscores`.
76-
77-
Responses must set the `Content-Type` header, as specified in the [Provider versioning](../provider/README.md#versioning) section. They must also specify the current API version being served in the JSON-formatted response body, under the `version` key.
78-
79-
Response bodies must be a `UTF-8` encoded JSON object.
80-
81-
#### HTTP Response Codes
81+
Jurisdictions can be served by agencies through the following REST API, or via [flat-files](#flat-files). See [Authorization](#authorization).
8282

83-
The response to a client request must include a valid HTTP status code defined in the [IANA HTTP Status Code Registry](https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml)
84-
85-
[Top](#table-of-contents)
83+
[Top][toc]
8684

8785
## Schema
8886

@@ -116,9 +114,23 @@ Formatted in JSON, a Jurisdiction object should look like this:
116114
"timestamp": Timestamp
117115
}
118116
```
117+
[Top][toc]
119118

120119
## REST Endpoints
121120

121+
### Format
122+
123+
All response fields must use `lower_case_with_underscores`.
124+
125+
Responses must set the `Content-Type` header, as specified in the [Provider versioning](../provider/README.md#versioning) section. They must also specify the current API version being served in the JSON-formatted response body, under the `version` key.
126+
127+
Response bodies must be a `UTF-8` encoded JSON object.
128+
129+
### HTTP Response Codes
130+
131+
The response to a client request must include a valid HTTP status code defined in the [IANA HTTP Status Code Registry](https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml)
132+
133+
122134
### GET /Jurisdictions
123135

124136
Gets all of an agency's Jurisdictions. Served by agencies.
@@ -150,7 +162,7 @@ Response codes:
150162
- 404 - not found
151163
- 500 - Server error
152164

153-
[Top](#table-of-contents)
165+
[Top][toc]
154166

155167
## Flat Files
156168

@@ -165,14 +177,15 @@ The publishing Agency should establish and communicate to interested parties how
165177

166178
The `updated` field in the payload wrapper should be set to the time of publishing a revision, so that it is simple to identify a changed file.
167179

168-
[Top](#table-of-contents)
180+
[Top][toc]
169181

170182
## Examples
171183

172184
See the [Jurisdiction Examples](examples/README.md) for a sample `jurisdictions.json` file.
173185

174186
See the [Geography Examples](/geography/examples/README.md) for an example `geographies.json`.
175187

176-
[Top](#table-of-contents)
188+
[Top][toc]
177189

178190
[modes]: /modes#list-of-supported-modes
191+
[toc]: #table-of-contents

‎metrics/README.md‎

Lines changed: 17 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -10,10 +10,10 @@ The Metrics API endpoints are intended to be implemented by regulatory agencies,
1010

1111
- [General Information](#general-information)
1212
- [Implementation](#implementation)
13+
- [Authorization](#authorization)
1314
- [Data Requirements](#data-requirements)
1415
- [Beta Feature](#beta-feature)
1516
- [Date and Time Format](#date-and-time-format)
16-
- [Authorization](#authorization)
1717
- [Data Redaction](#data-redaction)
1818
- [Metrics Discovery API](#metrics-discovery-api)
1919
- [Metrics Query API](#metrics-query-api)
@@ -58,6 +58,22 @@ Here are initial design use cases and scenarios for Metrics.
5858

5959
[Top][toc]
6060

61+
## Authorization
62+
63+
### For Agencies hosting the Metrics API
64+
65+
MDS Metrics endpoint producers **SHALL** provide authorization for API endpoints via a bearer token based auth system. When making requests, the endpoints expect one of two scopes `metrics:read` or `metrics:read:provider` to be present as part of the `scope` claims in a [JSON Web Token](https://jwt.io/) (JWT) `access_token` in the `Authorization` header, in the form `Authorization: Bearer <access_token>`. The token issuance, expiration and revocation policies are at the discretion of the agency. [JSON Web Token](/general-information.md#json-web-tokens) is the recommended format.
66+
67+
If a client has a `metrics:read` scope, they are permitted to read _all_ metrics available via the Metrics API.
68+
69+
If a client has a `metrics:read:provider` scope, they are only permitted to read metrics which pertain to a particular `provider_id` claim in the aforementioned [JWT](https://jwt.io/) `access_token`.
70+
71+
Further scopes and requirements may be added at the discretion of the agency, depending on their particular access control needs.
72+
73+
General authorization details are specified in the [Authorization section](/general-information.md#authorization) in MDS General Information.
74+
75+
[Top][toc]
76+
6177
## Data Requirements
6278

6379
The Metrics API does not replace required MDS Provider and Agency endpoints (e.g., [trips](/provider#trips), [events](/provider#events), [vehicles](/provider#vehicles), etc.) in any way. City regulators use disaggregated data access for policy, data validation, auditing, and operational needs, and the Metrics API is not designed to serve these purposes.
@@ -82,20 +98,6 @@ All interval durations (duration) are [ISO 8601](https://en.wikipedia.org/wiki/I
8298

8399
[Top][toc]
84100

85-
## Authorization
86-
87-
### For Agencies hosting the Metrics API
88-
89-
When making requests, the Metrics API expects one of two scopes `metrics:read` or `metrics:read:provider` to be present as part of the `scope` claims in a [JWT](https://jwt.io/) `access_token` in the `Authorization` header, in the form `Authorization: Bearer <access_token>`. The token issuance, expiration and revocation policies are at the discretion of the Agency.
90-
91-
If a client has a `metrics:read` scope, they are permitted to read _all_ metrics available via the Metrics API.
92-
93-
If a client has a `metrics:read:provider` scope, they are only permitted to read metrics which pertain to a particular `provider_id` claim in the aforementioned [JWT](https://jwt.io/) `access_token`.
94-
95-
Further scopes and requirements may be added at the discretion of the Agency, depending on their particular access control needs.
96-
97-
[Top][toc]
98-
99101
## Data Redaction
100102

101103
Some combinations of dimensions, filters, time, and geography may return a small count of trips, which could increase a privacy risk of re-identification. To correct for that, Metrics does not return data below a certain count of results. This data redaction is called k-anonymity, and the threshold is set at a k-value of 10. For more explanation of this methodology, see our [Data Redaction Guidance document](https://github.com/openmobilityfoundation/mobility-data-specification/wiki/MDS-Data-Redaction).

‎policy/README.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -10,13 +10,13 @@ This specification describes the digital relationship between _mobility as a ser
1010

1111
- [General information](#general-information)
1212
- [Background](#background)
13+
- [Authorization](#authorization)
1314
- [Update Frequency](#update-frequency)
1415
- [Updating or Ending Policies](#updating-or-ending-policies)
1516
- [Versioning](#versioning)
1617
- [Distribution](#distribution)
1718
- [REST Endpoints](#rest-endpoints)
1819
- [Responses and Error Messages](#responses-and-error-messages)
19-
- [Authorization](#authorization)
2020
- [Policies](#policies)
2121
- [Query Parameters](#query-parameters)
2222
- [Geographies](#geographies)
@@ -71,6 +71,10 @@ The machine-readable format allows Providers to obtain policies and compute comp
7171

7272
[Top][toc]
7373

74+
### Authorization
75+
76+
This endpoint should be made public. Authorization is not required.
77+
7478
### Update Frequency
7579

7680
The publishing agency should establish beforehand and communicate to providers how frequently the Policy endpoints are expected to change, how often they should be polled to get the latest information, and expectations around emergency updates.
@@ -127,10 +131,6 @@ The response to a client request must include a valid HTTP status code defined i
127131

128132
See the [Responses section][responses] for information on valid MDS response codes and the [Error Messages section][error-messages] for information on formatting error messages.
129133

130-
### Authorization
131-
132-
This endpoint should be made public. Authorization is not required.
133-
134134
### Policies
135135

136136
**Endpoint**: `/policies/{id}`

‎provider/README.md‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ This specification contains a data standard for *mobility as a service* provider
99
## Table of Contents
1010

1111
* [General Information](#general-information)
12+
* [Authorization](#authorization)
1213
* [Versioning](#versioning)
1314
* [Modes](#modes)
1415
* [Responses and Error Messages](#responses-and-error-messages)
@@ -37,12 +38,20 @@ This specification contains a data standard for *mobility as a service* provider
3738

3839
## General Information
3940

40-
The following information applies to all `provider` API endpoints. Details on providing authorization to endpoints is specified in the [auth](auth.md) document.
41+
The following information applies to all `provider` API endpoints.
4142

4243
This specification uses data types including timestamps, UUIDs, and vehicle state definitions as described in the MDS [General Information][general-information] document.
4344

4445
[Top][toc]
4546

47+
### Authorization
48+
49+
MDS Provider endpoint producers **SHALL** provide authorization for API endpoints via a bearer token based auth system. When making requests, the endpoints expect `provider_id` to be part of the claims in a [JSON Web Token](https://jwt.io/) (JWT) `access_token` in the `Authorization` header, in the form `Authorization: Bearer <access_token>`. The token issuance, expiration and revocation policies are at the discretion of the agency. [JSON Web Token](/general-information.md#json-web-tokens) is the recommended format.
50+
51+
General authorization details are specified in the [Authorization section](/general-information.md#authorization) in MDS General Information.
52+
53+
[Top][toc]
54+
4655
### Versioning
4756

4857
`provider` APIs must handle requests for specific versions of the specification from clients.

0 commit comments

Comments
 (0)