wbtiger
/
foundationdb
mirror of https://github.com/apple/foundationdb.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Further formatting and phrasing changes

This commit is contained in:
Junhyun Shim 2022-09-15 08:13:21 +02:00
parent e6e67a271c
commit f57c5f1f16
1 changed files with 30 additions and 28 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

58
documentation/sphinx/source/authorization.rst
View File

@ -9,7 +9,7 @@ Introduction
:ref:`Multi-tenant <multi-tenancy>` database implies a couple of new concepts that did not previously exist in FoundationDB.
The first is the concept of privilege levels: we have *data-plane clients* whose typical workload is limited to accessing a tenant keyspace.
On the other hand, we have *control-plane clients* or *administrators* who may read or update cluster-wide configurations through system keyspaces.
On the other hand, we have *control-plane clients* or *administrators* who may read or update cluster-wide configurations through system keyspace.
These operations also include creation and deletion of tenants.
The second is access control: with multiple tenant keyspaces, it comes naturally that we would want to restrict database access of a client to a subset of them.
@ -23,12 +23,12 @@ Trusted clients are authorized to perform any operation that pre-authorization F
Untrusted clients may only request what is necessary to access tenant keyspaces for which they are authorized.
Untrusted clients are blocked from accessing anything in the system keyspace or issuing management operations that modifies the cluster in any way.
In order to be considered a trusted client, a client needs to be :ref:`configured with a valid chain of X.509 certificates and a private key matching the leaf certificate <configuring-tls>`,
In order to be considered a trusted client, a client needs to be :ref:`configured with a valid chain of X.509 certificates and a private key <configuring-tls>`,
and its certificate chain must be trusted by the server.
If the server was configured with trusted IP subnets, i.e. run with one or more ``--trusted-subnet-SUBNET_NAME`` followed by a CIDR block describing the subnet,
then the client's IP as seen from the server must additionally belong to one of the subnets.
Choosing to respond with empty certificate chain during `client authentication <https://www.rfc-editor.org/rfc/rfc5246#section-7.4.6>`_,
Choosing to respond with an empty certificate chain during `client authentication <https://www.rfc-editor.org/rfc/rfc5246#section-7.4.6>`_,
or not belonging to one of the trusted subnets marks the client as untrusted.
.. note:: Presenting a bad or untrusted certificate chain causes the server to break the client connection and eventually throttle the client.
@ -37,7 +37,7 @@ or not belonging to one of the trusted subnets marks the client as untrusted.
Access Control
--------------
To restrict client access only to a pertinent subset of tenant keyspaces, authorization feature allows database administrators
To restrict untrusted client's database access to a subset of tenant keyspaces, authorization feature allows database administrators
to grant tenant-scoped access in the form of `JSON Web Tokens <https://www.rfc-editor.org/rfc/rfc7519>`_.
Token verification is performed against a set of named public keys written in `JWK Set <https://www.rfc-editor.org/rfc/rfc7517#section-5>`_ format.
A token's header part must contain the `key identifier <https://www.rfc-editor.org/rfc/rfc7515.html#section-4.1.4>`_ of the public key which shall be used to verify the token itself.
@ -50,38 +50,39 @@ Those fields are marked as **NOT required**.
:align: left
:widths: auto
=============== =========== ======== ==================================================== ===========================================================================
=============== =========== ======== ==================================================== ================================================================================
Containing Part Field Name Required Purpose Reference
=============== =========== ======== ==================================================== ===========================================================================
Header ``typ`` Yes Type of JSON Web Signature. Must be ``JWT``. `RFC7515 <https://www.rfc-editor.org/rfc/rfc7515#section-4.1.9>`__
Header ``alg`` Yes Algorithm used to generate the signature. Only `RFC7515 <https://www.rfc-editor.org/rfc/rfc7515#section-4.1.1>`__
=============== =========== ======== ==================================================== ================================================================================
Header ``typ`` Yes Type of JSON Web Signature. Must be ``JWT``. `RFC7519 Section 5.1 <https://www.rfc-editor.org/rfc/rfc7519#section-5.1>`_
Header ``alg`` Yes Algorithm used to generate the signature. Only `RFC7515 Section 4.1.1 <https://www.rfc-editor.org/rfc/rfc7515#section-4.1.1>`_
``ES256`` and ``RS256`` are supported.
Must match the ``alg`` attribute of public key.
Header ``kid`` Yes Name of public key with which to verify the token. `RFC7515 <https://www.rfc-editor.org/rfc/rfc7515#section-4.1.4>`__
Header ``kid`` Yes Name of public key with which to verify the token. `RFC7515 Section 4.1.4 <https://www.rfc-editor.org/rfc/rfc7515#section-4.1.4>`_
Must match the ``kid`` attribute of public key.
Claim ``exp`` Yes Timestamp after which token is not accepted. `RFC7519 <https://www.rfc-editor.org/rfc/rfc7519#section-4.1.4>`__
Claim ``nbf`` Yes Timestamp before which token is not accepted. `RFC7519 <https://www.rfc-editor.org/rfc/rfc7519#section-4.1.5>`__
Claim ``iat`` Yes Timestamp at which token was issued. `RFC7519 <https://www.rfc-editor.org/rfc/rfc7519#section-4.1.6>`__
Claim ``tenants`` Yes Tenants for which token holder is authorized. N/A
Claim ``exp`` Yes Timestamp after which token is not accepted. `RFC7519 Section 4.1.4 <https://www.rfc-editor.org/rfc/rfc7519#section-4.1.4>`_
Claim ``nbf`` Yes Timestamp before which token is not accepted. `RFC7519 Section 4.1.5 <https://www.rfc-editor.org/rfc/rfc7519#section-4.1.5>`_
Claim ``iat`` Yes Timestamp at which token was issued. `RFC7519 Section 4.1.6 <https://www.rfc-editor.org/rfc/rfc7519#section-4.1.6>`_
Claim ``tenants`` Yes Tenants names for which token holder is authorized. N/A
Must be an array.
Claim ``iss`` No Issuer of the token. `RFC7519 <https://www.rfc-editor.org/rfc/rfc7519#section-4.1.1>`__
Claim ``sub`` No Subject of the token. `RFC7519 <https://www.rfc-editor.org/rfc/rfc7519#section-4.1.2>`__
Claim ``aud`` No Intended recipients of the token. Must be an array. `RFC7519 <https://www.rfc-editor.org/rfc/rfc7519#section-4.1.3>`__
Claim ``jti`` No String that uniquely identifies a token. `RFC7519 <https://www.rfc-editor.org/rfc/rfc7519#section-4.1.7>`__
=============== =========== ======== ==================================================== ===========================================================================
Claim ``iss`` No Issuer of the token. `RFC7519 Section 4.1.1 <https://www.rfc-editor.org/rfc/rfc7519#section-4.1.1>`_
Claim ``sub`` No Subject of the token. `RFC7519 Section 4.1.2 <https://www.rfc-editor.org/rfc/rfc7519#section-4.1.2>`_
Claim ``aud`` No Intended recipients of the token. Must be an array. `RFC7519 Section 4.1.3 <https://www.rfc-editor.org/rfc/rfc7519#section-4.1.3>`_
Claim ``jti`` No String that uniquely identifies a token. `RFC7519 Section 4.1.7 <https://www.rfc-editor.org/rfc/rfc7519#section-4.1.7>`_
=============== =========== ======== ==================================================== ================================================================================
Keys with which to verify the token must be serialized in `JWK Set <https://www.rfc-editor.org/rfc/rfc7517#section-5>`_ format and stored in a file.
Public keys with which to verify the token must be serialized in `JWK Set <https://www.rfc-editor.org/rfc/rfc7517#section-5>`_ format and stored in a file.
The location of the key set file must be passed as command line argument ``--authorization-public-key-file`` to the ``fdbserver`` executable.
Public keys in the set must be either `RSA <https://datatracker.ietf.org/doc/html/rfc7518#section-6.3>`_ public keys
containing ``n`` and ``e`` parameters, each containing `Base64urlUInt <https://www.rfc-editor.org/rfc/rfc7518#section-2>`_-encoded modulus and exponent,
or `Elliptic Curve <https://datatracker.ietf.org/doc/html/rfc7518#section-6.2>`_ public keys on a ``P-256`` curve,
where ``crv`` parameter is set to ``P-256`` and ``x`` and ``y`` parameters contain
`base64url <https://datatracker.ietf.org/doc/html/rfc4648#section-5>`_-encoded affine coordinates.
In addition, each public key JSON object in set must contain ``kty`` (set to ``EC`` or ``RSA``) field to indicate public key algorithm,
In addition, each public key JSON object in set must contain ``kty`` (set to either ``EC`` or ``RSA``) field to indicate public key algorithm,
along with ``kid``, and ``alg`` fields to be compared against their token header counterparts.
Private keys are strongly recommended against being included in the public key set and, if found, are excluded from consideration.
.. note:: By design, FoundationDB authorization feature does not support revocation of outstanding tokens. Use extra caution in assigning long token durations.
.. note:: By design, FoundationDB authorization feature does not support revocation of outstanding tokens.
Use extra caution in signing tokens with long token durations.
Enabling Clients to use Authorization Tokens
============================================
@ -96,14 +97,14 @@ It is the client's responsibility to keep the token up-to-date, by timely assign
Public Key Rotation
===================
FoundationDB's internal public key set automatically refreshes itself based on the file's latest content every ``PUBLIC_KEY_FILE_REFRESH_INTERVAL_SECONDS`` seconds.
The in-memory set of public keys does not update unless the key file is a correct JWK set.
FoundationDB's internal public key set automatically refreshes itself based on the key set file's latest content every ``PUBLIC_KEY_FILE_REFRESH_INTERVAL_SECONDS`` seconds.
The in-memory set of public keys does not update unless the key file holds a correct `JWK Set`_.
Token Caching
=============
In a single-threaded runtime environment such as FoundationDB, it is important not to let the main thread be bogged down by computationally expensive operations,
such as cryptographic signature verification. FoundationDB internally caches the tokens that are considered valid at the time of verification in a fixed-size LRU cache,
In a single-threaded runtime environment such as FoundationDB, it is important not to let the main thread be overloaded with computationally expensive operations,
such as token signature verification. FoundationDB internally caches the tokens that are considered valid at the time of verification in a fixed-size cache,
whose size may be configured using ``TOKEN_CACHE_SIZE`` knob.
.. note:: Token cache is independent of the active public key set. Once the token reaches the cache, it is valid until its expiration time,
@ -112,6 +113,7 @@ whose size may be configured using ``TOKEN_CACHE_SIZE`` knob.
Allowing Untrusted Clients to Access Tenant Data Without Tokens
===============================================================
Rolling out a public key distribution infrastructure and an authorization-enabled FoundationDB in lockstep is not an easy feat.
To support incremental rollout, FoundationDB introduces a ``ALLOW_TOKENLESS_TENANT_ACCESS`` boolean knob,
which preserves the TLS-based privilege level policy without clients having to set authorization tokens to their transactions in order to access tenant data.
Rolling out a public key distribution infrastructure and an authorization-enabled FoundationDB cluster in lockstep might not be feasible with large scale distributed systems.
To support incremental rollout, authorization feature introduces ``ALLOW_TOKENLESS_TENANT_ACCESS`` boolean knob,
which preserves the TLS-based privilege level policy without untrusted clients having to set authorization tokens to their transactions in order to access tenant data.
With this knob active, any authorization token assigned to the client transaction is simply ignored.