Single Sign-On (SSO) with Google, Facebook, Twitter, and Custom SSO

A common method for authenticating logins in Knack is called Single Sign-On (SSO) where other services like Google can be used to authenticate your users.

What is Single Sign-On (SSO)?

A common method for authenticating logins is called Single Sign-On, or SSO, where other services like Facebook, Twitter, or Google can be used to authenticate the user.

You can add these services as options for your users to authenticate their account (register as a user) and log in to your apps:

On a login page, open the login view settings to add Single Sign-Ons. There you can select the "Add Provider" option under "Single Sign On". There you will be able to choose the provider type.

 

After selecting a provider type, you will be prompted to add your credentials. You can also edit these later from the login settings.

 

Google SSO

A Google Project must first be created on the Google Developers Console. Once added, click on the Credentials tab, the "Create Credentials" link, and choose "OAuth Client ID":

 

Complete the highlighted sections as detailed in the images below, then click "Create":

 

Enter the information specific to your account in the fields as shown below:

Edit the settings and add the URL and domain your app is using to the Redirect URIs and the Javascript Origins.

Doing this will generate a Client ID:

You can there copy the generated ID and Client secret and add them to your Knack credentials.

Facebook SSO

A Facebook app must first be created on the Facebook Developers Site. You'll need to enter the app URL where the login requests are coming from. Add this by clicking on App, Settings, and then adding a Platform for "Web". You can then enter the URL.

Here's an example of getting the Facebook credentials:

 

X (Twitter) SSO

A Twitter app must first be created in the Twitter App Management site. You can add your app without specifying any technical URLs or callbacks.

Click on the "API Keys" tab to get your SSO credentials:

 

Advanced Single Sign-On

The following options are available on our Corporate plans and above or with the Pro plan add-on. See our pricing page for more.

There are two ways to tie user groups between the identity provider and Knack. Both require setting up user roles in Knack in advance:

• Send each group a link to a page where only their user role has access to the page. When the user logs in for the first time, they'll be assigned to the user role set to have access from that login page. If multiple user roles have access, then the user will be assigned all user roles with access to that page.

• Import your users into their respective user roles in Knack before giving them access to the app.

Domain Restrictions

Both the Google and OpenID SSO providers have the option to enforce domain restrictions. This means that you can provide a domain to restrict authorization to. Only accounts with emails from that domain will be authorized.

For example, by entering "knack.com" with a Google SSO, only Google accounts with an email address using knack.com will be authorized.

Custom SSO Providers

Besides authenticating with common SSO providers, custom providers can also be set up with additional configuration parameters. Supported SSO schemes include SAML 1.1 and 2 (including Shibboleth) and OAuth 1.0a and 2.

On a login page, open the login view settings to add Single Sign-on. There you can select the "Add Provider" option under "Single Sign On". There you will be able to choose the provider type.

To get started, open the login view settings to add Single Sign-on. There you can select the "Add Provider" option under "Single Sign On". There you will be able to choose the provider type.

 

For each provider type, there are several standard settings. These settings include:

• Provider Name: This is what will appear on the button on your login form.

• Button Color: The color that will appear in the background of your Single Sign-On button.

• Button Font Color: The font color that the Provider Name will show up as on the Single Sign-On button.

Additionally, there are several custom options for each provider type. They are as follows:

OAuth 1.0a

If your OAuth provider requires that you provide a Callback URL, you should use the base URL of your app.

• Request URL: The URL utilized to obtain an OAuth request token.

• Access URL: The URL that is used to obtain an access token from the authorized request token.

• User Authorization URL: The URL used to obtain user authorization.

• Consumer Key: A key (normally assigned to you by your OAuth provider) that allows your app to identify itself to the provider.

• Consumer Secret: Used to establish ownership of the Consumer Key.

OAuth 2.0

If your OAuth provider requires that you provide a Redirect URL, you should use the base URL of your app.

• Authorization URL: The URL that your user is redirected to obtain permissions when they click the SSO button.

• Access Token URL: Used to obtain a token to verify future requests to the authentication provider to act on your user’s behalf.

• Client ID: The Client ID is a unique string that identifies your app with your OAuth provider.

• Client Secret: A secret key provided by your authorization provider, used to sign all private communications with the authorization provider

SAML 1.1 and 2.0

If your SAML provider requires that you provide an Assertion Consumer Service endpoint, you should use the AssertionConsumerService value that can be found when downloading the metadata information after setting up the SAML provider from your login page's settings.

An example format for an App located in the US is:

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

If the app is on our HIPAA or GovCloud environments, you'll need to make sure you're utilizing this endpoint:

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

PROVIDER_NAME is the name you chose for your custom SAML provider in the Knack Builder. SAML providers require several options:

• Provider Entry Point: The SAML Entry Point address as given by your SAML Identity Provider Identity. Provider entry point where the SAML authentication request will be sent.

• Issuer (Issuer string to supply to Identity Provider): The Issuer String, as provided by your SAML Identity Provider. Name of this Service Provider to supply to the Identity Provider.

• Identity Provider’s Certificate: Optional Identity Provider Certificate. This allows you to sign your SAML requests with RSA-SHA1 certificates, used for validating responses from the Identity Provider.

• Private Signing Certificate: Optional Private Signing Certificate, used to sign your request. This allows you to sign your SAML requests with RSA-SHA1 certificates.

• Decryption Private Certificate: Optional private key that will be used to attempt to decrypt any encrypted assertions that are received from the Identity Provider.

• Decryption Public Certificate: Public certificate matching the decryption private certificate. Required if configured with a decryption private certificate.

• Authentication Context: Optional Authentication Context class to present to the Identity Provider.

• ID, First Name, Last Name, Email: These items are pre-filled with standard SAML assertions; change them to the correct properties for your assertion document as needed.

Additional Setup for SSO Setup

All custom SSO providers will need some additional properties set as well, so that a user’s information can be pulled from the remote authentication service:

• Profile URL (OAuth only): The URL where information about a user’s account can be retrieved. The Profile URL will be sent a GET request authenticated by the user’s token and will be expected to return a JSON object.

  • This is required. The following is an example object and will be used to explain the following fields:

{
  "id": 12345,
  "info": {
    "name": {
      "first": "John",
      "last": "Smith"
    },
    "email": "john.smith@knackhq.com"
  }
}

• ID property: The ID property of the JSON object provided by your provider’s Profile URL. In the object example, this would be given as "id". This is required.

• First Name property: The First Name property of the JSON object provided by your provider’s Profile URL. In the object example, this would be given as "info.name.first".

• Last Name property: The Last Name property of the JSON object provided by your provider’s Profile URL. In the object example, this would be given as "info.name.last".

• Email Address property: The Email Address property of the JSON object provided by your provider’s Profile URL. In the object example, this would be given as "info.email".

Notes & Troubleshooting

Everyone gets logged in as the same user regardless of credentials:

This usually means that one of the "property" values is not mapped out correctly in the Knack SSO provider setup. Please double-check that you've entered the right values for the "ID", "First Name", "Last Name", and "Email Address" properties.