Add SAML single sign-on to your app

1. 1

   Ask Lovable to enable SAML SSO for your app in the project chat, or go to 'More → Cloud → Users → Auth settings → SAML SSO' and turn it on.

   This opens a form where you'll find two important web addresses (ACS URL and Audience URI) that Lovable needs to communicate with the company's login system.

2. 2

   Copy the 'ACS URL' and 'Audience URI' from Lovable.

   These are unique identifiers for your app that the company's login system will need to know.

3. 3

   In the company's login system (like Okta), create a new SAML 2.0 application and paste the 'ACS URL' and 'Audience URI' into the correct fields.

   This tells the company's login system how to send users back to your app after they've signed in.

4. 4

   Configure the company's login system to send the user's email as an 'EmailAddress' and map their primary email to an 'email' attribute.

   This ensures your app receives the correct email address for the user when they sign in.

5. 5

   Assign the users or groups who should be able to sign in to this new application in the company's login system.

   This controls who from the company can use this sign-in method for your app.

6. 6

   Copy the 'metadata URL' from the company's login system.

   This URL contains all the information Lovable needs to understand and trust the company's login system.

7. 7

   Go back to the Lovable form (either in chat or 'Auth settings') and paste the 'metadata URL' into the 'SAML metadata URL' field.

   This completes Lovable's side of the setup, allowing it to communicate with the company's login system.

8. 8

   Enter a comma-separated list of email domains (e.g., 'acme.com, acme.co.uk') that should use this login system.

   This tells Lovable which users, based on their email address, should be directed to this specific company login system when they try to sign in.

9. 9

   Click 'Submit' (in chat) or 'Save' (in the UI).

   This applies all your settings and enables the SAML SSO feature.

10. 10

    Ask Lovable in the project chat: "Add a 'Sign in with SSO' option to my sign-in page that prompts for an email and routes users to their SAML provider".

    This adds a button or link to your app's login screen, allowing users to start the SSO process.

11. 11

    Test the sign-in flow by opening your published app in an incognito window, going to the sign-in page, and entering an email address from one of your configured domains.

    This confirms that the entire setup works correctly and users can successfully sign in using their company's system.

Enable SAML SSO for this app

SAML SSO

Stands for Security Assertion Markup Language Single Sign-On. It's a standard way for users to log into one application (your app) using their existing login from another system (like their company's identity provider), without needing a separate username and password for your app.

Identity Provider (IdP)

The system that stores and manages user identities and authenticates them. Examples include Okta, Microsoft Entra ID (formerly Azure AD), or Google Workspace. It's where users enter their username and password.

Service Provider (SP)

The application or service that users are trying to access. In this case, your app is the Service Provider.

ACS URL

Assertion Consumer Service URL. This is a specific web address on your app's side where the Identity Provider sends the user's successful login information after they've authenticated.

Audience URI

Also known as SP Entity ID. This is a unique identifier for your app that the Identity Provider uses to confirm it's sending login information to the correct service.

Metadata URL

A web address provided by the Identity Provider that contains all the necessary configuration details (like security certificates and endpoints) for your app to communicate with it securely.

SP-initiated sign-in

This means the user starts the login process from your app (the Service Provider). They click a 'Sign in with SSO' button, and then your app redirects them to their company's login page.

IdP-initiated sign-in

This means the user starts the login process from their company's login system (the Identity Provider), typically by clicking an icon or tile for your app on their company's dashboard. This specific feature is not supported for end-user logins in Lovable apps.

JIT provisioning

Just-In-Time provisioning. This means that a user's account in your app is automatically created the very first time they successfully sign in using SAML, rather than needing to be set up beforehand.

SCIM provisioning

System for Cross-domain Identity Management. This is a standard for automatically managing user accounts (creating, updating, deleting) between an Identity Provider and other applications. Lovable does not support this for end-user logins in your app.

• Trying to use SAML SSO for your team's access to Lovable itself instead of for your app's end users.
• Not having admin access to a SAML 2.0 identity provider that publishes a public metadata URL.
• Forgetting to copy both the ACS URL and Audience URI from Lovable into your IdP's SAML application.
• Not mapping the user's primary email to an 'email' attribute in your IdP.
• Forgetting to copy the IdP's metadata URL back into Lovable.
• Not providing the correct email domains that should use the IdP.
• Expecting IdP-initiated sign-in to work for your app's end users (only SP-initiated is supported).
• Not adding a 'Sign in with SSO' entry point to your app's UI after configuring SAML.
• Assuming that enabling SAML automatically disables other sign-in methods; you must disable them explicitly if you want to enforce SSO-only.
• Having an 'Invalid metadata' error because the metadata URL is incorrect or not publicly accessible.
• Users not being redirected to the IdP because their email domain isn't in your configured list.
• Users landing back on the sign-in page after successfully logging in at the IdP, often due to incorrect redirect handling in your app or an unlisted app URL.
• Sign-in failing after IdP login because the SAML assertion is missing an email or the ACS URL/Audience URI don't exactly match.