3rd party authentication

In Award Force, 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: the SAML module is only available to those with an Enterprise subscription

Enabling third party authentication

  1. Navigate to Settings > Users > Registration
  2. Select the Enable registration via 3rd party authentication checkbox from the 'Registration' area
    Screen_Shot_2020-12-03_at_10.02.57_AM.png
  3. Choose the channels you wish to allow in the '3rd party authentication' box
    Screen_Shot_2021-11-16_at_13.11.05.png
  4. Save 

Social authentication

Award Force 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. 

Screen_Shot_2020-12-03_at_10.06.27_AM.png

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 Award Force. 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 (Award Force) and the identity provider (your system).

Award Force 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 Award Force account via SAML will be provided the default role. For most programs this will be the entrant role. 

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

Setting up SAML

  1. 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
    Screen_Shot_2021-11-16_at_13.39.44.png
    Note: Award Force is not the identity provider.
  5. Save

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

Account linking

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

If the email already exists within Award Force, 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

Award Force 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 Award Force the first thing you’ll need to do is check whether they already exist in Award Force.

Get user by email 

Using the 'Get user by email' endpoint you can check whether the user exists by passing their email address to Award Force. If this endpoint returns empty then you’ll need to create the user in Award Force. 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@awardforce.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.awardsplatform.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.awardsplatform.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 Award Force. 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@awardforce.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.

Need more help? Get in touch!

Simply send us a message via this form and we will get back to you quickly!
Our globally distributed client success team are here to help 24 hours a day, Monday to Friday.