Connectors & Helpers
Embed - White Label Portal
Data and Dashboards
Best Practice Guides
1.1 Embed Integration via SSO
SSO integration for SaaS companies
The below steps explain how you can integrate the Embed (integration white label portal) into your own SaaS application.
1. Passing data to Locoia
SSO means single sign-on. This method allows SaaS company's end customers to enable integrations using Locoia without needing to log in - the most native way possible.
SSO with a JWT claim, as per the payload-example below:
1
{
2
"embed_user_id": "1234567890",
3
"embed_user_name": "John Doe",
4
"embed_account_id": "2345678545678",
5
"embed_account_name": "ABC Ltd.",
6
"embed_state": {
7
"your_custom_field": "your_custom_value",
8
"your_custom_field_2": "your_custom_value_2"
9
},
10
"client_authentication": {
11
"auth_type": "username_password",
12
"connector_id": "proprietary_connector_id",
13
"name": "connector_auth_name",
14
"auth_token": "",
15
"auth_details": "",
16
"api_endpoint": "",
17
"refresh_token": "",
18
"user_input": {},
19
"password": "end_user_password",
20
"username": "end_user_username"
21
},
22
"iat": 1516239022,
23
"exp": 1516539022
24
}
Copied!
JWT payload explained:
- embed_user_id: id of the end-user - required
- embed_user_name: name (first and last) of the end-user - optional
- embed_user_email: e-mail of the end-user - optional
- embed_user_language: user's language - optional (either de-DE or en-US). To change the language of the iframe, pass lang=de or en
- embed_account_id: your account id of your end-customer - required
- embed_account_name: your account name of your end-customer - optional
- embed_state: A string or dictionary to pass all kinds of values that you want to be accessible by the created embed flow - optional
- client_authentication: A dictionary with the connector auth details for the proprietary connector specified in the embed. You can find more details here - optional
- exp: expiry time stamp in epoch seconds - required
- iat: issued timestamp in epoch seconds - required
2. Creating the JWT token
Code examples in Python and node.js to convert the payload with JWT and a secret to the jwtToken:
Python
node.js
1
# Preparing the JWT based on a payload and secret.
2
3
import jwt
4
import time
5
6
secret = "secret can be found in your DI account upon creation of embed"
7
epoch_time = int(time.time())
8
9
# epoch time plus 1 hour
10
payload = {
11
"embed_user_id": "1234567890",
12
"embed_user_name": "John Doe",
13
"embed_account_id": "2345678545678",
14
"embed_account_name": "ABC Ltd.",
15
"iat": epoch_time,
16
"exp": epoch_time + 3600
17
}
18
19
jwtToken = jwt.encode(
20
payload,
21
secret,
22
algorithm="HS256",
23
headers={"alg": "HS256", "typ": "JWT"}
24
)
25
26
# Print jwtToken
27
print(jwtToken)
28
29
# Output: eyJhbGciOiJIUzI1Ni ... cPZg
Copied!
1
// Preparing the JWT based on a payload and secret.
2
3
const sign = require('jwt-encode');
4
const secret = 'secret can be found in your DI account upon creation of embed';
5
6
const payload = {
7
embed_user_id: '1234567890',
8
embed_user_name: 'John Doe',
9
embed_account_id: '2345678545678',
10
embed_account_name: 'ABC Ltd.',
11
iat: 1516239022,
12
exp: 1516539022
13
};
14
15
const jwtToken = sign(payload, secret);
16
17
// Print jwtToken
18
console.log(jwtToken);
19
20
// Output: eyJhbGciOiJIUzI1Ni ... cPZg
Copied!
Similar examples can be found for other languages.
3. Creating the white label iframe within your app
In the menu at Settings > Embedding you can find the iframe code, which looks similar and only need to replace the jwtToken with the token - as per the above creation example.
HTML
1
<iframe
2
id="embedded"
3
name="embedded"
4
src="https://api.locoia.com/embedded?embeddedId={UUID4 provided by the app}&token={jwtToken}&lang=de"
5
style="border-style: none; width: 100%; height: 1000px;"
6
>
7
</iframe>
Copied!
To change the language, you can adjust the query string parameter lang=de (German) to `en for English.
Last modified 4d ago