enterprise guides init

docs/README.md

@@ -13,10 +13,16 @@ This guide is for advanced users and those who will be setting up and maintainin
 This guide contains more detailed information about how to install Metabase for production use. It covers topics like SSL termination, deploying via Docker Containers vs. Jars, as well as the tradeoffs involved.
 
 
-## Enterprise Edition
+## Enterprise Edition Guides
 
-#### [Enterprise Features Guide](enterprise-guide/start.md)
-Here's where to go for help using the features included in the Enterprise Edition of Metabase.
+#### [Manage large-scale deployments](#)
+Learn how to integrate your SSO with Metabase, set up data sandboxes for different user groups, and keep tabs on everything with the Audit tool.
+
+#### [Power analytics in your own web app](#)
+This guide shows you the different ways you can embed Metabase in your own web application to create seamless native analytics experiences.
+
+#### [Let customers log in to your white-labeled Metabase instance](#)
+If you'd like to allow customers to log in to see specific dashboards, or to explore individual tables filtered down to only show them their own data, this is the guide for you.
 
 
 ## For Developers

docs/enterprise-customer-facing-guide/overview.md

+## An overview of setting up your instance for customers
+
+Before we start, this guide presumes that your situation is that you have some customers, clients, stakeholders, or other interested parties who are outside of your own organization, and you'd like to let them log in to your Metabase instance.
+
+The problem that typically comes along with this is that you have plenty of things that you *don't* want them to see: internal company dashboards, data tables that may contain information of *other* customers, and more.
+
+And maybe as much as you love Metabase's UI, you'd also like to make it look more like your own company's branding so that your customers don't get all confused.
+
+If your head is nodding up and down, then great, stick around. This guide will go over solutions for all those problems.

docs/enterprise-customer-facing-guide/sandboxes.md

+---
+
+## Next: customizing Metabase's logo and colors

docs/enterprise-customer-facing-guide/setting-up-sso.md

+## Let you customers log in with SSO using SAML or JWT
+In addition to Google auth, LDAP, and email-based sign in, the Enterprise edition of Metabase lets you connect your single sign-on solution to Metabase. This can make it easier for your customers to log in to your Metabase instance, and automatically assign the correct group and permissions to them.
+
+There are slightly different steps to take depending on whether your SSO solution uses SAML or JWT. We'll cover SAML first.
+
+
+## Authenticating with SAML
+
+Connecting Metabase to your SAML identity provider lets your team access Metabase with ease through SSO.
+
+### Enabling SAML authentication
+First, head over to the Settings section of the Admin Panel, then click on the Authentication tab. Click the `Configure` button in the SAML section of the Authentication page, and you'll see this form:
+
+![SAML form](images/saml-form.png)
+
+Click the toggle at the top of the form to enable SAML authentication, then fill in the form with the information about your identity provider. **Make sure to turn this on**, otherwise SAML-based authentication won't work, even if all of your settings are right.
+
+Here's a breakdown of each of the settings:
+
+**Identity Provider (IDP) URI:** This is where Metabase will redirect login requests. That is, it's where your users go to log in to your SSO.
+
+**Identity Provider Certificate:** This is a an encoded certificate that we will use when connecting to the IDP provider URI. This will look like a big blob of text that you'll want to copy and paste carefully — the spacing is important!
+
+#### Configuring your SAML identity provider
+
+Metabase will automatically log in Users authenticated with your SAML
+identity provider, but in order to do so the SAML assertion *must*
+contain attributes for each User's first name, last name, and email. The assertion should look something like the following:
+
+```
+<saml2:Assertion
+    xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion" ID="id4170618837332381492734749" IssueInstant="2019-03-27T17:56:11.067Z" Version="2.0">
+    <saml2:Issuer Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity">http://www.okta.com/Issuer</saml2:Issuer>
+    <saml2:Subject>
+        <saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">userName</saml2:NameID>
+        <saml2:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
+            <saml2:SubjectConfirmationData NotOnOrAfter="2019-03-27T18:01:11.246Z" Recipient="https://metabase.mycompany.com/auth/sso"/>
+        </saml2:SubjectConfirmation>
+    </saml2:Subject>
+    <saml2:Conditions NotBefore="2019-03-27T17:51:11.246Z" NotOnOrAfter="2019-03-27T18:01:11.246Z">
+        <saml2:AudienceRestriction>
+            <saml2:Audience>my-metabase-app</saml2:Audience>
+        </saml2:AudienceRestriction>
+    </saml2:Conditions>
+    <saml2:AuthnStatement AuthnInstant="2019-03-27T17:56:11.067Z">
+        <saml2:AuthnContext>
+            <saml2:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport</saml2:AuthnContextClassRef>
+        </saml2:AuthnContext>
+    </saml2:AuthnStatement>
+    <saml2:AttributeStatement>
+        <saml2:Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
+            <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">
+              Cam
+            </saml2:AttributeValue>
+        </saml2:Attribute>
+        <saml2:Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
+            <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">
+              Saul
+            </saml2:AttributeValue>
+        </saml2:Attribute>
+        <saml2:Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
+            <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">
+              cam@metabse.com
+            </saml2:AttributeValue>
+        </saml2:Attribute>
+    </saml2:AttributeStatement>
+</saml2:Assertion>
+```
+
+Most SAML identity providers we've used already include these
+assertions by default, but some (such as Okta) must be configured to
+include them. Here's an example of what your assertions configuration
+should look like in Okta. (You can find this page by going to `Admin > Applications > Metabase > General > SAML Settings [Edit]`).
+
+![Okta SAML Integration](images/saml-okta-setup.png)
+
+You can use other attribute names for these attributes if so desired;
+see the section below. The important thing is that first name (given
+name), last name (surname), and email address are included as
+attributes of the first assertion returned in the identity provider's
+SAML response.
+
+##### IMPORTANT NOTE!
+
+The email address *attribute* is used to log in an end user into a
+corresponding Metabase account (creating it if needed). Thus it is
+extremely critical that this email address MUST NOT be editable by end
+users themselves. Otherwise they could potentially access Metabase
+accounts other than their own by changing their email address.
+
+#### Settings for signing SSO requests (optional)
+These are additional settings you can fill in to sign SSO requests to
+ensure they don’t get tampered with.
+
+**SAML keystore path:** the absolute path to the keystore file to use for signing SAML requests.
+
+**SAML keystore password:** if it wasn't already self-evident, this is just the password for opening the keystore.
+
+**SAML keystore alias:** the alias for the key that Metabase should use for signing SAML requests.
+
+#### Settings for user attribute configuration (optional)
+These settings allow Metabase to automatically get each user's email address and first and last name.
+
+The settings that Metabase defaults to here might work for you out of the box, but you can override them if you know that your settings are different.
+
+Each of these input boxes needs a URI that points to the location of a SAML attribute.
+
+
+
+
+## JWT-based Authentication
+
+You can connect Metabase to your JWT-based identity provider to allow your Metabase users to authenticate through it.
+
+### Enabling JWT authentication
+First, navigate to the Settings section of the Admin area, then click on the Authentication tab. Click the `Configure` button in the JWT section of this page, and you'll see this form:
+
+![SAML form](images/JWT-auth-form.png)
+
+Click the toggle at the top of the form to enable JWT-based authentication, then fill in the form with the information about your identity provider. **Make sure to turn this on**, otherwise JWT authentication won't work, even if all of your settings are right.
+
+Here's a breakdown of each of the settings:
+
+**Identity Provider URI:** This is where Metabase will redirect login requests. That is, it's where your users go to log in through your identify provider.
+
+**String Used by the JWT Signing Key:** This is a string used to seed the private key that is used to validate JWT messages.
+
+#### User attribute configuration (optional)
+These are additional settings you can fill in to pass user attributes to Metabase.
+
+**Email attribute:** the key to retrieve each JWT user's email address.
+
+**First Name attribute:** the key to retrieve each JWT user's first name.
+
+**Last Name attribute:** if you guessed that this is the key to retrieve each JWT user's last name, well then you have been paying attention.
+
+
+---
+
+## Next: Creating data sandboxes for your customers

docs/enterprise-customer-facing-guide/start.md

+## Let customers log in to your white-labeled Metabase instance
+
+If you're going to have guests, you have to get your house in order first. This guide will show you how to make sure your Metabase instance is a comfy place for your customers to go
+
+* Overview
+* Setting up SSO
+* Set up data sandboxes
+* White labeling
+* Customizing drill-through

docs/enterprise-customer-facing-guide/white-labeling.md

+---
+
+## Next: customizing drill-through behavior