Skip to content

Requesting an OAuth client secret

Jump to bottom
Chris Ruppel edited this page Jul 1, 2020 · 5 revisions

As mentioned in this page, if you want to integrate your application with Humanitarian ID via OAuth 2 / OpenID Connect, you will need to request a client ID and secret from us. This can be done very easily by sending an email to [email protected].

Here is the information we will need from you:

  • Acknowledgement that you have read the Code of Conduct and that your use of this service will comply to the best of your ability with these guidelines.
  • Name of your site or application. This will need to be recognizable so H.ID users can identify and authorize your application.
  • What is the purpose of your application ? How does it relate to humanitarian work ?
  • Technology used by your application (Drupal, ASP, Node etc...)
  • Unique Base URL for the application to verify ownership and clarify the distinction between similarly named applications.
  • Login URL: The URL on the client site that triggers a login via H.ID authentication. This is used for our information only.
  • Redirect URL: The URL on the client site where the user is returned after authenticating on H.ID.
  • LastPass Email: we only share client secrets via secure notes in LastPass. If you do not already have an account, please create one, it's a free service.

⚠️ Note that the production environment of your application MUST use SSL (HTTPS) in order for your application to be accepted. If you are requesting a separate secret for local development, we will allow non-HTTPS Redirect URL values.

⚠️ Due to the nature of OAuth, you MUST request configuration on a per-URL basis. That means your production, staging, dev, and even local environments must all have their own OAuth secrets issued by the team. Your development team may choose to share the config for local environments (provided that all team members can settle on one local URL that they all use). There is no limit to how many OAuth clients you can request.

Example request

For the YourApp.example.com application the following might be provided.

Our Response

Based on your request we will generate and send you a two-part API Key.

  • Client ID: The "username" of the client application.
  • Client Secret: The "password" of the client application.

Safe Practices with the Client Secret

The Client Secret is provided for server-side API calls and debugging. If you embed it in client-side code it could be intercepted and your application's identity forged for API calls to Humanitarian.ID.

Example Response

Coming back to our YourApp.example.com example here is the information provided:

  • Client ID: yourapp
  • Client Secret: l91643whK068FkPwEW40SW1478rDc4wb

How to receive a client secret via LastPass

In Humanitarian ID all secrets for authentication clients are shared via LastPass. In order to accept a password share you will need to complete all of the following steps:

  • create a free account, install the browser plugin, and log in via the browser plugin.
  • Once you’ve done this, you can share the email you used to create the account with the Humanitarian ID team to receive the client-ID and secret as a secured shared note.
  • As by the requirements from OICT we only share secrets via LastPass as this is a free service. Unfortunately, we do not support other password sharing services.
Clone this wiki locally