zuul
/
zuul
Code Issues Proposed changes

Don't capitalize Token in docs 

These uses aren't proper nouns.

Change-Id: If1b217a32970a7bf06e7b7deaf53667d51190e37
This commit is contained in:
James E. Blair 2019-08-08 09:43:53 -07:00
parent 08e30b2916
commit fce1798e77
2 changed files with 18 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

24
doc/source/admin/tenant-scoped-rest-api.rst
View File

@ -19,21 +19,21 @@ JWT standard as established in this `RFC <https://tools.ietf.org/html/rfc7519>`_
Important Security Considerations
---------------------------------
Anybody with a valid Token can perform privileged actions exposed
through the REST API. Furthermore revoking Tokens, especially when manually
Anybody with a valid token can perform privileged actions exposed
through the REST API. Furthermore revoking tokens, especially when manually
issued, is not trivial.
As a mitigation, Tokens should be generated with a short time to
live, like 10 minutes or less. If the Token contains authorization Information
As a mitigation, tokens should be generated with a short time to
live, like 10 minutes or less. If the token contains authorization Information
(see the ``zuul.admin`` claim below), it should be generated with as little a scope
as possible (one tenant only) to reduce the surface of attack should the
Token be compromised.
token be compromised.
Exposing administration tasks can impact build results (dequeue-ing buildsets),
and pose potential resources problems with Nodepool if the ``autohold`` feature
is abused, leading to a significant number of nodes remaining in "hold" state for
extended periods of time. As always, "with great power comes great responsibility"
and Tokens should be handed over with discernment.
and tokens should be handed over with discernment.
Configuration
-------------
@ -60,8 +60,8 @@ authenticator similar to this one:
secret=exampleSecret
With such an authenticator, a Zuul operator can use Zuul's CLI to
issue Tokens overriding a tenant's access rules if need
be. A user can then use these Tokens with Zuul's CLI to perform protected actions
issue tokens overriding a tenant's access rules if need
be. A user can then use these tokens with Zuul's CLI to perform protected actions
on a tenant temporarily, without having to modify a tenant's access rules.
.. _jwt-format:
@ -81,12 +81,12 @@ Zuul can consume JWTs with the following minimal set of claims:
'sub': 'alice'
}
* **iss** is the issuer of the Token. It can be used to filter
* **iss** is the issuer of the token. It can be used to filter
Identity Providers.
* **aud**, as the intended audience, is usually the client id as registered on
the Identity Provider.
* **exp** is the Token's expiry timestamp.
* **iat** is the Token's date of issuance timestamp.
* **exp** is the token's expiry timestamp.
* **iat** is the token's date of issuance timestamp.
* **sub** is the default, unique identifier of the user.
JWTs can be extended arbitrarily with other claims. Zuul however can look for a
@ -101,7 +101,7 @@ in the authenticator's configuration. This claim has the following format:
}
}
The **admin** field is a list of tenants on which the Token's bearer is granted
The **admin** field is a list of tenants on which the token's bearer is granted
the right to perform privileged actions.
Manually Generating a JWT

12
doc/source/admin/tenants.rst
View File

@ -343,7 +343,7 @@ or **dequeue**.
.. note::
Rules can be overridden by the ``zuul.admin`` claim in a Token if if matches
Rules can be overridden by the ``zuul.admin`` claim in a token if if matches
an authenticator configuration where `allow_authz_override` is set to true.
See :ref:`Zuul web server's configuration <web-server-tenant-scoped-api>` for
more details.
@ -381,10 +381,10 @@ Below are some examples of how access rules can be defined:
This is the list of conditions that define a rule. A JWT must match **at
least one** of the conditions for the rule to apply. A condition is a
dictionary where keys are claims. **All** the associated values must
match the claims in the user's Token.
match the claims in the user's token.
Zuul's authorization engine will adapt matching tests depending on the
nature of the claim in the Token, eg:
nature of the claim in the token, eg:
* if the claim is a JSON list, check that the condition value is in the
claim
@ -396,10 +396,10 @@ Below are some examples of how access rules can be defined:
The special ``zuul_uid`` claim refers to the ``uid_claim`` setting in an
authenticator's configuration. By default it refers to the ``sub`` claim
of a Token. For more details see the :ref:`configuration section
of a token. For more details see the :ref:`configuration section
<web-server-tenant-scoped-api>` for Zuul web server.
Under the above example, the following Token would match rules
Under the above example, the following token would match rules
``affiliate_or_admin`` and ``alice_or_bob``:
.. code-block:: javascript
@ -417,7 +417,7 @@ Below are some examples of how access rules can be defined:
},
}
And this Token would only match rule ``affiliate_or_admin``:
And this token would only match rule ``affiliate_or_admin``:
.. code-block:: javascript