Table of Contents

Single Sign-On with Google, Facebook, Twitter, and Custom

Lesley Updated by Lesley

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:

image alt text

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.

Each service has different methods for setting up an app and obtaining these credentials:

Google

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

2018-12-07_17-24-03.png

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

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

These URLs must be identical to the URL that is in the browser that initiates the login. It is also important that both Redirect and Origin URLs use the same domain/sub-domain. Please make sure to replace any knack.com domain with knackhq.com.

This will generate a Client ID:

image alt text

You will need to copy and add to your Knack credentials.

The user's name and email address will be automatically added to the new user's record based on the information on their Google account.
The user role will be automatically assigned to the user based on the user roles 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.

Facebook

A Facebook app must first be created in 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:

image alt text
The user's name and email address will be automatically added to the new user's record based on the information on their Facebook account.
The user role will be automatically assigned to the user based on the user roles 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.

Twitter

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:

image alt text

Notes:

  • Make sure you enter your Callback URL when setting up your app or the login will not work.
  • Twitter does not return an email address from their service. The user will need to enter their email after they authenticate with Twitter.
  • If the user already has an account they should still be able to use the SSO options, but only if the emails are the same. If their Google or Facebook email is different then a new account will be added.
  • If you require users to fill out multiple fields to register for access, new users will be directed to the registration form after logging in with an SSO option.
  • The user role will be automatically assigned to the user based on the user roles 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.

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 role in knack before giving them access to the app

Domain Restrictions

Both the Google and OpenID SSO providers have an 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-ons. 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-ons. 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 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.
SAML requests currently only allow SP initiated logins (from the Knack-generated login screen) and not IDP initiated logins. When testing, if you see a 'Cannot GET' error that includes a URL ending with '/undefined', this is likely the reason why.

Additional Setup for SSO Setup

All custom SSO providers will need some additional properties setup 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. 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". 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".
Properties are case sensitive and need to be added as given by your SSO provider. For example, if you have an ID property of "nameID", using "NameID" instead will not allow a successful login.

Notes & Troubleshooting

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

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

There's no way for Knack to tell what the actual properties are; you will need to ask your network administrator for further assistance.

How did we do?

Manage Roles & Permissions

Manage User Records

Contact