/
sso.md
172 lines (118 loc) · 9.61 KB
/
sso.md
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
---
date: 2017-03-24T16:40:31Z
title: Single Sign On
menu:
main:
parent: "Tyk Dashboard"
weight: 0
---
## Introduction to Single Sign On (SSO)
### SSO - The generic use case
SSO gives users the ability to log in to multiple applications without the need to enter their password more than once.
[OIDC]({{< ref "advanced-configuration/integrate/api-auth-mode/open-id-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).
### SSO in Tyk
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" >}}).
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:
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)
#### Tyk Identity Broker (TIB)
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.
#### SSO with Open ID Connect or Social Providers
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.
In short, all you need is as follow:
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 `<portal-url>/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:
```
"sso_permission_defaults": {
"analytics": "read",
"apis": "write",
"hooks": "write",
"idm": "write",
"keys": "write",
"policies": "write",
"portal": "write",
"system": "write",
"users": "write",
"user_groups": "write"
}
```
As alternative, you can set `sso_default_group_id` to specify User Group ID assigned to SSO users.
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.
#### Sample Login Request
```{.copyWrapper}
GET /tap?nonce=YTNiOGUzZjctYWZkYi00OTNhLTYwODItZTAzMDI3MjM0OTEw HTTP/1.1
Host: localhost:3000
```
## SSO with LDAP Integration
Detailed instruction on setting [SSO with LDAP]({{< ref "advanced-configuration/integrate/3rd-party-identity-providers/dashboard-login-ldap-tib" >}}).
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.