authenticate/providers: add onelogin (#53)

- docs: fixes various typos and grammar errors

docs/docs/config-reference.md

@@ -4,7 +4,7 @@ sidebar: auto
 
 # Configuration Variables
 
-Pomerium primarily uses [environmental variables] to set configuration settings. If you are coming from kubernetes or docker based deployment this should feel very familiar. If not, check out the following primers.
+Pomerium uses [environmental variables] to set configuration settings. If you are coming from a kubernetes or docker background this should feel familiar. If not, check out the following primers.
 
 - [Store config in the environment](https://12factor.net/config)
 - [Kubernetes: Environment variables](https://kubernetes.io/docs/tasks/inject-data-application/define-environment-variable-container/)
@@ -21,7 +21,7 @@ Global settings are configuration variables that are shared by all services.
 - Default: `all`
 - Options: `all` `authenticate` or `proxy`
 
-Service mode sets the pomerium service(s) to run. For example, if you are just testing pomerium, you may want to use `all` and run in all-in-one mode. Alternatively, in production, you probably want to have several instances of each service running for scalability and high availability.
+Service mode sets the pomerium service(s) to run. If testing, you may want to set to `all` and run pomerium in "all-in-one mode." In production, you'll likely want to spin of several instances of each service mode for high availability.
 
 ### Address
 
@@ -37,7 +37,7 @@ Address specifies the host and port to serve HTTPS and gRPC requests from. If em
 - Type: [base64 encoded] `string`
 - Required
 
-Shared Secret is the base64 encoded random 256-bit key used to mutually authenticate requests between services. It's critical to store safely and recommended to use secure key-management system where available. Otherwise, `/dev/urandom` can be used to generate a the key. For example:
+Shared Secret is the base64 encoded 256-bit key used to mutually authenticate requests between services. It's critical that secret keys are random, and store safely. Use a key management system or `/dev/urandom/` to generate a key. For example:
 
 ```
 head -c32 /dev/urandom | base64
@@ -49,7 +49,7 @@ head -c32 /dev/urandom | base64
 - Type: `bool`
 - Default: `false`
 
-By default, JSON encoded logs are produced. Debug enables human-readable and more verbose logging to [standard out](https://en.wikipedia.org/wiki/Standard_streams#Standard_output_(stdout)). For production, it's recommended to be set to `false`.
+By default, JSON encoded logs are produced. Debug enables colored, human-readable, and more verbose logs to be streamed to [standard out](https://en.wikipedia.org/wiki/Standard_streams#Standard_output_(stdout)). In production, it's recommended to be set to `false`.
 
 For example, if true.
 
@@ -94,39 +94,41 @@ Certificate key is the x509 _private-key_ used to establish secure HTTP and gRPC
 - Required
 - Example: `https://auth.corp.example.com/oauth2/callback`
 
-Redirect URL is the url the user will be redirected to following authentication with a third-party identity provider (IdP). Note the URL ends with `/oauth2/callback`. This setting will mirror the URL set when configuring your [identity provider]. Typically, on the provider side, this is called an _authorized callback url_.
+Redirect URL is the url the user will be redirected to following authentication with the third-party identity provider (IdP). Note the URL ends with `/oauth2/callback`. This setting will mirror the URL set when configuring your [identity provider]. Typically, on the provider side, this is called an _authorized callback url_.
 
 ### Allowed Email Domains
 
 ::: warning 
-This setting will be deprecated with the upcoming release of authorization service module.
+This setting will be deprecated with the upcoming release of the authorization service.
 :::
 
 - Environmental Variable: `ALLOWED_DOMAINS`
-- Type: `[]string` (e.g. comma separated list of string)
+- Type: `[]string` (e.g. comma separated list of strings)
 - Required
 - Example: `engineering.corp-b.com,devops.corp-a.com`
 
-The allowed email domains settings dictates which email domains are valid for access. If an authenticated user has a domain email ending in a non-whitelisted domain, an error will be returned.
+The allowed email domains settings dictates which email domains are valid for access. If an authenticated user has a email ending in a non-whitelisted domain, the request will be denied as unauthorized.
 
 
 
 ### Proxy Root Domains
 
 - Environmental Variable: `PROXY_ROOT_DOMAIN`
-- Type: `[]string` (e.g. comma separated list of string)
+- Type: `[]string` (e.g. comma separated list of strings)
 - Required
 
-Proxy Root Domains specifies the domains that are allowed to proxy access from. If a proxy service attempts to authenticate a user from a non-whitelisted domain, an error will be returned. For example, `httpbin.corp.example.com` would be a valid domain under the proxy root domain `corp.example.com`.
+Proxy Root Domains specifies the sub-domains that can proxy requests. For example, `httpbin.corp.example.com` would be a valid domain under the proxy root domain `corp.example.com`. If a proxy service attempts to authenticate a user from a non-whitelisted domain, an error will be returned.
 
 ### Identity Provider Name
 
 - Environmental Variable: `IDP_PROVIDER`
 - Type: `string`
 - Required
-- Options: `azure` `google` `okta` `gitlab` or `oidc`
+- Options: `azure` `google` `okta` `gitlab` `onelogin` or `oidc`
 
-Provider is short-hand-name of the built-in OpenID Connect (oidc) identity provider to use to authenticate user requests. To use a generic provider, set to `oidc`. See [identity provider] for details.
+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`. 
+
+See [identity provider] for details.
 
 ### Identity Provider Client ID
 
@@ -134,7 +136,7 @@ Provider is short-hand-name of the built-in OpenID Connect (oidc) identity provi
 - Type: `string`
 - Required
 
-Client ID is the OAuth 2.0 Client Identifier retrieved from your identity provider. For a detailed explanation of an OpenID Connect Request, see the [OIDC RFC] or your identity provider's documentation. See [identity provider] for details.
+Client ID is the OAuth 2.0 Client Identifier retrieved from your identity provider. See your identity provider's documentation, and our [identity provider] docs for details.
 
 ### Identity Provider Client Secret
 
@@ -142,15 +144,15 @@ Client ID is the OAuth 2.0 Client Identifier retrieved from your identity provid
 - Type: `string`
 - Required
 
-Client ID is the OAuth 2.0 Secret Identifier retrieved from your identity provider. For a detailed explanation of an OpenID Client Secret, see the [OIDC RFC Section 9](https://openid.net/specs/openid-connect-core-1_0.html#ClientAuthentication) or your identity provider's documentation. See [identity provider] for details.
+Client Secret is the OAuth 2.0 Secret Identifier retrieved from your identity provider. See your identity provider's documentation, and our [identity provider] docs for details.
 
 ### Identity Provider URL
 
 - Environmental Variable: `IDP_PROVIDER_URL`
 - Type: `string`
-- Optional if your identity provider is a built-in IDP and has a static URL.
+- Required, depending on provider
 
-Provider URL is the base path to an identity provider's [OpenID connect discovery document](https://openid.net/specs/openid-connect-discovery-1_0.html) For example, google's URL would be `https://accounts.google.com` for [their discover URL](https://accounts.google.com/.well-known/openid-configuration).
+Provider URL is the base path to an identity provider's [OpenID connect discovery document](https://openid.net/specs/openid-connect-discovery-1_0.html). For example, google's URL would be `https://accounts.google.com` for [their discover document](https://accounts.google.com/.well-known/openid-configuration).
 
 ### Identity Provider Scopes
 
@@ -159,18 +161,18 @@ Provider URL is the base path to an identity provider's [OpenID connect discover
 - Default: `oidc`,`profile`, `email`, `offline_access` (typically)
 - Optional for built-in identity providers.
 
-Identity provider scopes correspond to access privilege scopes as defined in Section 3.3 of OAuth 2.0 RFC6749\. The scopes associated with Access Tokens determine what resources will be available when they are used to access OAuth 2.0 protected endpoints. If you are using a built-in provider, you probably don't want to set customized scopes.
+Identity provider scopes correspond to access privilege scopes as defined in Section 3.3 of OAuth 2.0 RFC6749. The scopes associated with Access Tokens determine what resources will be available when they are used to access OAuth 2.0 protected endpoints. If you are using a built-in provider, you probably don't want to set customized scopes.
 
 ## Proxy Service
 
 ### Routes
 
 - Environmental Variable: `ROUTES`
-- Type: `map[string]string` comma separated mapping of gatewayed (reverse-proxied) entities.
+- Type: `map[string]string` comma separated mapping of managed entities.
 - Required
 - Example: `https://httpbin.corp.example.com=http://httpbin,https://hello.corp.example.com=http://hello:8080/`
 
-Routes contains a mapping of routes to be managed by pomerium.
+The routes setting contains a mapping of routes to be managed by pomerium.
 
 ### Signing Key
 
@@ -196,16 +198,7 @@ Authenticate Service URL is the externally accessible URL for the authenticate s
 - Optional
 - Example: `pomerium-authenticate-service.pomerium.svc.cluster.local`
 
-Authenticate Service URL is the internal hostname for the authenticate service. Used in place of the authenticate service url for "behind-the-ingress communication. Setting is required for ingresses and load balancers that do not support HTTPS/2 or gRPC termination.
-
-### Authenticate Internal Service Address
-
-- Environmental Variable: `AUTHENTICATE_INTERNAL_URL`
-- Type: `string`
-- Optional
-- Example: `pomerium-authenticate-service.pomerium.svc.cluster.local`
-
-Authenticate Internal Service Address is the target location of the authenticate service. Used for "behind-the-ingress communication. Setting is required for ingresses and load balancers that do not support HTTPS/2 or gRPC termination.
+Authenticate Internal Service URL is the internal location of the authenticate service. This setting is used to override the authenticate service url for when you need to do "behind-the-ingress" inter-service communication. This is typically required for ingresses and load balancers that do not support HTTP/2 or gRPC termination.
 
 ### Authenticate Service Port
 
@@ -224,7 +217,7 @@ Authenticate Service Port is used to set the port value for authenticate service
 - Optional (but typically required if Authenticate Internal Service Address is set)
 - Example: `*.corp.example.com` if wild card or `authenticate.corp.example.com`
 
-When Authenticate Internal Service Address is set, secure service communication can fail because the external certificate name will not match the internally provided URL. This setting allows you to override that check. Should be set to value of the external certificate name.
+When Authenticate Internal Service Address is set, secure service communication can fail because the external certificate name will not match the internally routed service url. This setting allows you to override that check. 
 
 ### Certificate Authority
 

docs/docs/examples.md

@@ -4,7 +4,7 @@ sidebarDepth: 3
 
 # Example Configurations
 
-A collection of copy-and-pasteable example pomerium configurations for various types of clouds, use-cases, and deployments. All of these files can also be found in the git repository in the `docs/docs/examples/` directory.
+A collection of copy-and-paste-able configurations for various types of clouds, use-cases, and deployments. These files can also be found in the git repository in the `docs/docs/examples/` directory.
 
 :::tip
 
@@ -35,7 +35,7 @@ Uses the [latest pomerium build](https://hub.docker.com/r/pomerium/pomerium) fro
 - Minimal container-based configuration.
 - Docker and Docker-Compose based.
 - Runs a single container for all pomerium services
-- Routes default to on-prem [helloworld], [httpbin] containers.
+- Routes default to on-prem [helloworld], [httpbin].
 
 Customize for your identity provider run `docker-compose up -f basic.docker-compose.yml`
 
@@ -48,9 +48,9 @@ Customize for your identity provider run `docker-compose up -f basic.docker-comp
 - Docker and Docker-Compose based.
 - Uses pre-configured built-in nginx load balancer
 - Runs separate containers for each service
-- Routes default to on-prem [helloworld], [httpbin], and [gitlab] containers.
+- Routes default to on-prem [helloworld], and [httpbin].
 
-Customize for your identity provider run `docker-compose up -f gitlab.docker-compose.yml`
+Customize for your identity provider run `docker-compose up -f nginx.docker-compose.yml`
 
 #### nginx.docker-compose.yml
 
@@ -62,7 +62,7 @@ Customize for your identity provider run `docker-compose up -f gitlab.docker-com
 - Uses pre-configured built-in nginx load balancer
 - Runs separate containers for each service
 - Comes with a pre-configured instance of on-prem Gitlab-CE
-- Routes default to on-prem [helloworld], [httpbin], and [gitlab] containers.
+- Routes default to on-prem [helloworld], [httpbin], and [gitlab].
 
 Customize for your identity provider run `docker-compose up -f gitlab.docker-compose.yml`
 

docs/docs/identity-providers.md

@@ -1,22 +1,22 @@
 ---
 title: Identity Providers
 description: >-
-  This article describes how to connect pomerium to third-party identity
+  This article describes how to connect Pomerium to third-party identity
   providers / single-sign-on services. You will need to generate keys, copy
   these into your promerium settings, and enable the connection.
 ---
 
 # Identity Provider Configuration
 
-This article describes how to configure pomerium to use a third-party identity service for single-sign-on.
+This article describes how to configure Pomerium to use a third-party identity service for single-sign-on.
 
 There are a few configuration steps required for identity provider integration. Most providers support [OpenID Connect] which provides a standardized interface for IdentityProvider. In this guide we'll cover how to do the following for each identity provider:
 
 1. Establish a **Redirect URL** with the identity provider which is called after IdentityProvider.
-2. Generate a **Client ID** and **Client Secret**.
-3. Configure pomerium to use the **Client ID** and **Client Secret** keys.
+2. Generate a **[Client ID]** and **[Client Secret]**.
+3. Configure Pomerium to use the **[Client ID]** and **[Client Secret]** keys.
 
-## Azure
+## Azure Active Directory
 
 If you plan on allowing users to log in using a Microsoft Azure Active Directory account, either from your company or from external directories, you must register your application through the Microsoft Azure portal. If you don't have a Microsoft Azure account, you can [signup](https://azure.microsoft.com/en-us/free) for free.
 
@@ -53,7 +53,7 @@ Enter a name for the application, select **Web app/API** as the **Application Ty
 
 ![Create application form](./microsoft/azure-create-application.png)
 
-Next you will need to create a key which will be used as the **Client Secret** in Pomeriunm's configuration settings. Click on **Keys** from the **Settings** menu.
+Next you will need to create a key which will be used as the **[Client Secret]** in Pomerium's configuration settings. Click on **Keys** from the **Settings** menu.
 
 Enter a name for the key and choose the desired duration.
 
@@ -63,7 +63,7 @@ If you choose an expiring key, make sure to record the expiration date in your c
 
 :::
 
-Click on **Save** and the key will be displayed. **Make sure to copy the value of this key before leaving this screen**, otherwise you may need to create a new key. This value is used as the **Client Secret**.
+Click on **Save** and the key will be displayed. **Make sure to copy the value of this key before leaving this screen**, otherwise you may need to create a new key. This value is used as the **[Client Secret]**.
 
 ![Creating a Key](./microsoft/azure-create-key.png)
 
@@ -105,20 +105,20 @@ Navigate to **User Settings** then **Applications** using the left-hand menu.
 On the **Applications** page, add a new application by setting the following parameters:
 
 Field        | Description
------------- | --------------------------------------------
+------------ | --------------------------------------------------------------------
 Name         | The name of your web app
-Redirect URI | `https://${redirect-url}/oauth2/callback`
+Redirect URI | [Redirect URL] (e.g.`https://auth.corp.example.com/oauth2/callback`)
 Scopes       | **Must** select **read_user** and **openid**
 
 ![Create New Credentials](./gitlab/gitlab-create-application.png)
 
 1.Click **Save Application** to proceed.
 
-Your `Client ID` and `Client Secret` will be displayed:
+Your [Client ID] and [Client Secret] will be displayed:
 
 ![Gitlab OAuth Client ID and Secret](./gitlab/gitlab-credentials.png)
 
-Set `Client ID` and `Client Secret` in Pomerium's settings. Your [environmental variables] should look something like this.
+Set [Client ID] and [Client Secret] in Pomerium's settings. Your [environmental variables] should look something like this.
 
 ```bash
 REDIRECT_URL="https://sso-auth.corp.beyondperimeter.com/oauth2/callback"
@@ -130,7 +130,7 @@ IDP_CLIENT_ID="yyyy"
 IDP_CLIENT_SECRET="xxxxxx"
 ```
 
-When a user first uses pomerium to login, they will be presented with an authorization screen similar to the following.
+When a user first uses Pomerium to login, they will be presented with an authorization screen similar to the following.
 
 ![gitlab access authorization screen](./gitlab/gitlab-verify-access.png)
 
@@ -140,26 +140,26 @@ Log in to your Google account and go to the [APIs & services](https://console.de
 
 ![API Manager Credentials](./google/google-credentials.png)
 
-On the **Credentials** page, click **Create credentials** and choose **OAuth Client ID**.
+On the **Credentials** page, click **Create credentials** and choose **OAuth [Client ID]**.
 
 ![Create New Credentials](./google/google-create-new-credentials.png)
 
-On the **Create Client ID** page, select **Web application**. In the new fields that display, set the following parameters:
+On the **Create [Client ID]** page, select **Web application**. In the new fields that display, set the following parameters:
 
 Field                    | Description
------------------------- | -----------------------------------------
+------------------------ | --------------------------------------------------------------------
 Name                     | The name of your web app
-Authorized redirect URIs | `https://${redirect-url}/oauth2/callback`
+Authorized redirect URIs | [Redirect URL] (e.g.`https://auth.corp.example.com/oauth2/callback`)
 
 ![Web App Credentials Configuration](./google/google-create-client-id-config.png)
 
 Click **Create** to proceed.
 
-Your `Client ID` and `Client Secret` will be displayed:
+Your [Client ID] and [Client Secret] will be displayed:
 
 ![OAuth Client ID and Secret](./google/google-oauth-client-info.png)
 
-Set `Client ID` and `Client Secret` in Pomerium's settings. Your [environmental variables] should look something like this.
+Set [Client ID] and [Client Secret] in Pomerium's settings. Your [environmental variables] should look something like this.
 
 ```bash
 REDIRECT_URL="https://sso-auth.corp.beyondperimeter.com/oauth2/callback"
@@ -182,10 +182,10 @@ On the **Create New Application** page, select the **Web** for your application.
 Next, provide the following information for your application settings:
 
 Field                        | Description
----------------------------- | -----------------------------------------------------
+---------------------------- | ---------------------------------------------------------------------
 Name                         | The name of your application.
 Base URIs (optional)         | The domain(s) of your application.
-Login redirect URIs          | `https://${redirect-url}/oauth2/callback`.
+Login redirect URIs          | [Redirect URL] (e.g.`https://auth.corp.example.com/oauth2/callback`).
 Group assignments (optional) | The user groups that can sign in to this application.
 Grant type allowed           | **You must enable Refresh Token.**
 
@@ -193,7 +193,7 @@ Grant type allowed           | **You must enable Refresh Token.**
 
 Click **Done** to proceed. You'll be taken to the **General** page of your app.
 
-Go to the **General** page of your app and scroll down to the **Client Credentials** section. This section contains the **Client ID** and **Client Secret** to be used in the next step.
+Go to the **General** page of your app and scroll down to the **Client Credentials** section. This section contains the **[Client ID]** and **[Client Secret]** to be used in the next step.
 
 ![Okta Client ID and Secret](./okta/okta-client-id-and-secret.png)
 
@@ -207,6 +207,51 @@ IDP_CLIENT_ID="0oairksnr0C0fEJ7l0h7"
 IDP_CLIENT_SECRET="xxxxxx"
 ```
 
+## OneLogin
+
+Log in to your [OneLogin](https://www.onelogin.com/) account and head to the dashboard.
+
+Click **Apps** on the top menu. Select the **Add apps** menu item.
+
+![One Login Add a New App](./one-login/one-login-add-app.png)
+
+On the **Find Application** page, search for **openid**. Select **Openid Connect** by OneLogin, Inc.
+
+![One Login Add a New App](./one-login/one-login-add-open-id.png)
+
+On the App Configuration page, **name the app** and **select a logo**. Select **Save**.
+
+![One Login select logo](./one-login/one-login-select-logo.png)
+
+Next, set set the **Redirect URI's** setting to be Pomerium's [redirect url].
+
+![One Login set callback url](./one-login/one-login-callback-url.png)
+
+Go to the **SSO** page. This section contains the **[Client ID]** and **[Client Secret]** you'll use to configure Pomerium. 
+
+Also, be sure to also set the application type to **Web** and the token endpoint to be **POST**.
+
+
+![One Login SSO settings](./one-login/one-login-sso-settings.png)
+
+
+At this point, you will configure the integration from the Pomerium side. Your [environmental variables] should look something like this.
+
+```bash
+REDIRECT_URL="https://auth.corp.beyondperimeter.com/oauth2/callback"
+IDP_PROVIDER="onelogin"
+IDP_PROVIDER_URL="https://openid-connect.onelogin.com/oidc"
+IDP_CLIENT_ID="9e613ce0-1622-0137-452d-0a93c31f8392142934"
+IDP_CLIENT_SECRET="3e86ef0cc21b6dcf10c1d91e032568617d37e9fe1609ffd8042d3c25a560c36c"
+```
+
+After reloading Pomerium, you should be able to see any login events from your OneLogin events dashboard.
+
+![One Login Events Dashboard](./one-login/one-login-events.png)
+
+[client id]: ./config-reference.html#identity-provider-client-id
+[client secret]: ./config-reference.html#identity-provider-client-secret
 [environmental variables]: https://en.wikipedia.org/wiki/Environment_variable
 [oauth2]: https://oauth.net/2/
 [openid connect]: https://en.wikipedia.org/wiki/OpenID_Connect
+[redirect url]: ./config-reference.html#redirect-url