Skip to content

Integrating with HID via OAuth

Jump to bottom
Guillaume Viguier-Just edited this page Aug 22, 2017 · 17 revisions

As mentioned here, authentication of a client application with Humanitarian ID can be done via JSON Web Tokens or OAuth 2 / OpenID Connect. This page looks in details into the integration via the OAuth 2 / OpenID Connect, which is currently the most widely used method.

Web Standards

Humanitarian ID’s authentication service is built on OpenID Connect 1.0, an identity standard that layers on top of OAuth 2. If you are new to OpenID Connect or SSO integrations, the OpenID Connect FAQ is helpful.

Simple Authentication Process

This process relies on the OAuth Implicit Flow, a mechanism to grant access to users that minimizes exposure of secret keys. This is the preferred method for Javascript-based, browser-side applications where the request details for authentication might be exposed. This interaction facilitates logging a user into Humanitarian ID and identifying that user to your application for local authentication.

Request (https://auth.humanitarian.id/oauth/authorize)

You will begin the Authorization process by redirecting the user to the OAuth Authorization API with appropriate parameters. Let's walk through the process with an imaginary, previously registered application with the Client ID your-app-1. Issue an API Call to authorize the user with the following parameters:

  • client_id: The unique Client ID, in our example this is your-app-1.
  • redirect_uri: The redirect URI registered to your application. For a web application this should be an absolute URL. For a device application you will probably need to create a custom protocol handler, resulting in something like yourapp://authorized.
  • response_type: This is the parameter that instructs Humanitarian ID which authentication process you want to use. Specify “token” for the “Simple/Implicit” authentication process.
  • state: A random value generated for the request your application will receive in the response. Ensure this value matches before trusting the server response to avoid vulnerability to CSRF attacks.

Universal parameters

This parameter should be included with all requests. Even though we currently require a specific value for each of them, forwards compatibility with the evolution of Humanitarian ID requires these to be explicitly set in your client application.

  • scope: The specific set of access permissions being requested of the authentication service. This value should be specified as “profile”. In the future alternate scopes might be provided for different permissions to other services.

Example Request

Response

The service will verify your application and redirect the user to the next step, which might vary depending on the user’s status or whether the application has been used by this user before:

  • if the user is not currently logged into Humanitarian ID, they will be prompted to login on the Humanitarian ID site. If another application sends the user to HID to login, an existing session will be leveraged in lieu of requiring login credentials again.
  • if the user has never logged in with the client application before, they will be prompted to authorize the application to access their Humanitarian ID account.

Once these two steps are completed the user is redirected back to the original application, to the redirect_uri specified in the initial request. See the guide for details on the request back to the client.

Extra Secure Authentication Process

The “Extra Secure” authentication process uses the “Basic Flow” as described by OpenID Connect, which is built on the Auth grant flow in OAuth. This is the preferred authentication mechanism for server-based applications as it has an extra degree of security in the form of short-lived access tokens and the use of the client secret and JWT-encoded ID token that allows your application to actively check that the authentication being granted is correct and current for each interaction. See the Basic Flow Guide for details on integrating as an OAuth consumer.

Step 1 : Request Authorization Code

The authorization code is used to give the client application temporary access to interact with Humanitarian ID. It limits expose of the client secret.

Request (https://auth.humanitarian.id/oauth/authorize)

Issue an HTTP GET request to https://auth.humanitarian.id/oauth/authorize with the same parameter you would use on the Simple/Implicit Authentication Process. Replace the response_type value of ‘token’ with ‘code’ to trigger the “Extra Secure/Basic” authentication flow.

https://auth.humanitarian.id/oauth/authorize?response_type=code&client_id=your-app-1&scope=profile&redirect_uri=http://yourapp.example.com/oauthenticate&state=12345

In order to issue this request, add an Authorization header using your client secret as a Basic Authentication token.

Response

If successful, the user will receive an HTTP/1.1 302 response back to your specified redirect_url. In the query string you will receive an Authorization Code (code). This code should be stored by the client and used to request a short-time Access Token for use in further API calls.

## Step 2 : Request Access and ID Tokens

The next step is to use our Authorization Code to request temporary access to issue API calls. This extra step ensures that if somehow a specific API request is intercepted the credentials to replay the request will expire.

Request (https://auth.humanitarian.id/oauth/access_token)

The request for a new Access Token is submitted with a redirect uri that will eventually be used to redirect the client back to their ultimate destination. The token request is a synchronous action, we cannot move forward to Step 3 until after we receive and validate the response. There are 2 options to authenticate your client: either through the “Authorization” HTTP header, or through parameters added in the POST body.

Through the Authorization HTTP header:

POST /oauth/access_token HTTP/1.1
Host: auth.humanitarian.id
Authorization: Basic <client_id:client_secret(base64 encoded)>
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code&code=<Authentication Code>&redirect_uri=<redirect_uri>

Through the POST body:

POST /oauth/access_token HTTP/1.1
Host: auth.humanitarian.id
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code&code=<Authentication Code>&redirect_uri=<redirect_uri>&client_id=<Client 
ID>&client_secret=<Client Secret>
Clone this wiki locally