[DX-1401] Restructured SSO pages to improve clarity

tyk-docs/content/advanced-configuration/integrate.md

@@ -7,10 +7,10 @@ menu:
     parent: "Advanced Configuration"
 ---
 
-Tyk has multiple integration options with third parties, and these integrations can occur in a few places:
-
-* For plugins - Within the Gateway itself using Dynamic JS Middleware (Multi-Cloud or Tyk Self-Managed only)
-* For API Auth mode and Tyk's platform login - Externally to the gateway using a broker (The Tyk Identity Broker) (Tyk Self-Managed only)
-* For API Auth mode - Built-in federation support via JSON Web Tokens or Open ID Connect (Cloud, Multi-Cloud and On-Premises)
-
-All three of the above have different and unique use cases and can be deployed differently depending on your platform and integration requirements.
+In this section we provide examples that use the [Tyk Identity Broker]({{< ref "tyk-identity-broker" >}}) component embedded in the Tyk Dashboard, to integrate with common Identity Providers to offer [Single Sign-On (SSO)]({{< ref "advanced-configuration/integrate/sso" >}}) to your Tyk Dashboard:
+- [Auth0]({{< ref "tyk-stack/tyk-manager/sso/sso-auth0-tib" >}})
+- [Azure Active Directory]({{< ref "tyk-stack/tyk-manager/sso/dashboard-login-azure-sso" >}})
+- [Keycloak]({{< ref "product-stack/tyk-dashboard/advanced-configurations/sso/dashboard-login-keycloak-sso" >}})
+- [Okta]({{< ref "tyk-stack/tyk-manager/sso/dashboard-login-okta-tib" >}})
+- [Google+]({{< ref "advanced-configuration/integrate/3rd-party-identity-providers/social/dashboard-login-with-gplus" >}})
+- [Lightweight Directory Access Protocol (LDAP)]({{< ref "advanced-configuration/integrate/3rd-party-identity-providers/dashboard-login-ldap-tib" >}})

tyk-docs/content/advanced-configuration/integrate/3rd-party-identity-providers.md

@@ -1,6 +1,6 @@
 ---
 date: 2017-03-24T16:56:58Z
-title: 3rd Party Identity Providers
+title: Single Sign-On integration
 menu:
   main:
     parent: "Integration Options"
@@ -9,21 +9,88 @@ aliases:
   - /integrate/3rd-party-identity-providers/
 ---
 
-## Dashboard SSO API
-The Dashboard exposes a special API to implement custom authentications for the Dashboard and Portal. See the [Dashboard Admin API]({{< ref "tyk-apis/tyk-dashboard-admin-api/sso" >}}) for more details.
+Tyk supports integration with 3rd Party Identity Providers (IdPs) for Single Sign-On (SSO) using several different approaches, providing complete flexibility to work within your existing software stack.
 
-You can use the `sso_permission_defaults` dashboard configuration option to configure the permissions of users created via SSO API. See the SSO API docs above.
+This makes use of the [Tyk Identity Broker]({{< ref "tyk-identity-broker" >}}) (TIB) which provides a service-level component that enables delegated identities to be authorised and provide authenticated access to various Tyk components such as the Tyk Dashboard, the [Tyk Classic Developer Portal]({{< ref "tyk-developer-portal/tyk-portal-classic" >}}) and Tyk Gateway API.
 
-In addition you can set custom login pages for the dashboard and portal using `sso_custom_login_url` and `sso_custom_portal_login_url` dashboard configuration options.
+The following methods are supported:
+- [OpenID Connect (OIDC)](#sso-using-open-id-connect)
+- [Security Assertion Markup Language (SAML)](#sso-using-saml)
+- [Lightweight Directory Access Protocol (LDAP)]({{< ref "advanced-configuration/integrate/3rd-party-identity-providers/ldap" >}})
+- Integration with [Social Providers]({{< ref "advanced-configuration/integrate/3rd-party-identity-providers/social" >}})
+- Integration with [Custom Proxy]({{< ref "advanced-configuration/integrate/3rd-party-identity-providers/custom" >}})
+- [Logging into an APP using Google+]({{< ref "advanced-configuration/integrate/3rd-party-identity-providers/social/app-login-with-gplus" >}})
 
-## Tyk Identity Broker (TIB) Overview 
+Check out [this section]({{< ref "advanced-configuration/integrate" >}}) for worked examples of integrations with popular 3rd Party IdPs.
 
-### What is the Tyk Identity Broker?
+## SSO using Open ID Connect
 
-The Tyk Identity Broker (TIB) provides a service-level component that enables delegated identities to be authorised and provide authenticated access to various Tyk components such as the Tyk Dashboard, the Tyk Developer Portal and Tyk Gateway API flows such as OAuth access tokens and regular API tokens.
+To configure your Tyk Dashboard to work with a 3rd Party IdP all you need to do is:
 
-Internally the TIB uses the Dashboard SSO API mentioned above.
+1. Access the **Identity Manager** under System Management in the Tyk Dashboard
+2. Create a profile for your preferred IdP
+3. Get the `client_id` + `secret` that are defined on your IdP
+4. Set the `Callback URL` generated by Tyk on your IdP
+5. Provide your SSO profile in Tyk with the `Discover URL (well known endpoint)`
+6. Visit the Login URL after saving your profile to initialize the login
+7. More documentation of the flow can be found on our [GitHub TIB repo README](https://github.com/TykTechnologies/tyk-identity-broker)
+
+## SSO using SAML
+
+SAML authentication is a way for a service provider, such as the Tyk Dashboard or Tyk Classic Developer Portal, to assert the Identity of a User via a third party.
+
+Tyk Identity Broker can act as the go-between for the Tyk Dashboard and Tyk Classic Developer Portal and a third party identity provider. Tyk Identity broker can also interpret and provide information about the user who is logging in such as Name, Email and group or role metadata for enforcing role based access control in the Tyk Dashboard.
+
+The provider config for SAML has the following values that can be configured in a Profile:
+
+`SAMLBaseURL` - The Tyk Identity Broker host that will be used in the metadata document for the Service Provider. This will form part of the metadata URL used as the Entity ID by the IdP. The redirects configured in the IdP must match the expected host and URI configured in the metadata document made available by Tyk Identity Broker.
+
+`FailureRedirect` - Where to redirect failed login requests.
+
+`IDPMetaDataURL` - The metadata URL of your IDP which will provide Tyk Identity Broker with information such as EntityID, Endpoints (Single Sign On Service Endpoint, Single Logout Service Endpoint), its public X.509 cert, NameId Format, Organisation info and Contact info.
+
+This metadata XML can be signed providing a public X.509 cert and the private key.     
+
+`CertLocation`: An X.509 certificate and the private key for signing your requests to the IDP, this should be one single file with the cert and key concatenated. When using internal identity broker, this value should be the id of the certificate uploaded via certificate manager in dashboard, otherwise it should be a path where the certificate is placed.
+
+`ForceAuthentication` - Ignore any session held by the IDP and force re-login every request.
+
+`SAMLEmailClaim` - Key for looking up the email claim in the SAML assertion form the IDP. Defaults to: `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress`
+
+`SAMLForenameClaim` - Key for looking up the forename claim in the SAML assertion form the IDP. Defaults to: `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/forename`
+
+`SAMLSurnameClaim` - Key for looking up the surname claim in the SAML assertion form the IDP. Defaults to: `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname`
+
+Example profile configuration:
+
+```json
+{
+    "ActionType": "GenerateOrLoginUserProfile",
+    "ID": "saml-sso-login",
+    "OrgID": "{YOUR_ORGANISATION_ID}",
+    "CustomEmailField": "",
+    "IdentityHandlerConfig": {
+        "DashboardCredential": "{DASHBOARD_USER_API_KEY}"
+    },
+    "ProviderConfig": {
+        "SAMLBaseURL": "https://{HOST}",
+        "FailureRedirect": "http://{DASHBOARD_HOST}:{PORT}/?fail=true",
+        "IDPMetaDataURL": "{IDP_METADATA_URL}",
+        "CertLocation":"myservice.cert",
+        "ForceAuthentication": false,
+        "SAMLEmailClaim": "",
+        "SAMLForenameClaim": "",
+        "SAMLSurnameClaim": ""
+    },
+    "ProviderName": "SAMLProvider",
+    "ReturnURL": "http://{DASHBOARD_URL}:{PORT}/tap",
+    "Type": "redirect"
+}
+```
+### Example Video
+
+We have a video that explains how to provide Tyk Dashboard SSO Access via SAML using Microsoft Azure as an IDP and our internal Dashboard TIB.
+
+{{< youtube 4L9aetRrHqI >}}
 
-Starting from Tyk v3.0 the Tyk Identity Broker has been added as a built-in feature of the Tyk Dashboard. Users will no longer need to set up a separated instance of the service to make it work with Dashboard. However this is not mandatory and users still can set the configs to connect to an external TIB. 
 
-For more information on using TIB internally or configuring it externally, see the documentation for [Tyk Identity Broker (TIB)]({{< ref "tyk-identity-broker" >}}).

tyk-docs/content/advanced-configuration/integrate/3rd-party-identity-providers/custom.md

@@ -1,14 +1,12 @@
 ---
 date: 2017-03-24T16:59:41Z
-title: Custom
+title: Integrate with Custom Proxy
 menu:
   main:
     parent: "3rd Party Identity Providers"
 weight: 0 
 ---
 
-## <a name="integration"></a>Integration Tutorials: Custom Proxy Identity Provider
-
 The proxy identity provider is a generic solution to more legacy problems, as well as a way to handle flows such as basic auth access with third party providers or OAuth password grants where the request can just be passed through to the providing endpoint to return a direct response.
 
 The proxy provider will take a request, proxy it to an upstream host, capture the response, and analyse it for triggers of "success", if the triggers come out as true, then the provider will treat the request as authenticated and hand over to the Identity Handler to perform whatever action is required with the user data.

tyk-docs/content/advanced-configuration/integrate/3rd-party-identity-providers/ldap.md

@@ -1,6 +1,6 @@
 ---
 date: 2017-03-24T17:02:11Z
-title: LDAP
+title: Lightweight Directory Access Protocol (LDAP)
 menu:
   main:
     parent: "3rd Party Identity Providers"
@@ -10,15 +10,13 @@ aliases:
   - /integrate/3rd-party-identity-providers/openldap/
 ---
 
-## Integration Tutorials: LDAP
-
-The LDAP Identity Provider gives you functionality to bind a user to an LDAP server based on a username and password configuration. The LDAP provider currently does not extract user data from the server to populate a user object, but will provide enough defaults to work with all handlers.
+The Lightweight Directory Access Protocol (LDAP) is a standard protocol that maintains and provides access to "directory services" within a network. An LDAP Identity Provider (IdP) enables you to bind a user to an LDAP server based on a username and password configuration. The LDAP provider currently does not extract user data from the server to populate a user object, but will provide enough defaults to work with all handlers.
 
 ## Log into the Dashboard using LDAP
 
-Below is a sample TIB profile that can be used to log a user into the Dashboard using an LDAP pass-through provider:
+This is an example of a TIB profile that could be used to log a user into the Dashboard using an LDAP pass-through provider:
 
-```{.copyWrapper}
+```.json
 {
   "ActionType": "GenerateOrLoginUserProfile",
   "ID": "4",
@@ -40,17 +38,14 @@ Below is a sample TIB profile that can be used to log a user into the Dashboard
 
 ```
 
-The only step necessary to perform this is to send a POST request to the LDAP URL.
+The only step necessary to perform this is to send a `POST` request to the LDAP URL.
 
 TIB can pull a username and password out of a request in two ways:
-
-1.  Two form fields called "username" and "password"
+1.  Two form fields: `username` and `password`
 2.  A basic auth header using the Basic Authentication standard form
 
 By default, TIB will look for the two form fields. To enable Basic Auth header extraction, add `"GetAuthFromBAHeader": true` to the `ProviderConfig` section.
 
-The request should be a `POST`.
-
 If you make this request with a valid user that can bind to the LDAP server, Tyk will redirect the user to the dashboard with a valid session. There's no more to it, this mechanism is pass-through and is transparent to the user, with TIB acting as a direct client to the LDAP provider.
 
 {{< note success >}}
@@ -59,12 +54,13 @@ If you make this request with a valid user that can bind to the LDAP server, Tyk
 The `LDAPUserDN` field MUST contain the special `*USERNAME*` marker in order to construct the users DN properly.
 {{< /note >}}
 
+There is a full worked example for using LDAP to login to the Tyk Dashboard [here]({{< ref "advanced-configuration/integrate/3rd-party-identity-providers/dashboard-login-ldap-tib" >}}).
 
 ## Generate an OAuth token using LDAP
 
-The configuration below will take a request that is posted to TIB, authenticate it against LDAP, if the request is valid, it will redirect to the Tyk Gateway OAuth clients' `Redirect URI` with the token as a URL fragment:
+The configuration below will take a request that is posted to TIB and authenticate it against LDAP. If the request is valid it will redirect to the Tyk Gateway OAuth client's `Redirect URI` with the token provided as a URL fragment:
 
-```{.copyWrapper}
+```.json
 {
   "ActionType": "GenerateOAuthTokenForClient",
   "ID": "6",
@@ -95,13 +91,13 @@ The configuration below will take a request that is posted to TIB, authenticate
 }
 ```
 
-This configuration is useful for internal APIs that require valid OAuth tokens (e.g.a webapp or mobile app) but needs validation by an LDAP provider.
+This configuration is useful for internal APIs that need valid OAuth tokens (e.g. a webapp or mobile app) that require validation by an LDAP provider.
 
-## Log into the Developer Portal using LDAP
+## Log into the Classic Portal using LDAP
 
-LDAP requires little configuration, we can use the same provider configuration that we used to log into the Dashboard to target the Portal instead - notice the change in the handler configuration and the return URL:
+LDAP requires little configuration, we can use the same provider configuration that we used to log into the Dashboard to target the Classic Portal instead - notice the change in the handler configuration and the return URL:
 
-```{.copyWrapper}
+```json
 {
   "ActionType": "GenerateOrLoginDeveloperProfile",
   "ID": "5",
@@ -129,18 +125,18 @@ LDAP requires little configuration, we can use the same provider configuration t
 Once again, a simple `POST` request is all that is needed to validate a user via an LDAP provider.
 
 ## Using advanced LDAP search
-In some cases validation of a user CN is not enough, and it requires verifying if a user match some specific rules, like internal team ID. In this case TIB provides support for doing additional LDAP search check, and if result of this search returns only 1 record, it will pass the user.
 
-To make it work you need to specify 3 additional attributes in profile configuration file:
+In some cases the validation of a user CN is not enough, and you also need to verify that a user matches some specific rules, such as an internal team ID. In this case TIB can support additional LDAP search checks, and if the result of this search returns only 1 record, it will pass the user.
 
-* `LDAPBaseDN` - base DN used for doing LDAP search, for example `cn=dashboard,ou=Group`
-* `LDAPFilter` - filter applied to the search, should include the `*USERNAME*`variable. For example: `((objectCategory=person)(objectClass=user)(cn=*USERNAME*))`
-* `LDAPSearchScope` - This specifies the portion of the target subtree that should be considered. Supported search scope values include: 0 - baseObject (often referred to as "base"), 1 - singleLevel (often referred to as "one"), 2 - wholeSubtree (often referred to as "sub")
+To perform an advanced LDAP search, you need to specify three additional attributes in the profile configuration file:
+- `LDAPBaseDN`: the base DN used for doing LDAP search, for example `cn=dashboard,ou=Group`
+- `LDAPFilter`: the filter to be applied to the search, this should include the `*USERNAME*`variable. For example: `((objectCategory=person)(objectClass=user)(cn=*USERNAME*))`
+- `LDAPSearchScope`: this specifies the portion of the target subtree that should be considered. Supported search scope values include: 0 - baseObject (often referred to as "base"), 1 - singleLevel (often referred to as "one"), 2 - wholeSubtree (often referred to as "sub")
 
 For additional information about [LDAP search protocol](https://www.ldap.com/the-ldap-search-operation)
 
 Example profile using LDAP search filters:
-```{.copyWrapper}
+```json
 {
 	"ActionType": "GenerateOAuthTokenForClient",
 	"ID": "2",

tyk-docs/content/advanced-configuration/integrate/3rd-party-identity-providers/social.md

@@ -1,25 +1,34 @@
 ---
 date: 2017-03-24T16:58:32Z
-title: Social Provider
-menu:
-  main:
-    parent: "3rd Party Identity Providers"
-weight: 0
+title: Integrate with Social Identity Providers
+description: Overview of SSO integration with Social Providers
+tags: ["Single sign-on", "SSO", "integration", "social", "TIB", "Tyk Identity Broker", "identity"]
 ---
 
+The social provider for the Tyk Identity Broker is a thin wrapper around the excellent `goth` social auth library, modified slightly to work with a multi-tenant structure.
 
-## <a name="integration-tutorials-social"></a>Integration Tutorials: Social Overview
-The social provider for the Tyk Identity Broker is a thin wrapper around the excellent `goth` social auth library, modified slightly to work with a multi-tenant structure. The social provider should provide seamless integration with:
+The social provider should provide seamless integration with:
+- Bitbucket
+- Digital Ocean
+- Dropbox
+- GitHub
+- Google+
+- Linkedin
+- Twitter
+- Salesforce
 
-*   Bitbucket
-*   Digital Ocean
-*   Dropbox
-*   GitHub
-*   Google+
-*   Linkedin
-*   Twitter
-*   Salesforce
+The social provider is ideal for SSO-style logins for the Dashboard or for the Portal. For certain providers (mainly Google+), where email addresses are returned as part of the user data, a constraint can be added to validate the users domain. This is useful for Google For Business Apps users that want to grant access to the Dashboard for their domain users.
 
-The social provider is ideal for SSO-style logins for the Dashboard or for the Portal. For certain providers (mainly Google+), where email addresses are returned as part of the user data, a constraint can be added to validate the users domain. This is useful for Google For Business Apps users that want to grant access to their domain users for the Dashboard.
+Check out [this section]({{< ref "advanced-configuration/integrate" >}}) for SSO deployment examples.
 
-For more social provider examples see the Tyk Identity Broker (TIB) v0.2 Repo [Readme](https://github.com/TykTechnologies/tyk-identity-broker/blob/master/README.md#social).
+### Configuring your Social IdP in Tyk Dashboard
+
+Follow the steps below to configure your social IdP in Tyk Dashboard:
+
+1. Access the **Identity Manager** under System Management in the Tyk Dashboard
+2. Create a profile for your preferred IdP
+3. Retrieve the `client_id` and `secret` defined on your IdP
+4. Set the `Callback URL` generated by Tyk on your IdP
+5. Provide your SSO profile in Tyk with the `Discover URL (well known endpoint)`
+6. Visit the Login URL after saving your profile to initialize the login
+7. Further documentation of the flow can be found on our [GitHub TIB repo README](https://github.com/TykTechnologies/tyk-identity-broker)

tyk-docs/content/advanced-configuration/integrate/3rd-party-identity-providers/social/dashboard-login-with-gplus.md

@@ -9,9 +9,6 @@ aliases:
   - /integrate/3rd-party-identity-providers/social/dashboard-login-with-gplus/
 ---
 
-
-## Log into Dashboard with Google
-
 Similarly to logging into an app using Tyk, OAuth and Google Plus, if we have our callback URL and client IDs set up with Google, we can use the following profile setup to access our Dashboard using a social provider:
 
 ```{.copyWrapper}