Skip to main content

GlobalSign Atlas

GlobalSign Atlas is reached through its Certificate Management API ("HVCA") as a CA connector. CertAutoPilot logs in with your API key and secret over a TLS connection that presents your mTLS client certificate, checks that every name on the certificate is validated on your Atlas account (publishing the validation record in your zone when it is not), requests the certificate within the limits of your account's validation policy, stores it with the chain Atlas returns, and renews it on the usual threshold.

The contract and the certificate quota are yours: every certificate CertAutoPilot requests uses your Atlas account.

Before you start​

  • A GlobalSign Atlas account with a certificate pack (the quota the certificates come from) and access to the Atlas portal.
  • Outbound HTTPS from every CertAutoPilot worker to emea.api.hvca.globalsign.com on port 8443. A TLS-inspecting proxy on that path breaks the mTLS login — let the host through unmodified. See Outbound network.
  • For names not yet validated on the Atlas account: a zone with a DNS credential that can write TXT records, so CertAutoPilot can publish the validation record. Names already validated on the account need no zone — but a zone is still worth giving: when that validation ends, a renewal validates again through the zone, and a certificate's zone cannot be added later.

Set up step by step​

1. Create the API credential​

In the Atlas portal create an API credential for the certificate management (issuing) API. You get an API key (16 hexadecimal characters) and an API secret (40 hexadecimal characters). Keep the secret: CertAutoPilot stores it encrypted and never shows it again.

2. Save the connection​

Settings → Certificate Authorities → CA Connectors → Add connection:

FieldValue
NameAny name, unique in the project.
VendorGlobalSign Atlas.
Base URLLeave empty — CertAutoPilot uses https://emea.api.hvca.globalsign.com:8443/v2. An address with a query string, a fragment or a user name is refused: every API path is added to it.
API key / API secretFrom step 1.
mTLS client certificate / keyLeave empty for now (step 3), unless you already have a client certificate and its key for this API credential.

The connection can be saved before it has a client certificate, but it cannot be used yet: every call would fail in the TLS handshake (MTLS_CERT_MISSING).

3. Make the mTLS client certificate​

  1. Open the saved connection. In the mTLS client certificate card click Generate CSR. CertAutoPilot makes an RSA-2048 key, keeps it encrypted and shows its certificate request. Copy or Download it.
  2. In the Atlas portal open Credentials → mTLS Certificate → Generate an mTLS → Directly via the API, link it to the API credential from step 1, and give it the CSR.
  3. Download the certificate Atlas issues, paste it into Certificate issued for this CSR and click Save certificate. CertAutoPilot checks that it belongs to the generated key and switches to it. The card then shows the certificate's subject and expiry.

Atlas writes its own subject into the certificate (the name in the CSR is not kept); that is expected.

Renewing the client certificate. Click Generate another CSR before the certificate expires and repeat steps 2–3. The current key and certificate keep working until the new certificate is pasted. Test warns when the client certificate expires within 30 days.

Bringing your own. Use my own certificate and key instead takes a client certificate and private key made elsewhere (PEM). The key is stored encrypted and never shown again.

4. Test the connection​

Click Test on the connection. It logs in and reads the account's issuance quota — nothing is ordered. A success clears an error status. The quota Atlas reports through the API may read as unlimited even when the pack has a limit; the pack's real usage is shown only in the Atlas portal.

5. Issue a certificate​

Certificates → Issue Certificate, source CA Connector, pick the connection. There is no product to pick — the account's validation policy decides what is issued. Enter the domain names — as many as your account's validation policy allows (the wizard shows the limit). Below them, the zone that covers each name is suggested the same way as for ACME certificates; you can move a name to another zone. The names may live in several zones. A name with no zone is accepted only when it is already validated on the Atlas account. Key type: RSA 2048 (default), 3072 or 4096.

The renewal threshold must be below the longest validity your account's policy grants — a 30-day certificate with a 30-day threshold would be renewed halfway through its life and twice as many certificates ordered, so such a threshold is refused (CA_RENEWAL_THRESHOLD_TOO_LONG). The issue wizard reads the policy and suggests a third of the validity (10 days for a 30-day certificate, at most 90); a certificate created through the API without renewal_threshold_days gets the same value when the organisation default is not below the validity. The threshold must also be longer than the CA Order Deadline (default 72 hours ⇒ at least 4 days).

The account at a glance​

The connection's details page shows the Atlas account read live with read-only calls — nothing is ordered:

  • The validation policy — the key types and sizes, how many DNS names (and IP addresses) a certificate may carry, the longest validity, the key usages (and which optional one CertAutoPilot asks for), the extended key usage, the signature hashes, the subject fields and when the issuing CA expires.
  • Certificates issued and revoked on the account, and the quota as the API reports it (an AlphaSSL pack reads as unlimited there; its real usage is in the Atlas portal).
  • Validated domains — every domain claim on the account with its state, its expiry and how it was last validated. Expand a row for the names its proof may be published under and the addresses an approval e-mail may go to. A project admin can Remove a claim from the account; certificates already issued keep working, and the next certificate or renewal under it needs the domain validated again. A claim a certificate is waiting for cannot be removed — stop that validation first.
  • Certificates issued on the account (last 30 days, 90 days or a year) — every certificate Atlas issued on the account, through CertAutoPilot or elsewhere (the Atlas portal, another tool), with its serial, dates and whether it is active, expired or revoked. The ones CertAutoPilot holds link to the certificate and version. Certificates issued elsewhere cannot be imported from here: their private keys are not at Atlas.

The answer is cached for a minute per connection; Refresh reads it again. The issue wizard reads the same answer: it offers only the key types the policy allows, and for the domain you type it says whether a claim on the account already covers it (requested at once, no record) or whether CertAutoPilot validates it first.

There is no product choice on Atlas: each API credential belongs to one certificate pack and its policy. For another pack, create another API credential and another connection.

How domain validation works​

Atlas issues only for a domain with a verified claim on the account. A claim on a base domain (example.com) covers its subdomains (app.example.com). Claims are account-wide and independent of any certificate; they expire after a period Atlas sets.

For every certificate request CertAutoPilot:

  1. Checks the claims on the account (free). If the name is covered by a verified claim that is still valid for the request (at least one more hour), it requests the certificate at once — no DNS record is written. A claim about to end is renewed first: it gets a new token and counts again once GlobalSign shows it valid.

  2. Otherwise creates (or renews) the claim — for the domain of the name's zone, so one claim then covers every name in that zone; for the name itself when it has no zone — and publishes the TXT record Atlas asks for:

    _globalsign-domain-verification.<domain>. TXT "globalsign-domain-verification=<token>"

    through that zone's DNS credential. The record is not written at the domain apex, so other TXT records there (SPF and the like) are not touched.

  3. Waits until the record is visible on the configured resolvers, then asks Atlas to verify the claim. Atlas verifies within seconds once it sees the record.

  4. When every name is covered, a new order job requests the certificate, and the validation records are removed.

If a validation is waiting again when the order starts (a claim ran out in between), its record is written again and removed again when it ends.

The same domain on two accounts. Two connections (two GlobalSign API credentials) that validate the same domain publish different values under the same record name, and writing one would replace the other. The validation that started first keeps the name; the other one waits ("waiting for another validation of to finish") and writes its record when the first ends. Its order deadline keeps running while it waits.

Nothing is requested until every name is validated, so a validation that fails or does not finish before the order deadline costs no quota. Without a zone and without a verified claim the request stops with DOMAIN_NOT_VALIDATED before anything is ordered; validate the domain in the Atlas portal and re-issue, or issue a new certificate with a zone or one of the methods below (a certificate's zone and method are fixed when it is created).

Names in several zones​

One certificate can carry names that live in different zones — for example www.example.com and shop.example.org, each zone with its own DNS credential or provider.

  • In the issue wizard, the names are grouped by the zone suggested for each. A name the Atlas account has already validated may stay without a zone; a name it has not validated needs one.
  • Through the API, send domain_zones with the names that have a zone, each with its zone_id. Leave a name without a zone out of the list. zone_id, when sent too, must be the first name's zone. When every name uses one zone, zone_id alone is enough.
  • Each validation record is written, checked and removed through the zone that covers it. The certificate page shows every zone, and the order card says which zone each record was written into.
  • A name without a zone must be validated on the Atlas account when the certificate is requested. If it is not, the request stops with DOMAIN_NOT_VALIDATED before any record is written or anything is ordered.
  • A name and its wildcard (example.com and *.example.com) are validated together: both in the same zone, or both without one.
  • The rules for a listed name are the ones ACME certificates follow: the zone belongs to the project, the name is under it, and the zone has a DNS credential.
  • Names and zones are fixed when the certificate is created.
  • A zone or a DNS credential that a waiting validation still uses cannot be deleted.
  • This applies to automatic DNS. The other methods use no zone.

Proving a domain yourself​

The steps above are Automatic DNS, the default. When CertAutoPilot should not write into your DNS, pick another method on the issue wizard's Zone & Domain step (If GlobalSign Atlas has not validated the domain yet). These methods use no zone, and you choose the domain to validate: the name itself, or a parent domain, which then covers every name under it.

MethodWhat you doWhat CertAutoPilot does
Manual DNSPublish the TXT record the certificate's CA order card shows (_globalsign-domain-verification.<domain>, value globalsign-domain-verification=<token>). Remove it afterwards.Checks on each poll whether the record is visible on the configured resolvers, then asks Atlas to verify. It never writes or deletes the record.
HTTPServe the token the card shows at http://<domain>/.well-known/pki-validation/gsdv.txt (plain HTTP, port 80). The file may hold several tokens, at most 1024 bytes.Asks Atlas on each poll to fetch the file.
E-mailOn the card, click Send approval e-mail and choose an address — Atlas offers admin@, administrator@, webmaster@, hostmaster@ and postmaster@ the domain, plus contacts published in DNS. Someone with that mailbox clicks the link.Sends nothing on its own. After the send, it reads the claim on each poll and orders once it is validated.

The waiting time is the same order deadline as Automatic DNS; a proof that does not arrive by then ends the request without ordering anything (DOMAIN_VALIDATION_FAILED). A claim that runs out while waiting is renewed with a new token — the card then shows the new record or file, and an e-mail has to be sent again.

The HTTP and e-mail methods follow GlobalSign's API documentation; they are tested against a simulator, not against the live service. The token format in the HTTP file is taken to be the same as the DNS value.

Checking now​

While a validation waits, CertAutoPilot asks GlobalSign about it on a schedule: after 30 seconds, then 1, 2, 4 and 8 minutes, then every 15 minutes until the order deadline. Check now on the certificate's CA order card (operators) asks at once instead — useful right after the approval link was clicked, the record published or the file served. It only reads the validation at GlobalSign and buys nothing by itself; when the domain is validated, the order is placed as after a scheduled check. An asked-for check does not use up the scheduled ones and does not push the next scheduled check later.

Stopping a validation​

While the certificate waits for its domain validation, nothing has been ordered. Stop validation on the certificate's CA order card (operators) ends the wait for good:

  • It runs only while no order step of the certificate is running (otherwise it says so — try again in a moment) and only while no order exists.
  • The queued checks are cancelled, a record CertAutoPilot published is removed, and a check that was already running cannot restart the validation or order anything afterwards.
  • The certificate goes back to where it was: a re-issue to its earlier status, a renewal to renewal failed (it still needs renewing — renew when the domain can be validated), a first issuance to pending (both with DOMAIN_VALIDATION_STOPPED as Last error).
  • The claim already started on the Atlas account is left there; it may cover other names. Remove it in the Atlas portal if you no longer want it.
  • Revoke is not offered while a renewal or re-issue waits for its validation (the certificate is not at rest); stop the validation first, then revoke. The API's refusal says so.

Delete works on such a certificate too: it stops the validation the same way, then deletes the certificate. A certificate with an order already placed cannot be deleted until the order ends.

Because a validated claim lasts months (the one on the measured account lasts about a year) and covers subdomains, renewals normally need no validation at all. If one does — the claim expired — the renewal waits for the same proof as the first issuance, so keep the method you can repeat.

While the validation runs, the certificate's CA order card shows each domain, its record and whether it is waiting or validated. A request that stops before ordering (DOMAIN_NOT_VALIDATED, QUOTA_REACHED, POLICY_MISMATCH, DOMAIN_VALIDATION_FAILED) sends the cert.issuance_failed notification with the code, like a failure after an order.

Ordering and storing​

  • CertAutoPilot reads the account's validation policy before each request and sends only the fields it allows; a field the policy fixes is left out. A request that does not fit the policy is refused before sending with POLICY_MISMATCH: key type or RSA size, too many or too few names, a name outside the suffixes the policy allows, a required subject field, an extended key usage rule a TLS server certificate cannot meet. When the policy lets the request choose the extended key usage, TLS server authentication is asked for if one of the policy's patterns matches it in full; when usages are optional and none matches, nothing is sent and GlobalSign applies its default.
  • The public key goes in the form the policy asks for: a PKCS#10 request, or the SubjectPublicKeyInfo (PKCS8). When the policy requires a public key signature, CertAutoPilot signs the public key with the certificate's own key (SHA-256; the key itself never leaves CertAutoPilot). The PKCS8 form follows GlobalSign's API specification and is tested against a simulator only — the measured account uses PKCS#10.
  • The certificate gets the longest validity the policy allows.
  • Atlas issues within seconds of the request. CertAutoPilot stores the certificate with the chain from Atlas's trust-chain endpoint and runs the normal distribution.
  • No answer to the request. If the request was sent and got no usable answer (an HTTP 5xx or no answer at all), Atlas may or may not have created the certificate. CertAutoPilot records the moment of every request it sends and, before asking again with the same key, looks in the account's issued certificates around each of those moments for one with that public key, and uses it when found. The list shows a new certificate only about 20 seconds after it is issued, so a look soon after the last request waits for it first. Whenever the answer is not certain — the list cannot be read, it does not say how many certificates it holds, a listed certificate cannot be read, or the clock of the CertAutoPilot server and Atlas's clock differ by more than 10 minutes — the request stays unconfirmed and nothing is requested. Nothing is bought twice.
  • An unconfirmed request is shown on the certificate's order card. Re-issue asks again and is always safe. A project admin can also Discard request there when they are sure Atlas holds no certificate for it (the card links to the connection's issued certificates to check): the certificate goes back to its earlier status with ORDER_REQUEST_DISCARDED, and the next request is a new one — if Atlas did create a certificate for the discarded request, the new one uses quota for a second certificate. An expired certificate is then taken out of automatic renewal, so nothing is bought by itself.

Limits​

CertAutoPilot fixes none of these per account: each comes from your account's validation policy, read live (the connection's Account panel and the issue wizard show it), or is decided by GlobalSign when the request is sent. The values in brackets are those of the AlphaSSL account the connector was measured on.

LimitWhere it comes from
Names per certificateThe policy's number of DNS names (measured: 1). Several names are validated each on the account, then requested together.
Allowed namesThe policy may list the suffixes names must end with (measured: none — any name).
WildcardsThe policy does not say. CertAutoPilot sends the wildcard name and GlobalSign decides; a refusal comes before anything is issued and uses no quota. A *.example.com name is validated through example.com.
Key typesThe policy's key type: RSA with the sizes it lists (measured: 2048, 3072, 4096), or ECDSA — then CertAutoPilot offers P-256 and P-384 and GlobalSign decides, because the policy does not name curves in CertAutoPilot's terms.
ValidityThe longest the policy allows (measured: 30 days).
Extended key usageWhen the policy fixes it, GlobalSign sets it and nothing is sent. When the request may choose, CertAutoPilot asks for TLS server authentication (1.3.6.1.5.5.7.3.1), provided one of the policy's patterns allows it; a policy that does not allow it, or that requires more than one usage, is refused with POLICY_MISMATCH before anything is ordered.
SubjectCommon name only (domain-validated); a policy that requires another subject field is refused with POLICY_MISMATCH.
Key usageDigital signature always; key encipherment is optional on the measured policy and CertAutoPilot asks for it for RSA keys, so TLS 1.2 RSA key exchange works too. A policy that fixes it off gets digital signature only (ECDHE suites and TLS 1.3 work either way).
RevocationRevoke on the certificate (or on an earlier version in its history) revokes it at Atlas by its serial; Atlas accepts the reasons key compromise, affiliation changed, cessation of operation and superseded — any other reason is sent as unspecified. A certificate Atlas already revoked counts as revoked. Whether a revoked certificate returns its unit to your quota depends on your GlobalSign agreement (the measured trial pack did not). Revoking reaches only the certificate CertAutoPilot holds: when a request ended without an answer or the issued certificate could not be stored, the Revoke dialog warns that GlobalSign may hold another one, to be revoked in the Atlas portal.
Renew, Re-issue, RekeySee Renew, Re-issue and Rekey.

Renew, Re-issue and Rekey​

The certificate page explains the three (the ⓘ next to the buttons):

ActionWhat it doesQuota
RenewA new certificate request before the current one expires, with the validity the policy grants. The key follows the certificate's key rotation setting. A domain not validated on the account is validated first.One certificate.
Re-issueA new certificate request now, with a new key and the same names. Offered when the certificate is not active (its issuance failed, it expired, its renewal failed).One certificate.
RekeyGlobalSign issues a copy of the current, active certificate with a new key: the same names, no domain validation. The current certificate stays valid at GlobalSign — revoke it if its key was exposed.Not stated by GlobalSign's API: it depends on your agreement.

Rekey uses Atlas's rekey call. Because its cost and the new certificate's end date are not documented, CertAutoPilot treats it like a paid request: it is sent once and never repeated by itself; if it fails after it was sent — or the worker was interrupted while it was in flight — the certificate stays active with its current key, and Last error says that GlobalSign may hold a certificate for it (VENDOR_NO_RESPONSE): look in the Atlas portal before asking for another one. It asks for the same approval as Re-issue in projects that require one. Rekey has not been tried against a live account yet.

Error codes​

A failure writes <CODE>: <explanation> into the certificate's Last error and into the code variable of the cert.issuance_failed / cert.renewal_failed notification.

CodeMeaningWhat to do
AUTH_FAILEDAtlas refused the API key / secret, or the mTLS certificate is not linked to this API credential. The connection turns error.Check the key and secret; make sure the mTLS certificate was created for this API credential. Run Test, then Re-issue.
MTLS_CERT_MISSINGThe connection has no mTLS client certificate yet.Step 3.
MTLS_CERT_INVALIDThe mTLS client certificate has expired, is not valid yet, or does not match its key.Generate a new CSR and paste the new certificate.
QUOTA_REACHEDThe account's certificate quota is used up. No certificate was ordered.Add quota in the Atlas portal, then Re-issue (renewals retry on their ladder).
POLICY_MISMATCHThe request does not fit the account's validation policy. No certificate was ordered.The explanation names the rule (key type, key size, number of names, a required subject field).
REQUEST_INVALIDAtlas refused the request as malformed.The explanation carries Atlas's description.
RATE_LIMITEDToo many requests.Retried automatically.
SERVICE_BUSYAtlas answered an HTTP 5xx to a call that buys nothing.Retried automatically.
CERTIFICATE_NOT_FOUNDAtlas does not know the certificate CertAutoPilot asked about.Check the Atlas portal with the serial from the job log.
CERTIFICATE_REVOKEDThe certificate was revoked at Atlas before CertAutoPilot stored it.Re-issue.
CERTIFICATE_FAILEDAtlas reports the certificate in another state than issued or revoked.Check the Atlas portal; Re-issue.
UNEXPECTED_ANSWERAn answer CertAutoPilot does not understand.Check the job log; contact support with it.
DOMAIN_NOT_VALIDATEDThe name has no verified claim and no zone to validate it through (the certificate has none, or names none for that name). No certificate was ordered.Validate the domain in the Atlas portal and Re-issue, or issue a new certificate with a zone that has a DNS credential (or another validation method).
DOMAIN_VALIDATION_FAILEDAtlas did not accept the claim, or the proof (record, file or approval) did not arrive before the order deadline. No certificate was ordered.Check the record, the file or the e-mail named on the order card and in the job log, then Re-issue.
CA_VALIDATION_METHOD_UNSUPPORTEDThe certificate asks for a validation method the vendor does not offer.Pick another method.
CA_VALIDATION_EMAIL_NOT_ALLOWEDSend approval e-mail named an address Atlas does not accept for the domain. Nothing was sent.Choose one of the addresses offered.
CA_VALIDATION_NOT_WAITINGSend approval e-mail, Check now or Stop validation while no validation waits (it finished, failed, was stopped or an order was placed).Reload the certificate page.
CA_VALIDATION_BUSYStop validation while a step of the order is running.Try again in a moment.
DOMAIN_VALIDATION_STOPPEDAn operator stopped the domain validation. Nothing was ordered.Re-issue (or Renew for a renewal) when the domain can be validated.
CA_DOMAIN_IN_USERemove on a validated domain of the account while a certificate waits for it.Stop that certificate's validation first.
CLAIM_CHECK_RUNNINGRemove while Atlas is checking that domain right now.Try again in a moment.

The connector codes shared by every vendor — VENDOR_UNREACHABLE, VENDOR_NO_RESPONSE, VENDOR_REDIRECT, DCV_WRITE_FAILED, CA_ORDER_DEADLINE_EXCEEDED and the others — are in the error-code reference.

FAQ​

Do I need a zone for every certificate?​

No. A name covered by a verified claim on the Atlas account is issued without a zone and without a DNS record. A zone is needed only to let CertAutoPilot publish the validation record for a name that is not validated yet.

The wizard still lets you pick a zone for a name the account already validated, and it is worth doing for a certificate that renews automatically: a claim ends after a few months, and a renewal after that needs the zone to validate again. Without one that renewal stops with DOMAIN_NOT_VALIDATED, and because the zone is fixed when the certificate is created, the certificate has to be created again.

Can I see the private key of the mTLS client certificate?​

No. A key made by Generate CSR is stored encrypted and is never shown or returned by the API. If you need the key elsewhere, make the certificate yourself and use Use my own certificate and key instead.

Does generating a new CSR break the connection?​

No. The current key and certificate keep working until you paste the certificate issued for the new CSR.

Why does every renewal use quota?​

CertAutoPilot requests a new certificate for each renewal and each re-issue. Rekey is the only action that may not use quota, depending on your GlobalSign agreement. Plan the pack size with the certificate validity in mind.

The test says the quota is unlimited, but the pack has a limit​

The quota Atlas reports through the API does not reflect the pack. The pack's usage is shown in the Atlas portal.

See also​