Overview of JSON Signing and Encryption

EmpowerID’s REST-based APIs support the arbitrary signing and encryption of JSON content using the JSON Web Signature standard.

Controller actions designated with any one of [JsonWebSignature], [JsonWebEncryption] and [JsonWebSignatureEncryption] attributes and hosted in EmpowerID are assumed to support JSON signing and/or encryption.

The [JsonWebSignature] attribute signifies JSON signing only.
The [JsonWebEncryption] attribute signifies JSON encryption only.
The [JsonWebSignatureEncryption] attribute signifies JSON signing and encryption.

A controller action MAY NOT be decorated with more than one of the above attributes.

JSON Web Signature

A controller action expecting signed JSON requests should be decorated with the [JsonWebSignature] attribute in addition to any other action related attributes. The default API controller template in Workflow Studio includes an action decorated with this attribute.

[JsonWebSignature]
[HttpPost]
public IHttpActionResult GetUserJWS(InputModel model)
{
    var results = <results>;
 
    return this.Json((object)results);
}

To execute GetUserJWS successfully, the API request must be signed using the private key of the X509 certificate associated with the OAuth Provider Application in EmpowerID. An OAuth Provider Application in EmpowerID is typically identified by the APIKey specified in the header of the request. You may also override the GetJwsVerifyCertificate method in the API controller to ignore the certificate associated with the OAuth Provider Application and return a preferred certificate for the same purpose. The Workflow Studio API controller template generates the methods you may override.

Signing an API request

To sign an API request, call the Sign() static method on the TheDotNetFactory.Framework.JWS class and pass the JSON data and the X509 certificate. The sample code below assumes that the action, getuserjws, is decorated with the [JsonWebSignature] attribute.

The private key certificate is requiring to sign the JSON data passed to the Sign() method.

Client-side / Sender

X509Certificate2 signing = <your signing certificate>
string url = https://demoserver/api/ services/v1/Users/getuserjws;
string data = JWS.Sign(json, signing);
using (WebClient client = new WebClient())
{
    byte[] str = System.Text.Encoding.UTF8.GetBytes(data);
    byte[] results = client.UploadData(url, "POST", str);
    if (results != null)
        return System.Text.Encoding.UTF8.GetString(results);
    else
    return null;
}

Server-side / Action

[JsonWebSignature]
[HttpPost]
public IHttpActionResult GetUserJWS(InputModel model)
{
    var results = <results>;
 
    //JWS response
    return this.Json((object)results);
}

Encrypting an API request

To encrypt an API request, you can call the Jose.JWT.Encode() static method. The sample code below assumes that the action, getuserjwe, is decorated with the [JsonWebEncryption] attribute.

Client-side / Sender

Server-side / Action

Please note that the Jose.JWT.Decode() static method is called to decrypt the encrypted payload in an encrypted request; therefore, it is important that the encryption algorithm, encryption key, and the encryption key size are all correct and consistent with that of the sender. You must override the GetJWEDecryptionKey() method in the controller to return the encryption key. See the override method below.

IN THIS ARTICLE