diff --git a/docs/manual/_ext/webapidocs.py b/docs/manual/_ext/webapidocs.py index 6f27c70450922d63283fc2e2b8f7448886178558..f7cde07ab8969e1fd6f6d3996c6cceb4a3decca4 100644 --- a/docs/manual/_ext/webapidocs.py +++ b/docs/manual/_ext/webapidocs.py @@ -270,8 +270,10 @@ class ResourceDirective(Directive): uri_template = get_resource_uri_template(resource, not is_list) append_detail_row(tbody, "URI", nodes.literal(text=uri_template)) - # URI Parameters - #append_detail_row(tbody, "URI Parameters", '') + # Token Policy ID + if hasattr(resource, 'policy_id'): + append_detail_row(tbody, "Token Policy ID", + nodes.literal(text=resource.policy_id)) # HTTP Methods allowed_http_methods = self.get_http_methods(resource, is_list) diff --git a/docs/manual/webapi/2.0/api-token-policy.rst b/docs/manual/webapi/2.0/api-token-policy.rst new file mode 100644 index 0000000000000000000000000000000000000000..6ece050706fb4f7a8a98bb2c12516aa8368cbd30 --- /dev/null +++ b/docs/manual/webapi/2.0/api-token-policy.rst @@ -0,0 +1,142 @@ +.. _api-token-policies: + +================== +API Token Policies +================== + +.. versionadded:: 2.1 + +API tokens are used in Review Board 2.1+ to provide a safe form of +authentication for clients without exposing any user passwords. It also offers +a policy-based form of access control, limiting the capabilities of clients. + +Token policies can globally limit HTTP methods, allow or block HTTP methods +per-resource, or even allow or block them for specific resource item IDs. +Policies are written in JSON format. + +Despite the flexibility, it's easy to write custom policies. + + +Policy Sections +=============== + +All sections of a policy live in a top-level ``resources`` key: + +.. code-block:: javascript + + { + "resources": { + ... + } + } + +All policy sections will go under ``resources``. + +Each section of a token policy should specify ``allow`` and/or ``block`` +lists. These lists contain the list of all HTTP methods that are either +allowed or blocked (``"POST"``, ``"GET"``, ``"PUT"``, etc.). A special value +of ``"*"`` in the list matches all HTTP methods, which is handy for allowing +all methods by default and blocking just a few, or vice-versa. + +Any part of the API that is denied by a policy will return a +:ref:`webapi2.0-error-101` error. + + +Global Policy Section +--------------------- + +Within ``resources``, you can add a global policy section, ``"*"``, which sets +the default allowed or blocked HTTP methods for all resources: + +.. code-block:: javascript + + { + "resources": { + "*": { + "allow": [], + "block": [] + } + } + } + +For example, to only allow read-only access to the API: + +.. code-block:: javascript + + { + "resources": { + "*": { + "allow": ["GET", "HEAD", "OPTIONS"], + "block": ["*"] + } + } + } + +Global policies apply to any and all resources, unless overridden by a more +specific policy. + + +Resource Policy Sections +------------------------ + +To allow or block access to a specific resource, add a section with the +resources API policy identifier (found on any resource page in the +documentation). + +This may contain one or more sub-sections: ``"*"``, for rules applying to all +items in that resource, or ``""``, where the ID matches the ID of the +specific item in the resource that you want to limit access to. + +The resource-global policy will apply to both lists and items. + +The ID-specific policies are optional. In most cases, the resource-global +policy is all that's needed. + +.. code-block:: javascript + + { + "resources": { + "*": { + "allow": [], + "block": [] + }, + "": { + "allow": [], + "block": [] + }, + ... + } + } + +For example, to block all access to all repositories with the exception +of allowing read access to repository ID 3: + +.. code-block:: javascript + + { + "resources": { + "repository": { + "*": { + "block": ["*"] + }, + "3": { + "allow": ["GET", "HEAD", "OPTIONS"] + } + } + } + } + + +Policy Tips +=========== + +* To allow read access, you'll generally want to allow ``GET``, ``HEAD``, and + ``OPTIONS`` in the ``allow`` list. ``GET`` isn't always sufficient. + +* Clients are expected to follow links to get to a resource. Because of this, + if you're specifically allowing access to only certain resources, you will + also generally need to allow access to their parent resources. + +* You probably want to allow :ref:`webapi2.0-root-resource` and + :ref:`webapi2.0-server-info-resource`, if you're globally blocking ``GET`` + on all resource. diff --git a/docs/manual/webapi/2.0/authenticating.rst b/docs/manual/webapi/2.0/authenticating.rst index 06e2f55e8ac799f330df82769646b0f5053d19fd..339e235a813f72c2d2bac7158e03d0150f5ba324 100644 --- a/docs/manual/webapi/2.0/authenticating.rst +++ b/docs/manual/webapi/2.0/authenticating.rst @@ -7,27 +7,69 @@ Authenticating Logging In ========== -Review Board makes use of Basic HTTP Authentication for logging in. This is -new in Review Board 1.5 and makes authentication much easier to implement. +As of Review Board 2.1, there are two methods available for authenticating +using the API: Token-based authentication, and password-based authentication. +Prior to 2.1, password-based authentication was required. + +Token-based authentication is the preferred method, as it offers a safe, +secure way of providing an application or third-party service with a way to +access Review Board under your account without exposing your password. It also +offers policy-based access through +:ref:`API token policies `, which can restrict what a +client is able to do while authenticated with that token. If not logged in, any request that requires authentication will fail with -an HTTP 403 Unauthorized status. +an HTTP 403 Unauthorized status. This response will contain a +``WWW-Authenticate`` header to set ``Basic realm="Web API"``. + +Some clients, such as browsers, may choose to respond to this with a +password-based authentication request, but custom clients may use either +method. + +After a successful login, the client will receive a ``rbsessionid`` cookie +that the client should use for all further requests. The cookie will be valid +for one year. + + +Token-based Authentication +-------------------------- + +.. versionadded:: 2.1 + +Users will first need to create one or more tokens for their account. This is +done through the My Account -> API Tokens page. Simply click :guilabel:`Create +a new API token`, optionally set the policy and a description, and you're +done. + +To authenticate with a token, the client must send an ``Authorization`` header +as part of its next API request. The contents of this will be +:samp:`token {token_value}`, where ``token_value`` is the token you've chosen +from your My Account page. + +For example, if your auth token is +``8a6b5c6aa9e2f3f0a855b3275768c217b01c951c``, you would send:: + + Authorization: token 8a6b5c6aa9e2f3f0a855b3275768c217b01c951c + + +Password-based Authentication +----------------------------- -This response will contain a ``WWW-Authenticate`` header to set -``Basic realm="Web API"``. +Review Board makes use of Basic HTTP Authentication for logging in using a +user's username and password. -The client must respond with an ``Authorization`` header in the next -request to the URL. The contents of this will be :samp:`Basic {base64-auth}`. -The ``base64-auth`` part is a base64-encoded representation of the string -:samp:`{username}:{password}`. +When authenticating with Review Board (either preemptively, or in response to +an HTTP 403 Unauthorized response), the client may send an ``Authorization`` +header as part of its next API request. The contents of this will be +:samp:`Basic {base64-auth}`. The ``base64-auth`` part is a base64-encoded +representation of the string :samp:`{username}:{password}`. For example, for a username and password of ``joe`` and ``mypass``, you will base64-encode the string ``joe:mypass`` to get the resulting string -``am9lOm15cGFzcw==``, which you would then send as ``Basic am9lOm15cGFzcw==``. +``am9lOm15cGFzcw==``, which you would then send as +``Basic am9lOm15cGFzcw==``:: -After a successful login, you'll receive a ``rbsessionid`` cookie that the -client should use for all further requests. The cookie will be valid for a -year. + Authorization: Basic am9lOm15cGFzcw== Logging Out diff --git a/docs/manual/webapi/2.0/index.rst b/docs/manual/webapi/2.0/index.rst index d2202580613d04002a55f30f4a50ceb61b04fdec..eb17a198d29b1325d01e73ec6552b030194671f4 100644 --- a/docs/manual/webapi/2.0/index.rst +++ b/docs/manual/webapi/2.0/index.rst @@ -8,6 +8,7 @@ REST API 2.0 overview authenticating + api-token-policy resources/index errors/index glossary