mptyl/ThothII
1
0
Fork 0
Code Issues 25 Pull Requests Actions Packages Projects Releases 1 Wiki Activity
Files
cb50f5a6a4b1f117c65c42f5a0d444a4b965877d
ThothII/install/dwh-auth-server/index.html
T

160 lines
6.9 KiB
HTML
Raw Blame History

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8"/>
<meta content="IE=edge" http-equiv="X-UA-Compatible"/>
<meta content="width=device-width, initial-scale=1.0" name="viewport"/>
<link href="https://git.tylconsulting.it/thothii-docs/install/dwh-auth-server/" rel="canonical"/>
<link href="../../img/favicon.ico" rel="shortcut icon"/>
<meta content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=0" name="viewport"/>
<title>Server - ThothII Docs</title>
<link href="../../css/bootstrap-3.3.7.min.css" rel="stylesheet"/>
<link href="../../css/font-awesome-4.7.0.css" rel="stylesheet"/>
<link href="../../css/base.css" rel="stylesheet"/>
<link href="../../css/highlight.css" rel="stylesheet"/>
<link href="../../stylesheets/extra.css" rel="stylesheet"/>
<!-- HTML5 shim and Respond.js IE8 support of HTML5 elements and media queries -->
<!--[if lt IE 9]>
<script src="https://oss.maxcdn.com/libs/html5shiv/3.7.0/html5shiv.js"></script>
<script src="https://oss.maxcdn.com/libs/respond.js/1.3.0/respond.min.js"></script>
<![endif]-->
<script src="../../js/jquery-3.2.1.min.js"></script>
<script src="../../js/bootstrap-3.3.7.min.js"></script>
<script src="../../js/highlight.pack.js"></script>
<base target="_top"/>
<script>
var base_url = '../..';
var is_top_frame = false;
var pageToc = [
{title: "dwh-auth: server guide", url: "#_top", children: [
{title: "Security boundaries", url: "#security-boundaries" },
{title: "Installation", url: "#installation" },
{title: "Creating and revoking keys", url: "#creating-and-revoking-keys" },
{title: "Nginx integration", url: "#nginx-integration" },
]},
];
</script>
<script src="../../js/base.js"></script>
<script src="../../javascripts/layout-init.js"></script>
</head>
<body>
<script>
if (is_top_frame) { $('body').addClass('wm-top-page'); }
</script>
<div class="container-fluid wm-page-content">
<a name="_top"></a>
<div aria-label="navigation" class="row wm-article-nav-buttons" role="navigation">
<div class="wm-article-nav pull-right">
<a class="btn btn-xs btn-default pull-right" href="../dwh-auth-client-enrollment/">
Next
<i aria-hidden="true" class="fa fa-chevron-right"></i>
</a>
<a class="btn btn-xs btn-link" href="../dwh-auth-client-enrollment/">
Client enrollment
</a>
</div>
<div class="wm-article-nav">
<a class="btn btn-xs btn-default pull-left" href="../../usage/memory/">
<i aria-hidden="true" class="fa fa-chevron-left"></i>
Previous</a><a class="btn btn-xs btn-link" href="../../usage/memory/">
Memory
</a>
</div>
</div>
<h1 id="dwh-auth-server-guide"><code>dwh-auth</code>: server guide<a class="headerlink" href="#dwh-auth-server-guide" title="Permanent link"></a></h1>
<p><code>dwh-auth</code> protects the REST <code>/dwh/</code> route with a separate key for each ThothII installation.
It runs as a separate Linux service, does not read DWH data, and does not connect directly to
PostgreSQL.</p>
<div class="mermaid">flowchart LR
CLIENT["Installazione ThothII"] --&gt;|"X-API-Key"| NGINX["Nginx"]
NGINX --&gt; AUTH["dwh-auth\nUnix socket"]
AUTH --&gt; REGISTRY["Registro chiavi\nactive e revoked"]
AUTH --&gt;|"authorized"| REST["DWH REST"]
</div>
<h2 id="security-boundaries">Security boundaries<a class="headerlink" href="#security-boundaries" title="Permanent link"></a></h2>
<ul>
<li>A key identifies an installation, not a person.</li>
<li>Keys and backups stay in protected files and never enter Git, logs, arguments, or public JSON.</li>
<li>The registry stores digests and metadata, never the key in plaintext.</li>
<li>The REST route must be exposed only through verified TLS.</li>
</ul>
<h2 id="installation">Installation<a class="headerlink" href="#installation" title="Permanent link"></a></h2>
<p>Il servizio usa questi percorsi:</p>
<table>
<thead>
<tr>
<th>Oggetto</th>
<th>Percorso</th>
</tr>
</thead>
<tbody>
<tr>
<td>Binario</td>
<td><code>/usr/local/sbin/dwh-auth</code></td>
</tr>
<tr>
<td>Unit systemd</td>
<td><code>/etc/systemd/system/dwh-auth.service</code></td>
</tr>
<tr>
<td>Registro</td>
<td><code>/var/lib/dwh-auth/</code></td>
</tr>
<tr>
<td>Socket</td>
<td><code>/run/dwh-auth/verify.sock</code></td>
</tr>
<tr>
<td>Consegne protette</td>
<td><code>/root/dwh-auth-provision/</code></td>
</tr>
</tbody>
</table>
<p>Install the binary and unit with <code>root</code> ownership, create the <code>dwh-auth</code> service user, and enable
the unit with <code>systemctl enable --now dwh-auth</code>. The socket must be accessible to Nginx's group.</p>
<h2 id="creating-and-revoking-keys">Creating and revoking keys<a class="headerlink" href="#creating-and-revoking-keys" title="Permanent link"></a></h2>
<p>Esempio per l'installazione ACME Limited:</p>
<pre class="highlight"><code class="language-bash">sudo dwh-auth --registry-root /var/lib/dwh-auth key create \
--installation-id acme-factory-primary \
--description acme-factory-primary \
--output /root/dwh-auth-provision/acme-factory-primary.key</code></pre>
<p>Deliver the file through an enterprise vault or an authenticated channel. To rotate a key, create
a new one, distribute it, update the client, and revoke the old one using its public ID:</p>
<pre class="highlight"><code class="language-bash">sudo dwh-auth --registry-root /var/lib/dwh-auth key revoke \
--key-id PUBLIC_KEY_ID \
--reason scheduled-rotation</code></pre>
<p>Revocation is permanent. Keep encrypted registry backups before every mutation.</p>
<h2 id="nginx-integration">Nginx integration<a class="headerlink" href="#nginx-integration" title="Permanent link"></a></h2>
<p>Nginx forwards the key to the <code>dwh-auth</code> socket. Only an authorized response allows the request
to reach DWH REST. Missing, unknown, expired, or revoked keys receive <code>401</code>; an unavailable
service or registry produces <code>503</code>.</p>
<br/>
<div aria-label="navigation" class="row wm-article-nav-buttons" role="navigation">
<div class="wm-article-nav pull-right">
<a class="btn btn-xs btn-default pull-right" href="../dwh-auth-client-enrollment/">
Next
<i aria-hidden="true" class="fa fa-chevron-right"></i>
</a>
<a class="btn btn-xs btn-link" href="../dwh-auth-client-enrollment/">
Client enrollment
</a>
</div>
<div class="wm-article-nav">
<a class="btn btn-xs btn-default pull-left" href="../../usage/memory/">
<i aria-hidden="true" class="fa fa-chevron-left"></i>
Previous</a><a class="btn btn-xs btn-link" href="../../usage/memory/">
Memory
</a>
</div>
</div>
<br/>
</div>
<footer class="container-fluid wm-page-content">
<p>Documentation built with <a href="https://www.mkdocs.org/">MkDocs</a> using <a href="https://github.com/gristlabs/mkdocs-windmill">Windmill</a> theme by Grist Labs.</p>
</footer>
<script type="module">import mermaid from "https://unpkg.com/mermaid@10.4.0/dist/mermaid.esm.min.mjs";
mermaid.initialize({});</script></body>
</html>
Reference in New Issue View Git Blame Copy Permalink