Integrating with HID via OAuth
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.
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.
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.
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:
Set this value to profile. In the future alternate scopes might be provided for different permissions to other services, so for forward-compatibility you MUST send this parameter with all requests.
The unique Client ID, in our example this is your-app-1.
One of the redirect URIs 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. Please note that using redirect_url with the lowercase letter "L" on the end is incorrect. It must be URI with an "i".
This is the parameter that instructs Humanitarian ID which authentication process you want to use. Specify token for the “Simple/Implicit” authentication process.
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.
A number you send to HID once and only once. Sending this parameter reduces the possibility of replay-attacks (that is, if someone intercepted your authentication request, used it, then sent your request along as if nothing happened). Your system must manage the transmission and reception of unique nonce values, and react accordingly. It will become part of the hash when users are redirected back to your application. Random strings, millisecond timestamps, or incrementing integers can all be easy source of nonce data.
Be sure to properly escape all of these parameters, especially if you're using any URI reserved characters: !*'();:@&=+$,/?#[]. It does not affect anything negatively when you encode non-reserved characters, so the safest solution is to simply encode all parameter values.
- Website Authentication Request: https://auth.humanitarian.id/oauth/authorize?response_type=token&client_id=your-app-1&scope=profile&redirect_uri=https://yourapp.example.com/oauthenticate&state=12345
- Native Application Authentication Request: https://auth.humanitarian.id/oauth/authorize?response_type=token&client_id=your-app-1&scope=profile&redirect_uri=yourapp://authorized&state=12345
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 OpenID guide for details on the request back to the client.
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.
The authorization code is used to give the client application temporary access to interact with Humanitarian ID. It limits expose of the client secret.
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
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.
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.
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>
The response is a compound JSON object that contains the access token and a JWT-encoded ID token as specified in the OpenID Connect specification. The ID Token contains various details on the terms of access and should be verified as an extra step to validate the authenticity of the remote server.
The Access Token itself is used to sign further API calls on the authority of Humanitarian ID. The example below comes from the Basic Integration Guide.
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache
{
"access_token":"SlAV32hkKG",
"token_type":"Bearer",
"expires_in":3600,
"refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
"id_token":"eyJ0 ... NiJ9.eyJ1c ... I6IjIifX0.DeWt4Qu ... ZXso"
}
The User Account API allows you to pull information about the currently authenticated user. Humanitarian ID uses the Access Token to identify the user, confirm the client’s permission to access this API, and then returns the information the client needs to automatically authenticate the user on it’s end.
The access token should be sent using the Authorization HTTP header. Here is an example cURL command:
curl \
--request GET \
--url https://auth.humanitarian.id/account.json \
--header 'Authorization: Bearer TOKEN_GOES_HERE'The core account info for the user. It is up to the client application to maintain suitable mappings between its local identifier system and the information held by Humanitarian ID. However, the attribute that MUST be used in order to keep compliance with the OpenID Connect protocol is the “sub” attribute (see https://openid.net/specs/openid-connect-basic-1_0.html#IDToken ).
{
email: "[email protected]",
email_verified: true,
given_name: "Joe",
family_name: "User",
sub: "6c2ab0472f95f51ab358d92f"
}
- The OpenID Connect websites maintains a list of libraries and plugins that can help you integrate with the Authentication service. Some of these libraries are for providing an authentication service so read the description with care.
- If you need to integrate Humanitarian ID with a Drupal 7 website, you can very easily use the HybridAuth module, which provides integration with Humanitarian ID out of the box (refer to the quickstart
- JSON Web Token (JWT) debugger and integration information: http://jwt.io/