Quickstart on how to integrate with HID Auth

HID gives you the possibility to integrate your site with 2 different technologies:

1. OAuth 2 / OpenID Connect
2. JSON Web Tokens

Using OAuth 2 / OpenID Connect

If you want to use OAuth 2 / OpenID Connect, you will need the following information:

• OAuth client ID and secret: if you do not have one, you will need to request one
• Authorize URL: https://auth.humanitarian.id/oauth/authorize
• Access Token URL: https://auth.humanitarian.id/oauth/access_token
• User profile URL: https://auth.humanitarian.id/account.json

For help on understanding how OAuth 2 / OpenID Connect works, see this page.

Using JSON Web Tokens

The API endpoint for JSON Web Tokens is the following: https://api.humanitarian.id/api/v2/jsonwebtoken. More information about this endpoint can be found in the HID API documentation, available here. Also, you will find more information about JSON Web Tokens in general at https://jwt.io.

Integrations

Below are recommended ways to integrate Humanitarian ID with different platforms.

Drupal 7

The recommended way to integrate Humanitarian ID with a Drupal 7 site is using the Hybridauth module and library, using the latest version of the Hybridauth library v2.

After requesting the client ID and secret by emailing info@humanitarian.id, use the following steps:

1. Download the hybridauth module (use the dev version of the module or its latest stable version with this patch: https://www.drupal.org/files/issues/hybridauth-hid_integration-2717831-1-7.patch) in sites/all/modules/hybridauth and the library in sites/all/libraries/hybridauth
2. Move the file sites/all/libraries/hybridauth/additional-providers/hybridauth-humanitarianid/Providers/HumanitarianId.php in sites/all/libraries/hybridauth/hybridauth/Hybrid/Providers
3. Install the hybridauth module in your Drupal site
4. Check HumanitarianId in the list of Authentication providers
5. Under Settings, enter your client ID in Application ID and your client secret under “Application consumer key” and “Application consumer secret” and click “Save configuration”

Leave the rest of the settings untouched. This should allow you to get a working Humanitarian ID login button next to your Drupal login form.

If you want Humanitarian ID to become the ONLY way to log into your site, you will need to create a custom module to:

1. Disable the Drupal login form, user registration and password reset
2. Create a Login link in your site to point directly to the HID login method

Here is an example of code you could write to achieve this: https://gist.github.com/guillaumev/e4568fd9430b23cced92d1d592eb8b3c

Finally, this is not required, but if you want to avoid seeing the “Closing…” message while a user is logging in, make sure you:

1. Apply this patch to the hybridauth module: https://www.drupal.org/files/issues/2420167-hybridauth_closing-7.x-2.15.patch
2. In the hybridauth HID settings, set the “Authentication window type” to “Current window”

Drupal 8

The recommended way to integrate with a Drupal 8 website is to use the Social Auth HID module: https://drupal.org/project/social_auth_hid. Download and install the module, and insert your client ID and secret.

Auth0

See this page for how to integrate HID with Auth0.

Custom PHP

You will find a repository with an example client integration in PHP here.

Javascript and NodeJS

You will find a repository with an example client integration in Javascript, using the NodeJS framework here.