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 Notifying About Shipments.
  • 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. See Example Subscriptions.
  • 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.

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 Adding WebAuthn 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).

Shipping

  • 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 Key Quantities and Delivery Types.

  • 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 FAQs - FIDO Pre-reg for Okta.

Limits and Constraints

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.

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.