diff --git a/tyk-docs/content/advanced-configuration/integrate.md b/tyk-docs/content/advanced-configuration/integrate.md index da6e772080..b8424653e8 100755 --- a/tyk-docs/content/advanced-configuration/integrate.md +++ b/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" >}}) \ No newline at end of file diff --git a/tyk-docs/content/advanced-configuration/integrate/3rd-party-identity-providers.md b/tyk-docs/content/advanced-configuration/integrate/3rd-party-identity-providers.md index 8797d62ba3..0fb8ab08a4 100755 --- a/tyk-docs/content/advanced-configuration/integrate/3rd-party-identity-providers.md +++ b/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" >}}). diff --git a/tyk-docs/content/advanced-configuration/integrate/3rd-party-identity-providers/custom.md b/tyk-docs/content/advanced-configuration/integrate/3rd-party-identity-providers/custom.md index f15e415fdd..6e179de45e 100755 --- a/tyk-docs/content/advanced-configuration/integrate/3rd-party-identity-providers/custom.md +++ b/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 --- -## 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. diff --git a/tyk-docs/content/advanced-configuration/integrate/3rd-party-identity-providers/ldap.md b/tyk-docs/content/advanced-configuration/integrate/3rd-party-identity-providers/ldap.md index b74643e4ef..f176651ce4 100644 --- a/tyk-docs/content/advanced-configuration/integrate/3rd-party-identity-providers/ldap.md +++ b/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", diff --git a/tyk-docs/content/advanced-configuration/integrate/3rd-party-identity-providers/social.md b/tyk-docs/content/advanced-configuration/integrate/3rd-party-identity-providers/social.md index ec06b1cdd8..1c95c93741 100755 --- a/tyk-docs/content/advanced-configuration/integrate/3rd-party-identity-providers/social.md +++ b/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. -## 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) diff --git a/tyk-docs/content/advanced-configuration/integrate/3rd-party-identity-providers/social/dashboard-login-with-gplus.md b/tyk-docs/content/advanced-configuration/integrate/3rd-party-identity-providers/social/dashboard-login-with-gplus.md index 2bd7670d22..36c5280964 100644 --- a/tyk-docs/content/advanced-configuration/integrate/3rd-party-identity-providers/social/dashboard-login-with-gplus.md +++ b/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} diff --git a/tyk-docs/content/advanced-configuration/integrate/api-auth-mode.md b/tyk-docs/content/advanced-configuration/integrate/api-auth-mode.md deleted file mode 100755 index 413ef732d9..0000000000 --- a/tyk-docs/content/advanced-configuration/integrate/api-auth-mode.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -date: 2017-03-24T16:39:31Z -title: API Authentication Mode -menu: - main: - parent: "Integration Options" -weight: 0 ---- - -Tyk Gateway has built-in federation support via JSON Web Tokens or Open ID Connect diff --git a/tyk-docs/content/advanced-configuration/integrate/sso.md b/tyk-docs/content/advanced-configuration/integrate/sso.md index d98b248684..24ccebdbb4 100644 --- a/tyk-docs/content/advanced-configuration/integrate/sso.md +++ b/tyk-docs/content/advanced-configuration/integrate/sso.md @@ -1,143 +1,47 @@ --- date: 2017-03-24T16:40:31Z -title: Single Sign On +title: Single Sign-On menu: main: parent: "Tyk Dashboard" weight: 0 --- +Single Sign-On (SSO) gives users the ability to log in to multiple applications without the need to enter their password more than once. -## Introduction to Single Sign On (SSO) +[OpenID Connect]({{< ref "basic-config-and-security/security/authentication-authorization/openid-connect" >}}) (OIDC) and Security Assertion Markup Language (SAML) enables an application (such as Tyk Dashboard) to verify the identity of users without having to manage usernames and passwords locally, by offloading the identification process and secure storage of user credentials to a dedicated Identity Provider (IdP). The Authorisation server of the IdP identifies the users for a pre-registered and approved application (`client` in OAuth and OIDC terminology). -### SSO - The generic use case +[Tyk Identity Broker]({{< ref "tyk-identity-broker" >}}) is an open-source project that can be used to integrate Tyk Dashboard and Classic Portal with 3rd party identity providers (IDPs). TIB has been included as a built-in feature of the Tyk Dashboard since Tyk 3.0: no configuration is required and it is readily available for use. -SSO gives users the ability to log in to multiple applications without the need to enter their password more than once. -[OIDC]({{< ref "basic-config-and-security/security/authentication-authorization/openid-connect" >}}) or SAML enables an application to verify the identity of users from an organisation without the need to self store and manage them, and without doing the identification process and exposing their passwords to that application. Their lists of users and passwords are kept safe in one single place, in the IDP that the organisation has chosen to use. The Authorisation server of the IdP identify the users for a pre-registered and approved application (`client` in OAuth and OIDC terminology). +TIB allows you to implement single sign-on and use your existing user directory for login to the Tyk products. It has been designed as a glue-code solution, so it can integrate with almost any IdP. +
+
+{{< note success >}} +**Note** -### SSO in Tyk +To find out how to integrate with 3rd Party IdPs using different protocols, check out [this section]({{< ref "advanced-configuration/integrate/3rd-party-identity-providers" >}}). +
+
+For worked examples of specific 3rd Party integrations, including Auth0 and Okta, check out [this section]({{< ref "advanced-configuration/integrate" >}}). +{{< /note >}} -SSO is sometimes complicated to understand or set up but can be easily accomplished by using the built-in [Tyk Identity Broker (TIB)]({{< ref "tyk-identity-broker" >}}). +## How SSO works with Tyk Dashboard -Using our Tyk-Identity-Broker (TIB), you can do both - use your existing users directory to login to the **Dashboard** or **Developer Portal** and have an SSO. TIB, among other options, supports four methods for login to Tyk's UI: +Once you have configured the integration between Tyk Dashboard and your Identity Provider (typically using Tyk Identity Broker) then your users can simply log into Tyk Dashboard through your IdP. -1. Login with 3rd party social providers -2. Login with any IdP that supports OIDC -3. Login with any IdP that supports SAML -3. Login with LDAP (not using OIDC) +You can set custom login pages for the Dashboard and Classic Portal using the `sso_custom_login_url` and `sso_custom_portal_login_url` options respectively in the Tyk Dashboard config file (`tyk_analytics.conf`). -#### Tyk Identity Broker (TIB) +## SSO user permissions -TIB is an open-source project which can be used to integrate Tyk authentication with 3rd party identity providers (IDPs). Starting from Tyk v3.0, TIB has been added as a built-in feature of the Tyk Dashboard meaning there is no configuration required and it is readily available for use. TIB has been designed as a glue-code solution, so it can integrate with almost any identity provider (IDP) including all the known Social providers. See our [TIB detailed overview]({{< ref "tyk-identity-broker" >}}) for further information. +Logging in via SSO will grant the user **admin** rights in Tyk Dashboard, giving the user full access to configure and control the Dashboard. -#### SSO with Open ID Connect or Social Providers +You may not want all SSO users to assume administrator rights to your Tyk Dashboard, so you can configure alternative [default permissions](#setting-default-sso-permissions) that will be inherited instead. Of course, you might want certain users to have additional permissions (for example, your admin users) and so you can also assign [per-user permissions](#setting-user-specific-permissions). -SSO is sometimes complicated to understand or set up but once you get it and learn to use our Tyk-Identity-Broker it becomes an easy task. +### Setting default SSO permissions -In short, all you need is as follow: +The `sso_permission_defaults` option can be configured in the Tyk Dashboard config file (`tyk_analytics.conf`) to specify the [user permissions]({{< ref "basic-config-and-security/security/dashboard/user-roles" >}}) that should be granted to SSO users. -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 Docs for the flow can be found on our [GitHub TIB repo README](https://github.com/TykTechnologies/tyk-identity-broker) and our [3rd Party integration docs]({{< ref "advanced-configuration/integrate/3rd-party-identity-providers" >}}) - -### SSO with Social Identity Providers - -See [using a Social Identity Provider]({{< ref "advanced-configuration/integrate/3rd-party-identity-providers/social" >}}) for details of using SSO with Social Identity Providers. - -### SSO with OpenID Connect (OIDC) - -- Instruction on setting [SSO with Okta]({{< ref "tyk-stack/tyk-manager/sso/dashboard-login-okta-tib" >}}) -- Instructions on setting [SSO with Auth0]({{< ref "tyk-stack/tyk-manager/sso/sso-auth0-tib" >}}) -- Instructions on setting SSO with PingID - will be added soon -- Instructions on setting [SSO with Keycloak]({{< ref "product-stack/tyk-dashboard/advanced-configurations/sso/dashboard-login-keycloak-sso" >}}) - -### SSO with SAML - -SAML authentication is a way for a service provider, such as the Tyk Dashboard or 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 Portal and a third party identity provider. Tyk Identity broker can also interpret and pass along 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 host of TIB 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 about the IDP 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: - -``` -{ - "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 walks you through getting Tyk Dashboard SSO Access via SAML using Microsoft Azure as IDP and our internal Dashboard TIB. - -{{< youtube 4L9aetRrHqI >}} - -## Tyk's REST API for SSO - -The SSO API allows you to implement custom authentication schemes for the Dashboard and Portal. You can access the API by both admin and dashboard APIs. -Our Tyk Identity Broker (TIB) internally also uses these APIs. - -### Generate authentication token - -The Dashboard exposes two APIs: - -- `/admin/sso` - See [Dashboard Admin API SSO]({{< ref "tyk-apis/tyk-dashboard-admin-api/sso" >}}) for more details. -- `/api/sso` - See [Dashboard API SSO]({{< ref "tyk-apis/tyk-dashboard-api/sso" >}}) for more details. - -which allow you to generate a temporary authentication token, valid for 60 seconds. They make same thing you can select one of them and use it. -However, the admin API requires `admin-auth` header which should be same with `admin-secret` parameter in `tyk_analytics.conf`, the regular API requires `authorization` header which should be same with the user authentication token. - -### Using the Token - -Once you have issued a token you can login to the dashboard using the `/tap` url, or to the portal using the `/sso` URL, and provide an authentication token via the `nonce` query param. -If `nonce` is valid, Tyk will create a temporary user and log them in. - -If you want to re-use existing dashboard users, instead of creating temporary ones, you can set `"sso_enable_user_lookup": true` variable in the Dashboard config file (`tyk_analytics.conf`). This way you can set individual permissions for users logged via SSO. - -#### Set up default permissions for the dashboard - -If you use the token with `dashboard` scope, and would like to avoid login in as admin user (which is the default permissions), you can add the `sso_permission_defaults` configuration option to the Dashboard config file (`tyk_analytics.conf`) to specify SSO user permissions in the following format: +This option has the following format: ``` "sso_permission_defaults": { @@ -154,19 +58,22 @@ If you use the token with `dashboard` scope, and would like to avoid login in as } ``` -As alternative, you can set `sso_default_group_id` to specify User Group ID assigned to SSO users. +Alternatively, you can set `sso_default_group_id` in the Tyk Dashboard config file to assign SSO users to a [User Group]({{< ref "basic-config-and-security/security/dashboard/create-user-groups" >}}) where they will be granted the permissions associated with the group. -In order to set individual user permissions, you should first create this users in the dashboard first, set needed permissions, enable `sso_enable_user_lookup` to `true` inside dashboard config. If SSO user with the same email will be found in Dashboard users, it will re-use his permissions. +### Setting user-specific permissions -#### Sample Login Request +If `sso_enable_user_lookup` is set to `true` in the Tyk Dashboard config file then when someone logs in via SSO their email address is checked against all Tyk users configured in the Dashboard. If there is a match then they will inherit the permissions of that Tyk user. Thus, you can set permissions for a specific user by [creating a user]({{< ref "basic-config-and-security/security/dashboard/create-users" >}}) in the Dashboard first and assigning the required user permissions (e.g. `IsAdmin`) to this user. -```{.copyWrapper} -GET /tap?nonce=YTNiOGUzZjctYWZkYi00OTNhLTYwODItZTAzMDI3MjM0OTEw HTTP/1.1 -Host: localhost:3000 -``` +## Creating a custom SSO user using Tyk Dashboard API +You can implement custom authentication schemes for the Dashboard and Classic Portal from either [Tyk Dashboard Admin API]({{< ref "tyk-apis/tyk-dashboard-admin-api/sso" >}}) or [Tyk Dashboard API]({{< ref "tyk-apis/tyk-dashboard-api/sso" >}}). The functionality of the two APIs for SSO configuration are identical, however they require a different auth header to secure requests to the API: +- the Tyk Dashboard Admin API requires an `admin-auth` header which should match the `admin-secret` parameter in `tyk_analytics.conf` +- the Tyk Dashboard API requires an `authorization` header which should match the user authentication token -## SSO with LDAP Integration -Detailed instruction on setting [SSO with LDAP]({{< ref "advanced-configuration/integrate/3rd-party-identity-providers/dashboard-login-ldap-tib" >}}). +Both APIs' `/sso` endpoints will generate a temporary authentication token, valid for 60 seconds, that can be used to log in to the `/tap` endpoint, or to the portal using the `/sso` endpoint, providing the token via the `nonce` query param. If `nonce` is valid, Tyk will create a temporary user and log them in. -See [apply search filters]({{< ref "advanced-configuration/integrate/3rd-party-identity-providers/ldap#a-name-ldap-search-a-using-advanced-ldap-search" >}}) to add advanced search to your LDAP authentication. +For example: +```http +GET /tap?nonce=YTNiOGUzZjctYWZkYi00OTNhLTYwODItZTAzMDI3MjM0OTEw HTTP/1.1 +Host: localhost:3000 +``` \ No newline at end of file diff --git a/tyk-docs/content/basic-config-and-security/security/authentication-authorization/json-web-tokens.md b/tyk-docs/content/basic-config-and-security/security/authentication-authorization/json-web-tokens.md index 684a4d9419..ac9814fdc5 100755 --- a/tyk-docs/content/basic-config-and-security/security/authentication-authorization/json-web-tokens.md +++ b/tyk-docs/content/basic-config-and-security/security/authentication-authorization/json-web-tokens.md @@ -10,9 +10,18 @@ weight: 5 aliases: - /security/your-apis/json-web-tokens/ - /tyk-apis/tyk-gateway-api/api-definition-objects/jwt/docs/basic-config-and-security/security/authentication-authorization/json-web-tokens/ + - /advanced-configuration/integrate/api-auth-mode/ --- +A [JSON Web Token](https://jwt.io/introduction/) (JWT) is a JSON-based open standard (RFC 7519) for passing claims between parties in a web application environment. The tokens are designed to be compact, URL-safe and usable especially in web browser single sign-on (SSO) context. + +One of the best things about a JWT is that it is cryptographically signed, and can be signed in a number of ways such as using HMAC shared secret and RSA public/private key pairs. + +What is useful is when a token is issued by a third-party (e.g. an OAuth provider, or an SSO interface), that third party can use a private key to sign the claims of the token, and then any third-party can verify that the claims were issued by a safe third-party by validating the signature using a public key. + +JSON Web Tokens provide Tyk Gateway with built-in federation support. +--- ### Protecting an API with JWT @@ -67,15 +76,6 @@ You should receive response from your Upstream API. --- -## About JWTs -A [JSON Web Token](https://jwt.io/introduction/) (JWT) is a JSON-based open standard (RFC 7519) for passing claims between parties in a web application environment. The tokens are designed to be compact, URL-safe and usable especially in web browser single sign-on (SSO) context. - -One of the best things about a JWT is that it is cryptographically signed, and can be signed in a number of ways such as using HMAC shared secret and RSA public/private key pairs. - -What is useful is when a token is issued by a third-party (e.g. an OAuth provider, or an SSO interface), that third party can use a private key to sign the claims of the token, and then any third-party can verify that the claims were issued by a safe third-party by validating the signature using a public key. - ---- - ### JWT Signing Method Tyk allows you to select which cryptographic method to verify the JWT signature with with from: diff --git a/tyk-docs/data/menu.yaml b/tyk-docs/data/menu.yaml index b0ea614957..ffa80c1216 100644 --- a/tyk-docs/data/menu.yaml +++ b/tyk-docs/data/menu.yaml @@ -401,23 +401,31 @@ menu: show: True menu: - title: "Overview" - path: /advanced-configuration/integrate/sso + path: /advanced-configuration/integrate category: Page show: True - - title: "Login into the Dashboard using Azure AD - Guide" + - title: "Log in to Tyk Dashboard using Auth0" + path: /tyk-stack/tyk-manager/sso/sso-auth0-tib + category: Page + show: True + - title: "Log in to Tyk Dashboard using Azure AD" path: /tyk-stack/tyk-manager/sso/dashboard-login-azure-sso category: Page show: True - - title: "Login into the Dashboard using Okta - Guide" + - title: "Log in to Tyk Dashboard using Keycloak" + path: /product-stack/tyk-dashboard/advanced-configurations/sso/dashboard-login-keycloak-sso + category: Page + show: True + - title: "Log in to Tyk Dashboard using Okta" path: /tyk-stack/tyk-manager/sso/dashboard-login-okta-tib category: Page show: True - - title: "Login into the Dashboard using Auth0 - Guide" - path: /tyk-stack/tyk-manager/sso/sso-auth0-tib + - title: "Log in to Tyk Dashboard with Google+" + path: /advanced-configuration/integrate/3rd-party-identity-providers/social/dashboard-login-with-gplus category: Page - show: True - - title: "Login into the Dashboard using Keycloak - Guide" - path: /product-stack/tyk-dashboard/advanced-configurations/sso/dashboard-login-keycloak-sso + show: True + - title: "Login in to Tyk Dashboard using LDAP" + path: /advanced-configuration/integrate/3rd-party-identity-providers/dashboard-login-ldap-tib category: Page show: True - title: "Enterprise developer portal" @@ -1850,55 +1858,7 @@ menu: - title: "JQ Transforms" path: /advanced-configuration/transform-traffic/jq-transformations category: Page - show: True - - title: "Integration options" - category: Directory - show: True - menu: - - title: "Overview" - path: /advanced-configuration/integrate - category: Page - show: True - - title: "3rd Party identity providers" - category: Directory - show: True - menu: - - title: "3rd Party Identity Providers" - path: /advanced-configuration/integrate/3rd-party-identity-providers - category: Page - show: True - - title: "Custom" - path: /advanced-configuration/integrate/3rd-party-identity-providers/custom - category: Page - show: True - - title: "Login into the Dashboard using LDAP - Guide" - path: /advanced-configuration/integrate/3rd-party-identity-providers/dashboard-login-ldap-tib - category: Page - show: True - - title: "LDAP" - path: /advanced-configuration/integrate/3rd-party-identity-providers/ldap - category: Page - show: True - - title: "Social Provider" - path: /advanced-configuration/integrate/3rd-party-identity-providers/social - category: Page - show: True - - title: "Log into an APP with Google" - path: /advanced-configuration/integrate/3rd-party-identity-providers/social/app-login-with-gplus - category: Page - show: True - - title: "Log into Dashboard with Google" - path: /advanced-configuration/integrate/3rd-party-identity-providers/social/dashboard-login-with-gplus - category: Page - show: True - - title: "API authentication mode" - category: Directory - show: True - menu: - - title: "API Authentication Mode" - path: /advanced-configuration/integrate/api-auth-mode - category: Page - show: True + show: True - title: "Distributed Tracing" category: Directory show: True @@ -2521,7 +2481,11 @@ menu: - title: "API Ownership" path: /product-stack/tyk-dashboard/advanced-configurations/user-management/api-ownership category: Page - show: True + show: True + - title: "Single Sign-On" + path: /advanced-configuration/integrate/sso + category: Page + show: True - title: "Dashboard Administration" category: Directory show: True @@ -2578,6 +2542,30 @@ menu: category: Directory show: False menu: + - title: "Integration with 3rd Party Identity Providers" + category: Directory + show: True + menu: + - title: "Overview" + path: /advanced-configuration/integrate/3rd-party-identity-providers + category: Page + show: True + - title: "LDAP" + path: /advanced-configuration/integrate/3rd-party-identity-providers/ldap + category: Page + show: True + - title: "Social Providers" + path: /advanced-configuration/integrate/3rd-party-identity-providers/social + category: Page + show: True + - title: "Custom Proxy" + path: /advanced-configuration/integrate/3rd-party-identity-providers/custom + category: Page + show: True + - title: "Google Apps OAuth" + path: /advanced-configuration/integrate/3rd-party-identity-providers/social/app-login-with-gplus + category: Page + show: True - title: "Open Policy Agent (OPA)" category: Directory show: True