Signature Service API
Version 2
Introduction
The MobilityGuard OneGate is a server platform that handles many kinds of strong authentication, and controls access and single sign-on to internal and external systems. The MobilityGuard signature service is also a part of the OneGate platform and can be used by third party applications to create digital signatures.
This document specifies the API that can be used by such applications (in this document referred to as the “requesting application”). The signatures are usually performed using electronic ID’s of some sort, e.g. digital certificates normally issued to individual users. Depending on the type of electronic ID different signing mechanisms are used, with either client or server based software performing the actual signature operation.
The MobilityGuard signature service handles several different signing methods and the main benefit for applications to use this API is to leave the details regarding the signature to the signature service.
Changes from version 1
One of the main features of the OneGate server is the reversed proxy function that allows organizations to publish applications on the inside of the organizations' network securely on-line. In the first version of the API it was assumed that all requests from the client to the requesting web application were proxied through the OneGate server. In version 2 of the API, changes have been made to allow any application to use the signature service, whether they are accessed directly or placed behind the OneGate server.
Roles
The following section describe the different roles involved in the signing procedure.
Requesting application
The application that holds the information that should be signed. The requesting application creates a signature request containing the data to sign and other information about how the signature should be performed. The requesting application must also handle the resulting signature for storage.
Signature service
The OneGate signature service handles the signature request and initiates some signature method. For signature methods require interaction with the user or the signature client, the service also contains a front-end for the user agent. The service handles the resulting signature, performing validity and certificate revocation checks and returns the resulting signature to the requesting application. It may also check the signing certificate so it belonged to the anticipated person. The signature service does normally not archive any signatures and only keeps logs of the signature operations.
Signature backend / revocation service
Depending on the signature method, the signature service will be using different backends. Some backends handle the actual signing, either by communicating with the client application containing the certificate via a side channel (BankID RP and Telia RP) or by actually creating the signature itself (as is done in the eID 2.0 central signature service). In other cases the signing operation is done in a client directly communicating with the OneGate server (like a browser plug-in) and the third party is only used to validate the signature or revocation status of the certificate.
API Overview
This API uses SOAP web services as the interface for the requesting application but also handle requests directly from the client to allow any signature method to be used without changes in the requesting application.
This is an example of a typical signing process:
-
The user chooses to sign by clicking a button in the requesting web application
-
The requesting application calls the “Sign” method of the SOAP API
-
The signature service responds with an orderRef value and a redirect URL
-
The application redirects the user to the redirect URL attaching the orderRef parameter
-
The web browser sends the request containing the orderRef parameter to the URL
-
The OneGate web frontend handles the request and handles the signature process. N number of steps, sometimes including user authentication or letting the user select signature method.
-
The OneGate server sends the user a redirect back to the requesting web application
-
The user makes a request to the requesting application.
-
The requesting application calls the “Collect” operation of the SOAP API
-
The OneGate sends the result of the signing process
-
The requesting application might display a message to the user, either something like “Signature process complete” or “An error occurred, try again?”
Figure 1 API overview
After the requesting application has called the “Sign” method, the order to sign is valid for a certain amount of time, normally 10 minutes. After that time, the user cannot complete the signature. After another 5 minutes, the signature request and response are removed from the signature service and cannot be collected by the requesting application.
SOAP API
The signature consists of a SOAP API that can be used by relying parties. The definition of the SOAP API is available here:
https://eidt.funktionstjanster.se:18898/SignService?wsdl
Methods
| Method Name | Description |
|---|---|
| Sign | Add a signature request to the service |
| Collect | Check for signature result |
Method “Sign”
The Sign method is used to add a signature request to the signature service that can be retrieved when the client connects to the OneGate server.
Method “Sign” Parameters
| Parameter | |
|---|---|
| requesterId | Mandatory. The ID of the requesting application. This corresponds to a signing client configuration in the sign service configuration. |
| policyId | Optional. ID of the configuration to use. If not specified the default policy of the signservice will be used. See below. |
| transactionId | Mandatory. Used for tracking the session. See below. |
| returnUrl | Mandatory. Used for redirecting back to requesting application. It must be an URL containing the protocol scheme used, ex. https://myapp.com |
| signerInfo | Information about the signer. See below. |
| userVisibleData | The text to be displayed and signed. Must be UTF-8 encoded, the value must be Base64 encoded. (Max 40.000 characters after Base64 encoding). The text can be formatted using CR=new line, LF=new line and CRLF=new line. |
| userNonVisibleData | Data that is not displayed to the user at time of signature computation. The value should be Base64- encoded. (max 200.000 characters after Base64-encoding) |
| endUserInfo | Information about the client (like IP address) |
| fileReferenceId | Reference to an external file containing TBS (for future use, should not be set) |
| fileMetadata | Metadata of an external TBS file (for future use, should not be set) |
PolicyId
It is possible to select a configured policy by specifying a policy ID in the signature request. For a list of available policy ID:s, see documentation for the specific installation. If a policy is not specified, a default policy will be selected.
TransactionId
Used for tracking the transactions regarding a user signature session. Should be a base64 string with at least 64 bit entropy. The transactionId is returned in the response and should be reused for all transactions regarding the same user session. Please note that the transactionId may in turn be sent in third parties like validation backends, so it should not be used as a session key or in any way be considered a secret.
SignerInfo
Depending on the signature method and policy this may be used to initialize the signature process. For example, the BankID signature process can be started for a specific citizen without asking the user for a personal number. If this value is specified and the user is already authenticated with another personal number error code SIGNER_MATCH_FAILED will be returned.
For other signature methods the specified attributes are used to make sure that the correct signing certificate was used. If the service detects that the wrong certificate was used a SIGNER_MATCH_FAILED error will also be returned.
| Special keys used | Used for |
|---|---|
| 1.2.752.29.4.13 | Swedish “personnummer”. BankID RP/ Telia RP: Initializing signature process for the person with the specified personal number. (The OID used is from the eID 2.0 specification). |
| (Other) | Other attributes will be checked against values of those attributes of the subject of the signing certificate. |
Method “Sign” return values
| Return parameter | |
|---|---|
| transactionId | Same string as was given as a parameter to the Sign method. |
| orderRef | Order reference that should be included when redirecting the client to the OneGate server. |
| redirectUrl | The URL which to redirect the user, please see section about redirection below. |
Method “Collect”
The collect method is normally called after the user has been redirected back to the requesting application. Since the signature order will by default time out after 10 minutes, it is recommended that the requesting application automatically requests the signature response after that time in case the signature was completed but the client could not be redirected back for some reason.
Method “Collect” Parameters
| Parameter | |
|---|---|
| transactionId | A string with the same value that was used for the “Sign” method |
| orderRef | The orderRef returned from the “Sign” method |
Method “Collect” Return values
| Return Parameter | |
|---|---|
| transactionId | Same transactionId as was given as input to the method |
| progressStatus | Status of the signature procedure. See below. |
| signature | A string containing the signature. See below. |
| attributes | A list of key-value attributes. See below. |
Progress status
Values are OUTSTANDING_TRANSACTION (indicating that we are still waiting for the transaction to complete) and COMPLETE. If the user has returned to the requesting application and the collect method returned OUTSTANDING_TRANSACTION, the operation might be considered to have been cancelled by the user. It is possible that the user used the browser's back button for example.
Signature
If the progressStatus was COMPLETE, the response contains a signature. The signature is returned as a Base64 encoded string but the actual format depends on the signing method used. Sometimes it is an XMLDSig signature, in other cases it is a PKCS#7 signature. The signature together with the set of returned attributes (containing possible revocation information) should be archived.
Attributes
The information returned in the attribute list depends on the configuration of the OneGate server. However, this is a suggested set of attributes (copied from the list of attributes used by CGI GRP service with permission):
| Attribute name | Value |
|---|---|
| cert.subject.cn | The given name and surname of the user |
| cert.subject.givenname | All given names for the user |
| cert.subject.surname | Surname of the user |
| cert.subject.serialnumber | Serial number of the subject (Used for Swedish social security number (personnummer) in Swedish eID certificates) |
| cert.serialnumber | The serial number of the user’s certificate. Unique for the used certificate and good to have for forensic purpose. |
| cert.notafter | Date when the users certificate expires. |
| cert.notbefore | Creation day for the user’s certificate. |
| security.level | Level Of Assurance. LOA3 and 4 are used today by Swedish eID. 3: used for “BankID på fil” and “Mobilt BankID”, 4: used for “BankID på kort”. |
| validation.ocsp.response | The electronic receipt of the validation. String (b64) XML-signature signed by a certificate that has the same issuer as the certificate being verified. Should be saved for evidence purpose. |
| cert.issuer.cn | Common Name of the issuer in the user certificate. |
| cert.issuer.o | Organization name of the issuer in the user certificate |
| cert.issuer.c | Country of the issuer. Example: SE |
Client redirection
If the Sign method returns a redirectUrl, the requesting application should redirect the user to the web frontend of the signature service. The redirection can either be done with a HTTP Location header or with an HTML form using POST. It is not recommended for the application to include the URL as a HTTP link in a page since it is easier for the user to bookmark the URL containing the secret “orderref” value or send it to another user.
The application should always use the URL returned in the response in the redirection. The parameter should be called “orderref” (with lower case letters).
Example HTTP redirection:
HTTP/1.1 302 Found Location: https://m00-esign.login.company.com/signservice/v2/sign?orderref=abc123
Example HTML Form POST: