Single Sign-On (SSO) with Google and Custom SSO

What You'll Learn

Single Sign-On (SSO) lets your users log in to your Knack app with an existing account from another service instead of a Knack username and password. This article covers how to add Google SSO to a login page, how to configure custom OAuth and SAML providers, and how user records and roles are handled when someone logs in through SSO.

What Is Single Sign-On (SSO)?

Single Sign-On (SSO) is an authentication method that lets an outside service verify a user's identity instead of Knack. Your users click an SSO button on your login page, authenticate with that service, and get access to your app without creating a separate Knack password.

Users can use SSO both to register as a new user and to log in to an existing account.

Add an SSO Provider to a Login Page

You add SSO providers from the login view settings on any login page.

1. Open the page with your login view.
2. Open the login view settings.
3. Find the Single Sign On section and click Add Provider.
4. Choose the provider type.
5. Enter the credentials from that provider.

You can edit or remove a provider later from the same login view settings.

Set Up Google SSO

Google SSO requires a Google Cloud project with an OAuth client ID. You create the project in the Google Cloud Console, then paste the generated credentials into your Knack login view settings.

1. Open the Google Cloud Console and create a project, or select an existing one.
2. Go to APIs & Services > Credentials.
3. Click Create Credentials and choose OAuth client ID.
4. Select Web application as the application type and give it a name.
5. Add your app's domain under Authorized JavaScript origins. See the domain formats below.
6. Add your app's full login URL under Authorized redirect URIs.
7. Click Create.
8. Copy the Client ID and Client secret.
9. In Knack, open your login view settings, add a Google provider, and paste both values.

Which Domain to Use

Knack apps use the knack.com domain. Use these formats when filling in the Google Cloud Console fields:

Replace (accountSlug) with your account slug and (appSlug) with your app slug.

If your configuration still lists older knackhq.com entries, you can leave them in place. Extra entries don't interfere with logins on the current domain.

For help updating an existing Google or Microsoft Entra ID configuration, including the domains needed for Next-Gen apps, see Updating Your App's SSO Configuration to Include Knack.com.

Facebook and X (Twitter) SSO

Facebook and X (formerly Twitter) SSO are no longer supported and can't be added as providers.

How User Records and Roles Are Assigned

When a new user logs in through SSO for the first time, Knack creates their user record automatically using the name and email address from the authenticating service.

Knack assigns user roles based on the login page the user came through. The user gets every role that has access to that login page. If three roles can access the page, the new user is assigned all three.

There are two ways to control which role a user ends up in:

• Send each group a link to a login page where only their role has access.
• Import your users into their correct roles before giving them access to the app.

Advanced Single Sign-On

Advanced SSO covers domain restrictions and custom identity providers using OAuth or SAML.

Domain Restrictions

Google and OpenID providers can restrict authorization to a specific email domain. Only accounts with an email address at that domain are authorized.

For example, entering knack.com on a Google SSO provider means only Google accounts with a knack.com email address can log in.

Custom SSO Providers

Custom providers are added the same way as Google. Open the login view settings, click Add Provider under Single Sign On, and choose your provider type.

Supported schemes are SAML 1.1 and 2.0 (including Shibboleth) and OAuth 1.0a and 2.0.

Every provider type shares three display settings:

The remaining settings depend on the provider type you choose.

OAuth 1.0a Settings

OAuth 1.0a providers require four credential values plus three URLs from your provider. If your provider asks for a Callback URL, use the base URL of your app.

OAuth 2.0 Settings

OAuth 2.0 providers require two URLs and two credential values. If your provider asks for a Redirect URL, use the base URL of your app.

SAML 1.1 and 2.0 Settings

SAML providers require an entry point, an issuer string, and an identity provider certificate. Optional certificates cover request signing and assertion encryption.

If your SAML provider asks for an Assertion Consumer Service endpoint, use the AssertionConsumerService value from the metadata you download after setting up the SAML provider in your login view settings.

Standard US format:

https://us-api.knack.com/v1/applications/YOUR_APP_ID/auth/PROVIDER_NAME/return

HIPAA and GovCloud environments:

https://usgc-api.knack.com/v1/applications/YOUR_APP_ID/auth/PROVIDER_NAME/return

The ID property links to the email field in Knack, so the email address must be included in the SAML request.

Map User Profile Properties for OAuth Providers

OAuth providers need a Profile URL so Knack can pull user details from the authentication service. When a user logs in, Knack sends a GET request to this URL with the user's token and expects a JSON object in response.

Example response:

{
  "id": 12345,
  "info": {
    "name": {
      "first": "John",
      "last": "Smith"
    },
    "email": "[email protected]"
  }
}

Using the example above, you would map the properties like this:

The Profile URL and ID property are required. The ID property is whatever value in the JSON object uniquely identifies the user.

Notes and Troubleshooting

Every user logs in as the same account

This almost always means a property value is mapped incorrectly in your SSO provider setup. Recheck the ID, First Name, Last Name, and Email Address property values against the JSON your provider returns.

Knack can't tell you what those values should be. If you're unsure, contact your network administrator or your identity provider's support.

Google SSO login fails or redirects incorrectly

Check that your Authorized JavaScript origins and Authorized redirect URIs in the Google Cloud Console match the exact URL in the browser address bar when the login starts. Both must use the same domain and subdomain.

A new user can't be created on first login

Check your registration settings on the login page. If registration is set to No, SSO won't create new user records and users without an existing account will be denied.

Next Steps

• About Logins & Registrations covers login views, registration settings, and how users access protected pages.
• Managing User Roles & Permissions explains how roles control what each user can see and do.
• Configuring SAML SSO with Microsoft Entra ID (formerly Azure AD) walks through a full SAML setup with a specific identity provider.