diff --git a/docs/GETTING_STARTED.md b/docs/GETTING_STARTED.md index 3f28fd14..9f24598e 100644 --- a/docs/GETTING_STARTED.md +++ b/docs/GETTING_STARTED.md @@ -418,7 +418,7 @@ Please enter a password to encrypt the provisioner private key? password }, [...] -# launch CA... +## launch CA... $ step-ca $(step path)/config/ca.json Please enter the password to decrypt ~/.step/secrets/intermediate_ca_key: password 2019/02/21 12:09:51 Serving HTTPS on :9443 ... @@ -453,22 +453,23 @@ $ step ca renew site.crt site.key error renewing certificate: Unauthorized ``` -## Leverage G-Suite's OAuth OIDC as authenticate personal certificates for users +## Use Oauth OIDC to obtain personal certificates -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. +To authenticate users with the CA you can leverage services that expose OAuth +OpenID Connect identity providers. One of the most common providers, 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. **Public** will let anybody with a Google Account -log in, incl. `gmail.com` accounts. +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. +**Public** 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** @@ -476,15 +477,18 @@ 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. +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. +Now using `clientID` and `clientSecret` run the 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 \ @@ -494,8 +498,9 @@ $ step ca provisioner add Google --type oidc --ca-config $(step path)/config/ca. --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: +Start up the online CA or send a HUP signal if it's already running to reload +the configuration and pick up the new provisioner. Now users should be able to +obtain certificates using the familiar `step ca certificate` flow: ```bash $ step ca certificate sebastian@smallstep.com personal.crt personal.key @@ -517,7 +522,8 @@ X.509v3 TLS Certificate (ECDSA P-256) [Serial: 2295...5799] to: 2019-03-27T19:02:58Z ``` -Now it's easy for anybody in the G-Suite organization to self-serve fetching valid certificates. +Now it's easy for anybody in the G-Suite organization to obtain valid personal +certificates! ## Notes on Securing the Step CA and your PKI.