Entity API: Security Schemes | Janrain Education Center

janrain-signed

Our Registration API supports a custom HTTP scheme based on a keyed-HMAC (Hash Message Authentication Code) for authentication. Using this helps to protect against replay attacks, and ensures that client secrets are well protected.

APID Authorization Headers

Example Request


  GET /entity.find?type_name=user&filter=lastUpdated >= '2016-01-01'HTTP/1.1
  Host:training-pse.janraincapture.com
  Date: 2016-02-2619:08:44
  Authorization:Signature apkrahlfumwse2e9nvrrotv6vchuptzw:rRSudiGtMM5hEHYcwP49kt18jNk=

Signature

To generate the signature you will need the following:

The root-anchored API endpoint (for example /entity.find).
The parameters of the API call as key=value pairs, sorted alphabetically and separated by newlines (\n).
The date as specified in the Date header in your request.
Your client_secret.
Your client_id.

To generate the signature:

Concatenate the endpoint, datetime, and sorted parameters with newline characters ('\n'). This creates the string that we will sign.
Use the client_secret to sign the string using SHA-1, then base64 encode the result.
Prepend your client_id to this signature with a colon (:).

The resulting string is a signature that uniquely identifies a single request.

Below we have included a python implementation of the signed header request for further clarity and convenience:


importhmac
frombase64 importb64encode
fromhashlib importsha1
defmake_signed_auth_header(endpoint, params, datetime, client_id, secret):
    kv_params = ['{}={}'.format(k, v) fork, v inparams.items()]
    kv_params.sort()
    kv_string = '\n'.join(kv_params)
    str_to_sign = '{}\n{}\n{}\n'.format(endpoint, datetime, kv_string)
    hashed_str = b64encode(hmac.new(secret, str_to_sign, sha1).digest())
    return{'Authorization': 'Signature {}:{}'.format(client_id, hashed_str)}

For code examples in other languages, take a look at our sample code repo.

Authorization string

Used to send the authorization signature.

Example:

Authorization: Signature apkrahlfumwse2e9nvrrotv6vchuptzw:Pm0y2b8b/tH4HrEqKqSm7zQk1s8=

basic-auth

Our Registration API supports basic HTTP authentication using your application owner credentials. To create the authorization code, combine your client ID and secret like this client_id + ":" + secret, then base64 encode the result. Most RESTful frameworks support basic authentication natively.

Authorization string

Used to send the authorization code.

Example:

Authorization: Basic aW1fYV9saXR0bGVfdGVhX3BvdF9zaG9ydF9hbmRfc3Q6b3V0X2hlcmVfaXNfbXlfaGFuZGxlX2hlcmVfaXNfbXk=

janrain-oauth

Some of our Registration API endpoints support a custom variant of OAuth using access tokens. The following endpoints accept OAuth acccess token authentication:

Authorization string

Used to send the access token.

Example:

Authorization: OAuth SlAV32hkKG