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.
Enabling 3rd party authentication
- Navigate to Settings > Users > Registration
- Select the Enable registration via 3rd party authentication checkbox from the 'Registration' area
- Choose the channels you wish to allow in the '3rd party authentication' box
If you wish to disable the default Good Grants login, simply select the Disable login form on home page checkbox before saving.
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 for both registration and login as shown below.
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.
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
- Navigate to Settings > Users > Registration
- Ensure 'Enable registration via 3rd party authentication' has been enabled
- In the '3rd party authentication' box, select the SAML checkbox
- Key in the issuer, single sign-on service URL, and X.509 certificate from your identity provider
Note: Good Grants is not the identity provider.
- If desired, select the Encrypt SAML certificate checkbox and input your SAML certificate private key
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
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 ____.awardsplatform.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.
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) -
"name": "Test Name",
"en_GB": "Role name"
"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.
This will return a unique token you can use to sign the user into Good Grants. The example response -
Once you’ve got the token you can redirect the user to the following URL to automatically sign them in -
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 -
An example body -
"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.