Okta

Enterprise

To configure Appsmith to use Okta as a SAML provider, follow the steps below:

Prerequisites

1. A self-hosted Appsmith instance. See the installation guides for installing Appsmith.

2. Before setting up Single Sign-On (SSO), ensure that you have already configured a custom domain for your instance.

3. In Appsmith, go to Admin Settings > Authentication and click Enable on SAML 2.0.

4. Copy the Redirect URL and Entity ID from the SAML 2.0 configuration page to add them later in the Okta settings.

SAML configuration in Appsmith

Create application on Okta

1. Log in to your Okta account and on the Get started with Okta page, click Add App for Use single sign on.

2. On the Browse App Integration Catalog page, click Create New App.

3. A pop-up titled Create a new app integration appears. Choose SAML 2.0 as the Sign-in method and click Next.

4. On the Create SAML Integration page, add a name for your app in General settings. Click Next.

5. In Configure SAML:

a. Add the Redirect URL in Single sign-on URL field.

b. Add the Entity ID in the Audience URI (SP Entity ID) field.

c. From the Name ID format options, select emailAddress.

d. Pick Email from the Application username options.

e. Click Next to proceed.

6. If you are only interested in simple authentication via SAML, you can skip this step. However, if you want to configure custom claims, follow the steps below:

In the Attribute Statements section, add your custom attributes:

• Name: Enter the attribute name in the desired format (e.g., firstName, lastName, email). Copy the claim name to add it later in the Appsmith SAML configurations.

• Name Format: Select a Name format. This is the format that the Name attribute is provided to your app:

• Value: Choose the corresponding value from the predefined list (e.g., user.firstName, or user.email).

7. Fill in the required feedback or additional information in the final step and click Finish.

8. On your application's homepage, go to the Sign-on tab and copy the Metadata URL from the SAML 2.0 section to add it later in the SAML configurations in Appsmith.

9. Go to the Assignments tab, and click Assign to assign people or groups to this application.

Register Okta in Appsmith

caution

If you are running Appsmith on Google Cloud Run or AWS ECS, make sure to configure your service before setting up SSO. For detailed instructions, see the Configure Google Cloud Run for SSO, or Create PostgreSQL RDS for SAML SSO guide.

To complete the SAML configuration, you have to register the identity provider on Appsmith. Appsmith provides three options to register the identity provider as mentioned below:

Metadata URL (recommended)

To register Okta as the identity provider on Appsmith, follow the steps below:

1. Go to the SAML 2.0 configuration page in Appsmith and navigate to Register Identity Provider section.

2. Add the copied Metadata URL in the Metadata URL field under the Register Identity Provider section.

3. To configure custom SAML claims (if added in the Okta's Attribute Statements) in Appsmith, Click the Advanced section.

a. For each custom claim, enter a name in the Key field that references the custom SAML claim within Appsmith.

b. In the Value field, enter the exact claim name that you copied from the Okta's Attribute Statements section.

Metadata XML

To set up SAML using the raw Metadata XML file, follow the steps below:

1. Open the copied Metadata URL in a browser tab and copy the XML content.

2. Navigate to Appsmith and add the raw XML in the Metadata XML field under the Register Identity Provider section in the SAML 2.0 configuration page.

3. To configure custom SAML claims (if added in the Okta's Attribute Statements) in Appsmith, Click the Advanced section.

a. For each custom claim, enter a name in the Key field that references the custom SAML claim within Appsmith.

b. In the Value field, enter the exact claim name that you copied from the Okta's Attribute Statements section.

IdP Data

If you have Identity provider data like X509 Public Certificate, Email, you can choose this option to configure SAML.

1. Open the Metadata URL in a browser tab or open the Metadata XML file.

2. Add the following values from XML tags in IdP Data under the Register Identity Provider section in the Appsmith SAML 2.0 configuration page:

IdP Data Field	Metadata XML Tag
Entity ID	Enter the value of the entityID attribute specified in the <EntityDescriptor> tag.
Single Sign-On URL	Enter the value of location attribute specified in the <SingleSignOnService> tag.
X509 Public Certificate	Enter the value specified in the <X509Certificate> tag.
Email	Enter the value specified in the <NameIDFormat> tag.

3. To configure custom SAML claims (if added in the Okta's Attribute Statements) in Appsmith, Click the Advanced section.

a. For each custom claim, enter a name in the Key field that references the custom SAML claim within Appsmith.

b. In the Value field, enter the exact claim name that you copied from the Okta's Attribute Statements section.

Once you have added the details, click the SAVE & RESTART button to save the configuration and restart the instance.

info

If you're running Appsmith on a Kubernetes cluster with an HA configuration, after completing the setup, run the following command to ensure the new authentication settings are properly applied:

kubectl rollout restart deployment/appsmith -n

After the Appsmith instance restarts, try logging in again to your account. You'll see a login screen with the SIGN IN WITH SAML SSO button.

Login with SAML SSO

Troubleshooting

If you are facing issues contact the support team using the chat widget at the bottom right of this page.

See also

• Setup SCIM provisioning
• Remove Account Update Screen