• Thanks
• Yubikey ykman PIV Commands
• Introduction
• FAQs
• Setup Steps

Thanks to Jay Lee for the original version of this document.

GAMADV-XTD3 supports using a YubiKey to generate and store the service account's private RSA key. Private keys generated by the YubiKey cannot be exported even to the computer running GAMADV-XTD3. When compared to the plain text oauth2service.json file with the private key stored in text, the YubiKey offers a more secure option that prevents digital theft and copying of the private key. Instead of reading the private key from the oauth2service.json file and signing requests itself, GAMADV-XTD3 will simply send signing requests to the YubiKey and get back the signature.

GAMADV-XTD3 version 6.50.01 or higher is required. Best practice is to always use the latest version of GAMADV-XTD3.

No, while Titan keys are great as security keys / U2F / 2SV, that is not the protocol being used by GAMADV-XTD3 here. GAMADV-XTD3 uses the PIV app of YubiKeys to work with service accounts. You need to use a genuine Yubikey..

No, the admin credentials GAMADV-XTD3 stores in oauth2.txt are not protected by the YubiKey as they are not using RSA private keys. Only the service account credentials normally stored in oauth2service.json are protected. The service account credentials are used for domain-wide delegation operations like managing Workspace user data in Drive, Gmail and Calendar. Note that GAMADV-XTD3 also has the ability to perform admin actions as a delegated admin service account (DASA). See instructions for setting up DASA. When DASA is setup, GAMADV-XTD3 will use the service account to authenticate which can be protected by the YubiKey.

The YubiKey can be configured with a PIN that must be entered in order for it to sign data with the private key. GAMADV-XTD3 stores this PIN string in the oauth2service.json file so it can use it as needed. What this means is that an attacker would need to steal both the physical YubiKey and the PIN stored in oauth2service.json. The recommendation is to store oauth2service.json and the rest of the GAM directory on an encrypted partition. The YubiKey itself should also be kept in a secure location.

Yes but in practice this does not work very well with GAMADV-XTD3. The YubiKey will need to be touched every time there is a GAMADV-XTD3 command running which for batch or cron jobs may be constant. GAMADV-XTD3 can use a PIN configured on the YubiKey in order to offer an additional layer of protection.

No, because the YubiKey generated the private key it cannot be digitally exported from the YubiKey so there is no chance for it to be copied and stolen. Instead you should physically secure the YubiKey from theft.

When using domain-wide delegation with GAMADV-XTD3, the service account and anyone possessing the service account private key oauth2service.json file has access to the Gmail, Drive and Calendar data of ALL Workspace users in your domain. For this reason, whether using a YubiKey or not, you should take strong measures to protect the service account private key.

1. Upgrade to at least GAMADV-XTD3 6.50.01.

2. If you are using a new YubiKey or don't care about the PIV app data on the YubiKey

   1. Tell GAMADV-XTD3 to reset and configure the PIV app data on the YubiKey. This wipes all existing keys and configuration and then configures a private key and PIN for GAMADV-XTD3.
   • Single YubiKey - gam yubikey reset_piv
   • Multiple YubiKeys - gam yubikey reset_piv yubikeyserialnumber <Number>
   2. During the PIV reset, GAMADV-XTD3 will print out a PIN for the private key, record this key.

3. If you are already using the YubiKey and wish to preserve the PIV app data and keys

   1. You need to configure one of the PIV slots for a private key GAMADV-XTD3 can use.
   • ykman piv keys generate ykman piv keys generate -P <Text> --pin-policy ALWAYS --touch-policy NEVER --algorithm RSA2048 9a new_pubkey.txt
   • Use 9a for the AUTHENTICATION slot, 9c for the SIGNATURE slot
   2. You need to generate a certificate for that slot.
   • ykman piv certificates generate ykman piv certificates generate -P <Text> --subject "GAM Service Account" -d 36500 9a new_pubkey.txt
   • Use 9a for the AUTHENTICATION slot, 9c for the SIGNATURE slot

4. Now that you have a private key on your YubiKey, tell GAMADV-XTD3 to use that instead of the private_key stored in oauth2service.json. We can do that by rotating the key:

copy oauth2service.json to oauth2service.save
gam create sakey yubikey yubikey_pin yubikey_slot AUTHENTICATION|SIGNATURE

The yubikey argument tells GAMADV-XTD3 to use a private key on a plugged in YubiKey. The yubikey_pin argument tells GAMADV-XTD3 to prompt you to input the PIN that was set in the previous step. The yubikey_slot argument tells GAMADV-XTD3 which PIV slot to use on the YubiKey.

If there are problems, you can go back to the original oauth2service.json.

copy oauth2service.json to oauth2service.yk
copy oauth2service.save to oauth2service.json

6. Now you should be able to run GAMADV-XTD3 commands like:

gam user admin@example.com check serviceaccount

and see the YubiKey lights flash as the YubiKey interacts with GAMADV-XTD3 to sign the GAMADV-XTD3 authentication requests. If you look at the oauth2service.json file, you'll see it contains some new fields like yubikey_serial and yubikey_pin but no longer contains the private_key field where GAMADV-XTD3 would normally store the private key data.

7. As a last step, since YubiKey-stored private keys do not need to be and should not be rotated, you can remove the service account's permissions to change it's own key. Navigate to the Cloud Console select the correct project and service account and on the Permissions tab, edit and remove the "Service Account Key Admin" permission that the service account has to itself.