update the documentation for auth0 to include group/role information (#1502)

Signed-off-by: Jon Carl <jon.carl@auth0.com>

docs/.vuepress/config.js

@@ -98,6 +98,7 @@ module.exports = {
           sidebarDepth: 0,
           children: [
             "identity-providers/",
+            "identity-providers/auth0",
             "identity-providers/azure",
             "identity-providers/cognito",
             "identity-providers/github",

docs/docs/identity-providers/auth0.md

@@ -15,7 +15,7 @@ meta:
 
 ## Create Regular Web Application
 
-On the **Create New Application** page, select the **Regular Web Application** for your application.
+On the **Create New Application** page, name your application and select the **Regular Web Application** for your application. This is the application that your users will login to.
 
 ![Auth0 Create Application Select Platform](./img/auth0/create.png)
 
@@ -27,6 +27,50 @@ Next, provide the following information for your application settings:
 | Application Login URI        | Authenticate URL (e.g. `https://${authenticate_service_url}`)             |
 | Allowed Callback URLs        | Redirect URL (e.g. `https://${authenticate_service_url}/oauth2/callback`).|
 
-Make sure to click **Save Changes** when you're done.
+Make sure to click **Save Changes** at the bottom of the page when you're done.
 
-On the same **Settings** page you can copy the **Domain** and use it as the provider url (e.g. `https://dev-xyz.us.auth0.com`), as well as the **Client ID** and **Client Secret**.
+On the same **Settings** page you can copy the **Domain** and use it as the provider url (e.g. `https://dev-xyz.us.auth0.com`), as well as the **[Client ID]** and **[Client Secret]**.
+
+## Service Account
+
+Next we'll create an application to handle machine-to-machine communication from Pomerium to Auth0 in order to retrieve and establish group membership. 
+
+::: tip
+
+Auth0 refers to groups as roles.
+
+:::
+
+Select **Applications** on the left menu. On the Applications page, click the **Create Application** button to create a new app.
+
+On the **Create New Application** page, name your application and select the **Machine to Machine Application** for your application. A different application is used for grabbing roles to keep things more secure.
+
+![Auth Create Application Select Service Account Platform](./img/auth0/create-m2m.png)
+
+Click **Create** and on the next page select **Auth0 Management API** from the dropdown. For the scopes use the **Filter** on the right to narrow things down to `role` and choose the `read:roles` and `read:role_members` scopes.
+
+![Auth0 Management API Scopes](./img/auth0/m2m-scopes.png)
+
+Finish things off by clicking **Authorize**.
+
+To build the `idp_service_account` for Auth0 you need to base64-encode a JSON document containing the **Client ID** and **Client Secret** of the application:
+
+```json
+{
+  "client_id": "...",
+  "secret": "..."
+}
+```
+You can now configure Pomerium with the identity provider settings retrieved in the previous steps. Your [environmental variables] should look something like this.
+
+```bash
+IDP_PROVIDER="auth0"
+IDP_PROVIDER_URL="https://hayward-jackal.us.auth0.com"
+IDP_CLIENT_ID="REPLACE_ME" # from the application the users login to
+IDP_CLIENT_SECRET="REPLACE_ME" # from the application the users login to
+IDP_SERVICE_ACCOUNT="REPLACE_ME" # built from the machine-to-machine application which talks to the Auth0 Management API
+```
+
+[client id]: ../../reference/readme.md#identity-provider-client-id
+[client secret]: ../../reference/readme.md#identity-provider-client-secret
+[environmental variables]: https://en.wikipedia.org/wiki/Environment_variable

docs/reference/readme.md

@@ -635,7 +635,7 @@ Client Secret is the OAuth 2.0 Secret Identifier retrieved from your identity pr
 - Config File Key: `idp_provider`
 - Type: `string`
 - Required
-- Options: `azure` `google` `okta` `onelogin` or `oidc`
+- Options: `auth0` `azure` `google` `okta` `onelogin` or `oidc`
 
 Provider is the short-hand name of a built-in OpenID Connect (oidc) identity provider to be used for authentication. To use a generic provider,set to `oidc`.
 

examples/config/config.example.env

@@ -30,6 +30,14 @@ export COOKIE_SECRET="$(head -c32 /dev/urandom | base64)"
 
 # Identity Provider Settings
 
+# Auth0
+# export IDP_PROVIDER="auth0"
+# export IDP_PROVIDER_URL="https://REPLACEME.us.auth0.com"
+# export IDP_CLIENT_ID="REPLACEME" # from the application the users login to
+# export IDP_CLIENT_SECRET="REPLACEME" # from the application the users login to
+# the following is optional and only needed if you want role (Auth0 calls groups roles) data
+# export IDP_SERVICE_ACCOUNT="REPLACEME" # built from the machine-to-machine application which talks to the Auth0 Management API
+
 # Azure
 # export IDP_PROVIDER="azure"
 # export IDP_PROVIDER_URL="https://login.microsoftonline.com/REPLACEME/v2.0"

examples/config/config.example.yaml

@@ -34,6 +34,14 @@ authenticate_service_url: https://authenticate.corp.beyondperimeter.com
 
 # Identity Provider Settings
 
+# Auth0
+# idp_provider: "auth0"
+# idp_provider_url: "https://REPLACEME.us.auth0.com"
+# idp_client_id: "REPLACEME" # from the application the users login to
+# idp_client_secret: "REPLACEME" # from the application the users login to
+# the following is optional and only needed if you want role (Auth0 calls groups roles) data
+# idp_service_account: "REPLACEME" # built from the machine-to-machine application which talks to the Auth0 Management API
+
 # Azure
 # idp_provider: "azure"
 # idp_provider_url: "https://login.microsoftonline.com/REPLACEME/v2.0"