Passwordless Access to Broadbean's API
This page documents how we implement Passwordless access to the AdCourier system.
The method involves signing requests to allow us to verify that the sender is trusted.
The system provides third parties with a private encryption token linking it to an AdCourier company that is used to generate a signature.
This signature allows access without the need to supply a password.
The signature is generated using the encryption token to create a hash of a signature message composed of the AdCourier Username, the time the signature was generated (measured in ms since the epoch) and the API Key of the party who are generating the signature.
The encryption token is tagged to a unique combination of API Key and the Company identified by the AdCourier username the access is requested on behalf of.
External Setup (AdCourier URLs)
To implement a call to an AdCourier page that allows Passwordless login the integrator should use the URL they wish to access (including any configuration parameters they wish to supply).
They should then append four additional parameters to that URL:
- username - the Broadbean username that they wish to access AdCourier as
- time - the time in milliseconds since January 1st 1970
- signature - A SHA256/HMAC message digest encoded with the shared encryption token
- api_key - The integrator's API Key
The message body that should be encrypted for the signature parameter should be: username|time|api_key
Most programming languages will have readily available libraries implementing the required hashing algorithms that allow the message body and encryption token to be passed in and which return the required signature hash. This should be returned as a hexidecimal string without any modifications.
The same username, api key and time should be supplied in the additional parameters as the ones used to generate the signature body.
Please ensure that the base URL you wish to connect to is accessible by the username you request Passwordless access for.
The signature should be generated in exactly the same fashion as the one used for AdCourier URLs (see above).
To supply the signature to our API the node in the container should be replaced with:
<Signature> <Hash>f71a9eeb6c8e7709aef2dcfc0725ca35ab38687b36f4fb6feeee124bf4dac79c</Hash> <Time>1395834265000</Time> </Signature>
Checking the digest produced by your encryption libraryIf you used a message body of testmessage
And used an encryption key of: 123456789
It will generate this signature: 9cba4d1d75689509208a97b1ca42f786a630a891e2410bfb11a84feb7a4807ad
One common issue with tokens is that the clock on the machine the token is generated on is not correctly set.
As the signature auth tokens have approximately 5 minutes of validity a machine with a clock running 5 minutes or more slow can never generate a valid token.
For this reason we would recommend ensuring the machine clock is kept correct.
This will be a matter for your Systems administration team.
http://www.ntp.org/ may be of help here.
- The encryption token should *never* be supplied in the URL un-encrypted.
- The signature parameter should appear as a 64 character alphanumeric string with all lower case letters.
- The authentication digest will be valid for around 5 minutes from the time supplied.
- Authentication times in the future are invalid and will be rejected.
- The digests cannot be stored - they must be created on demand.
- If the encryption token is compromised you should inform Broadbean immediately and you will be issued with a new token