This sample levarages Criipto Verify for signing documents.
To sign documents (text) on your own website(s), you will need 2 things:
- An
Criipto Verify
account (you can sign up for a free test account on criipto.com) - A small amount of work on your website
For the purpose of illustration, we'll pretend that this demo web app is your actual web site. You can use the guide below, and the contents of this repository, as a step-by-step guide to providing your actual website with signed agreements from your users.
Start by cloning the repository to your development box, and open the .sln file in VS 2015.
Press play (F5
) to start, and you are ready to try the signature flow.
Enter the text you would like to have signed in the input field.
Select the desired method for document signing in the dropdown, and the process starts by
a browser redirection to Criipto Verify
(potentially inside an iframe).
Criipto Verify
will then start and run the flow for the selected signature method, and when done,
Criipto Verify
will deliver the signed document back to your website.
Once delivered, you can use your designated JWT signature validation library to ensure that the
response did indeed come from your Criipto Verify
tenant, and you must validate that the text which was
signed matches what you asked Criipto Verify
to sign. This value is roundtripped by Criipto Verify
in the
signtext
property in the returned response.
You must store the raw response in your backend data store of choice, along with
the JWT signing keys which can be fetched from your Criipto Verify
tenant's OpenID Connect discovery endpoint.
That is required in case a user ever questions the validity of the agreement later on.
And that's all there is to it - your web site can now go ahead and proceed with whatever was agreed upon by the user.
You have 2 options for running the Criipto Verify
signature flow: You can either use
a full-blown browser redirection, or you can run it inside an iframe. This demo site let's you choose which one
to test - but beware (see below) that not all signature methods work with the iframed approch.
The first option (redirection) is the simplest way, and also the one with the broadest reach
(all signature methods supports this on all platforms). The second option (iframed) can be used with
most signature methods - except same-device Swedish BankId on most mobile operating systems (with Windows Phone 10 being a curious exception).
For an up-to-date view of the frame-able methods, check out the Criipto Verify
authentication demo site on GitHub
For a redirection-based integration, you can choose between two different delivery mechanisms for the resulting signed document:
- HTTP POST (the default): Result is sent to your backend for validation via an auto-submitting form.
- URL fragment: Result 'reference' is sent in the URL fragment (aka location hash), via a 302 Redirect from
Criipto Verify
. Add aresponseStrategy=urlFragment
query string parameter in the request toCriipto Verify
to use this delivery mechanism. You can then open an invisible iframe using the URL present in the fragment, which will trigger awindow.postMessage
event along the same lines as the iframe-based integration described below.Criipto Verify
does not support direct delivery of the result in a GET response, because in most cases, the size of the result would create a URL that exceeds the URL length limitations enforced by most browsers.
For iframe-based integrations, you have the additional option of the following delivery mechanism:
- DOM event: Result is made available in the browser via the
window.postMessage
API. Add aresponseStrategy=postMessage
query string parameter in the request toCriipto Verify
to use this delivery mechanism.
In any case, the signed document is delivered on a URL, or window, which is entirely under
your control. You have to pre-register the desired target URL in Criipto Verify
first, though, to avoid
phishing attacks (and the like) against your users. You can roundtrip dynamic state parameters through
Criipto Verify
by adding them to the query string.
This demo contains the code needed to get the signing process up and running on .NET 4.6.1.
But any platform that can validate asymmetrically signed Json Web Tokens can be used.
(for a very comprehensive overview of such libraries for various platforms, check out Auth0's
JWT.io).
The demo runs in IISExpress on port 44300, using the default-generated SSL certificate for localhost.
It is configured to run against the online test-and-development instance of Criipto Verify
, which, in turn,
has been set up to accept signing requests from https://localhost:44300
.
You can of course use your own Criipto Verify
tenant for this as well. In that case, you'll need to register
an application in Criipto Verify
with a proper returnUrl (value for this demo is https://localhost:44300/Signature/Done
),
and change the values of the following appSetting
entries in web.config
:
verify:tenantAuthority
verify:applicationRealm
The HTTP layer consists of a single controller: SignatureController
.
The controller handles the routing, which is not very advanced here, and uses the classes in
the easyIDSignature.cs
module to handle the interation with Criipto Verify
.
The SignatureController
has 3 action methods:
Text
(HTTP GET): Displays the landing pageText
(HTTP POST): Receives the designated text-to-sign, and the selected signature method. Starts the signing process withCriipto Verify
.Done
(HTTP POST): Receives the signed document fromCriipto Verify
, and does the validation. Check the comments in the code for further details - and please do send us a Pull Request if you have suggestions, or find that the documentation is lacking.
The easyIDSignature.cs
module wraps the details of .NET's JWT parsing and validation,
and the peculiarities of the different signature schemes supported by Criipto Verify
.
Expect quite a few nitty-gritty details if you decide to take a peek at it, but we
certainly encourage you to do so: If you are already familiar with OpenID Connect and JWT's, it
should contain no surprises. If not, we hope it can serve as a starting point for getting aqcuainted
with these matters.