diff --git a/docs/GETTING_STARTED.md b/docs/GETTING_STARTED.md index f08c1a06..af79c470 100644 --- a/docs/GETTING_STARTED.md +++ b/docs/GETTING_STARTED.md @@ -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 diff --git a/docs/oidc1.png b/docs/oidc1.png new file mode 100644 index 00000000..37b54370 Binary files /dev/null and b/docs/oidc1.png differ diff --git a/docs/oidc2.png b/docs/oidc2.png new file mode 100644 index 00000000..5e12ae9e Binary files /dev/null and b/docs/oidc2.png differ diff --git a/docs/oidc3.png b/docs/oidc3.png new file mode 100644 index 00000000..da46dc20 Binary files /dev/null and b/docs/oidc3.png differ