SSO LDAP, OIDC, SAML, Social

tyk-docs/content/api-management/custom-auth-with-proxy-identity-provider.md

@@ -0,0 +1,50 @@
+---
+title: "Custom Authentication with Proxy Identify Provider"
+date: 2025-01-10
+tags: ["Tyk Identity Broker", "TIB", "Identity Provider", "Identity Handler", "SSO", "Custom Authentication", "Custom Proxy Provder"]
+description: "Learn how to integrate external services with Tyk API Gateway. Discover how to use middleware plugins, webhooks, and service discovery to extend your API functionality and connect with third-party systems."
+keywords: ["Tyk Identity Broker", "TIB", "Identity Provider", "Identity Handler", "SSO", "Custom Authentication", "Custom Proxy Provder"]
+---
+
+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 analyze 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.
+
+Success can be triggered using three methods:
+
+1.  Response code: e.g. if this is an API request, a simple `200` response would suffice to act as a successful authentication.
+2.  Response body exact match: You can have a base64 encoded body that you would expect as a successful match, if the two bodies are the same, then the request will be deemed successful.
+3.  Regex: Most likely, the response might be dynamic (and return a response code, timestamp or other often changing parameter), in which case you may want to just match the response to a regex.
+
+These can be used in conjunction as gates, e.g. a response must be `200 OK` and match the regex in order to be marked as successful.
+
+## JSON Data and User names
+
+The Proxy provider can do some clever things, such as extract JSON data from the response and decode it, as well as pull username data from the Basic Auth header (for example, if your identity provider supports dynamic basic auth).
+
+## Log into the Dashboard with the Proxy Provider
+
+The configuration below will proxy a request to `http://{TARGET-HOSTNAME}:{PORT}/` and evaluate the response status code, if the status code returned is `200` then TIB will assume the response is JSON (`"ResponseIsJson": true`) to extract an access token (e.g. if this is an OAuth pass-through request) and try and find an identity to bind the Dashboard user to in the `user_name` JSON field of the response object (`"UsernameField": "user_name"`):
+
+```{.copyWrapper}
+{
+  "ActionType": "GenerateOrLoginUserProfile",
+  "ID": "7",
+  "OrgID": "{YOUR-ORG-ID}",
+  "ProviderConfig": {
+    "AccessTokenField": "access_token",
+    "ExtractUserNameFromBasicAuthHeader": false,
+    "OKCode": 200,
+    "OKRegex": "",
+    "OKResponse": "",
+    "ResponseIsJson": true,
+    "TargetHost": "http://{TARGET-HOSTNAME}:{PORT}/",
+    "UsernameField": "user_name"
+  },
+  "ProviderName": "ProxyProvider",
+  "ReturnURL": "http://{DASH-DOMAIN}:{DASH-PORT}/tap",
+  "Type": "redirect"
+}
+```
+
+

tyk-docs/content/api-management/single-sign-on-saml.md

@@ -0,0 +1,66 @@
+---
+title: "Single Sign On (SS0) with SAML"
+date: 2025-01-10
+tags: ["Tyk Identity Broker", "TIB", "Identity Provider", "Identity Handler", "SSO", "Custom Authentication", "Custom Proxy Provder", "SAML", "OIDC", "OpenID Connect", "Profies", "IDPs", "Social Provider" ,"LDAP"]
+description: "Learn how to integrate external services with Tyk API Gateway. Discover how to use middleware plugins, webhooks, and service discovery to extend your API functionality and connect with third-party systems."
+keywords: ["Tyk Identity Broker", "TIB", "Identity Provider", "Identity Handler", "SSO", "Custom Authentication", "Custom Proxy Provder", "SAML", "OIDC", "OpenID Connect", "Profies", "IDPs", "Social Provider" ,"LDAP"]
+---
+
+## 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, Organization 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_ORGANIZATION_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"
+}
+```
+### Video Demonstration
+
+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-docs/content/api-management/single-sign-on-social-idp.md

@@ -0,0 +1,154 @@
+---
+title: "SSO with Social Identity Providers"
+date: 2025-01-10
+tags: ["Tyk Identity Broker", "TIB", "Identity Provider", "Identity Handler", "SSO", "Custom Authentication", "Custom Proxy Provder", "SAML", "OIDC", "OpenID Connect", "Profies", "IDPs", "Social Provider" ,"LDAP"]
+description: "Learn how to integrate external services with Tyk API Gateway. Discover how to use middleware plugins, webhooks, and service discovery to extend your API functionality and connect with third-party systems."
+keywords: ["Tyk Identity Broker", "TIB", "Identity Provider", "Identity Handler", "SSO", "Custom Authentication", "Custom Proxy Provder", "SAML", "OIDC", "OpenID Connect", "Profies", "IDPs", "Social Provider" ,"LDAP"]
+---
+
+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:
+
+*   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 their domain users for the Dashboard.
+
+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).
+
+<br>
+
+{{< note success >}}
+**Note**
+
+To activate SSO on the Dashboard or Developer portal, there’s no requirement to install TIB separately; it is integrated into the Dashboard and Developer Portal. You have two configurations for SSO within the dashboard:
+1. **Using Embedded TIB**: No need to install it separately.
+2. **Using External TIB**: If you are using a previous version of the Dashboard or Portal, you can still use SSO with TIB installed as a separate application.
+{{< /note >}}
+
+
+### Log into an APP with Github OAuth
+
+{{< youtube gqUaDM4aJTw >}}
+
+### Log into an APP with Google (Oauth)
+
+A common use case for Tyk Gateway users is to enable users to log into a web app or mobile app using a social provider such as Google, but have that user use a token in the app that is time-delimited and issued by their own API (or in this case, Tyk).
+
+Tyk can act as an OAuth provider, but requires some glue code to work, in particular, generating a token based on the authentication of a third party, which needs to run on a server hosted by the owner of the application. This is not ideal in many scenarios where authentication has been delegated to a third-party provider (such as Google or Github).
+
+In this case, we can enable this flow with Tyk Gateway by Using TIB.
+
+What the broker will do is essentially the final leg of the authentication process without any new code, simply sending the user via TIB to the provider will suffice for them to be granted an OAuth token once they have authenticated in a standard, expected OAuth pattern.
+
+Assuming we have created a client ID and secret in Google Apps to grant ourselves access to the users data, we need those details, and some additional ones from Tyk itself.
+
+#### To Set up an OAuth client with Google Apps
+
+1. Go to the [Google Developer Console](https://console.developers.google.com/) and create a new app
+2. Register a new OAuth client. Let's call it WebApp 1 (Select "New Credentials -> OAuth Client ID")
+3. Select Web App
+4. Add the following URL (modify for your domain) to the "Authorized redirect URIs" section: `http://tib-hostname:TIB-PORT/auth/{PROFILE-ID}/gplus/callback`
+
+#### Create an OAuth Client in Tyk Dashboard
+
+TIB will use the OAuth credentials for GPlus to access and authenticate the user, it will then use another set of client credentials to make the request to Tyk to generate a token response and redirect the user, this means we need to create an OAuth client in Tyk Dashboard before we can proceed.
+
+One quirk with the Tyk API is that requests for tokens go via the base APIs listen path (`{listen_path}/toauth/authorize`), so we will need to know the listen path and ID of this API so TIB can make the correct API calls on your behalf.
+
+```{.copyWrapper}
+{
+  "ActionType": "GenerateOAuthTokenForClient",
+  "ID": "3",
+  "IdentityHandlerConfig": {
+    "DashboardCredential": "{DASHBOARD-API-ID}",
+    "DisableOneTokenPerAPI": false,
+    "OAuth": {
+      "APIListenPath": "{API-LISTEN-PATH}",
+      "BaseAPIID": "{BASE-API-ID}",
+      "ClientId": "{TYK-OAUTH-CLIENT-ID}",
+      "RedirectURI": "http://{APP-DOMAIN}:{PORT}/{AUTH-SUCCESS-PATH}",
+      "ResponseType": "token",
+      "Secret": "{TYK-OAUTH-CLIENT-SECRET}"
+    }
+  },
+  "MatchedPolicyID": "567a86f630c55e3256000003",
+  "OrgID": "53ac07777cbb8c2d53000002",
+  "ProviderConfig": {
+    "CallbackBaseURL": "http://{TIB-DOMAIN}:{TIB-PORT}",
+    "FailureRedirect": "http://{PORTAL-DOMAIN}:{PORTAL-PORT}/portal/login/?fail=true",
+    "UseProviders": [{
+      "Key": "GOOGLE-OAUTH-CLIENT-KEY",
+      "Name": "gplus",
+      "Secret": "GOOGLE-OAUTH-CLIENT-SECRET"
+    }]
+  },
+  "ProviderConstraints": {
+    "Domain": "",
+    "Group": ""
+  },
+  "ProviderName": "SocialProvider",
+  "ReturnURL": "",
+  "Type": "redirect"
+}
+```
+
+There's a few new things here we need to take into account:
+
+*   `APIListenPath`: This is the listen path of your API, TIB uses this to generate the OAuth token.
+*   `BaseAPIID`: The base API ID for the listen path mentioned earlier, this forms the basic access grant for the token (this will be superseded by the `MatchedPolicyID`, but is required for token generation).
+*   `ClientId`: The client ID for this profile within Tyk Gateway.
+*   `Secret`: The client secret for this profile in Tyk Gateway.
+*   `RedirectURI`: The Redirect URL set for this profile in the Tyk Gateway.
+*   `ResponseType`: This can be `token` or `authorization_code`, the first will generate a token directly, the second will generate an auth code for follow up access. For SPWA and Mobile Apps it is recommended to just use `token`.
+
+When TIB successfully authorizes the user, and generates the token using the relevant OAuth credentials, it will redirect the user to the relevant redirect with their token or auth code as a fragment in the URL for the app to decode and use as needed.
+
+There is a simplified flow, which does not require a corresponding OAuth client in Tyk Gateway, and can just generate a standard token with the same flow.
+
+### 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}
+{
+  "ActionType": "GenerateOrLoginUserProfile",
+  "ID": "2",
+  "IdentityHandlerConfig": null,
+  "MatchedPolicyID": "1C",
+  "OrgID": "53ac07777cbb8c2d53000002",
+  "ProviderConfig": {
+    "CallbackBaseURL": "http://:{TIB-PORT}",
+    "FailureRedirect": "http://{DASH-DOMAIN}:{DASH-PORT}/?fail=true",
+    "UseProviders": [{
+      "Name": "gplus",
+      "Key": "GOOGLE-OAUTH-CLIENT-KEY",
+      "Secret": "GOOGLE-OAUTH-CLIENT-SECRET"
+    }]
+  },
+  "ProviderConstraints": {
+    "Domain": "yourdomain.com",
+    "Group": ""
+  },
+  "ProviderName": "SocialProvider",
+  "ReturnURL": "http://{DASH-DOMAIN}:{DASH-PORT}/tap",
+  "Type": "redirect"
+}
+```
+
+The login to the Dashboard makes use of a one-time nonce to log the user in to the session. The nonce is only accessible for a few seconds. It is recommended that in production use, all of these transactions happen over SSL connections to avoid MITM snooping.
+
+`Domain` constraint ensures that only users from `yourdomain.com` domain-based email accounts are allowed to login. 
+ Replace it with correct domain or remove this section if you don't want to set this constraint.
+
+
+When TIB successfully authorizes the user, and generates the token using the relevant OAuth credentials, it will redirect the user to the relevant redirect with their token or auth code as a fragment in the URL for the app to decode and use as needed.
+
+There is a simplified flow, which does not require a corresponding OAuth client in Tyk Gateway, and can just generate a standard token with the same flow.
+
+

tyk-docs/data/menu.yaml

@@ -317,8 +317,29 @@ menu:
               path: /api-management/security-features
             - title: "Identity Management"
               path: /api-management/external-service-integration
-              category: Page
+              category: Directory
               show: True
+              menu:
+              - title: "SSO with Social IDP"
+                path: /api-management/single-sign-on-social-idp
+                category: Page
+                show: True
+              - title: "SSO with OpenID Connect"
+                path: /api-management/single-sign-on-oidc
+                category: Page
+                show: True
+              - title: "SSO with SAML"
+                path: /api-management/single-sign-on-saml
+                category: Page
+                show: True
+              - title: "SSO with LDAP"
+                path: /api-management/single-sign-on-ldap
+                category: Page
+                show: True
+              - title: "Custom Authentication"
+                path: /api-management/custom-auth-with-proxy-identity-provider
+                category: Page
+                show: True
       - title: "Deploy Tyk"
         category: Label
         show: True