Add description of ALLOW_TOKENLESS_TENANT_ACCESS knob
Also fix typos and formatting
This commit is contained in:
Junhyun Shim
parent
bb3e8e9e5e
commit
29b89eddae
|
|
@ -8,30 +8,30 @@ 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 clients whose typical workload is limited to accessing a tenant keyspace.
|
||||
On the other hand, we have *administrators* who may read or update cluster-wide configurations through system keyspaces.
|
||||
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.
|
||||
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.
|
||||
|
||||
Privilege Levels
|
||||
----------------
|
||||
|
||||
Authorization feature extends FoundationDB's existing TLS policy to distinguish administrators from data clients,
|
||||
Authorization feature extends FoundationDB's existing TLS policy to distinguish administrators from data-plane clients,
|
||||
making TLS configuration a prerequisite for enabling authorization.
|
||||
There are only two privilege levels: *trusted* versus *untrusted* clients.
|
||||
Trusted clients are authorized to perform any operation that pre-authorization FoundationDB clients used to do, including accessing the system keyspace.
|
||||
Trusted clients are authorized to perform any operation that pre-authorization FoundationDB clients used to perform, including those accessing the system keyspace.
|
||||
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 keys <enable-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 keys <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 decribing the subnet,
|
||||
then the client's IP as seen from the server must also belong to one of the subnets.
|
||||
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>`_,
|
||||
or not belonging to the trusted subnet marks the client as untrusted.
|
||||
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 connection and eventually throttle the client.
|
||||
.. note:: Presenting a bad or untrusted certificate chain causes the server to break the client connection and eventually throttle the client.
|
||||
It does not let the client connect untrusted.
|
||||
|
||||
Access Control
|
||||
|
|
@ -40,35 +40,40 @@ Access Control
|
|||
To restrict client access only to a pertinent 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 (or `kid <https://www.rfc-editor.org/rfc/rfc7515.html#section-4.1.4>`_) of the public key which shall be used to verify itself.
|
||||
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.
|
||||
Below is the list of token fields recognized by FoundationDB.
|
||||
Note that some of the fields are *recognized* by FoundationDB but not actively used in enforcing security, pending future implementation.
|
||||
Those fields are marked as *NOT required*.
|
||||
Note that some of the fields are *recognized* by FoundationDB but not *actively used* in enforcing security, pending future implementation.
|
||||
Those fields are marked as **NOT required**.
|
||||
|
||||
=============== =========== ======== ==================================================== ===========================================================================
|
||||
Containing Part Field Name Required Purpose Reference
|
||||
=============== =========== ======== ==================================================== ===========================================================================
|
||||
Header ``typ`` YES Type of JSON Web Signature. Must be ``JWT``. `RFC7515 4.1.9 <https://www.rfc-editor.org/rfc/rfc7515#section-4.1.9>`_
|
||||
Header ``alg`` YES Algorithm used to generate the signature. Only `RFC7515 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 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 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 4.1.5 <https://www.rfc-editor.org/rfc/rfc7519#section-4.1.5>`_
|
||||
Claim ``iat`` YES Timestamp at which token was issued. `RFC7519 4.1.6 <https://www.rfc-editor.org/rfc/rfc7519#section-4.1.6>`_
|
||||
Claim ``tenants`` YES Tenants for which token holder is authorized. N/A
|
||||
Must be an array.
|
||||
Claim ``iss`` NO Issuer of the token. `RFC7519 4.1.1 <https://www.rfc-editor.org/rfc/rfc7519#section-4.1.1>`_
|
||||
Claim ``sub`` NO Subject of the token. `RFC7519 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 4.1.3 <https://www.rfc-editor.org/rfc/rfc7519#section-4.1.3>`_
|
||||
Claim ``jti`` NO String that uniquely identifies a token. `RFC7519 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 a `JWK Set <https://www.rfc-editor.org/rfc/rfc7517#section-5>`_ format and stored in a file.
|
||||
.. table:: JSON Web Token Fields supported by FoundationDB
|
||||
: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>`__
|
||||
``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>`__
|
||||
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
|
||||
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>`__
|
||||
=============== =========== ======== ==================================================== ===========================================================================
|
||||
|
||||
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.
|
||||
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.
|
||||
|
|
@ -78,19 +83,20 @@ Private keys are strongly recommended against being included in the public key s
|
|||
|
||||
.. note:: By design, FoundationDB authorization feature does not support revocation of outstanding tokens. Use extra caution in assigning long token durations.
|
||||
|
||||
Enabling clients to use Authorization Tokens
|
||||
Enabling Clients to use Authorization Tokens
|
||||
============================================
|
||||
|
||||
In order to use an untrusted client with an authorization token, a client must be configured to trust the server's CA,
|
||||
but must not be configured to use its certificates and keys. More concretely, a client's ``TLS_CA_FILE`` must include the server's root CA certificate,
|
||||
and a client must not be configured with its own ``TLS_CERTIFICATE_FILE`` or ``TLS_KEY_FILE``, neither programmatically nor by environment variable.
|
||||
but must not be configured to use the client's own certificates and keys.
|
||||
More concretely, the client's ``TLS_CA_FILE`` must include the server's root CA certificate,
|
||||
but the client must not be configured with its own ``TLS_CERTIFICATE_FILE`` or ``TLS_KEY_FILE``, neither programmatically nor by environment variable.
|
||||
Before performing a tenant data read or update, a client must set transaction option ``AUTHORIZATION_TOKEN`` with the token string as argument.
|
||||
It is the client's responsibility to keep the token up-to-date.
|
||||
It is the client's responsibility to keep the token up-to-date, by timely assigning a new token to the transaction object.
|
||||
|
||||
Public Key Rotation
|
||||
===================
|
||||
|
||||
Public key set automatically refreshes itself based on the file's latest content every ``PUBLIC_KEY_FILE_REFRESH_INTERVAL_SECONDS``.
|
||||
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.
|
||||
|
||||
Token Caching
|
||||
|
|
@ -102,3 +108,10 @@ 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,
|
||||
regardless of any key rotation that takes place thereafter.
|
||||
|
||||
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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue