diff --git a/docs-en/rest-pki-core/on-premises/azure/_category_.json b/docs-en/rest-pki-core/on-premises/azure/_category_.json new file mode 100644 index 0000000..2577e74 --- /dev/null +++ b/docs-en/rest-pki-core/on-premises/azure/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "Setup on Azure App Services", + "key": "rest-pki-core/on-premises/azure", + "position": 4 +} diff --git a/docs-en/rest-pki-core/on-premises/azure/index.md b/docs-en/rest-pki-core/on-premises/azure/index.md new file mode 100644 index 0000000..1a00d48 --- /dev/null +++ b/docs-en/rest-pki-core/on-premises/azure/index.md @@ -0,0 +1,11 @@ +--- +sidebar_position: 1 +slug: /rest-pki/core/on-premises/azure +--- + +# Rest PKI Core - Setup on Azure App Services + +## See also + +* [Installing Rest PKI Core on Azure App Services](install.md) +* [Updating Rest PKI Core on Azure App Services](update.md) diff --git a/docs-en/rest-pki-core/on-premises/azure/install.md b/docs-en/rest-pki-core/on-premises/azure/install.md new file mode 100644 index 0000000..5a3b048 --- /dev/null +++ b/docs-en/rest-pki-core/on-premises/azure/install.md @@ -0,0 +1,306 @@ +--- +sidebar_position: 2 +sidebar_label: "Install" +slug: /rest-pki/core/on-premises/azure/install +--- + +# Installing Rest PKI Core on Azure App Services + +To install an [on-premises](../index.md) instance of [Rest PKI Core](../../index.md) on an [Azure App Service](https://docs.microsoft.com/azure/app-service/overview), +follow the steps below. For other platforms, [click here](../index.md#platforms). + +:::tip +To be able to use the free SSL certificates provided by *App Service Managed Certificates*, we suggest not choosing "naked domains", +that is, domains without a subdomain portion, for example ~~patorum.com~~. Prefer, for instance, `restpki.patorum.com`. +::: + + +## Preparation + +The instructions below assume that you already have the [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) installed locally and that you +already have the following resources created on your Azure account: + +* A *SQL Server* (creating the *SQL database* is covered by this article) +* An *App Service Plan* with the **Linux** operating system (creating the App Service is covered by this article) +* A DNS zone for the domain used to access Rest PKI Core + +During the installation, some resources will be created: + +* A *Container Registry* +* A database (*SQL database*) +* A *storage account* +* An App Service + +We suggest creating a **resource group** to group the resources you create. However, this is merely an organizational measure. What +really matters is that **all resources are created in the same region**. This is essential for the system to work properly. + +:::note +The steps below describe the most basic creation of each resource. Depending on your infrastructure you may want to take +additional security or resilience measures, such as restricting access to a private network. +::: + + +## Creating a *Container registry* + +Follow the steps below to create a *container registry* to store a local copy of the system's Docker images: + +1. Under **Container registries**, click **+ Create** +1. On the first tab (*Basics*) + * Fill in the fields according to your infrastructure (following the region chosen for the system) + * Take note of the chosen *registry name* + * Under *SKU*, choose **Basic** +1. Click **Review + create**, then **Create** + +Once the *container registry* has been created, replicate the system's Docker image to it (replace `MY_ACR_NAME` with the name chosen +in the previous step): + +```sh +az login +``` + +:::note +If you have access to more than one Azure account, you may need to pass the `--tenant YOUR_TENANT` argument +::: + + +```sh +az acr login --name MY_ACR_NAME +az acr import --name MY_ACR_NAME --source docker.io/lacunasoftware/restpkicore:4.2.5 --image restpkicore:4.2.5 +``` + +:::tip +Replace `4.2.5` with the currently recommended version (see the [Docker setup](../docker.md)) +::: + + +## Creating the database + +Follow the steps below to create a database for the system (you must have a *SQL Server* previously created): + +1. Under **SQL databases**, click **+ Create** +1. On the first tab (*Basics*), fill in the fields according to your infrastructure (following the region chosen for the system) +1. Click the **Additional settings** tab +1. Under **Collation**, enter `Latin1_General_100_CI_AI` +1. Click **Review + create** +1. Click **Create** + +:::warning +The database *collation* **MUST BE** `Latin1_General_100_CI_AI`. Creating the database with a different *collation* will likely cause the installation to fail! +::: + + +Once the database has been created, click **Go to resource**. Then obtain the *connection string*: + +1. Click **Connection strings** +1. Take note of the connection string shown under the **ADO.NET (SQL authentication)** section + +:::note +In the copied connection string, replace the `{your_password}` placeholder with the database password +::: + + +## Creating a *storage account* + +We need a *storage account* to store files (the system stores files outside the database to keep it organized) and also the +system logs. Follow the steps below to create a *storage account* (if you want to use an existing account, skip this part): + +1. Under **Storage accounts**, click **+ Create** +1. On the first tab (*Basics*), fill in the fields according to your infrastructure (following the region chosen for the system) + * Under *Performance*, choose **Standard** + * Under *Redundancy*, choose the option you prefer (we suggest **Zone-redundant storage (ZRS)** -- [click here](https://azure.microsoft.com/documentation/articles/storage-redundancy/) + for details on the different replication options) +1. Click **Review** +1. Click **Create** + +Once the *storage account* has been created, click **Go to resource**. Then obtain a *connection string*: + +1. In the *storage account* settings, click **Access keys** +1. Under the **key1** section, take note of the value of the **Connection string** field + +## Creating the App Service + +Follow the steps below to create an *App Service* (you must have an *App Service Plan* previously created with the **Linux** operating system): + +1. Under **App Services**, click **+ Create** then **+ Web App** +1. On the first tab (*Basics*), fill in the fields according to your infrastructure (following the region chosen for the system) + * Under *Publish*, choose **Docker Container** + * Under *Operating System*, choose **Linux** + * Under *Region*, choose the region where your *app service plan* is located + * Under *Linux Plan*, choose your *app service plan* + * Click **Next : Docker >** +1. On the next tab (*Docker*), fill in: + * Under *Options*, leave the **Single Container** option + * Under *Image Source*, select **Azure Container Registry** + * Under *Registry*, select the *container registry* created earlier + * Under *Image* and *Tag*, select the system's image/tag according to the `az acr import` command run earlier + * Leave the *Startup Command* option **blank** + * Click **Review + create** +1. Click **Create** + +Once the App Service has been created, click **Go to resource**. Then take note of its domain, for example `my-app-service.azurewebsites.net`. + +Go to the App Service **Configuration** and add the following settings: + +* `ASPNETCORE_ENVIRONMENT`: `Azure` +* `Bindings__HttpsMode`: `Strict` +* `STANDBY`: `True` + +Save the settings. + +Still in the App Service configuration, go to the **General settings** tab and, under the **HTTPS Only** option, select **Off** (the application itself will take care of requiring HTTPS access in the most appropriate way). + +Then go to **Custom domains** and copy the **Custom Domain Verification ID** (this value will be needed later). + +## Domain configuration + +Create the DNS record for the domain used to access Rest PKI Core: + +:::note +In the instructions below, we will use the creation of the record for the domain `app.patorum.com` as an example +::: + + +1. Under **DNS zones**, click the zone the domain belongs to (e.g.: `patorum.com`) +1. Click **+ Record set** +1. Under *Name*, type the leftmost portion of the domain (e.g.: `app`) +1. Under *Type*, select **CNAME** +1. Under *Alias record set*, select **No** +1. Under *Alias*, fill in the App Service domain (e.g.: `my-app-service.azurewebsites.net`) +1. Click **OK** +1. Click **+ Record set** again +1. Under *Name*, type `asuid.` followed by the leftmost portion of the domain (e.g.: `asuid.app`) +1. Under *Type*, select **TXT** +1. Under *Value*, paste the **Custom Domain Verification ID** previously copied from the App Service +1. Click **OK** + +:::note +If you do not use Azure as the DNS server for your zones, perform the equivalent procedure on your DNS server +::: + + +After creating the record, add the domain to the *App Service*: + +1. Back in the App Service settings, click **Custom domains** +1. Click **+ Add custom domain** +1. Select **All other domain services** +1. Leave the **App Service Managed Certificate** and **SNI SSL** options selected +1. Under *Domain*, fill in the domain (e.g.: `app.patorum.com`) +1. Click **Validate** +1. After validation, click **Add** + +## Rest PKI Core configuration + +On the App Service side menu, under the *Development Tools* section, click **SSH**, then **Go →**. You will be taken to a terminal. Navigate +to the `/app` folder: + +```bash +cd /app +``` + +:::tip +Even though the terminal appears to start in the `/app` folder, the command above **is necessary** due to an Azure bug +::: + + +Run the command below to generate the cryptographic key used to encrypt sensitive values stored in the database: + +```cmd +dotnet Lacuna.RestPki.Site.dll -- gen-enc-key +``` + +Take note of the generated value. + +Choose a strong password to protect *root* access to the dashboard, and compute the hash of that password with the command below: + +```cmd +dotnet Lacuna.RestPki.Site.dll -- hash-root-pass +``` + +Again, take note of the generated value. + +Close the terminal, returning to the Azure portal. On the App Service, go to **Configuration** and add the following settings: + +* `General__AppDiscriminator`: see the [App discriminator](#app-discriminator) section below +* `General__EncryptionKey`: the cryptographic key generated above +* `General__RootPasswordHash`: the *root* password hash computed above +* `General__SiteUrl`: the public URL of the site (e.g.: `https://restpki.patorum.com/`) +* `General__SiteName` (optional): the name of your Rest PKI Core instance (defaults to *Rest PKI Core*) +* `Oidc__Enabled`: `False` (disables the [OpenID Connect integration](../configure-oidc.md), for now) + +:::note +If you want to enable user management through OpenID Connect, leave the `General__RootPasswordHash` setting blank and follow the steps on +[Configure OpenID Connect](../configure-oidc.md). +::: + + +Also add the settings described in the sections below. + +### App discriminator {#app-discriminator} + +The `General__AppDiscriminator` setting identifies the instance and is used to derive the system's data protection keys. + +:::warning +This setting is **required** on Azure App Services. If it is not set explicitly, a value is derived automatically and may +**change when the container is recreated**, which prevents the decryption of sensitive data already stored, causing **data loss**. Choose a +stable value (for example `RestPkiCore`) and **never change it** after installation. For more details, see the *Set an explicit AppDiscriminator* +section of the article [Update from 2.x to 3.0](../major-updates/update-30.md#2-set-an-explicit-appdiscriminator). +::: + + +* `General__AppDiscriminator`: a stable value identifying the instance, e.g.: `RestPkiCore` + +### PKI Suite + +PKI Suite settings: + +* `PkiSuite__SdkLicense`: your license for the PKI SDK, in Base64 format (**required**) +* `PkiSuite__WebLicense`: your license for the Web PKI component in binary (Base64) format. Only required if users will sign documents with certificates on their computers (in-browser signature via Web PKI) + +### Blob Storage + +*storage account* configuration (the storage type and container name already come preconfigured for the Azure environment): + +* `BlobStorage__ConnectionString`: the *connection string* of the *storage account* created earlier +* `BlobStorage__ContainerName` (optional): the name of the *container* used to store files. If omitted, a container named *restpki* is used. + +### Logging + +Log configuration (the Azure Table log *sink* already comes preconfigured for the Azure environment): + +* `Serilog__WriteTo__0__Args__connectionString`: the *connection string* of the *storage account* created earlier +* `Serilog__WriteTo__0__Args__storageTableName` (optional): the name of the table used to store the logs. If omitted, a table named *RestPkiCoreLog* is used. + +### Connection string + +In the *Connection strings* section (at the bottom of the settings page), click **+ New connection string** and fill in: + +* **Name**: `DefaultConnection` +* **Value**: the connection string value obtained while creating the database +* **Type**: choose **SQLAzure** + +:::tip +Rest PKI Core is also compatible with PostgreSQL. If you want to use an Azure Database for PostgreSQL database, please contact support for more +information. For details on the supported databases, see [Preparing a database](../prepare-database.md). +::: + + +Save the settings made so far by clicking **Save**. + +:::note +Whenever the documentation mentions something like "in the **Sec** section, set the **Conf** setting to ...", on Azure App Services you must +compose the setting name from the section and setting names separated by `__` (**two** underscores), that is, in the example above: `Sec__Conf` +::: + + +## Starting the App Service + +Finally, remove the `STANDBY` setting from the App Service and save the settings. Then access the public URL of the site (the first access may take a few moments). + +Authenticate with the *root* password chosen during configuration. You will then have access to the dashboard. + +To start using the system, create a [subscription](../create-sub.md) and add an administrative user to it. + +## See also + +* [Creating a subscription on Rest PKI Core](../create-sub.md) +* [Updating Rest PKI Core on Azure App Services](update.md) diff --git a/docs-en/rest-pki-core/on-premises/azure/update.md b/docs-en/rest-pki-core/on-premises/azure/update.md new file mode 100644 index 0000000..37e4fdc --- /dev/null +++ b/docs-en/rest-pki-core/on-premises/azure/update.md @@ -0,0 +1,27 @@ +--- +sidebar_position: 3 +sidebar_label: "Update" +slug: /rest-pki/core/on-premises/azure/update +--- + +# Updating Rest PKI Core on Azure App Services + +Before updating, check whether the new version requires additional migration steps: + +* [Update from 2.x to 3.0](../major-updates/update-30.md) +* [Update from 3.x to 4.0](../major-updates/update-40.md) + +Then, replicate the new Docker image of the system to your *container registry* (replace `MY_ACR_NAME` with the name chosen during installation +and `4.2.5` with the desired version): + +```sh +az login +az acr login --name MY_ACR_NAME +az acr import --name MY_ACR_NAME --source docker.io/lacunasoftware/restpkicore:4.2.5 --image restpkicore:4.2.5 +``` + +Finally, on the system's App Service, go to **Deployment Center** and, in the **Tag** field, select the new version and click **Save**. + +## See also + +* [Installing Rest PKI Core on Azure App Services](install.md) diff --git a/docs-en/rest-pki-core/on-premises/check-version.md b/docs-en/rest-pki-core/on-premises/check-version.md index 461fc77..c07a72d 100644 --- a/docs-en/rest-pki-core/on-premises/check-version.md +++ b/docs-en/rest-pki-core/on-premises/check-version.md @@ -1,5 +1,5 @@ --- -sidebar_position: 4 +sidebar_position: 5 sidebar_label: "Checking the installed version" slug: /rest-pki/core/on-premises/check-version --- diff --git a/docs-en/rest-pki-core/on-premises/configure-blob-storage.md b/docs-en/rest-pki-core/on-premises/configure-blob-storage.md index d708c45..5318038 100644 --- a/docs-en/rest-pki-core/on-premises/configure-blob-storage.md +++ b/docs-en/rest-pki-core/on-premises/configure-blob-storage.md @@ -1,5 +1,5 @@ --- -sidebar_position: 5 +sidebar_position: 6 sidebar_label: "Blob Storage Configuration" slug: /rest-pki/core/on-premises/configure-blob-storage --- diff --git a/docs-en/rest-pki-core/on-premises/configure-email.md b/docs-en/rest-pki-core/on-premises/configure-email.md index 2def757..24ea33d 100644 --- a/docs-en/rest-pki-core/on-premises/configure-email.md +++ b/docs-en/rest-pki-core/on-premises/configure-email.md @@ -1,5 +1,5 @@ --- -sidebar_position: 6 +sidebar_position: 7 sidebar_label: "Configure email sending" slug: /rest-pki/core/on-premises/configure-email --- diff --git a/docs-en/rest-pki-core/on-premises/configure-oidc.md b/docs-en/rest-pki-core/on-premises/configure-oidc.md index 7d59520..4f8417f 100644 --- a/docs-en/rest-pki-core/on-premises/configure-oidc.md +++ b/docs-en/rest-pki-core/on-premises/configure-oidc.md @@ -1,5 +1,5 @@ --- -sidebar_position: 7 +sidebar_position: 8 sidebar_label: "Configure OpenID Connect" slug: /rest-pki/core/on-premises/configure-oidc --- diff --git a/docs-en/rest-pki-core/on-premises/configure-timestamp.md b/docs-en/rest-pki-core/on-premises/configure-timestamp.md index cedd0ce..4eed215 100644 --- a/docs-en/rest-pki-core/on-premises/configure-timestamp.md +++ b/docs-en/rest-pki-core/on-premises/configure-timestamp.md @@ -1,5 +1,5 @@ --- -sidebar_position: 8 +sidebar_position: 9 sidebar_label: "Timestamping Configuration" slug: /rest-pki/core/on-premises/configure-timestamp --- diff --git a/docs-en/rest-pki-core/on-premises/create-sub.md b/docs-en/rest-pki-core/on-premises/create-sub.md index d006dba..eb66a6d 100644 --- a/docs-en/rest-pki-core/on-premises/create-sub.md +++ b/docs-en/rest-pki-core/on-premises/create-sub.md @@ -1,5 +1,5 @@ --- -sidebar_position: 9 +sidebar_position: 10 sidebar_label: "Creating a subscription" slug: /rest-pki/core/on-premises/create-sub --- diff --git a/docs-en/rest-pki-core/on-premises/docker.md b/docs-en/rest-pki-core/on-premises/docker.md index 04bcf9b..2e06759 100644 --- a/docs-en/rest-pki-core/on-premises/docker.md +++ b/docs-en/rest-pki-core/on-premises/docker.md @@ -1,5 +1,5 @@ --- -sidebar_position: 10 +sidebar_position: 11 sidebar_label: "Setup on Docker" slug: /rest-pki/core/on-premises/docker --- diff --git a/docs-en/rest-pki-core/on-premises/index.md b/docs-en/rest-pki-core/on-premises/index.md index 76b6ad5..54b2b9a 100644 --- a/docs-en/rest-pki-core/on-premises/index.md +++ b/docs-en/rest-pki-core/on-premises/index.md @@ -15,7 +15,7 @@ Rest PKI Core is compatible with: * Windows Server * [Linux](linux/index.md) * [Docker](docker.md) -* Azure App Services +* [Azure App Services](azure/index.md) Click on one of the platforms above for specific setup instructions. diff --git a/docs-en/rest-pki-core/on-premises/logging.md b/docs-en/rest-pki-core/on-premises/logging.md index 08c101d..f9bed52 100644 --- a/docs-en/rest-pki-core/on-premises/logging.md +++ b/docs-en/rest-pki-core/on-premises/logging.md @@ -1,5 +1,5 @@ --- -sidebar_position: 11 +sidebar_position: 12 sidebar_label: "Logging" slug: /rest-pki/core/on-premises/logging --- diff --git a/docs-en/rest-pki-core/on-premises/prepare-database.md b/docs-en/rest-pki-core/on-premises/prepare-database.md index 54717fe..eb6be1a 100644 --- a/docs-en/rest-pki-core/on-premises/prepare-database.md +++ b/docs-en/rest-pki-core/on-premises/prepare-database.md @@ -1,5 +1,5 @@ --- -sidebar_position: 12 +sidebar_position: 13 sidebar_label: "Preparing a database" slug: /rest-pki/core/on-premises/prepare-database --- diff --git a/docs-en/rest-pki-core/on-premises/unprivileged-db-user.md b/docs-en/rest-pki-core/on-premises/unprivileged-db-user.md index 393cacb..587ce90 100644 --- a/docs-en/rest-pki-core/on-premises/unprivileged-db-user.md +++ b/docs-en/rest-pki-core/on-premises/unprivileged-db-user.md @@ -1,5 +1,5 @@ --- -sidebar_position: 13 +sidebar_position: 14 sidebar_label: "Running without db_owner privileges" slug: /rest-pki/core/on-premises/unprivileged-db-user --- diff --git a/docs-en/rest-pki-core/on-premises/vulnerabilities.md b/docs-en/rest-pki-core/on-premises/vulnerabilities.md index 45f7cdb..acfbdab 100644 --- a/docs-en/rest-pki-core/on-premises/vulnerabilities.md +++ b/docs-en/rest-pki-core/on-premises/vulnerabilities.md @@ -1,5 +1,5 @@ --- -sidebar_position: 14 +sidebar_position: 15 sidebar_label: "Vulnerability checks" slug: /rest-pki/core/on-premises/vulnerabilities --- diff --git a/docs/rest-pki-core/on-premises/azure/_category_.json b/docs/rest-pki-core/on-premises/azure/_category_.json new file mode 100644 index 0000000..1b49a7a --- /dev/null +++ b/docs/rest-pki-core/on-premises/azure/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "Setup em Azure App Services", + "key": "rest-pki-core/on-premises/azure", + "position": 4 +} diff --git a/docs/rest-pki-core/on-premises/azure/index.md b/docs/rest-pki-core/on-premises/azure/index.md new file mode 100644 index 0000000..90123c4 --- /dev/null +++ b/docs/rest-pki-core/on-premises/azure/index.md @@ -0,0 +1,11 @@ +--- +sidebar_position: 1 +slug: /rest-pki/core/on-premises/azure +--- + +# Rest PKI Core - Setup em Azure App Services + +## Veja também + +* [Instalação do Rest PKI Core em Azure App Services](install.md) +* [Atualização do Rest PKI Core em Azure App Services](update.md) diff --git a/docs/rest-pki-core/on-premises/azure/install.md b/docs/rest-pki-core/on-premises/azure/install.md new file mode 100644 index 0000000..40d7169 --- /dev/null +++ b/docs/rest-pki-core/on-premises/azure/install.md @@ -0,0 +1,306 @@ +--- +sidebar_position: 2 +sidebar_label: "Instalação" +slug: /rest-pki/core/on-premises/azure/install +--- + +# Instalação do Rest PKI Core em Azure App Services + +Para instalar uma instância [*on premises*](../index.md) do [Rest PKI Core](../../index.md) em um [Azure App Service](https://docs.microsoft.com/azure/app-service/overview), +siga os passos abaixo. Para outras plataformas, [clique aqui](../index.md#platforms). + +:::tip +Para permitir o uso do recurso de certificados SSL gratuitos pelo *App Service Managed Certificates*, sugerimos não escolher "naked domains", ou seja, +domínios sem porção de subdomínio, por exemplo ~~patorum.com~~. Prefira, por exemplo, `restpki.patorum.com`. +::: + + +## Preparação + +As instruções a seguir assumem que você já tem instalado localmente o [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) e já possui +os seguintes recursos criados na sua conta do Azure: + +* Um *SQL Server* (a criação do *SQL database* é coberta por este artigo) +* Um *App Service Plan* com sistema operacional **Linux** (a criação do App Service é coberta por este artigo) +* Uma zona de DNS referente ao domínio de acesso ao Rest PKI Core + +Durante a instalação, serão criados alguns recursos: + +* Um *Container Registry* +* Um banco de dados (*SQL database*) +* Uma *storage account* +* Um App Service + +Sugerimos criar um **resource group** para agrupar os recursos criados. Entretanto, essa é uma medida com propósito meramente de organização. O que +realmente é importante é que **todos os recursos sejam criados na mesma região**. Isso é fundamental para o funcionamento adequado do sistema. + +:::note +Os passos abaixo descrevem a criação mais básica de cada recurso. Dependendo da sua infraestrutura você pode querer tomar cuidados +adicionais de segurança ou resiliência, como por exemplo restringir o acesso a uma rede privada. +::: + + +## Criação de um *Container registry* + +Siga os procedimentos abaixo para criar um *container registry* para armazenar localmente uma cópia das imagens de Docker do sistema: + +1. Na opção **Container registries**, clique em **+ Create** +1. Na primeira aba (*Basics*) + * Preencha os dados conforme a sua infraestrutura (seguindo a região escolhida para o sistema) + * Tome nota do *registry name* escolhido + * Em *SKU*, escolha **Basic** +1. Clique em **Review + create**, em seguida em **Create** + +Uma vez concluída a criação do *container registry*, replique a imagem de Docker do sistema para ele (substitua `MY_ACR_NAME` pelo nome escolhido +no passo anterior): + +```sh +az login +``` + +:::note +Caso você tenha acesso a mais de uma conta no Azure, pode ser necessário passar o argumento `--tenant YOUR_TENANT` +::: + + +```sh +az acr login --name MY_ACR_NAME +az acr import --name MY_ACR_NAME --source docker.io/lacunasoftware/restpkicore:4.2.5 --image restpkicore:4.2.5 +``` + +:::tip +Substitua `4.2.5` pela versão atualmente recomendada (veja a [instalação em Docker](../docker.md)) +::: + + +## Criação do banco de dados + +Siga os procedimentos abaixo para criar um banco de dados para o sistema (você precisa ter um *SQL Server* previamente criado): + +1. Na opção **SQL databases**, clique em **+ Create** +1. Na primeira aba (*Basics*), preencha os dados conforme a sua infraestrutura (seguindo a região escolhida para o sistema) +1. Clique na aba **Additional settings** +1. Em **Collation** preencha `Latin1_General_100_CI_AI` +1. Clique em **Review + create** +1. Clique em **Create** + +:::warning +A *collation* do banco de dados **PRECISA SER** `Latin1_General_100_CI_AI`. Criar o banco de dados com uma *collation* diferente provavelmente fará com que a instalação falhe! +::: + + +Uma vez concluída a criação do banco de dados, clique em **Go to resource**. Em seguida, obtenha a *connection string*: + +1. Clique em **Connection strings** +1. Tome nota da connection string exibida na seção **ADO.NET (SQL authentication)** + +:::note +Substitua na connection string copiada o trecho `{your_password}` pela senha do banco de dados +::: + + +## Criação de uma *storage account* + +Precisamos de uma *storage account* para armazenar arquivos (o sistema armazena arquivos fora do banco de dados para mantê-lo organizado) e também os +logs de sistema. Siga os passos abaixo para criar uma *storage account* (caso queira utilizar uma conta existente, pule essa parte): + +1. Em **Storage accounts**, clique em **+ Create** +1. Na primeira aba (*Basics*), preencha os dados conforme a sua infraestrutura (seguindo a região escolhida para o sistema) + * Em *Performance*, escolha **Standard** + * Em *Redundancy*, escolha a opção que preferir (sugerimos a opção **Zone-redundant storage (ZRS)** -- [clique aqui](https://azure.microsoft.com/documentation/articles/storage-redundancy/) + para detalhes sobre as diferentes opções de replicação) +1. Clique em **Review** +1. Clique em **Create** + +Uma vez concluída a criação da *storage account*, clique em **Go to resource**. Em seguida, obtenha uma *connection string*: + +1. Nas configurações da *storage account*, clique em **Access keys** +1. Na seção **key1**, tome nota do valor do campo **Connection string** + +## Criação do App Service + +Siga os procedimentos abaixo para criar um *App Service* (você precisa ter um *App Service Plan* previamente criado com sistema operacional **Linux**): + +1. Em **App Services**, clique em **+ Create** em seguida em **+ Web App** +1. Na primeira aba (*Basics*), preencha os dados conforme a sua infraestrutura (seguindo a região escolhida para o sistema) + * Em *Publish*, escolha **Docker Container** + * Em *Operating System*, escolha **Linux** + * Em *Region*, escolha a região onde está o seu *app service plan* + * Em *Linux Plan*, escolha o seu *app service plan* + * Clique em **Next : Docker >** +1. Na aba seguinte (*Docker*), preencha: + * Em *Options*, deixe a opção **Single Container** + * Em *Image Source*, selecione **Azure Container Registry** + * Em *Registry*, selecione o *container registry* criado anteriormente + * Em *Image* e *Tag*, selecione a imagem/tag do sistema conforme o comando `az acr import` realizado anteriormente + * Deixe a opção *Startup Command* **em branco** + * Clique em **Review + create** +1. Clique em **Create** + +Uma vez concluída a criação do App Service, clique em **Go to resource**. Em seguida, tome nota de seu domínio, por exemplo `meu-app-service.azurewebsites.net`. + +Vá em **Configuration** do App Service e adicione as seguintes configurações: + +* `ASPNETCORE_ENVIRONMENT`: `Azure` +* `Bindings__HttpsMode`: `Strict` +* `STANDBY`: `True` + +Salve as configurações. + +Ainda na configuração do App Service, vá na aba **General settings** e, na opção **HTTPS Only**, marque **Off** (a própria aplicação se encarregará de exigir acesso via HTTPS da maneira mais adequada). + +Em seguida, vá em **Custom domains** e copie o **Custom Domain Verification ID** (esse valor será necessário mais à frente). + +## Configuração do domínio + +Crie o registro de DNS para o domínio de acesso ao Rest PKI Core: + +:::note +Nas instruções abaixo, utilizaremos como exemplo a criação do apontamento para o domínio `app.patorum.com` +::: + + +1. Em **DNS zones**, clique na zona à qual o domínio pertence (ex: `patorum.com`) +1. Clique em **+ Record set** +1. Em *Name*, digite a porção mais à esquerda do domínio (ex: `app`) +1. Em *Type*, selecione **CNAME** +1. Em *Alias record set*, selecione **No** +1. Em *Alias*, preencha o domínio do App Service (ex: `meu-app-service.azurewebsites.net`) +1. Clique em **OK** +1. Clique novamente em **+ Record set** +1. Em *Name*, digite `asuid.` seguido da porção mais à esquerda do domínio (ex: `asuid.app`) +1. Em *Type*, selecione **TXT** +1. Em *Value*, cole o valor do **Custom Domain Verification ID** anteriormente copiado do App Service +1. Clique em **OK** + +:::note +Caso você não utilize o Azure como servidor de DNS das zonas, realize o procedimento equivalente no seu servidor de DNS +::: + + +Após criar o apontamento, adicione o domínio ao *App Service*: + +1. De volta às configurações do App Service, clique em **Custom domains** +1. Clique em **+ Add custom domain** +1. Selecione **All other domain services** +1. Deixe selecionadas as opções **App Service Managed Certificate** e **SNI SSL** +1. Em *Domain*, preencha o domínio (ex: `app.patorum.com`) +1. Clique em **Validate** +1. Após a validação, clique em **Add** + +## Configuração do Rest PKI Core + +No menu lateral do App Service, na seção *Development Tools*, clique em **SSH**, em seguida em **Go →**. Você será levado a um terminal. Navegue +para a pasta `/app`: + +```bash +cd /app +``` + +:::tip +Embora o terminal pareça iniciar na pasta `/app`, o comando acima **é necessário** devido a um bug do Azure +::: + + +Execute o comando abaixo para gerar a chave criptográfica utilizada para cifrar valores sensíveis no banco de dados: + +```cmd +dotnet Lacuna.RestPki.Site.dll -- gen-enc-key +``` + +Tome nota do valor gerado. + +Escolha uma senha forte para proteger o acesso de *root* ao painel de controle, e calcule o hash dessa senha com o comando abaixo: + +```cmd +dotnet Lacuna.RestPki.Site.dll -- hash-root-pass +``` + +Novamente, tome nota do valor gerado. + +Feche o terminal, voltando ao portal do Azure. No App Service, vá em **Configuration** e adicione as seguintes configurações: + +* `General__AppDiscriminator`: veja a seção [App discriminator](#app-discriminator) abaixo +* `General__EncryptionKey`: chave criptográfica gerada acima +* `General__RootPasswordHash`: hash da senha de *root* calculado acima +* `General__SiteUrl`: URL pública do site (ex: `https://restpki.patorum.com/`) +* `General__SiteName` (opcional): nome da sua instância do Rest PKI Core (o padrão é *Rest PKI Core*) +* `Oidc__Enabled`: `False` (desabilita a [integração com OpenID Connect](../configure-oidc.md), por ora) + +:::note +Caso queira habilitar o gerenciamento de usuários via OpenID Connect, deixe a configuração `General__RootPasswordHash` em branco e siga os passos em +[Configuração de OpenID Connect](../configure-oidc.md). +::: + + +Adicione, também, as configurações descritas nas seções a seguir. + +### App discriminator {#app-discriminator} + +A configuração `General__AppDiscriminator` identifica a instância e é utilizada para derivar as chaves de proteção de dados do sistema. + +:::warning +Esta configuração é **obrigatória** no Azure App Services. Caso não seja definida explicitamente, um valor é derivado automaticamente e pode +**mudar quando o container é recriado**, o que impede a decifragem dos dados sensíveis já armazenados, causando **perda de dados**. Escolha um valor +estável (por exemplo `RestPkiCore`) e **nunca o altere** após a instalação. Para mais detalhes, veja a seção *Defina um AppDiscriminator explícito* do artigo +[Atualização da versão 2.x para 3.0](../major-updates/update-30.md). +::: + + +* `General__AppDiscriminator`: um valor estável que identifica a instância, ex: `RestPkiCore` + +### PKI Suite + +Configurações do PKI Suite: + +* `PkiSuite__SdkLicense`: sua licença para o PKI SDK, no formato Base64 (**obrigatório**) +* `PkiSuite__WebLicense`: sua licença para o componente Web PKI no formato binário (Base64). Somente obrigatório se os usuários forem assinar documentos com certificados em seus computadores (assinatura no navegador via Web PKI) + +### Blob Storage + +Configuração da *storage account* (o tipo de armazenamento e o nome do container já vêm pré-configurados para o ambiente Azure): + +* `BlobStorage__ConnectionString`: *connection string* da *storage account* criada anteriormente +* `BlobStorage__ContainerName` (opcional): nome do *container* a ser utilizado para armazenar arquivos. Caso omitido, um container denominado *restpki* é utilizado. + +### Logging + +Configuração de log (o *sink* de logs para o Azure Table já vem pré-configurado para o ambiente Azure): + +* `Serilog__WriteTo__0__Args__connectionString`: *connection string* da *storage account* criada anteriormente +* `Serilog__WriteTo__0__Args__storageTableName` (opcional): nome da tabela a ser utilizada para armazenar os logs. Caso omitido, uma tabela denominada *RestPkiCoreLog* é utilizada. + +### Connection string + +Na seção *Connection strings* (final da página de configurações), clique em **+ New connection string** e preencha: + +* **Name**: `DefaultConnection` +* **Value**: valor da connection string obtido durante a criação do banco de dados +* **Type**: escolha **SQLAzure** + +:::tip +O Rest PKI Core também é compatível com PostgreSQL. Caso deseje utilizar um banco de dados Azure Database for PostgreSQL, entre em contato com o suporte +para obter mais informações. Para detalhes sobre os bancos de dados suportados, veja [Preparando um banco de dados](../prepare-database.md). +::: + + +Salve as configurações feitas até o momento clicando em **Save**. + +:::note +Sempre que a documentação mencionar algo como "na seção **Sec**, atribua a configuração **Conf** ao valor ...", no Azure App Services você deve +compor o nome da configuração com os nomes da seção e da configuração separados por `__` (**dois** *underscores*), ou seja, no exemplo acima: `Sec__Conf` +::: + + +## Iniciando o App Service + +Por fim, remova a configuração `STANDBY` do App Service e salve as configurações. Em seguida, acesse a URL pública do site (o primeiro acesso pode demorar alguns instantes). + +Autentique-se com a senha de *root* escolhida durante a configuração. Você então terá acesso ao painel de controle. + +Para começar a utilizar o sistema, crie uma [organização](../create-sub.md) e adicione um usuário administrador a ela. + +## Veja também + +* [Criação de organização no Rest PKI Core](../create-sub.md) +* [Atualização do Rest PKI Core em Azure App Services](update.md) diff --git a/docs/rest-pki-core/on-premises/azure/update.md b/docs/rest-pki-core/on-premises/azure/update.md new file mode 100644 index 0000000..61aa2b1 --- /dev/null +++ b/docs/rest-pki-core/on-premises/azure/update.md @@ -0,0 +1,27 @@ +--- +sidebar_position: 3 +sidebar_label: "Atualização" +slug: /rest-pki/core/on-premises/azure/update +--- + +# Atualização do Rest PKI Core em Azure App Services + +Antes de atualizar, verifique se a nova versão exige passos adicionais de migração: + +* [Atualização da versão 2.x para 3.0](../major-updates/update-30.md) +* [Atualização da versão 3.x para 4.0](../major-updates/update-40.md) + +Em seguida, replique a nova imagem de Docker do sistema para o seu *container registry* (substitua `MY_ACR_NAME` pelo nome escolhido durante a instalação +e `4.2.5` pela versão desejada): + +```sh +az login +az acr login --name MY_ACR_NAME +az acr import --name MY_ACR_NAME --source docker.io/lacunasoftware/restpkicore:4.2.5 --image restpkicore:4.2.5 +``` + +Por fim, no App Service do sistema, vá em **Deployment Center** e, no campo **Tag**, selecione a nova versão e clique em **Save**. + +## Veja também + +* [Instalação do Rest PKI Core em Azure App Services](install.md) diff --git a/docs/rest-pki-core/on-premises/check-version.md b/docs/rest-pki-core/on-premises/check-version.md index 414e127..5c62f7c 100644 --- a/docs/rest-pki-core/on-premises/check-version.md +++ b/docs/rest-pki-core/on-premises/check-version.md @@ -1,5 +1,5 @@ --- -sidebar_position: 4 +sidebar_position: 5 sidebar_label: "Verificando a versão instalada" slug: /rest-pki/core/on-premises/check-version --- diff --git a/docs/rest-pki-core/on-premises/configure-blob-storage.md b/docs/rest-pki-core/on-premises/configure-blob-storage.md index 87e07ef..a82b459 100644 --- a/docs/rest-pki-core/on-premises/configure-blob-storage.md +++ b/docs/rest-pki-core/on-premises/configure-blob-storage.md @@ -1,5 +1,5 @@ --- -sidebar_position: 5 +sidebar_position: 6 sidebar_label: "Configuração de Blob Storage" slug: /rest-pki/core/on-premises/configure-blob-storage --- diff --git a/docs/rest-pki-core/on-premises/configure-email.md b/docs/rest-pki-core/on-premises/configure-email.md index 84816bb..680a890 100644 --- a/docs/rest-pki-core/on-premises/configure-email.md +++ b/docs/rest-pki-core/on-premises/configure-email.md @@ -1,5 +1,5 @@ --- -sidebar_position: 6 +sidebar_position: 7 sidebar_label: "Configuração de envio de email" slug: /rest-pki/core/on-premises/configure-email --- diff --git a/docs/rest-pki-core/on-premises/configure-oidc.md b/docs/rest-pki-core/on-premises/configure-oidc.md index 117e7aa..43c52e8 100644 --- a/docs/rest-pki-core/on-premises/configure-oidc.md +++ b/docs/rest-pki-core/on-premises/configure-oidc.md @@ -1,5 +1,5 @@ --- -sidebar_position: 7 +sidebar_position: 8 sidebar_label: "Configuração de OpenID Connect" slug: /rest-pki/core/on-premises/configure-oidc --- diff --git a/docs/rest-pki-core/on-premises/configure-timestamp.md b/docs/rest-pki-core/on-premises/configure-timestamp.md index 01131c3..aadc942 100644 --- a/docs/rest-pki-core/on-premises/configure-timestamp.md +++ b/docs/rest-pki-core/on-premises/configure-timestamp.md @@ -1,5 +1,5 @@ --- -sidebar_position: 8 +sidebar_position: 9 sidebar_label: "Configuração de Timestamping" slug: /rest-pki/core/on-premises/configure-timestamp --- diff --git a/docs/rest-pki-core/on-premises/create-sub.md b/docs/rest-pki-core/on-premises/create-sub.md index 00851fe..8c3b758 100644 --- a/docs/rest-pki-core/on-premises/create-sub.md +++ b/docs/rest-pki-core/on-premises/create-sub.md @@ -1,5 +1,5 @@ --- -sidebar_position: 9 +sidebar_position: 10 sidebar_label: "Criação de organização" slug: /rest-pki/core/on-premises/create-sub --- diff --git a/docs/rest-pki-core/on-premises/docker.md b/docs/rest-pki-core/on-premises/docker.md index 666458a..c0ec4dd 100644 --- a/docs/rest-pki-core/on-premises/docker.md +++ b/docs/rest-pki-core/on-premises/docker.md @@ -1,5 +1,5 @@ --- -sidebar_position: 10 +sidebar_position: 11 sidebar_label: "Setup em Docker" slug: /rest-pki/core/on-premises/docker --- diff --git a/docs/rest-pki-core/on-premises/index.md b/docs/rest-pki-core/on-premises/index.md index fa7ee83..ea3de5d 100644 --- a/docs/rest-pki-core/on-premises/index.md +++ b/docs/rest-pki-core/on-premises/index.md @@ -16,7 +16,7 @@ O Rest PKI Core é compatível com os seguintes ambientes: * [Windows Server](windows-server.md) * [Linux](linux/index.md) * [Docker](docker.md) -* Azure App Services +* [Azure App Services](azure/index.md) Clique em um dos ambientes acima para obter instruções específicas de instalação e atualização. diff --git a/docs/rest-pki-core/on-premises/logging.md b/docs/rest-pki-core/on-premises/logging.md index e5c60cd..162cc97 100644 --- a/docs/rest-pki-core/on-premises/logging.md +++ b/docs/rest-pki-core/on-premises/logging.md @@ -1,5 +1,5 @@ --- -sidebar_position: 11 +sidebar_position: 12 sidebar_label: "Logs" slug: /rest-pki/core/on-premises/logging --- diff --git a/docs/rest-pki-core/on-premises/prepare-database.md b/docs/rest-pki-core/on-premises/prepare-database.md index 9e686e3..75a7528 100644 --- a/docs/rest-pki-core/on-premises/prepare-database.md +++ b/docs/rest-pki-core/on-premises/prepare-database.md @@ -1,5 +1,5 @@ --- -sidebar_position: 12 +sidebar_position: 13 sidebar_label: "Preparando um banco de dados" slug: /rest-pki/core/on-premises/prepare-database --- diff --git a/docs/rest-pki-core/on-premises/unprivileged-db-user.md b/docs/rest-pki-core/on-premises/unprivileged-db-user.md index 63d7d09..9586e5b 100644 --- a/docs/rest-pki-core/on-premises/unprivileged-db-user.md +++ b/docs/rest-pki-core/on-premises/unprivileged-db-user.md @@ -1,5 +1,5 @@ --- -sidebar_position: 13 +sidebar_position: 14 sidebar_label: "Operando sem ser owner do banco" slug: /rest-pki/core/on-premises/unprivileged-db-user --- diff --git a/docs/rest-pki-core/on-premises/vulnerabilities.md b/docs/rest-pki-core/on-premises/vulnerabilities.md index 3c4483b..592d896 100644 --- a/docs/rest-pki-core/on-premises/vulnerabilities.md +++ b/docs/rest-pki-core/on-premises/vulnerabilities.md @@ -1,5 +1,5 @@ --- -sidebar_position: 14 +sidebar_position: 15 sidebar_label: "Verificações de vulnerabilidades" slug: /rest-pki/core/on-premises/vulnerabilities --- diff --git a/docs/rest-pki-core/on-premises/windows-server.md b/docs/rest-pki-core/on-premises/windows-server.md index 906d9d9..817625a 100644 --- a/docs/rest-pki-core/on-premises/windows-server.md +++ b/docs/rest-pki-core/on-premises/windows-server.md @@ -1,5 +1,5 @@ --- -sidebar_position: 15 +sidebar_position: 16 sidebar_label: "Configuração no Windows Server" slug: /rest-pki/core/on-premises/windows-server ---