Authentication API: Security Schemes

 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:

1. Concatenate the endpoint, datetime, and sorted parameters with newline characters ('\n'). This creates the string that we will sign.
2. Use the client secret to sign the string using SHA-1, then base64 encode the result.
3. 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

Responses

basic-auth

Several of the Authentication API endpoints support 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

none-required

The following Authentication APIs don't require authentication:

• /oauth/auth_native
• /oauth/auth_native_traditional
• /oauth/forgot_password_native
• /oauth/link_account_native
• /oauth/register_native
• /oauth/register_native_traditional
• /oauth/unlink_account_native
• /oauth/update_profile_native
• /oauth/verify_email_native

However, to call these endpoints your request must include a token and the client ID of a login client. See the individual endpoint documentation for more information.