:title: Authenticated Actions .. _authentication: Authenticated Actions ===================== Users can perform some privileged actions at the tenant level through protected endpoints of the REST API, if these endpoints are activated. The supported actions are **autohold**, **enqueue/enqueue-ref**, **dequeue/dequeue-ref** and **promote**. These are similar to the ones available through Zuul's CLI. The protected endpoints require a bearer token, passed to Zuul Web Server as the **Authorization** header of the request. The token and this workflow follow the JWT standard as established in this `RFC `_. Important Security Considerations --------------------------------- 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 (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. 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. Configuration ------------- .. important:: In order to use admin commands in the zuul command line interface, at least one HS256 authenticator should be configured. To enable tenant-scoped access to privileged actions, see the Zuul Web Server component's section. To set access rules for a tenant, see :ref:`the documentation about tenant definition `. Most of the time, only one authenticator will be needed in Zuul's configuration; namely the configuration matching a third party identity provider service like dex, auth0, keycloak or others. It can be useful however to add another authenticator similar to this one: .. code-block:: ini [auth zuul_operator] driver=HS256 allow_authz_override=true realm=zuul.example.com client_id=zuul.example.com issuer_id=zuul_operator 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 on a tenant temporarily, without having to modify a tenant's access rules. .. _jwt-format: JWT Format ---------- Zuul can consume JWTs with the following minimal set of claims: .. code-block:: javascript { 'iss': 'jwt_provider', 'aud': 'my_zuul_deployment', 'exp': 1234567890, 'iat': 1234556780, 'sub': 'alice' } * **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. * **sub** is the default, unique identifier of the user. JWTs can be extended arbitrarily with other claims. Zuul however can look for a specific **zuul** claim, if the ``allow_authz_override`` option was set to True in the authenticator's configuration. This claim has the following format: .. code-block:: javascript { 'zuul': { 'admin': ['tenant-one', 'tenant-two'] } } 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 ------------------------- An operator can generate a JWT by using the settings of a configured authenticator in ``zuul.conf``. For example, in Python, and for an authenticator using the ``HS256`` algorithm: .. code-block:: python >>> import jwt >>> import time >>> jwt.encode({'sub': 'user1', 'iss': , 'aud': , 'iat': time.time(), 'exp': time.time() + 300, 'zuul': { 'admin': ['tenant-one'] } }, , algorithm='HS256') 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ6dXVsIjp7ImFkbWluIjpbInRlbmFudC1vbmUiXX0sInN1YiI6InZlbmttYW4iLCJpc3MiOiJtYW51YWwiLCJleHAiOjE1NjAzNTQxOTcuMTg5NzIyLCJpYXQiOjE1NjAzNTM4OTcuMTg5NzIxLCJhdWQiOiJ6dXVsIn0.Qqb-ANmYv8slNUVSqjCJDL8HlH9L7nnLtLU2HBGzQJk' Online resources like https://jwt.io are also available to generate, decode and debug JWTs. Debugging --------- If problems appear: * Make sure your configuration is correct, especially callback URIs. * More information can be found in Zuul's web service logs. * From the user's side, activating the web console in the browser can be helpful to debug API calls. Interfacing with Other Systems ------------------------------ Here are some how-tos to help administrators enable OpenID Connect authentication in Zuul and Zuul's Web UI. .. toctree:: :maxdepth: 1 howtos/openid-with-google howtos/openid-with-keycloak howtos/openid-with-microsoft tutorials/keycloak