Workspace onboarding
The key ceremony that creates a Ledger Enterprise Workspace: who attends, the hosted and on-premises variants, each step, and what the ceremony produces.
Workspace onboarding is the key ceremony that creates your Workspace. It runs one time, before anyone can sign in to the Ledger Enterprise interface.
Role: the first three Administrators of a new Workspace, and its three Shared Owners.
What the ceremony is
Ledger creates the onboarding for your organization and gives you an onboarding ID. The ceremony then runs in the Onboarding app, a separate application from the Ledger Enterprise interface. The participants connect their Ledger devices to the Onboarding app, one device at a time.
The ceremony has two variants. Ledger sets the variant when it creates the onboarding.
Where the Hardware Security Module (HSM) runs
Ledger hosts it
On your organization's premises
Ledger devices
6: 3 Administrator devices and 3 Shared Owner devices
3 Administrator devices
Master seed
Generated in the HSM from three shards, one from each Shared Owner device
No Shared Owners and no master seed step
Specific step
Register shared owners and Collect shards
Register external signer
Each device holds one role for the whole ceremony. The Onboarding app shows the roles as Administrator and Shared Owner. An Administrator of the ceremony becomes a Master Administrator of the Workspace.
Before the ceremony
Each participant has a Ledger Stax that is set up with a PIN. See Your security device.
Each device runs the firmware and the Ledger Vault app version that Ledger Enterprise requires. On the Onboarding app home page, select Update my device to check a device and install the updates.
The Administrators agree on their three Administrator names. See Administrator names.
Join the ceremony
Open the Onboarding app.
In Your Onboarding ID, enter the onboarding ID that Ledger gave you.
Select Join my organization.
Select Start. If the ceremony has already started, the page shows the current step, and the button reads Join session.
The side panel of the Onboarding app shows the ceremony as Key ceremony, with the steps that your team completed.
The steps of a hosted Workspace
The Onboarding app names each step in its side panel. The steps run in this order.
1. Declare required devices
Each device is assigned to a role, and checked before it joins the ceremony.
Select Claim.
Select Administrator device or Shared Owner device.
Select Claim an Administrator device or Claim a Shared Owner device.
Connect the device.
Unlock the device.
Follow the checks on the screen. The Onboarding app checks the firmware and the Ledger Vault app, and offers to install updates.
Select Claim.
Do these steps again for each device: 3 Administrator devices and 3 Shared Owner devices.
Select Continue.
A device can be claimed one time only. To correct a claim, open the menu on the device card. Then select Un-claim. Each role takes exactly 3 devices.
2. Register administrators
Each Administrator device registers a user in the HSM.
Select Start.
Connect an Administrator device.
In Administrator name, enter the name of this Administrator.
Select Onboard my device.
Follow the instructions on the Ledger device.
Do these steps again for the two other Administrator devices.
Select Continue.
When you select Continue, the HSM creates the Master Administrator group of the three Administrators, with a Confirmation Threshold of 2.
3. Register shared owners
Each Shared Owner device registers in the HSM, so that it can contribute to the master seed later. A Shared Owner does not enter a name: the Onboarding app names each Shared Owner from its device ID.
Select Start.
Connect a Shared Owner device.
Select Onboard my device.
Follow the instructions on the Ledger device.
Do these steps again for the two other Shared Owner devices.
Select Continue.
4. Workspace settings
The three Administrators review the default settings of the Workspace and the registered users. Each approval is a signature from an Administrator device.
Select Start.
Connect an Administrator device.
Select Review settings.
Review the details on the Ledger device.
Approve on the Ledger device.
Do these steps again for the two other Administrator devices.
Select Continue.
All three Administrators must approve. Two approvals are not enough at this step.
5. Collect shards
Each Shared Owner device approves the onboarding details and sends its shard of the master seed to the HSM. The shard travels encrypted.
Select Start.
Connect a Shared Owner device.
Select Collect my shard.
Follow the instructions on the Ledger device.
Do these steps again for the two other Shared Owner devices.
Select Continue.
The HSM generates the master seed from the three shards. See The master seed.
6. Launch workspace
Select Launch followed by your Workspace name.
When the page shows that your Workspace is ready, select Download summary.
Select Go to followed by your Workspace name to open the Ledger Enterprise interface.
The steps of an on-premises Workspace
An on-premises Workspace has no Shared Owners. Its steps are:
Declare required devices, with 3 Administrator devices only.
Register administrators, as for a hosted Workspace.
Workspace settings. The three Administrators approve the Master Administrator group.
Register external signer. The three Administrators approve the external signer that the HSM uses to create the Workspace partition. Each Administrator selects Review external signer, then approves on the Ledger device.
Launch workspace, as for a hosted Workspace.
After the launch, Master Administrators manage the external signer keys in Workspace settings.
What the ceremony produces
The Workspace, with the name that Ledger set when it created the onboarding.
Three Master Administrators. Each one is a Personal Security Device (PSD) user with the Administrator role, and signs in with their Ledger device.
A Confirmation Threshold of 2. Each Workspace governance Request needs the approval of 2 Master Administrators. See Workspace settings.
The master seed, in the HSM of a hosted Workspace.
The onboarding summary, a PDF file titled "Ledger Enterprise Onboarding Summary".
The summary holds the Workspace name, the onboarding ID and the completion date. For each Shared Owner device, it gives the public key and the device ID. For each Administrator device, it also gives the user name.
The ceremony creates no Operators, no Accounts and no Policies. After the launch, the Master Administrators invite the other users from Users. See Users.
Administrator names
The Administrator name becomes the user name of the Master Administrator in the Workspace.
It has 1 to 19 characters, after the Onboarding app removes the spaces at the start and at the end.
It uses printable ASCII characters only. Letters with accents and other scripts are refused.
Each name is unique in the onboarding.
It cannot be changed later.
The Onboarding app asks for a name with no personal information, such as "Admin 1". The app does not check this.
Shared Owners
A Shared Owner holds one of the three shards of the master seed of a hosted Workspace. A Workspace has exactly three Shared Owners.
A Shared Owner is not a user of the Workspace. A Shared Owner does not sign in, and does not approve Requests.
After the ceremony, the three Shared Owners are needed again only to recover the master seed. The recovery uses the 24-word recovery phrase of each Shared Owner device, not the device itself. See Recovering the master seed.
A device cannot be both an Administrator device and a Shared Owner device in the same ceremony.
Replacing a Shared Owner
A Shared Owner can leave your organization, or die. Your organization keeps the role covered with its own process. Ledger does not run this process.
A recommended set-up:
Keep each shard in its own bank safe. A shard here is the recovery phrase of one Shared Owner device.
Apply strict access controls to each safe.
Define a process that hands over the access to a safe to a new Shared Owner when the previous one leaves.
Warning: You may doubt the integrity of this process, or a shard may be lost or compromised. In either case, contact your Technical Account Manager (TAM) at Ledger at once for advice.
The master seed
The master seed is the root of the keys of every Account in a hosted Workspace.
The HSM generates it from three shards. Each Shared Owner device gives one shard.
It never leaves the HSM. No person and no device holds it.
To recover it outside the HSM, all three Shared Owner recovery phrases are necessary.
What can go wrong
This onboarding ID doesn’t exist. Please check your entry, or contact support.
No onboarding has this ID
Check the ID that Ledger gave you
This onboarding ID cannot be reached at the moment. Please try again later or contact support.
The Onboarding app cannot load the onboarding
Try again later
Connect exactly one Ledger device
More than one Ledger device is connected
Disconnect the other devices
An action is required: open the Vault app
The Ledger Vault app is not open on the device
Open the Ledger Vault app, then claim again
This device was already claimed and cannot be added a second time.
The device already has a role in this ceremony
Use a different device, or un-claim the first claim
Warning, with Cleanup registration
A device registration did not complete
Select Cleanup registration, then register the device again
An Administrator with same name or public key has already registered. Please check that you are using the right device & name.
The name or the device is already registered in this ceremony
Enter a different name, or connect the right device
Administrator name must be 19 characters or fewer.
The name is too long
Enter a shorter name
Administrator name can only contain printable ASCII characters.
The name has a character outside printable ASCII
Remove the character
Related
Last updated