Skip to content

Commit

Permalink
Expand motivation and add instructions for PIN
Browse files Browse the repository at this point in the history
  • Loading branch information
dinvlad committed Aug 15, 2020
1 parent 814a423 commit 6b55341
Showing 1 changed file with 21 additions and 4 deletions.
25 changes: 21 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,24 @@

Generate Google Service Account tokens with your YubiKey!

## Motivation

This is perhaps the most secure way to use Google credentials
outside of Google Cloud, since the private key never leaves the device,
and so it cannot be leaked or stolen without physically stealing the YubiKey.

Additionally, each operation is protected with a YubiKey PIN,
providing a 2nd factor of authentication as something a user knows
(in addition to something a user has, which is the YubiKey itself).

In this way, a single YubiKey can represent the identity
of a user across many Service Accounts, without the need
to send the private key material over the wire at any point.

This makes it even more secure than Service Account impersonation,
where a user's long-term refresh token has been traditionally
stored on their machine, and could thus be compromised.

## Requirements

YubiKey 4+
Expand All @@ -18,26 +32,29 @@ pip3 install google-yubikey

## Usage

1. Run this only once to set up a private key on the YubiKey,
1. Set up YubiKey PIN, as explained
[here](https://developers.yubico.com/PIV/Guides/Device_setup.html).

2. Run this only once to set up a private key on the YubiKey,
or to renew it after expiration:

```
google-yubikey private-key
```

2. Run this once to register YubiKey with each Service Account:
3. Run this once to register YubiKey with each Service Account:

```
google-yubikey public-key -a <service_account_email>
```

3. Run this every time you'd like to generate a Service Account token:
4. Run this every time you'd like to generate a Service Account token:

```
google-yubikey token -a <service_account_email>
```

4. Further customization options are available through:
5. Further customization options are available through:

```
google-yubikey [<command>] -h
Expand Down

0 comments on commit 6b55341

Please sign in to comment.