Merge pull request #76 from 0xPolygonID/vault-authentication

adds Vault Authentication article

docs/issuer/vault-auth.md

@@ -0,0 +1,77 @@
+---
+id: vault-auth
+title: Issuer Node and Vault Authentication
+description: Learn the two options for authenticating with Vault in the Issuer Node.
+keywords: 
+  - docs
+  - polygon id
+  - issuer node
+  - vault
+  - authentication
+  - token
+  - username
+  - password
+---
+
+## Authenticating with Vault in Issuer Node: Two Options Explained
+
+The issuer node supports two authentication alternatives to securely store private keys and DIDs within Vault.
+In this article, we'll guide you through utilizing each of these alternatives assuming you're running the issuer node using Docker and Docker Compose.
+
+## Authentication via Vault Token
+
+This option, an older method utilized by the issuer node, relies on using the root token generated by Vault upon its initialization.
+
+To employ this method, follow these steps:
+
+1. Set the following environment variable in the `.env-issuer` file:
+
+    `ISSUER_VAULT_USERPASS_AUTH_ENABLED=false`
+
+    Another option is to remove the `ISSUER_VAULT_USERPASS_AUTH_ENABLED` entry from the file to get the default value (false)
+
+2. Run the command below to add the Vault token to the `.env-issuer` configuration file:
+
+    `make add-vault-token`
+
+
+After step 2, the `.env-issuer` configuration file should contain an entry similar to this:
+
+`ISSUER_KEY_STORE_TOKEN=hvs.HW8Qup9s6LBUA0ff8Q1TO6Uc`
+
+Finally, start or restart the issuer node to ensure it includes the change in the file.
+
+:::note
+
+You can verify the token generated by Vault to match it with the value in the `.env-issuer` file using this command:
+
+```bash
+`make print-vault-token`
+```
+
+This command will print the Vault token in the terminal, and it should match the one configured in the `.env-issuer` file.
+:::
+
+## Authentication via Username and Password
+
+Upon Vault startup, an initialization script is executed. Among its tasks, it creates the user `issuernode` with the password `issuernodepwd` for the issuer node. To use this authentication alternative in Vault, follow these steps:
+
+1. Set the following environment variables in the `.env-issuer` file:
+
+    `ISSUER_VAULT_USERPASS_AUTH_ENABLED=true`
+
+    `ISSUER_VAULT_USERPASS_AUTH_PASSWORD=issuernodepwd`
+
+2. Restart the issuer node if necessary.
+
+You might want to change the password for the `issuernode` user. To do this, follow these steps:
+
+1. Execute `make new_password=new_password change-vault-password`
+2. Update the value of the environment variable in the `.env-issuer` file: `ISSUER_VAULT_USERPASS_AUTH_PASSWORD=new_password`
+3. Restart the issuer node if necessary.
+
+:::tip Which Option to Choose?
+
+Well, it depends on the context, where you're running the issuer node, and whether you have permissions to access the Vault-generated token.
+
+:::

sidebars.js

@@ -96,6 +96,7 @@ module.exports = {
             "issuer/schema-exs",
           ]
         },
+        "issuer/vault-auth",
         "issuer/credential-marketplace",
         "contracts/credential-linkage",
         "issuer/cred-issue-methods",