Redox Source Auth v2

Redox Source Auth 2.0 uses the Smart Backend Services Authorization Guide, which in turn is based on RFC6749, The OAuth 2.0 Authorization Framework, and RFC7523, JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants. The following articles will introduce you to the concepts behind those standards, and how to use it in Redox.

Depending on when you made your Source, you may see an option to upgrade, once you upgrade there will be a grace period where the old Auth method still works.   

When you are off of Legacy Auth – you will see new options to pick the signing algorithm.

HS384

HS384 works much like Legacy Auth. You still have an API key and a Secret, except the secret is used to sign the request, rather than being transmitted as part of the request.  

RS384/ES384

RS384/ES384 relies on certificates to sign the request. This method is preferred to HS384 because Redox only needs to keep your public key on file.

There are two ways to share your public key:

    1. By exposing a JSON Web Key Set URL (JWKS). This is the preferred option because it allows you to rotate keys at will.
    2. Manually pasting public keys into the Redox Dashboard

Part 2 Creating a Token Request

Once your source is configured, you need to craft a token request, sign it, and send it to Redox.

https://jwt.io/ has a centralized list of SDKs available. Make sure you find one that supports “Sign” and the algorithm of your choice (HS384, RS384, or ES384).

Authentication JWT Header
    • alg (required) The JWA algorithm (e.g., `RS384`, `ES384`, `HS384`) used for signing the authentication JWT.
    • kid (required for RS384/ES384) The identifier of the key-pair used to sign this JWT. This identifier SHALL be unique within the client’s JWK Set.
    • typ (required) Fixed value: JWT.
  • jku (optional, only applies to RS384/ES384) The URL to the JWK Set containing the public key(s). When present, this should match the url in the dashboard.
Authentication JWT Claims
    • iss required Issuer of the JWT — the client’s client_id, as presented in the Source dashboard (note that this is the same as the value for the sub claim)
    • sub required The service’s client_id, as presented in the Source dashboard (note that this is the same as the value for the iss claim)
    • aud required Redox’s “token URL” (the same URL to which this authentication JWT will be posted — https://api.redoxengine.com/oauth/token)
    • exp required Expiration time integer for this authentication JWT, expressed in seconds since the “Epoch” (1970-01-01T00:00:00Z UTC). This time SHALL be no more than five minutes in the future.
  • jti required A nonce string value that uniquely identifies this authentication JWT. This value may be a unique ID to audit the request in your system.  
Post Parameters

After generating an authentication JWT, you will request an access token via HTTP POST to the Redox authorization server token endpoint URL, using content-type application/x-www-form-urlencoded with the following parameters:

    • scope required The scope of access requested. See note about scopes below
    • grant_type required Fixed value: client_credentials
    • client_assertion_type required Fixed value: urn:ietf:params:oauth:client-assertion-type:jwt-bearer
    • client_assertion required Signed authentication JWT value (see above)

https://api.redoxengine.com/oauth/token is the token URL.

POST /oauth/token HTTP/1.1
Host: api.redoxeninge.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&scope=redox:/Subscription/12345&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&client_assertion=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzM4NCIsImtpZCI6ImVlZTlmMTdhM2I1OThmZDg2NDE3YTk4MGI1OTFmYmU2In0.eyJpc3MiOiJiaWxpX21vbml0b3IiLCJzdWIiOiJiaWxpX21vbml0b3IiLCJhdWQiOiJodHRwczovL2F1dGhvcml6ZS5zbWFydGhlYWx0aGl0Lm9yZy90b2tlbiIsImV4cCI6MTQyMjU2ODg2MCwianRpIjoicmFuZG9tLW5vbi1yZXVzYWJsZS1qd3QtaWQtMTIzIn0.l2E3-ThahEzJ_gaAK8sosc9uk1uhsISmJfwQOtooEcgUiqkdMFdAUE7sr8uJN0fTmTP9TUxssFEAQnCOF8QjkMXngEruIL190YVlwukGgv1wazsi_ptI9euWAf2AjOXaPFm6t629vzdznzVu08EWglG70l41697AXnFK8GUWSBf_8WHrcmFwLD_EpO_BWMoEIGDOOLGjYzOB_eN6abpUo4GCB9gX2-U8IGXAU8UG-axLb35qY7Mczwq9oxM9Z0_IcC8R8TJJQFQXzazo9YZmqts6qQ4pRlsfKpy9IzyLzyR9KZyKLZalBytwkr2lW7QU3tC-xPrf43jQFVKr07f9dA

Sample Node.js implementation


'use strict';
const fs = require('fs');
const jwt = require('jsonwebtoken');
const uuid = require(‘uuid’);
var privateKEY  = fs.readFileSync('./private.key', 'utf8');
var publicKEY  = fs.readFileSync('./public.key', 'utf8');

/*
====================   JWT Signing =====================
*/
var payload = {
};
var signOptions = {
issuer:  “my_client_id”,
subject:  “my_client_id”,
audience:  “https://api.redoxengine.com/oauth/token”,
jwtid: uuid.v4()
expiresIn:  "5m",
algorithm:  "RS384"   
};
var token = jwt.sign(payload, privateKEY, signOptions);
console.log("Token :" + token);
Response

The response from the token URL will be either a 200 response with an access token, expiration time, and other metadata or an error.

 

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
 “access_token”: “eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c”,
 “token_type”: “bearer”,
 “expires_in”: 300,
 “scope”: “”
}

 

Error Responses will always be 400 response per RFC 6749.

HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

 

{
“error”:”invalid_request”
}


Error messages are intentionally sparse, to prevent disclosing information to potential attackers. Contact Redox support for troubleshooting.

In the event your application receives a response other than 200 or 400, the calling code should wait a few seconds and retry.

Part 3 Making Requests to Redox

Requests to Redox work the same as before. Specifically, use an Authorization header with the string “Bearer “ including a space, followed by the token obtained from the auth server. See RFC 6750.  

POST https://api.redoxengine.com/endpoint
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c