Skip to content

Latest commit

 

History

History
143 lines (99 loc) · 5.98 KB

index.mdx

File metadata and controls

143 lines (99 loc) · 5.98 KB

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 and follow vault's plugin registration instructions.

(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:

    $ 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:

    $ 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.

    $ 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

    $ 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

    $ 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

    $ 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

    $ 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

    $ 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.

    $ vault write atlas/tidy

Usage

asciicast

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 for more details.