Signature Gateway

We define a Signature Gateway as a mechanism by which, when the user of a web application must sign a document, he/she is redirected to a safe signature page. In that page the user will be able to view the document, as well as the signatures it already contains, and digitally sign (or reject) it.

(This mechanism is very similar to the way payment gateways work).

A simplified usage pattern of PortaSigma is as follows:

  • A user (issuer) creates one or more signature transactions by uploading several documents and choosing for each a list of desired signers

  • The signers receive a notification with a link to the document(s)

  • From the link, the signers connect to PortaSigma in order to view and sign or reject the document(s)

PortaSigma as a Signature Gateway

The scenario where PortaSigma acts as a signature gateway includes:

  • A web client application, that the user is browsing, and that will eventually lead him to a signature page

  • PortaSigma

PortaSigma acts as a container of signature requests. These may have been created manually in the PortaSigma site, or they may have been created by the client application, or even a third application that interacts with both (e.g. an ERP).

Once a signature request has been created by any of the described mechanisms, it can be accessed for signing. This may be done by accessing PortaSigma in the usual fashion, or as a gateway.

Gateway Operation

The gateway works as follows:

  1. The user is browsing the client application

  2. The client application offers the user the possibility to sign a document

  3. The client application redirects the user to PortaSigma, to the page corresponding with the signature request (that must already exist in PortaSigma) for this user. This redirect includes an additional parameter - the return URL

  4. PortaSigma authenticates the user by means of a user’s certificate, in order to verify that she has legitimate access to this signature request

  5. PortaSigma shows the signature page to the user, displaying the document and its signatures (if it is already signed by other users) as well as additional required signers.

  6. The user may choose to sign the document or reject the signature request

  7. PortaSigma redirects the user back to the client application, by using the return URL. A parameter with the result is appended to the URL (signed, rejected, error)

URL specification

Redirection to PortaSigma

There are two signature cases: * Signature with digital certificate * Signature with user/password

Both cases have the same methods, but for signing with digital cert the context URL is gateway and for signing with user/password is usergateway.

URL for a single signature request:

<ps-root>/<context>/sign.html?id=<id>&urlreturn=<urlreturn>&logout=<logout>

URL for multiple signature requests:

<ps-root>/<context>/sign.html?id=<id1>&id=<id2>&id=<id3>&urlreturn=<urlreturn>&logout=<logout>&view=<view>

Deprecated URL for a single signature request (do not use):

<ps-root>/request/view.html?id=<id>&url=<urlreturn>

Where:

Variable

Description

Examples

ps-root

Root URL for PortaSigma web application
https://app.portasigma.com
http://192.168.0.12:8080/portasigma

context

gateway for signing with digital certificate, or usergateway for signing with user/password
https://app.portasigma.com/gateway/sign or
https://app.portasigma.com/usergateway/sign

id

ID of the signature request (one signer of the document)
12
27

urlreturn

Return URL. It must be enough for the client application to fully identify this signature request and process the return value
http://myapp.com/notify/32-EE-245
http://server/afterSignature.do?ref=24

logout

Boolean indicating if a logout from PortaSigma has to be performed after the signature (optional, default false)
true
false

view

Boolean affecting only a multiple request URL, indicates whether the signature documents have to be revised by the signer or not. (optional, default true)
true
false

Warning: if your return URL contains several parameters (e.g. url?a=1&b=2) you will need to escape the & character so that it is not confused as a parameter to the signature gateway (escape code for & is %26). Same thing may apply to other characters, so it is a good idea to apply URL-escaping to your whole return URL. E.g. if your URL is http://xyz.com/return?x=12&y=ABC, the resulting gateway URL will be:

https://app.portasigma.com/gateway/sign.html?id=12&urlreturn=http://xyz.com/return?x=12%26y=ABC https://app.portasigma.com/usergateway/sign.html?id=12&urlreturn=http://xyz.com/return?x=12%26y=ABC

Redirection to the client application

The return redirection that PortaSigma will make will be via an HTTP GET to the return URL plus some additional parameters:

Parameter

Description

Values

status

State of the signature request

after the operation
signed: the user has signed all documents
rejected: the user has rejected at least one document

result

Operation result
success: signature or rejection executed correctly
accessDenied: the user attempted to acces the signature request but was not authorized
pageNotFound: the signature request was not found (invalid ID, or incorrect URL)

signed

Signed documents
Multivalued parameter with the IDs of the signed requests

unsigned

Unsigned documents
Multivalued parameter with the IDs of the unsigned requests

Examples, for different return URL:

http://myapp.com/notify/32-EE-245?status=signed&result=success
http://server/afterSignature.do?ref=24&status=rejected&result=success
http://server/afterSignature.do?ref=24&result=accessDenied