Add docs for OIDC with Gsuite

This commit is contained in:
Sebastian Tiedtke 2019-03-26 13:44:31 -07:00
parent 2f2e748aca
commit 725db1e127
4 changed files with 64 additions and 0 deletions

View file

@ -453,6 +453,70 @@ $ step ca renew site.crt site.key
error renewing certificate: Unauthorized
```
## Leverage G-Suite's OAuth OIDC as authenticate personal certificates for users
To authenticate users with the CA you can leverage services that expose OAuth OpenID
Connect identity providers. One of the most common provider and the one we'll use in
this example is G-Suite.
Navigate to the Google APIs developer console and pick a suitable project from the
top navbar's dropdown.
![Google Dev Console](oidc1.png)
In the masthead navigation click **Credentials** (key symbol) and then "OAuth consent
screen" from the subnav. Fill out naming details, all mandatory fields, and decide if
your app is of type **Public** or **Internal**. Internal will make sure the access scope
is bound to your G-Suite organization. **Publi** will let anybody with a Google Account
log in, incl. `gmail.com` accounts.
Move back to **Credentials** on the subnav and choose "OAuth client ID" from the
**Create credentials** dropdown. Since OIDC will be used from the `step CLI` pick **Other**
from the available options and pick a name (e.g. **Step CLI**).
![Create credential](oidc2.png)
On successful completion, a confirmation modal with both `clientID` and `clientSecret` will
be presented. Please note that the `clientSecret` will allow applications access to the configured
OAuth consent screen. However, it will not allow direct authentication of users without their own
MfA credentials per account.
![OIDC credentials](oidc3.png)
Now using `clientID` and `clientSecret` run following command to add G-Suite as a provisioner to
`step certificates`. Please see [`step ca provisioner add`](https://smallstep.com/docs/cli/ca/provisioner/add/)'s docs for all available configuration options and descriptions.
```bash
$ step ca provisioner add Google --type oidc --ca-config $(step path)/config/ca.json \
--client-id 972437157139-ssiqna0g4ibuhafl3pkrrcb52tbroekt.apps.googleusercontent.com \
--client-secret RjEk-GwKBvdsFAICiJhn_RiF \
--configuration-endpoint https://accounts.google.com/.well-known/openid-configuration \
--domain yourdomain.com --domain gmail.com
```
Start up the online CA or send a HUP signal if it's already running to pick up the new provisioner.
Now users should be able to fetch certificates using the familiar `step ca certificate` flow:
```bash
$ step ca certificate sebastian@smallstep.com personal.crt personal.key
Use the arrow keys to navigate: ↓ ↑ → ←
What provisioner key do you want to use?
fYDoiQdYueq_LAXx2kqA4N_Yjf_eybe-wari7Js5iXI (admin)
▸ 972437157139-ssiqna0g4ibuhafl3pkrrcb52tbroekt.apps.googleusercontent.com (Google)
✔ Key ID: 972437157139-ssiqna0g4ibuhafl3pkrrcb52tbroekt.apps.googleusercontent.com (Google)
✔ CA: https://localhost
✔ Certificate: personal.crt
✔ Private Key: personal.key
$ step certificate inspect --short localhost.crt
X.509v3 TLS Certificate (ECDSA P-256) [Serial: 2295...5799]
Subject: localhost
Issuer: Local CA Intermediate CA
Provisioner: admin [ID: fYDo...5iXI]
Valid from: 2019-03-26T19:02:58Z
to: 2019-03-27T19:02:58Z
```
## Notes on Securing the Step CA and your PKI.
In this section we recommend a few best practices when it comes to

BIN
docs/oidc1.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 59 KiB

BIN
docs/oidc2.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 72 KiB

BIN
docs/oidc3.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 57 KiB