Skip to content
This repository has been archived by the owner on Jul 23, 2024. It is now read-only.

Commit

Permalink
ENG-7519: Update Approzium with latest dependencies (#235)
Browse files Browse the repository at this point in the history
Co-authored-by: Eric Freilafert <efreilafert@cyral.com>
  • Loading branch information
VictorGFM and efreila authored Jan 20, 2022
1 parent 1a62a98 commit 5922c15
Show file tree
Hide file tree
Showing 25 changed files with 5,099 additions and 7,866 deletions.
6 changes: 6 additions & 0 deletions docs/.prettierrc
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
{
"semi": false,
"singleQuote": true,
"printWidth": 100,
"arrowParens": "avoid"
}
2 changes: 1 addition & 1 deletion docs/babel.config.js
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
module.exports = {
presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
};
}
20 changes: 12 additions & 8 deletions docs/docs/architecture.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -6,15 +6,19 @@ import Image from '@theme/IdealImage';

A system using Approzium for database connection comprises these components:

* **Application** - Application that accesses a database and is running on a cloud platform that provides cloud IAM services. It establishes the database connection using the Approzium SDK.
* **Database** - The database that the service wants to connect to.
* **IAM Service** - IAM service provided by the cloud platform the service is using. It handles requests such as verifying the service's identity. For example, in AWS, this is called the [STS](https://docs.aws.amazon.com/STS/latest/APIReference/welcome.html).
* **Secrets Manager** - Secure storage where database credentials are stored. Examples include Hashicorp Vault, AWS Secrets Manager, Google Cloud Secret Manager, Azure Key Vault, and Kubernetes Secrets.
* **Approzium Authenticator** - Approzium service that interfaces with the Approzium SDK and with the secrets manager. This service verifies the service's identity, retrieves the credentials from the secrets manager, and calculates the authentication challenge response.
- **Application** - Application that accesses a database and is running on a cloud platform that provides cloud IAM services. It establishes the database connection using the Approzium SDK.
- **Database** - The database that the service wants to connect to.
- **IAM Service** - IAM service provided by the cloud platform the service is using. It handles requests such as verifying the service's identity. For example, in AWS, this is called the [STS](https://docs.aws.amazon.com/STS/latest/APIReference/welcome.html).
- **Secrets Manager** - Secure storage where database credentials are stored. Examples include Hashicorp Vault, AWS Secrets Manager, Google Cloud Secret Manager, Azure Key Vault, and Kubernetes Secrets.
- **Approzium Authenticator** - Approzium service that interfaces with the Approzium SDK and with the secrets manager. This service verifies the service's identity, retrieves the credentials from the secrets manager, and calculates the authentication challenge response.

Here is the connection sequence for such a system:
<Image img={require('./images/architecture-diagram.png')} />
<br/>

<br />
<Image img={require('/img/architecture-diagram.png')} />
<br />
<br />


1. The SDK initiates connection to the database server. The initial startup sequence varies for different databases but generally includes providing the database user used by the application as well as negotiating the authentication method.
2. The database server responds with an authentication challenge. Typically, the challenge includes some randomized data that is used by the client to calculate the correct response hash.
Expand All @@ -23,6 +27,6 @@ Here is the connection sequence for such a system:
5. The Approzium Authenticator verifies the application's identity by checking the proof provided by the application with the IAM service.
6. The Approzium Authenticator obtains the cleartext password for the requested database server from the secrets manager. The password is stored in the secrets manager along with a set of IAM roles allowed to access it, and the authenticator checks that the application's IAM role exists in this set before proceeding.
7. The Approzium Authenticator uses the cleartext password and the authentication challenge data to calculate the authentication response hash expected by the database and sends it to the SDK.
8. The Approzium SDK simply forwards the authentication response hash to the database.
8. The Approzium SDK simply forwards the authentication response hash to the database.

After that, your connection is successfully established! 😄
118 changes: 57 additions & 61 deletions docs/docs/configuration.mdx

Large diffs are not rendered by default.

3 changes: 2 additions & 1 deletion docs/docs/installation.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -48,12 +48,13 @@ Start-Process -Filepath "$PSScriptRoot/authenticator.exe" -ArgumentList $args
```

## Docker

```
docker run approzium/authenticator:latest
```

## Terraform 0.12 and Above

To speed you up, we offer stock Terraform configs for deploying the Approzium Authenticator. They live
[in our Github repo](https://github.com/cyralinc/approzium/tree/develop/terraform). We would also like
[in our Github repo](https://github.com/cyralinc/approzium/tree/main/terraform). We would also like
to add support for GCP and Azure, and we welcome community contributions.
3 changes: 2 additions & 1 deletion docs/docs/overview.md → docs/docs/overview.mdx
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
---
title: Overview
slug: /
---

import Image from '@theme/IdealImage';
Expand Down Expand Up @@ -40,7 +41,7 @@ Approzium is developed by the engineering team at Cyral and is available under t
## Overview
Approzium comprises two components that are deployed independently -- an SDK that runs as part of the application code, and a standalone service called the Authenticator with which the SDK interacts on behalf of the application.

<Image img={require('./images/overview-diagram.png')} />
<Image img={require('/img/overview-diagram.png')} />

Together, the SDK and Authenticator provide observability and security benefits to the application. The SDK has the ability to query infrastructure metadata services native to the various cloud platforms, and to orchestration frameworks such as Kubernetes to generate rich execution time context about the application.

Expand Down
14 changes: 11 additions & 3 deletions docs/docs/quickstart.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ title: Quickstart
---

This guide will show you how to:

- Deploy the Authenticator.
- Store database credentials in Vault to be retrieved by the Authenticator.
- Connect to a Postgres database through the Approzium Python SDK.
Expand All @@ -12,7 +13,7 @@ This guide will show you how to:
- Head to [our latest release](https://github.com/cyralinc/approzium/releases/latest)
- Choose the appropriate binary for your operating system, and run it with a set of commands like:

```
```shell
curl -LO https://github.com/cyralinc/approzium/releases/download/v0.2.0/darwin_amd64.zip
unzip darwin_amd64.zip

Expand All @@ -25,8 +26,10 @@ For availability, we recommend running the Authenticator in a long-running envir
than in a short-lived environment (like in AWS Lambda).

### Storing Credentials in Vault

The Authenticator expects credentials for a single database user as a secret stored against the database user as the key.
The secret contains the database password and a set of IAM roles allowed to access the credentials in the following structure.

```shell
cat dbuser1-creds.json
{
Expand All @@ -44,25 +47,30 @@ For database access to be granted to a caller, the caller's exact `iam_arn` must
For assumed roles, either the role ARN or the assumed role ARN may be used to grant access.

Enable Vault KV Version 1 (see [Vault documentation](https://www.vaultproject.io/docs/secrets/kv/kv-v1) for more information).

```shell
vault secrets enable -path=approzium -version=1 kv
```

Put the secret at path `approzium/<DATABASE_HOST:DATABASE_PORT>` with your database user as the key.

```shell
vault write approzium/1.2.3.4:5432 @dbuser1-creds.json
```

## SDK Usage

### Python

Install the SDK in your client.

```shell
pip3 install 'approzium[sqllibs]'
```

Connect to your database as follows. (Note: TLS should **not** be disabled in production environments,
see [our Python guide](https://approzium.readthedocs.io/en/latest/api.html#approzium.AuthClient) for how to configure them.)

```python
from approzium import AuthClient
from approzium.psycopg2 import connect
Expand All @@ -82,11 +90,11 @@ cur.execute('SELECT 1')

The Approzium Go SDK currently supports MD5 authentication to Postgres.

```
```shell
go get github.com/cyralinc/approzium
```

```
```go
package main

import (
Expand Down
119 changes: 65 additions & 54 deletions docs/docusaurus.config.js
Original file line number Diff line number Diff line change
@@ -1,73 +1,84 @@
module.exports = {
// @ts-check
// Note: type annotations allow type checking and IDEs autocompletion

const lightCodeTheme = require('prism-react-renderer/themes/github')
const darkCodeTheme = require('prism-react-renderer/themes/dracula')

/** @type {import('@docusaurus/types').Config} */
const config = {
title: 'Approzium',
tagline: 'The tagline of my site',
url: 'https://approzium.com',
baseUrl: '/',
onBrokenLinks: 'throw',
onBrokenMarkdownLinks: 'warn',
favicon: 'img/apzm-icon.svg',
organizationName: 'cyralinc',
projectName: 'approzium',
themeConfig: {
navbar: {
title: 'Approzium',
logo: {
alt: 'Approzium Logo',
src: 'img/apzm-icon.svg',
},
links: [
{
to: 'docs/',
activeBasePath: 'docs',
label: 'Documentation',
position: 'right',
},
{
href: 'https://github.com/cyralinc/approzium',
label: 'GitHub',
position: 'right',
},
{
href: 'https://cyral.com',
label: 'Cyral',
position: 'right',
},
],
},
algolia: {
apiKey: '8ce076a38f6bf25b30877ca2251ec1e4',
indexName: 'prod_APPROZIUM_DOCS',
appId: '51LSIHDN1A', // Optional, if you run the DocSearch crawler on your own
algoliaOptions: {}, // Optional, if provided by Algolia
},
googleAnalytics: {
trackingID: 'UA-172971690-1',
anonymizeIP: true, // Should IPs be anonymized?
},

footer: {
style: 'light',
copyright: `Copyright © ${new Date().getFullYear()} Cyral, Inc.`,
},
},
plugins: [
'@docusaurus/plugin-ideal-image',
'@docusaurus/plugin-google-analytics'
],
presets: [
[
'@docusaurus/preset-classic',
{
'classic',
/** @type {import('@docusaurus/preset-classic').Options} */
({
docs: {
// It is recommended to set document id as docs home page (`docs/` path).
homePageId: 'overview',
sidebarPath: require.resolve('./sidebars.js'),
// Please change this to your repo.
editUrl:
'https://github.com/facebook/docusaurus/edit/master/website/',
editUrl: 'https://github.com/cyralinc/approzium/tree/main/docs',
},
theme: {
customCss: require.resolve('./src/css/custom.css'),
},
},
googleAnalytics: {
trackingID: 'UA-172971690-1',
anonymizeIP: true, // Should IPs be anonymized?
},
}),
],
],
};
themeConfig:
/** @type {import('@docusaurus/preset-classic').ThemeConfig} */
({
navbar: {
title: 'Approzium',
logo: {
alt: 'Approzium Logo',
src: 'img/apzm-icon.svg',
},
items: [
{
to: 'docs/',
activeBasePath: 'docs',
label: 'Documentation',
position: 'right',
},
{
href: 'https://github.com/cyralinc/approzium',
label: 'GitHub',
position: 'right',
},
{
href: 'https://cyral.com',
label: 'Cyral',
position: 'right',
},
],
},
algolia: {
apiKey: '8ce076a38f6bf25b30877ca2251ec1e4',
indexName: 'prod_APPROZIUM_DOCS',
appId: '51LSIHDN1A', // Optional, if you run the DocSearch crawler on your own
},
footer: {
style: 'light',
copyright: `Copyright © ${new Date().getFullYear()} <a href="https://cyral.com/">Cyral, Inc.</a>`,
},
prism: {
defaultLanguage: 'python',
},
}),

plugins: ['docusaurus-plugin-sass', '@docusaurus/plugin-ideal-image'],
}

module.exports = config
26 changes: 18 additions & 8 deletions docs/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -15,20 +15,30 @@
"url": "https://github.com/cyralinc/approzium.git"
},
"scripts": {
"docusaurus": "docusaurus",
"start": "docusaurus start",
"build": "docusaurus build",
"swizzle": "docusaurus swizzle",
"deploy": "docusaurus deploy"
"deploy": "docusaurus deploy",
"clear": "docusaurus clear",
"serve": "docusaurus serve",
"write-translations": "docusaurus write-translations",
"write-heading-ids": "docusaurus write-heading-ids"
},
"dependencies": {
"@docusaurus/core": "^2.0.0-alpha.58",
"@docusaurus/plugin-google-analytics": "^2.0.0-alpha.37",
"@docusaurus/plugin-ideal-image": "^2.0.0-alpha.39",
"@docusaurus/preset-classic": "^2.0.0-alpha.58",
"@docusaurus/core": "^2.0.0-beta.14",
"@docusaurus/plugin-ideal-image": "^2.0.0-beta.14",
"@docusaurus/preset-classic": "^2.0.0-beta.14",
"@mdx-js/react": "^1.6.21",
"clsx": "^1.1.1",
"jpeg-js": "^0.4.0",
"react": "^16.8.4",
"react-dom": "^16.8.4"
"docusaurus-plugin-sass": "^0.2.1",
"prism-react-renderer": "^1.2.1",
"react": "^17.0.1",
"react-dom": "^17.0.1",
"sass": "^1.49.0"
},
"devDependencies": {
"prettier": "^2.5.1"
},
"browserslist": {
"production": [
Expand Down
22 changes: 19 additions & 3 deletions docs/sidebars.js
Original file line number Diff line number Diff line change
@@ -1,4 +1,18 @@
module.exports = {
/**
* Creating a sidebar enables you to:
- create an ordered group of docs
- render a sidebar for each doc of that group
- provide next/previous navigation
The sidebars can be generated from the filesystem, or explicitly defined here.
Create as many sidebars as you want.
*/

// @ts-check

/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
const sidebars = {
someSidebar: [
'overview',
'quickstart',
Expand All @@ -14,10 +28,12 @@ module.exports = {
{
type: 'link',
label: 'Python',
href: 'https://approzium.readthedocs.io/en/latest/'
href: 'https://approzium.readthedocs.io/en/latest/',
},
],
},
'roadmap',
],
};
}

module.exports = sidebars
Loading

0 comments on commit 5922c15

Please sign in to comment.