You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: articles/sso/index.md
+35-5
Original file line number
Diff line number
Diff line change
@@ -9,16 +9,42 @@ SSO (Single Sign On) occurs when a user logs in to one Client and is then signed
9
9
10
10
Google's implementation of login for their products, such as Gmail, YouTube, Google Analytics, and so on, is an example of SSO. Any user that is logged in to one of Google's products are automatically logged in to their other products as well.
11
11
12
-
## How SSO Works
13
-
14
-
SSO works by means of a *central service*. In the case of Google, this central service is [Google Accounts](https://accounts.google.com). When a user first logs in, Google Accounts creates a cookie, which persists with the user as they navigate to other Google-owned services. The process flow is as follows:
12
+
Single Sign On usually makes use of a *Central Service* which orchestrates the single sign on between multiple clients. In the example of Google, this central service is [Google Accounts](https://accounts.google.com). When a user first logs in, Google Accounts creates a cookie, which persists with the user as they navigate to other Google-owned services. The process flow is as follows:
15
13
16
14
1. The user accesses the first Google product.
17
15
2. The user receives a Google Accounts-generated cookie.
18
16
3. The user navigates to another Google product.
19
17
4. The user is redirected again to Google Accounts.
20
18
5. Google Accounts sees that the user already has an authentication-related cookie, so it redirects the user to the requested product.
21
19
20
+
## An overview of how SSO works with Auth0
21
+
22
+
In the case of SSO with Auth0, the *Central Service* is the Auth0 Authorization Server.
23
+
24
+
Let's look at how the SSO flow looks when using Auth0 and a user visits your application for the first time:
25
+
26
+
1. Your application will redirect the user to the Auth0 Hosted Lock page where they can log in.
27
+
2. Auth0 will check to see whether there is an existing SSO cookie.
28
+
3. Because this is the first time the user visits this Hosted Lock page, and no SSO cookie is present, they may be presented with username and password fields and also possibly some Social Identity Providers such as LinkedIn, GitHub, etc. (The exact layout of the Lock screen will depend on the [Identity Providers](/identityproviders) you have configured.
4. Once the user has logged in, Auth0 will set an SSO cookie
33
+
5. Auth0 will also redirect back to your web application and will return an `id_token` containing the identity of the user.
34
+
35
+
Now let's look at flow when the user returns to your website for a subsequent visit:
36
+
37
+
1. Your application will redirect the user to the Auth0 Hosted Lock page where they can sign in.
38
+
2. Auth0 will check to see whether there is an existing SSO cookie.
39
+
3. This time Auth0 finds an SSO cookie and instead of displaying the normal Lock screen with the username and password fields, it will display a Lock screen which indicates that we know you the user is, as they have already logged in before. They can simply confirm that they want to log in with that same account.
5. Auth0 will also redirect back to your web application and will return an `id_token` containing the identity of the user.
45
+
46
+
If an SSO cookie is present you can also sign the user in silently, i.e. without even displaying Lock so they can enter their credentials. This is covered in more detail in the next section.
47
+
22
48
## How to Implement SSO with Auth0
23
49
24
50
::: panel-info Enabling Identity Providers
@@ -33,9 +59,13 @@ Near the bottom of the *Settings* page, toggle **Use Auth0 instead of the IdP to
You can set the Client's SSO flag using the [Auth0 Management API](/api/management/v2#!/Clients/patch_clients_by_id).
62
+
Alternatively you can also set the Client's SSO flag using the [Auth0 Management API](/api/management/v2#!/Clients/patch_clients_by_id).
63
+
64
+
Once you have set the SSO flag for your Client in the Auth0 Dashboard, you must add logic to your application to check the user's SSO status. Checking the user's SSO status can only be done via JavaScript by making use of the [`getSSOData`](/libraries/auth0js#sso) function in the [auth0.js library](/libraries/auth0js).
65
+
66
+
The result of this function will indicate whether an SSO cookie is present, and if so it will return the SSO data of the user which can then subsequently be used to log the user in silently without even displaying Lock.
37
67
38
-
Once you have set the SSO flag in Auth0, you must add logic to your Client to check the user's SSO status. This logic can be implemented either client-side (using JavaScript) or server-side:
68
+
For more detailed information on how to implement this, please refer to the following documents:
Copy file name to clipboardexpand all lines: articles/sso/regular-web-apps-sso.md
+25-14
Original file line number
Diff line number
Diff line change
@@ -4,30 +4,40 @@ description: Server-side SSO with regular web applications.
4
4
5
5
# Server-side SSO (Regular Web Apps)
6
6
7
-
Let's say we have three applications
7
+
To log a user in silently (i.e. without displaying the Lock screen) the following conditions need to be met:
8
8
9
-
* App 1: app1.com (single page app)
10
-
* App 2: app2.com (single page app)
11
-
* App 3: app3.com (regular web app)
9
+
1. The Client needs to be configured to **Use Auth0 instead of the IdP to do Single Sign On** in the [Clients section of the Auth0 Management Dashboard](${manage_url}/#/clients)
10
+
2. An SSO cookie must exist for the tenant's domain. In other words the user must have signed in previously, and the SSO cookie which was saved is still valid.
11
+
3. When calling the Auth0 authentication endpoint, the connection name is passed along for which the user must be signed in. This connection name is the same as the one specified in the SSO cookie. You can pass the connection name along either as a parameter when calling the `signin` function of the [**auth0.js** Library](https://auth0.com/docs/libraries/auth0js), or by passing the `connection` query string parameter when calling the `/authorize` endpoint of the [Authentication API](/api/authentication)
12
12
13
-
> You can see an example of a Regular Web App configured to use SSO in [this github repository](https://github.com/auth0/auth0-sso-sample/tree/master/app3.com)
13
+
## The SSO scenario
14
+
15
+
In our SSO scenario, let's say we have 3 applications
16
+
17
+
* App 1: app1.com (Single Page App)
18
+
* App 2: app2.com (Single Page App)
19
+
* App 3: app3.com (Regular Web app)
20
+
21
+
If a user logs in to any of these applications, and then subsequently navigates from this application to any of the other applications, we would want the user to be logged in automatically.
22
+
23
+
In this document we will be looking specifically how to achieve this in a Regular Web Application
14
24
15
25
## Case 1: The user is already logged in and clicks on a link that redirects to a specific URL app3.com
16
26
17
-
The user logs in on app1.com and clicks on a link that should take them to a particular URL on app3.com. In this case, you can create an endpoint on the target application (app3) that will redirect to the URL the user wanted to go after SSO. For example:
27
+
The user logs in on one of the Single Page Applications and click on a link that should take them to a particular URL on app3.com. In this case, you can create an endpoint on the target application (app3) that will redirect to the URL the user wanted to go after SSO. For example:
This endpoint would check if the user is already logged in to this app. If they are, then redirect to the target URL. If the user is not logged in to the application, then redirect to Auth0 for SSO:
33
+
This endpoint would check if the user is already logged in to this app. If they are, then redirect to the target URL. If the user is not logged in to the application, then redirect to Auth0 for SSO, passing along the name of the connection to use:
24
34
25
-
```
35
+
```text
26
36
handle("/sso")
27
37
if (user is already logged in)
28
38
redirect to targetUrl
29
39
else
30
-
redirect to "https://YOURS.auth0.com/authorize?client_id=…&redirect_uri=http://urlTo/callback&response_type=code&state=' + targetUrl
40
+
redirect to "https://${account.namespace}/authorize?client_id=…&connection=<connection name>&redirect_uri=http://urlTo/callback&response_type=code&state=' + targetUrl
The user is logged in on app1.com and opens a new tab and goes to app3.com. You would expect the user to be automatically signed in. To do that, you need to redirect the user to the following URL in a filter or a middleware:
@@ -99,5 +110,5 @@ If the user was already logged in before, then Auth0 will automatically redirect
99
110
The user has never logged in to any app. In this case, the filter or middleware mentioned in the previous point checks if the user is authenticated or not, and in the case they're not, redirects the user to the following URL:
Copy file name to clipboardexpand all lines: articles/sso/single-page-apps-sso.md
+82-22
Original file line number
Diff line number
Diff line change
@@ -4,26 +4,95 @@ description: Client-side SSO with single page applications.
4
4
5
5
# Client-side SSO (Single Page Apps)
6
6
7
-
Let's say you have three applications:
7
+
To log a user in silently (i.e. without displaying the Lock screen) the following conditions need to be met:
8
8
9
-
* App 1: app1.com (single page app)
10
-
* App 2: app2.com (single page app)
11
-
* App 3: app3.com (regular web app)
9
+
1. The Client needs to be configured to **Use Auth0 instead of the IdP to do Single Sign On** in the [Clients section of the Auth0 Management Dashboard](${manage_url}/#/clients)
10
+
2. An SSO cookie must exist for the tenant's domain. In other words the user must have signed in previously, and the SSO cookie which was saved is still valid.
11
+
3. When calling the Auth0 authentication endpoint, the connection name is passed along for which the user must be signed in. This connection name is the same as the one specified in the SSO cookie. You can pass the connection name along either as a parameter when calling the `signin` function of the [**auth0.js** Library](/libraries/auth0js), or by passing the `connection` query string parameter when calling the `/authorize` endpoint of the [Authentication API](/api/authentication)
12
12
13
-
> You can see an example of a SPA configured to use SSO in [this github repository](https://github.com/auth0/auth0-sso-sample/tree/master/app1.com)
13
+
## The SSO scenario
14
14
15
-
The user logs in on app1.com and tries to access app2.com. Since app2.com is a Single Page App you need to have some code like the following to do SSO. This code should be on every SPA you have (In this case App1 and App2).:
15
+
In our SSO scenario, let's say we have 3 applications
16
+
17
+
* App 1: app1.com (Single Page App)
18
+
* App 2: app2.com (Single Page App)
19
+
* App 3: app3.com (Regular Web app)
20
+
21
+
If a user logs in to any of these applications, and then subsequently navigates from this application to any of the other applications, we would want the user to be logged in automatically.
22
+
23
+
In this document we will be looking specifically how to achieve this in a Single Page (JavaScript) Application
24
+
25
+
## Obtaining the SSO cookie information
26
+
27
+
If a users logs in to any of the applications and then subsequently tries to log in to any of the other applications, you can check to see whether an SSO session is active for that user by making use of the `getSSOData` function in the [auth0.js library](/libraries/auth0js#sso).
28
+
29
+
```js
30
+
auth0.getSSOData(function (err, ssoData) {
31
+
if (err) returnconsole.log(err.message);
32
+
expect(ssoData.sso).to.exist;
33
+
});
34
+
```
35
+
36
+
This function will return an `ssoData` object which will indicate whether an active SSO session exist. The `ssoData` object will contain the fields as per the following example:
## Passing the Connection Name when logging the user in
54
+
55
+
You can then use this information to call the `signin` function to log the user in. When you call the `signin` function you pass along the name of the connection used in the active SSO session as the `connection` parameter. Auth0 will determine that an SSO cookie is saved for that connection, and will log the user directly without displaying the Lock user interface.
56
+
57
+
58
+
```js
59
+
auth0.getSSOData(function (err, ssoData) {
60
+
if (!err &&ssoData.sso) {
61
+
auth0.signin({
62
+
connection:ssoData.lastUsedConnection.name,
63
+
scope:'openid name picture',
64
+
params: {
65
+
state:getQueryParameter('targetUrl')
66
+
}
67
+
});
68
+
} else {
69
+
// Display regular login option, e.g. a Login button which will invoke Lock
70
+
}
71
+
});
72
+
```
73
+
74
+
## Full SSO Sample Code
75
+
76
+
Below is an expanded code sample of how you can implement this in a SPA application using jQuery to either show or hide the Login button or user information depending on whether a user is logged in or not.
77
+
78
+
The full code sample for both the SPA applications as well as the normal web application can be found in [this github repository](https://github.com/auth0/auth0-sso-sample/tree/master/app1.com)
16
79
17
80
```html
18
81
<scripttype="text/javascript">
19
82
// hide the page in case there is an SSO session (to avoid flickering)
20
83
document.body.style.display='none';
21
84
22
85
// instantiate Lock
23
-
var lock =newAuth0Lock(''${account.clientId}', ''${account.namespace}');
86
+
var lock =newAuth0Lock('${account.clientId}', '${account.namespace}', {
87
+
auth: {
88
+
params: {
89
+
scope:'openid name picture'
90
+
}
91
+
}
92
+
});
24
93
var auth0 =newAuth0({
25
-
domain:''${account.namespace}',
26
-
clientID: ''${account.clientId}',
94
+
domain:'${account.namespace}',
95
+
clientID:'${account.clientId}',
27
96
callbackOnLocationHash:true
28
97
});
29
98
@@ -76,37 +145,28 @@ The user logs in on app1.com and tries to access app2.com. Since app2.com is a S
76
145
// Showing Login
77
146
$('.btn-login').click(function (e) {
78
147
e.preventDefault();
79
-
lock.show({
80
-
auth: {
81
-
params: {
82
-
scope:'openid name picture'
83
-
}
84
-
}
85
-
});
148
+
lock.show();
86
149
});
87
150
88
151
</script>
89
152
90
153
<!-- Regular login -->
91
154
<body>
92
-
<buttononclick="lock.show()">Login</button>
155
+
<buttonclass="btn-login">Login</button>
93
156
</body>
94
157
```
95
158
96
-
If the single sign on happens against app3.com (a regular web app), then you have to redirect to `app3.com/sso?targetUrl=/foo/bar`. Read more about this on [Single Sign On with Regular Web Apps](/sso/regular-web-apps-sso).
97
-
98
159
## Single Logout
99
160
100
-
If the user logged out from app1.com, then we want to clean up the token on app2.com (and app3.com). Read more about [Single Log Out](/logout).
161
+
If the user logged out from app1.com, then we want to clean up the token on app2.com (and app3.com). Read more about [Single Log Out](/logout).
101
162
102
-
To do that, you have to check every X amount of time whether the SSO session is still alive in Auth0. If it is not, then remove the token from storage for the app.
163
+
To do that, you have to check every X amount of time whether the SSO session is still alive in Auth0. If it is not, then remove the token from Local Storage for the application. This will ensure that the user's local session is cleared.
103
164
104
165
```js
105
166
setInterval(function() {
106
167
// if the token is not in local storage, there is nothing to check (i.e. the user is already logged out)
0 commit comments