Add files via upload

website/content/docs/secrets/GlobalSign.mdx

@@ -0,0 +1,143 @@
+
+---
+layout: docs
+page_title: GlobalSign Atlas - Secrets Engine
+sidebar_title: GlobalSign Atlas
+description: |-
+  The GlobalSign Atlas secrets engine for Vault issuing and managing Atlas certificates.
+---
+
+# GlobalSign Atlas Secret Engine
+
+The GlobalSign Atlas secret engine generates, issues, and manages certificates
+dynamically in your ATLAS account. This simplifies certificate issuance
+and life cycle management, as the engine can manage key generation, life cycle. Additionally
+this enables codifying and mapping issuance policy to internal authentication methods such as
+public cloud credentials or SSO solutions.
+
+# Setup
+
+Most secrets engines must be configured in advance before they can perform their
+functions. These steps are usually completed by an operator or configuration
+management tool.
+
+This documentation assumes you have already registered the Atlas plugin with your Vault instance,
+ if you haven't please download the [latest release](https://github.com/globalsign/atlas-hashicorp-vault/releases) and follow [vault's plugin registration instructions](https://www.vaultproject.io/docs/internals/plugins#plugin-registration).
+
+**_(Note: We have automated most of these plugin registration steps and user can directly navigate to_** `atlas-hashicorp-vault` **_and run_** `make`**_. This will register the plugin and start server)_**
+
+1.  Enable the GlobalSign Atlas secrets engine:
+
+    ```bash
+    $ vault secrets enable atlas
+    Success! Enabled the atlas secrets engine at: atlas/
+    ```
+
+    By default, the secrets engine will mount at the name of the engine. To
+    enable the secrets engine at a different path, use the `-path` argument.
+
+2.  Configure the credentials that Vault uses to communicate with Atlas to issue and
+    manage certificates:
+
+    ```bash
+    $ vault write atlas/config/authn \
+        api_key=<Your_Atlas_API_Key>
+        api_secret=<Your_Atlas_API_Secret>
+        api_cert=$(base64 --wrap=0 < ./your_atlas_client_certificate.pem)
+        api_cert_key=$(base64 --wrap=0 < ./your_atlas_client_certificate_key.pem)
+    ```
+
+    Internally, Vault will connect to GlobalSign Atlas using these credentials.
+
+    ~> **Notice:** Your client certificate should be provided as a base64 encoded PEM certificate and PEM private key.
+        You can acquire the certificate from your account manager.
+    ~> **Notice:** If you are getting PEM not recognized errors, you may need to add the `--wrap=0` flag to your base64 commands.
+
+3.  Configure a Vault role that maps to a set of permissions.
+    ```bash
+    $ vault write atlas/roles/my-role allow_any_name=true enforce_hostnames=false
+    ```
+
+    This creates a role named "my-role". When users generate certificates against
+    this role, Vault will validate the certificate request against the permissions.
+    Vault will then send the certificate request to be issued by your Atlas instance.
+
+    The above role constraints are permissive, we would recommend tighter rules to fit your use case. Note that your Atlas account
+    policy will also apply to issued certificates, only certificates that meet both local and Alas policies will be issued.
+
+
+4.  Issue a Certificate through Vault using your role
+    ```bash
+    $ vault write atlas/issue/my-role common_name="example.com" ttl=24h
+    ```
+
+    This creates a Private Key and a Certificate using the provided role and certificate configuration. You can reference this
+    certificate in future requests using the serial number returned in the response.
+
+    Keep note of your private key, you won't be able to retrieve it in future requests.
+
+5.  Sign a CSR through Vault using your role
+    ```bash
+    $ vault write atlas/sign/my-role csr="$(cat my_signing_request.csr)" ttl=48h
+    ```
+
+    This will evaluate your signing request and other options against your local role and Atlas account policy, if successful it will
+    return a signed certificate and serial number for future reference.
+
+6. List Your Certificates
+    ```bash
+    $ vault list atlas/certs
+    ```
+
+    This returns a list of certificate serial numbers that have been issued through this Vault cluster. This can be used for
+    getting more details or revoking certificates.
+
+7. Get Details on a Certificate
+    ```bash
+    $ vault read atlas/cert/00-00-00-00-00-00-00-...
+    ```
+
+    This will give you the certificate pem and other issuance metadata, you can get the serial number from the certificate itself if
+    you would like to reverse this, but you must separate hex pairs with `-`.
+
+    Note that you can only get details on certificates issued through this Vault cluster, once a certificate is expired
+    or revoked it will remain visible here for a short period of time.
+
+
+8. Revoking a Certificate
+    ```bash
+    $ vault write atlas/revoke serial_number=00-00-00-00-00-00-00-...
+    ```
+
+    Just like Get details this requires a `-` separated serial number. This will have your Atlas account add the certificate to
+    relevant revocation lists, and update its status within the Vault cluster.
+
+    If you are revoking lots of certificates it's a good idea to invoke tidy, which will clean up excess metadata within Vault.
+
+    ```bash
+    $ vault write atlas/tidy
+    ```
+
+
+## Usage
+
+[![asciicast](https://asciinema.org/a/K5k9khe33IN7Ewot6yMN6yjBB.svg)](https://asciinema.org/a/K5k9khe33IN7Ewot6yMN6yjBB)
+
+## Troubleshooting
+
+If you get stuck at any time, simply run `vault path-help atlas` or with a subpath for
+interactive help output.
+
+### Not Authenticated Error
+
+If you are seeing unauthenticated errors from Atlas you may need to update the credentials stored in Atlas. You can do this by calling the `config/authn` endpoint.
+
+### Unable to Find Certificate Issued Outside of Vault
+
+The Atlas plugin will only keep track of certificates issued through the plugin, outside certificates won't be visible nor can they be mutated.
+
+## API
+
+The Atlas secrets engine has a full HTTP API. Please see the
+[Atlas secrets engine API](https://github.com/globalsign/atlas-hashicorp-vault/blob/master/website/pages/api-docs/secret/vault-plugin-secrets-atlas/index.mdx) for more
+details.