Merge pull request #835 from openmobilityfoundation/feature-authoriza…

…tion

Consolidating authorization across APIs

agency/README.md

@@ -9,10 +9,10 @@ This specification contains a collection of RESTful APIs used to specify the dig
 ## Table of Contents
 
 * [General Information](#general-information)
+  * [Authorization](#authorization)
   * [Versioning](#versioning)
   * [Modes](#modes)
   * [Responses and Error Messages](#responses-and-error-messages)
-  * [Authorization](#authorization)
   * [GBFS](#gbfs)
 * [Vehicles](#vehicles)
   * [Vehicle - Status](#vehicle---status)
@@ -34,6 +34,14 @@ This specification uses data types including timestamps, UUIDs, and vehicle stat
 
 [Top][toc]
 
+### Authorization
+
+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.
+
+General authorization details are specified in the [Authorization section](/general-information.md#authorization) in MDS General Information.
+
+[Top][toc]
+
 ### Versioning
 
 `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.
 
 [Top][toc]
 
-### Authorization
-
-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.
-
-[Top][toc]
-
 ### GBFS
 
 See the [GBFS Requirement](/README.md#gbfs-requirement) language for more details.

general-information.md

@@ -4,7 +4,7 @@ This document contains specifications that are shared between the various MDS [A
 
 ## Table of Contents
 
-- [Authentication](#authentication)
+- [Authorization](#authorization)
 - [Beta Features](#beta-features)
 - [Costs and Currencies](#costs-and-currencies)
 - [Data Types](#data-types)
@@ -25,11 +25,49 @@ This document contains specifications that are shared between the various MDS [A
 - [Vehicle States](#vehicle-states)
 - [Versioning](#versioning)
 
-## Authentication
+## Authorization
+
+Outlines shared authorization details and methods across all MDS APIs.
+
+### Endpoint Requirements  
+
+All MDS Provider, Agency, and Metrics APIs require authentication, as outlined.
 
 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.
 
-All other MDS APIs require authentication, as outlined.
+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. 
+
+### Header
+
+The `Authorization` header is sent as part of an HTTP request. Example:
+
+```
+GET /trips HTTP/1.1
+Host: api.provider.co
+Authorization: Bearer <token>
+```
+
+More info on how to document [Bearer Auth in swagger](https://swagger.io/docs/specification/authentication/bearer-authentication/).
+
+### JSON Web Tokens
+
+JSON Web Token ([JWT](https://jwt.io/introduction/)) is **RECOMMENDED** as the token format.
+
+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.
+
+> 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.
+
+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.
+
+JWT provides a helpful [debugger](https://jwt.io/#debugger) for testing your token and verifying security.
+
+### OAuth 2.0
+
+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.
+
+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.
+
+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.
 
 [Top][toc]
 

geography/README.md

@@ -11,11 +11,11 @@ Geographical data will be stored as GeoJSON and read from either `geographies.js
 ## Table of Contents
 
 * [General Information](#general-information)
+  * [Authorization](#authorization)
   * [Versioning](#versioning)
 * [Distribution](#distribution)
   * [Flat Files](#flat-files)
   * [Response Format](#response-format)
-  * [Authorization](#authorization)
 * [Schema](#schema)
   * [Geography Fields](#geography-fields)
   * [Previous Geographies](#previous-geographies)
@@ -32,6 +32,12 @@ The following information applies to all `geography` API endpoints.
 
 [Top][toc]
 
+### Authorization
+
+This endpoint should be made public. Authorization is not required.
+
+[Top][toc]
+
 ### Versioning
 
 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.
 
 [Top][toc]
 
-### Authorization
-
-This endpoint should be made public. Authorization is not required.
-
-[Top][toc]
-
 ## Schema
 
 See the [Endpoints](#endpoints) below for links to their specific JSON Schema documents.

jurisdiction/README.md

@@ -8,9 +8,9 @@ This specification details the purpose, use cases, and schema for Jurisdictions.
 
 - [Background](#background)
 - [Beta Feature](#beta-feature)
+- [Authorization](#authorization)
 - [Use Cases](#use-cases)
 - [Distribution](#distribution)
-  - [REST](#rest)
 - [Schema](#schema)
 - [REST Endpoints](#rest-endpoints)
 - [Flat Files](#flat-files)
@@ -33,12 +33,22 @@ A jurisdiction is:
 - Purview to make rules over physical boundaries and modal boundaries (e.g. a jurisdiction could be for taxis only)
 - A way of tracking revisions in an agency's authority
 
+[Top][toc]
+
 ## Beta Feature
 
 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.
 
 **[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) 
 
+[Top][toc]
+
+### Authorization
+
+This endpoint should be made public. Authorization is not required.
+
+[Top][toc]
+
 ## Use Cases
 
 ### 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
 Example: The City of Miami has different data visualization tools from the city of Coral Gables
 Those tools can be granted data access from the SaaS tool based on the jurisdiction's stable identifier.
 
-[Top](#table-of-contents)
+[Top][toc]
 
 ## Distribution
 
-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.
-
-### REST
-
-All response fields must use `lower_case_with_underscores`.
-
-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.
-
-Response bodies must be a `UTF-8` encoded JSON object.
-
-#### HTTP Response Codes
+Jurisdictions can be served by agencies through the following REST API, or via [flat-files](#flat-files). See [Authorization](#authorization).
 
-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)
-
-[Top](#table-of-contents)
+[Top][toc]
 
 ## Schema
 
@@ -116,9 +114,23 @@ Formatted in JSON, a Jurisdiction object should look like this:
 	"timestamp": Timestamp
 }
 ```
+[Top][toc]
 
 ## REST Endpoints
 
+### Format
+
+All response fields must use `lower_case_with_underscores`.
+
+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.
+
+Response bodies must be a `UTF-8` encoded JSON object.
+
+### HTTP Response Codes
+
+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)
+
+
 ### GET /Jurisdictions
 
 Gets all of an agency's Jurisdictions. Served by agencies.
@@ -150,7 +162,7 @@ Response codes:
 - 404 - not found
 - 500 - Server error
 
-[Top](#table-of-contents)
+[Top][toc]
 
 ## Flat Files
 
@@ -165,14 +177,15 @@ The publishing Agency should establish and communicate to interested parties how
 
 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.
 
-[Top](#table-of-contents)
+[Top][toc]
 
 ## Examples
 
 See the [Jurisdiction Examples](examples/README.md) for a sample `jurisdictions.json` file. 
 
 See the [Geography Examples](/geography/examples/README.md) for an example `geographies.json`.
 
-[Top](#table-of-contents)
+[Top][toc]
 
 [modes]: /modes#list-of-supported-modes
+[toc]: #table-of-contents

metrics/README.md

@@ -10,10 +10,10 @@ The Metrics API endpoints are intended to be implemented by regulatory agencies,
 
 - [General Information](#general-information)
 - [Implementation](#implementation)
+- [Authorization](#authorization)
 - [Data Requirements](#data-requirements)
 - [Beta Feature](#beta-feature)
 - [Date and Time Format](#date-and-time-format)
-- [Authorization](#authorization)
 - [Data Redaction](#data-redaction)
 - [Metrics Discovery API](#metrics-discovery-api)
 - [Metrics Query API](#metrics-query-api)
@@ -58,6 +58,22 @@ Here are initial design use cases and scenarios for Metrics.
 
 [Top][toc]
 
+## Authorization
+
+### For Agencies hosting the Metrics API
+
+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.
+
+If a client has a `metrics:read` scope, they are permitted to read _all_ metrics available via the Metrics API.
+
+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`.
+
+Further scopes and requirements may be added at the discretion of the agency, depending on their particular access control needs.
+
+General authorization details are specified in the [Authorization section](/general-information.md#authorization) in MDS General Information.
+
+[Top][toc]
+
 ## Data Requirements
 
 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
 
 [Top][toc]
 
-## Authorization
-
-### For Agencies hosting the Metrics API
-
-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.
-
-If a client has a `metrics:read` scope, they are permitted to read _all_ metrics available via the Metrics API.
-
-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`.
-
-Further scopes and requirements may be added at the discretion of the Agency, depending on their particular access control needs.
-
-[Top][toc]
-
 ## Data Redaction
 
 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

@@ -10,13 +10,13 @@ This specification describes the digital relationship between _mobility as a ser
 
 - [General information](#general-information)
   - [Background](#background)
+  - [Authorization](#authorization)
   - [Update Frequency](#update-frequency)
   - [Updating or Ending Policies](#updating-or-ending-policies)
   - [Versioning](#versioning)
   - [Distribution](#distribution)
 - [REST Endpoints](#rest-endpoints)
   - [Responses and Error Messages](#responses-and-error-messages)
-  - [Authorization](#authorization)
   - [Policies](#policies)
     - [Query Parameters](#query-parameters)
   - [Geographies](#geographies)
@@ -71,6 +71,10 @@ The machine-readable format allows Providers to obtain policies and compute comp
 
 [Top][toc]
 
+### Authorization
+
+This endpoint should be made public. Authorization is not required.
+
 ### Update Frequency
 
 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
 
 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.
 
-### Authorization
-
-This endpoint should be made public. Authorization is not required.
-
 ### Policies
 
 **Endpoint**: `/policies/{id}`  

provider/README.md

@@ -9,6 +9,7 @@ This specification contains a data standard for *mobility as a service* provider
 ## Table of Contents
 
 * [General Information](#general-information)
+  * [Authorization](#authorization)
   * [Versioning](#versioning)
   * [Modes](#modes)
   * [Responses and Error Messages](#responses-and-error-messages)
@@ -37,12 +38,20 @@ This specification contains a data standard for *mobility as a service* provider
 
 ## General Information
 
-The following information applies to all `provider` API endpoints. Details on providing authorization to endpoints is specified in the [auth](auth.md) document.
+The following information applies to all `provider` API endpoints. 
 
 This specification uses data types including timestamps, UUIDs, and vehicle state definitions as described in the MDS [General Information][general-information] document.
 
 [Top][toc]
 
+### Authorization
+
+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.
+
+General authorization details are specified in the [Authorization section](/general-information.md#authorization) in MDS General Information.
+
+[Top][toc]
+
 ### Versioning
 
 `provider` APIs must handle requests for specific versions of the specification from clients.