Browse Source
web: add tenant and project scoped, JWT-protected actions
web: add tenant and project scoped, JWT-protected actions
A user with the right JSON Web Token (JWT) can trigger a autohold, reenqueue or dequeue a buildset from the web API. The Token is expected to include a key called "zuul.admin" that contains a list of the tenants the user is allowed to perform these actions on. The Token must be passed as a bearer token in an Authorization header. The Token is validated thanks to authenticator declarations in Zuul's configuration file. Change-Id: Ief9088812f44368f14234ddfa25ba872526b8735changes/07/576907/66
Matthieu Huin
2 years ago
16 changed files with 1258 additions and 4 deletions
-
2doc/source/admin/client.rst
-
110doc/source/admin/components.rst
-
1doc/source/admin/index.rst
-
104doc/source/admin/tenant-scoped-rest-api.rst
-
9etc/zuul.conf-sample
-
9releasenotes/notes/admin_web_api-1331c81070a3e67f.yaml
-
6tests/base.py
-
31tests/fixtures/zuul-admin-web.conf
-
360tests/unit/test_web.py
-
7zuul/cmd/web.py
-
19zuul/driver/__init__.py
-
14zuul/driver/auth/__init__.py
-
183zuul/driver/auth/jwt.py
-
79zuul/exceptions.py
-
66zuul/lib/auth.py
-
262zuul/web/__init__.py
@ -0,0 +1,104 @@ |
|||
:title: Tenant Scoped REST API |
|||
|
|||
Tenant Scoped REST API |
|||
====================== |
|||
|
|||
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** and |
|||
**dequeue/dequeue-ref**. 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 <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 |
|||
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 |
|||
------------- |
|||
|
|||
See the Zuul Web Server component's section about enabling tenant-scoped access to |
|||
privileged actions. |
|||
|
|||
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': 'venkman' |
|||
} |
|||
|
|||
* **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': <issuer_id>, |
|||
'aud': <client_id>, |
|||
'iat': time.time(), |
|||
'exp': time.time() + 300, |
|||
'zuul': { |
|||
'admin': ['tenant-one'] |
|||
} |
|||
}, <secret>, algorithm='HS256') |
|||
'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ6dXVsIjp7ImFkbWluIjpbInRlbmFudC1vbmUiXX0sInN1YiI6InZlbmttYW4iLCJpc3MiOiJtYW51YWwiLCJleHAiOjE1NjAzNTQxOTcuMTg5NzIyLCJpYXQiOjE1NjAzNTM4OTcuMTg5NzIxLCJhdWQiOiJ6dXVsIn0.Qqb-ANmYv8slNUVSqjCJDL8HlH9L7nnLtLU2HBGzQJk' |
|||
|
|||
Online resources like https://jwt.io are also available to generate, decode and |
|||
debug JWTs. |
|||
@ -0,0 +1,9 @@ |
|||
--- |
|||
features: |
|||
- | |
|||
Add an endpoint protection mechanism to zuul-web's REST API, based on the JWT |
|||
standard. A user can access protected endpoints with a valid bearer token. |
|||
The actions associated to these endpoints are tenant-scoped via a token claim. |
|||
Zuul supports token signatures using the HS256 or RS256 algorithms. External |
|||
JWKS are also supported. |
|||
Current protected endpoints are "autohold", "enqueue" and "dequeue". |
|||
@ -0,0 +1,31 @@ |
|||
[gearman] |
|||
server=127.0.0.1 |
|||
|
|||
[scheduler] |
|||
tenant_config=main.yaml |
|||
relative_priority=true |
|||
|
|||
[merger] |
|||
git_dir=/tmp/zuul-test/merger-git |
|||
git_user_email=zuul@example.com |
|||
git_user_name=zuul |
|||
|
|||
[executor] |
|||
git_dir=/tmp/zuul-test/executor-git |
|||
|
|||
[connection gerrit] |
|||
driver=gerrit |
|||
server=review.example.com |
|||
user=jenkins |
|||
sshkey=fake_id_rsa_path |
|||
|
|||
[web] |
|||
static_cache_expiry=1200 |
|||
|
|||
[auth zuul_operator] |
|||
driver=HS256 |
|||
allow_authz_override=true |
|||
realm=zuul.example.com |
|||
client_id=zuul.example.com |
|||
issuer_id=zuul_operator |
|||
secret=NoDanaOnlyZuul |
|||
@ -0,0 +1,14 @@ |
|||
# Copyright 2019 OpenStack Foundation |
|||
# Copyright 2019 Red Hat, Inc. |
|||
# |
|||
# Licensed under the Apache License, Version 2.0 (the "License"); you may |
|||
# not use this file except in compliance with the License. You may obtain |
|||
# a copy of the License at |
|||
# |
|||
# http://www.apache.org/licenses/LICENSE-2.0 |
|||
# |
|||
# Unless required by applicable law or agreed to in writing, software |
|||
# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT |
|||
# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the |
|||
# License for the specific language governing permissions and limitations |
|||
# under the License. |
|||
@ -0,0 +1,183 @@ |
|||
# Copyright 2019 OpenStack Foundation |
|||
# Copyright 2019 Red Hat, Inc. |
|||
# |
|||
# Licensed under the Apache License, Version 2.0 (the "License"); you may |
|||
# not use this file except in compliance with the License. You may obtain |
|||
# a copy of the License at |
|||
# |
|||
# http://www.apache.org/licenses/LICENSE-2.0 |
|||
# |
|||
# Unless required by applicable law or agreed to in writing, software |
|||
# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT |
|||
# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the |
|||
# License for the specific language governing permissions and limitations |
|||
# under the License. |
|||
|
|||
import logging |
|||
import time |
|||
import jwt |
|||
import requests |
|||
import json |
|||
|
|||
from zuul import exceptions |
|||
from zuul.driver import AuthenticatorInterface |
|||
|
|||
|
|||
logger = logging.getLogger("zuul.auth.jwt") |
|||
|
|||
|
|||
class JWTAuthenticator(AuthenticatorInterface): |
|||
"""The base class for JWT-based authentication.""" |
|||
|
|||
def __init__(self, **conf): |
|||
# Common configuration for all authenticators |
|||
self.uid_claim = conf.get('uid_claim', 'sub') |
|||
self.issuer_id = conf.get('issuer_id') |
|||
self.audience = conf.get('client_id') |
|||
self.realm = conf.get('realm') |
|||
self.allow_authz_override = conf.get('allow_authz_override', False) |
|||
|
|||
def _decode(self, rawToken): |
|||
raise NotImplementedError |
|||
|
|||
def decodeToken(self, rawToken): |
|||
"""Verify the raw token and return the decoded dictionary of claims""" |
|||
try: |
|||
decoded = self._decode(rawToken) |
|||
except jwt.exceptions.InvalidSignatureError: |
|||
raise exceptions.AuthTokenInvalidSignatureException( |
|||
realm=self.realm) |
|||
except jwt.DecodeError: |
|||
raise exceptions.AuthTokenUndecodedException( |
|||
realm=self.realm) |
|||
except jwt.exceptions.ExpiredSignatureError: |
|||
raise exceptions.TokenExpiredError( |
|||
realm=self.realm) |
|||
except jwt.InvalidIssuerError: |
|||
raise exceptions.IssuerUnknownError( |
|||
realm=self.realm) |
|||
except jwt.InvalidAudienceError: |
|||
raise exceptions.IncorrectAudienceError( |
|||
realm=self.realm) |
|||
except Exception as e: |
|||
raise exceptions.AuthTokenUnauthorizedException( |
|||
realm=self.realm, |
|||
msg=e) |
|||
if not all(x in decoded for x in ['aud', 'iss', 'exp', 'sub']): |
|||
raise exceptions.MissingClaimError(realm=self.realm) |
|||
if self.uid_claim not in decoded: |
|||
raise exceptions.MissingUIDClaimError(realm=self.realm) |
|||
expires = decoded.get('exp', 0) |
|||
if expires < time.time(): |
|||
raise exceptions.TokenExpiredError(realm=self.realm) |
|||
zuul_claims = decoded.get('zuul', {}) |
|||
admin_tenants = zuul_claims.get('admin', []) |
|||
if not isinstance(admin_tenants, list): |
|||
raise exceptions.IncorrectZuulAdminClaimError(realm=self.realm) |
|||
if admin_tenants and not self.allow_authz_override: |
|||
msg = ('Issuer "%s" attempt to override User "%s" ' |
|||
'authorization denied') |
|||
logger.info(msg % (decoded['iss'], decoded[self.uid_claim])) |
|||
logger.debug('%r' % admin_tenants) |
|||
raise exceptions.UnauthorizedZuulAdminClaimError( |
|||
realm=self.realm) |
|||
if admin_tenants and self.allow_authz_override: |
|||
msg = ('Issuer "%s" attempt to override User "%s" ' |
|||
'authorization granted') |
|||
logger.info(msg % (decoded['iss'], decoded[self.uid_claim])) |
|||
logger.debug('%r' % admin_tenants) |
|||
return decoded |
|||
|
|||
def authenticate(self, rawToken): |
|||
decoded = self.decodeToken(rawToken) |
|||
return (decoded[self.uid_claim], |
|||
decoded.get('zuul', {}).get('admin', [])) |
|||
|
|||
|
|||
class HS256Authenticator(JWTAuthenticator): |
|||
"""JWT authentication using the HS256 algorithm. |
|||
|
|||
Requires a shared secret between Zuul and the identity provider.""" |
|||
|
|||
name = algorithm = 'HS256' |
|||
|
|||
def __init__(self, **conf): |
|||
super(HS256Authenticator, self).__init__(**conf) |
|||
self.secret = conf.get('secret') |
|||
|
|||
def _decode(self, rawToken): |
|||
return jwt.decode(rawToken, self.secret, issuer=self.issuer_id, |
|||
audience=self.audience, |
|||
algorithms=self.algorithm) |
|||
|
|||
|
|||
class RS256Authenticator(JWTAuthenticator): |
|||
"""JWT authentication using the RS256 algorithm. |
|||
|
|||
Requires a copy of the public key of the identity provider.""" |
|||
|
|||
name = algorithm = 'RS256' |
|||
|
|||
def __init__(self, **conf): |
|||
super(RS256Authenticator, self).__init__(**conf) |
|||
with open(conf.get('public_key')) as pk: |
|||
self.public_key = pk.read() |
|||
|
|||
def _decode(self, rawToken): |
|||
return jwt.decode(rawToken, self.public_key, issuer=self.issuer_id, |
|||
audience=self.audience, |
|||
algorithms=self.algorithm) |
|||
|
|||
|
|||
class RS256withJWKSAuthenticator(JWTAuthenticator): |
|||
"""JWT authentication using the RS256 algorithm. |
|||
|
|||
Requires the URL of the certificates used by the Identity Provier. It can |
|||
be found usually under the key "jwks_uri" at the provider's |
|||
.well-known/openid-configuration URL.""" |
|||
|
|||
algorithm = 'RS256' |
|||
name = 'RS256withJWKS' |
|||
|
|||
def __init__(self, **conf): |
|||
super(RS256withJWKSAuthenticator, self).__init__(**conf) |
|||
self.keys_url = conf.get('keys_url', None) |
|||
|
|||
def _decode(self, rawToken): |
|||
unverified_headers = jwt.get_unverified_header(rawToken) |
|||
key_id = unverified_headers.get('kid', None) |
|||
if key_id is None: |
|||
raise exceptions.JWKSException( |
|||
self.realm, 'No key ID in token header') |
|||
# TODO keys can probably be cached |
|||
try: |
|||
certs = requests.get(self.keys_url).json() |
|||
except Exception as e: |
|||
msg = 'Could not fetch Identity Provider keys at %s: %s' |
|||
logger.error(msg % (self.keys_url, e)) |
|||
raise exceptions.JWKSException( |
|||
realm=self.realm, |
|||
msg='There was an error while fetching ' |
|||
'keys for Identity Provider') |
|||
for key_dict in certs['keys']: |
|||
if key_dict.get('kid') == key_id: |
|||
key = jwt.algorithms.RSAAlgorithm.from_jwk( |
|||
json.dumps(key_dict)) |
|||
return jwt.decode(rawToken, key, issuer=self.issuer_id, |
|||
audience=self.audience, |
|||
algorithms=self.algorithm) |
|||
raise exceptions.JWKSException( |
|||
self.realm, |
|||
'Cannot verify token: public key %s ' |
|||
'not listed by Identity Provider' % key_id) |
|||
|
|||
|
|||
AUTHENTICATORS = { |
|||
'HS256': HS256Authenticator, |
|||
'RS256': RS256Authenticator, |
|||
'RS256withJWKS': RS256withJWKSAuthenticator, |
|||
} |
|||
|
|||
|
|||
def get_authenticator_by_name(name): |
|||
return AUTHENTICATORS[name] |
|||
@ -0,0 +1,66 @@ |
|||
# Copyright 2019 OpenStack Foundation |
|||
# Copyright 2019 Red Hat, Inc. |
|||
# |
|||
# Licensed under the Apache License, Version 2.0 (the "License"); you may |
|||
# not use this file except in compliance with the License. You may obtain |
|||
# a copy of the License at |
|||
# |
|||
# http://www.apache.org/licenses/LICENSE-2.0 |
|||
# |
|||
# Unless required by applicable law or agreed to in writing, software |
|||
# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT |
|||
# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the |
|||
# License for the specific language governing permissions and limitations |
|||
# under the License. |
|||
|
|||
import logging |
|||
import re |
|||
import jwt |
|||
|
|||
from zuul import exceptions |
|||
import zuul.driver.auth.jwt as auth_jwt |
|||
|
|||
|
|||
class AuthenticatorRegistry(object): |
|||
"""Registry of authenticators as they are declared in the configuration""" |
|||
|
|||
log = logging.getLogger("Zuul.AuthenticatorRegistry") |
|||
|
|||
def __init__(self): |
|||
self.authenticators = {} |
|||
self.default_realm = None |
|||
|
|||
def configure(self, config): |
|||
for section_name in config.sections(): |
|||
auth_match = re.match(r'^auth ([\'\"]?)(.*)(\1)$', |
|||
section_name, re.I) |
|||
if not auth_match: |
|||
continue |
|||
auth_name = auth_match.group(2) |
|||
auth_config = dict(config.items(section_name)) |
|||
|
|||
if 'driver' not in auth_config: |
|||
raise Exception("Auth driver needed for %s" % auth_name) |
|||
|
|||
auth_driver = auth_config['driver'] |
|||
try: |
|||
driver = auth_jwt.get_authenticator_by_name(auth_driver) |
|||
except IndexError: |
|||
raise Exception( |
|||
"Unknown driver %s for auth %s" % (auth_driver, |
|||
auth_name)) |
|||
# TODO catch config specific errors (missing fields) |
|||
self.authenticators[auth_name] = driver(**auth_config) |
|||
if auth_config.get('default', 'false').lower() == 'true': |
|||
self.default_realm = auth_config.get('realm', 'DEFAULT') |
|||
if self.default_realm is None: |
|||
self.default_realm = 'DEFAULT' |
|||
|
|||
def authenticate(self, rawToken): |
|||
unverified = jwt.decode(rawToken, verify=False) |
|||
for auth_name in self.authenticators: |
|||
authenticator = self.authenticators[auth_name] |
|||
if authenticator.issuer_id == unverified.get('iss', ''): |
|||
return authenticator.authenticate(rawToken) |
|||
# No known issuer found, use default realm |
|||
raise exceptions.IssuerUnknownError(self.default_realm) |
|||
Write
Preview
Loading…
Cancel
Save
Reference in new issue