Best Practices and Troubleshooting

The following sections provide recommendations, best practices and troubleshooting support when working with the YubiEnterprise Console.

Best Practices

General Recommendations

  • Checking service status: If YubiEnterprise Delivery appears to be behaving strangely, check the status of YubiEnterprise Services: http://status.yubico.com/. Subscribe to that page to receive updates related to YubiEnterprise Console planned maintenance and/or downtime.
  • Mail notifications: The YubiEnterprise Delivery system automatically notifies shipment recipients by email for example when products are sent, or if there is a problem with a delivery. Ensure to inform your users and recipients about this so that these emails from Yubico are not regarded as phishing attempts. For more information, see Shipment Notifications.
  • Contacting Support: If you need to contact Customer Support, ensure to use the dedicated support form for YubiEnterprise Delivery. For security reasons, the email address submitted in the support form must be from a designated Console user. It is also helpful to provide a best contact to be notified of orders that have returned to sender.

Shipment Requests

  • Recipient information: To ensure a successful delivery of YubiKeys, it is important that the correct recipient information is entered in the shipment request. Ensure to review the guidelines provided in Recipient Information.

  • Key quantities: Using the YubiEnterprise Delivery service you can ship keys to many countries around the world. Each destination country has a maximum number of keys per shipment request. For some countries you can include up to 500 keys per shipment request, and some countries have a single key limit per shipment due to custom duty regulations. For more information, see Destinations and Quantities.

  • Shipping destinations: The countries you want to ship to must first be enabled for your organization in the YubiEnterprise Delivery system. This is done during the onboarding setup of your organization. To enable more shipping destinations, contact Support.

  • Company name and phone number: When entering recipient information in a shipment request, do not provide a company name if you are shipping to a residential address, since this might cause delivery issues with the carrier. Always provide a valid phone number to the recipient since many carriers use this phone number to enable final delivery.

  • Updating or cancelling shipment requests: This can be done until 2am PST (10am GMT) the day after they were entered. Delivery time to different parts of the world varies. For more information, see Time Frames.

  • Delivery exceptions: A “Delivery Exception” shipment status is triggered when a carrier is citing an order delivery issue. Below are some common reasons for delivery exceptions:

    • Address is undeliverable, or there was no access to delivery location
    • Door code (digicode) or telephone number required to deliver
    • Longer than normal delivery timeline
    • Company name on a residential address
    • Item was held by customs, or was lost
    • Weather or operational delays
    • Customer has a mail hold for delivery, or refused delivery

    To investigate delivery issues, you can check the tracking information (if available) for your shipment.

  • Refunds and replacements: In some cases shipments fail to arrive at their destination due to delivery errors. When this happens, a shipment can be replaced or refunded. For more information, see the Yubico Enterprise Return Merchandise Authorization policy.

  • Shipping pre-registered keys with Okta: For questions and guidance related to Yubico FIDO Pre-reg for Okta, see FIDO Pre-reg with Okta FAQs.

Subscription & Inventory Management

  • Understanding subscriptions: With a YubiEnterprise Subscription you purchase YubiKey licenses through an end user-based subscription model and select preferred YubiKeys over time, with replacement and upgrade options as needs evolve. To learn more about subscriptions, see Modes of Purchase.
  • Preventing inventory expiry: As a Subscription customer, to ensure that you do not let keys in any of your inventories expire unused, create a spreadsheet to plan the allocation of products across users and inventory types. Check your organizations’ Console Dashboard regularly to verify available inventory.
  • License usage: When creating shipment requests in the YubiEnterprise Console, you will be able to select from all your available inventory. Ensure to select form the correct inventory when creating shipment requests for replacement and backup YubiKeys. See Examples.

User Management

  • Preventing account lockout: Ensure your organization has at least two Console Owners for the account. This way, if a Console Owner is locked out, the other Console Owner can easily reset their account as only a Console Owner can do user resets.

    If your organization only has one Console Owner and that person locks themselves out or leaves your organization, you must contact Yubico to set up a new Console Owner which might delay shipment requests. For more information, see User Management.

  • Backup key: It is recommended that Console users register at least two YubiKeys for their account to be able to log in if a key is lost. For more information, see Managing Login Credentials.

  • SSO and user management: Users invited to log in to the Console after SSO is enabled will not be prompted to set up a username and password. Therefore, if SSO is later disabled, those users will not be able to log in without SSO. If SSO is disabled, these users will need to be reset so that they may enroll the proper login credentials. For more information, see Single Sign-On (SSO).

Synced Passkeys

Before you upgrade to passwordless authentication when logging in to the Console, it is recommended to remove any existing synced passkeys associated with the YubiEnterprise Console login.

Leaving old synced passkeys for your account can cause confusion during the login process. Authentication might fail if your browser uses the wrong passkey, and you might experience issues when registering a new YubiKey-based passkey.

The following describes how to remove existing synced passkeys from some common instances.

  • Windows 11 - Microsoft Edge/Google/Chrome/Firefox

    1. Open Windows Settings.
    2. Go to Accounts > Passkeys.
    3. Delete any existing passkeys for https://login.yubico.com/.

  • Windows 10 - Microsoft Edge/Google Chrome/Firefox

    Deletion requires administrative privileges. Microsoft does not provide an official GUI for deleting passkeys in Windows 10. Instead you can use a command line tool from a command prompt as follows:

    • Key Listing: certutil -csp NGC -key -v
    • Key Deletion: certutil -csp NGC -delkey <identifier>

    If you prefer a GUI, you can use this webauthn-fido2-key-remover tool. However, this tool is not an official Yubico or Microsoft product and should be used at your own risk.

  • Apple OS X (15+)

    Microsoft Edge/Google Chrome are listed twice because earlier Edge/Chrome on OS X 15 did not support storing passkeys in the Apple Passwords app, later versions do. You might need to check all instances for passkeys.

    • Safari/Firefox/Microsoft Edge/Google Chrome
      1. Open the Passwords App.
      2. Go to the Passkeys section.
      3. Delete any existing passkeys for https://login.yubico.com/.
    • Microsoft Edge
      1. Go to your Edge profile passkeys on edge://wallet/passkeys.
      2. Delete any existing passkeys for https://login.yubico.com/.
    • Google Chrome
      1. Go to your Chrome profile passkeys on chrome://settings/passkeys.
      2. Delete any existing passkeys for https://login.yubico.com/.

  • Apple OS X (14)

    • Safari/Firefox
      1. Open the Settings App.
      2. Go to Passwords.
      3. Delete any existing passkeys for https://login.yubico.com/.
    • Microsoft Edge
      1. Go to your Edge profile passkeys on edge://wallet/passkeys.
      2. Delete any existing passkeys for https://login.yubico.com/.
    • Google Chrome
      1. Go to your Chrome profile passkeys on chrome://settings/passkeys.
      2. Delete any existing passkeys for https://login.yubico.com/.

  • Linux - Google Chrome

    1. Go to your Chrome profile passkeys on chrome://settings/passkeys
    2. Delete any existing passkeys for https://login.yubico.com/.

  • Android - Google Chrome

    You cannot delete passkeys using your Android phone, instead you need to use a desktop version of Chrome and log in using the same profile.

    1. Go to your Chrome profile passkeys on chrome://settings/passkeys
    2. Delete any existing passkeys for https://login.yubico.com/.

  • Apple iPadOS/Apple iOS (18+) - Safari

    1. Open the Passwords App.
    2. Go to the Passkeys section.
    3. Delete any existing passkeys for https://login.yubico.com/.

  • Apple iPadOS/Apple iOS (16-17) - Safari

    1. Open the Settings App.
    2. Go to Passwords.
    3. Delete any existing passkeys for https://login.yubico.com/.

Troubleshooting

Address Validation Errors

  • Managing incompletes: YubiEnterprise Delivery uses address validation services. However, even if an address exists in an address directory, it does not mean that the address is deliverable. To resolve address validation errors, edit the shipment request to ensure that the provided recipient information is correct and complete. For more information, see Reviewing Incompletes.
  • Address not accepted by carrier: If your shipment request fails with the status “Address Not Accepted by Carrier” this usually indicates that the street name in the recipient address is too long, exceeding the character limits set by the associated carrier. To solve this issue, edit the shipment request to shorten the address, or split the address between Address line 1 and 2, and then resubmit the shipment request. For more information, see Recipient Information.
  • Overriding address validation: The Yubico address validation service sometimes gives an error even if an address is valid. If you are confident that a provided address is valid, you have the option to override the address validation warnings generated by the system. For more information, see Address Validation.

Insufficient Inventory Errors

To maintain the window during which orders can be updated, edited, or cancelled, orders are held and processed in batch. Therefore there might be less inventory available by the time an order is processed than what was shown in purchase order details when the request was created. For more information, see Shipment Processing. Inventory can also be allocated by Yubico due to limited availability. For more information, see Shippable Inventory.

Shipment requests processed from an insufficient inventory are flagged with the status “Error: Processing Error, contact Support” in the Console, and the API message “Not enough Inventory for Shipment - ShipmentStateError”.

To resolve insufficient inventory errors, you can contact Yubico to request more inventory, and either update the product selection for the shipment request, or cancel it and create a new one when there is sufficient inventory available.

If you are using an API integration to create shipment requests, it is recommended to verify inventory availability before creating a shipment request to avoid insufficient inventory errors. For more information, see Inventory.

Shipment Status Codes

To check the status for a shipment, see Viewing Shipments. For explanations of shipment status codes and associated status messages, see Shipment Status Codes.

Shipment Error Messages

For shipment error messages, see Shipment Error Messages.

To file a support ticket for YubiEnterprise Delivery, click Support.