3rd party authentication

In Good Grants, you can enable 3rd party authentication as a way of allowing users to register and log into your program using external accounts. While this most commonly employs social media authentication through networks like Facebook or Twitter, your organisation can also use SAML or single sign-on. 

Important: only social authentication is available on the Intro plan. Access to the SAML module is only available to those with a Premium subscription as an add-on and comes included in Enterprise. To view our plan offerings, see our pricing page

Enabling 3rd party authentication

  1. From the Manage workspace, navigate to Settings > Users > Registration
  2. Select the Enable registration via 3rd party authentication checkbox from the 'Registration' area
    Enable registration via 3rd party .png
  3. Choose the channels you wish to allow in the '3rd party authentication' box
    3rd party authentication.png
  4. Save 

If you wish to disable the default Good Grants login, simply select the 3rd party authentication only checkbox before saving.

3rd party authentication only.png

Social authentication

Good Grants supports social authentication through Facebook, Twitter, WordPress/Drupal, Google, and LinkedIn. Simply follow the steps outlined above to enable registration and login for users through these channels. Once the selections have been saved, the social buttons will appear on your program's home page as shown below. 

Log in with social authentication options

On the first login via social authentication, the user will be redirected to a login or confirmation screen of the social network provider to verify their identity. During this process they may be presented with a consent screen outlining which details the social network provider will share. This consent is generated by the social network provider, not Good Grants. If the user does not wish to agree to the settings, they can simply cancel the process and register as normal.

Important: WordPress is only available when using WordPress.org combined with the installation of our plugin. Please refer to this help article for step-by-step instructions. 

SAML authentication

SAML stands for Security Assertion Markup Language and is a standard single sign-on (SSO) format -- essentially exchanging authentication and authorisation data between parties. In SAML, these parties are referred to as the service provider (Good Grants) and the identity provider (your system).

Good Grants supports both service provider-initiated login, (e.g. a button on the login screen of your platform) and identity provider-initiated login (e.g. a button placed on your intranet or another private site). Users that register for an Good Grants account via SAML will be provided the default role. For most programs this will be the applicant role. 

SAML is an optional add-on for your account. For more information and pricing, please get in touch.

Setting up SAML

  1. In the Manage workspace, navigate to Settings > Users > Registration
  2. Ensure 'Enable registration via 3rd party authentication' has been enabled
  3. In the '3rd party authentication' box, select the SAML checkbox
  4. Key in the issuer, single sign-on service URL, and X.509 certificate from your identity provider
    SAML checkbox in 3rd party authentication.png
    Note: Good Grants is not the identity provider.
  5. If desired, select the Encrypt SAML certificate checkbox and input your SAML public certificate or SAML certificate private key
  6. Save
Important: some identity providers, such as Microsoft Azure, require the information from the service provider before a certificate can be generated. In this case, you can use the following:

Identifier (Entity ID): https://<account url>/saml/metadata

Reply URL (Assertion Consumer Service URL): https://<account url>/saml/callback

The next steps will vary greatly based on your desired provider, and your IT team will likely need to be involved in the configuration, but the key facts to know are:

  • The provided name IDs should be persistent

  • The integration requires three attributes ('firstName', 'lastName', and 'email') to be present in the authentication response in order to create accounts for users authenticating with SAML

    Important: these attributes must be configured within your identity provider and match exactly. 

Account linking

The SAML response from the identity provider contains an email attribute, which is used to check if an account already exists within Good Grants. If it doesn't, a new account is created for the user.

If the email already exists within Good Grants, there's an additional step that allows the user to link their existing account with their SAML identity. The user will simply need to input the code that has been emailed to them. For security purposes the code expires in 10 minutes, but can be regenerated if necessary. If a new code is generated, the previous code is voided.

Service provider metadata

Once set up is complete, you will see a link under 'Service provider metadata' at the bottom of the Integration tab in your account. Clicking the link will open an XML file in a new tab.

The metadata contained in the XML file is unique to your account. The file contains some details which may be useful for future references, such as entityID URL and the Reply URL (also referred to as the Assertion Consumer Service (ACS) URL). The required attributes: firstName, lastName, email can also be found in the metadata.

The Reply URL always takes the format: https://your_account_URL/saml/callback where 'your_account_URL' will be ____.grantplatform.com or your custom domain if one has been configured.

Creating your own SSO integration

Good Grants supports social authentication, WordPress SSO, and SAML, however you may using different technologies and want to build your own integration. This is possible with our API. 

When a user on your platform wants to sign into Good Grants the first thing you’ll need to do is check whether they already exist in Good Grants.

Get user by email 

Using the 'Get user by email' endpoint you can check whether the user exists by passing their email address to Good Grants. If this endpoint returns empty then you’ll need to create the user in Good Grants. If the user does exist then this endpoint will return the slug which you can use to generate an auth token.

https://api.cr4ce.com/user/:email

Here’s an example response you’ll get if the user does exist (the slug, which you'll need for the next step is highlighted below in bold) -

{

  "analytics_cookies": false,

  "broadcast_emails": false,

  "confirmed_at": "2020-01-01T00:00:00Z",

  "created_at": "2020-01-01T00:00:00Z",

 "email": "no-reply@goodgrants.com",

  "first_name": "Test",

  "last_name": "Name",

  "marketing_cookies": false,

  "mobile": "+393216549873",

  "name": "Test Name",

  "necessary_cookies": false,

  "notification_emails": false,

  "notification_sms": false,

  "preferences": {

    "broadcast_emails": false,

    "notification_emails": false,

    "notification_sms": false

  },

  "roles": [

    {

      "slug": "OkvJXMNd",

     "link": "https://api.grantplatform.com/role/OkvJXMNd",

      "name": {

        "en_GB": "Role name"

      }

    }

  ],

  "slug": "EnDNqjlb",

  "social_sharing": false,

  "updated": "2020-01-01T00:00:00Z",

  "user_fields": [

    {

      "slug": "ErApVaqk",

     "link": "https://api.grantplatform.com/field/ErApVaqk",

      "label": {

        "en_GB": "Field label"

      },

      "value": "Field value"

    }

  ]

}

Get auth token

Once you’ve got the user slug you can request an auth token by making a request to the 'Get auth token' endpoint.

https://api.cr4ce.com/user/:slug/auth-token

This will return a unique token you can use to sign the user into Good Grants. The example response -

{

  "auth_token": "sKBO8pXpyd2R5FPssDP3CePlmH5OVTxj"

}

Once you’ve got the token you can redirect the user to the following URL to automatically sign them in -

https://[ACCOUNT_DOMAIN]/login?token=[TOKEN]

Create user

If the user doesn’t already exist on the program you can use the 'Create user endpoint' to create an account for them. You will need to submit a first name, last name, email address, and password as a minimum. 

The request is made to -

https://api.cr4ce.com/user

An example body -

{

    "first_name": "Test",

    "last_name": "Name",

    "email": "no-reply@goodgrants.com",

    "password": "123456789123",

    "mobile": "+393216549873",

    "roles": ["OkvJXMNd"],

    "preferences": 

    {

        "broadcast_emails": false,

        "notification_emails": false,

        "notification_sms": false

    },

    "user_fields":

    {

        "QVgKEqXR": "Field value"

    }

}'

The user's slug will be included in the response header which you can then use to generate an auth token.

For more information about our API, please refer to our API documentation.

Was this article helpful?
0 out of 0 found this helpful

Articles in this section