Share Retool apps
Learn how to share or embed apps to allow access without logging into Retool.
You can share Retool apps by embedding them in iframes or enabling public links. You can also add authentication to embedded apps if Retool is integrated with the same Identity Provider as the parent application. Adding authentication requires that you self-host Retool.
Retool Embed
Retool Embed is a new beta feature for allowing external users––partners, vendors, customers––to securely access embedded Retool apps within your product. You can use any authentication solution to give users access, and then control app behavior, data access, and audit usage on a per-user basis. See the Retool Embed documentation if you're interested in joining the beta.
If your apps don't need user authentication, you can create Public apps and embed them into your parent application using a public link.
Embed apps with JavaScript
You can embed apps using Retool's JavaScript SDK. After including the JavaScript SDK library, you initialize an instance of your Retool app and embed it at the specified location using window.retool.RetoolDashboard().
<html>
<head>
<script src="https://cdn.tryretool.com/embed.js"> </script>
</head>
<body>
<div style="height: 800px; width: 100%;" id="container"></div>
<script>
var rt =
window.retool.RetoolDashboard(document.getElementById('container'),
'https://retool.yoursite.com/apps/embedded-app')
</script>
</body>
</html>
Embed apps with React
To embed apps with React, install the react-retool npm module and then import it into your project.
// with npm
$ npm install react-retool --save
// with yarn
$ yarn add react-retool
import Retool from "react-retool";
function App() {
return (
<Retool url="https://retoolin.tryretool.com/embedded/public/f7607e1f-670a-4ebf-9a09-be54cf17181e" />
);
}
export default App;
See the React wrapper documentation for more information.
If you need to embed a Retool app into another web app, your code might look something like this.
import React from "react";
import Retool from "react-retool";
class App extends React.Component {
constructor(props) {
super(props);
this.state = { value: 0 };
}
buttonClicked(event) {
this.setState({ value: this.state.value + 1 });
}
render() {
return (
<div className="App">
<div className="parent-react-app-container">
<h1>I am a react app</h1>
<h2>
Value Retool will read on load:{" "}
<span id="id-value-retool-reads">hello</span>
</h2>
<div>
<h2>
<span id="other-id-value-retool-reads">{this.state.value}</span>
</h2>
<button onClick={this.buttonClicked}>
Increment Dynamic Value
</button>
</div>
</div>
<div className="retool-box">
<Retool url="https://retool.yoursite.com/apps/embedded-app" />
</div>
</div>
);
}
}
export default App;
Pass data between embedded and parent apps
Embedded Retool apps can use Parent Window Queries to read values from the parent application. They can also use JavaScript queries to pass data back to the parent app using the browser's postMessage API.
Pass data to an embedded app
You can read data from parent apps with Parent Window Queries. If you embed your app with JavaScript, pass the CSS selector for the value to read. With React, pass the key in the data prop that you want to read.
Pass data to the parent app
To pass data to the parent app, create a JavaScript query and use the postMessage API to send the data. For example, a query that sends the email address of the current_user to the parent app might look like this.
On the parent application side, the code to listen to and handle these messages might look like this.
window.addEventListener(
"message",
function (e) {
console.log("Parent window received: ", e.data);
},
false
);
The code to handle postMessage requests depends on your specific implementation. You might need to write something more complex than the above example.
User authentication in embedded apps
It's common to embed Retool apps into existing portals, tools, and applications. This makes it easier to provide a consistent and efficient app experience for external users, while making sure the data they see is secure.
The following sections explain how to provide a seamless experience to external users, without requiring a double-login (logging into the parent application, and separately into the embedded Retool app).
Retool Embed
Retool Embed is the recommended approach for authenticating end users into embedded Retool apps. You can use your existing authentication flow to generate a one-time URL that you can then use within an iframe.
User authentication with an Identity Provider
If you have SAML or OIDC SSO set up on your self-hosted Retool instance, you can also authenticate end users into embedded Retool apps. As long as your existing web application uses the same SSO Identity Provider (IDP) as Retool, you can share the user's authentication state between the parent and embedded apps.
Prevent double logins
If you configure your web application and Retool to use the same IDP, a user might have to SSO into the web application, and then have to SSO again into the embedded Retool app. To avoid this, you can set up Retool to automatically sign the user in with SSO instead of displaying a login screen. This works when the user has an existing, authenticated session on the IDP.
To configure this, set one of these environment variables to true in your docker.env file.
TRIGGER_SAML_LOGIN_AUTOMATICALLYif using SAML.TRIGGER_OAUTH_2_SSO_LOGIN_AUTOMATICALLYif using OIDC SSO.
Public apps
Public apps and Retool plans
Public apps are only available on Business and Enterprise plans.
You can share Retool apps publicly with a Public access link. You can share this link directly with users or embed the app in an iframe in other applications or web pages. These apps can be accessed by anyone on the internet and always reflect the production environment of the app.
To create a Public access link, open an app in the App editor and click the Share button in the top right. Select the Public tab and click Enable public link.
Public apps are not secure
You can add password protection to public apps but password protection isn't a robust authentication method. Don't put sensitive data in public Retool apps, even with password protection enabled.
The following example is a demo app from our Quickstart guide.
Updated 11 days ago