This document is the technical reference for Signaturgruppens Authentication Plugin client library.

Size: px

Start display at page:

Download "This document is the technical reference for Signaturgruppens Authentication Plugin client library."

Madlyn Small
6 years ago
Views:

1 1 Introduction This document is the technical reference for Signaturgruppens Authentication Plugin client library. The Authentication Plugin consist of a single.net 4.5 DLL (AuthenticationPlugin.dll), henceforth referred to as the client library. The API and configuration for the client library is described in this document. 2 Configuration All configuration for the client library is configured in the web.config file for your web application. This section describes the section you need to add and the possible settings that are available. 2.1 Configuration section The client library expects the following configuration section in the web.config file: <configuration> <configsections> <section name="authenticationplugin" type="signaturgruppen.authenticationplugin.configuration.authenticationpluginconfigurationsection, AuthenticationPlugin" />... <AuthenticationPlugin CertificateFile="~/App_Data/TestBlackBoxSelfSigned.p12" CertificateFilePassword="Test1234" BackendCertificateFile="~/App_Data/TestBlackBoxSelfSigned.p12.cer" BackendUrl=" web.config in latest demo]" Identifier="TestTu1" /> Introduction to CAPI If you store your certificates in the Windows Certificate Store, you can configure the client library to load certificates from there. This is done through the CryptoAPI (CAPI). In the following configuration parameters, names with a Capi suffix refers to certificates loaded through the CryptoAPI Configuration settings The AuthenticationPlugin section has the following possible parameters Page 1

2 Setting Identifier BackendUrl BackendCertificateFile BackendCertificateCapi BackendCertificateCapiFindType CertificateFile CertificateFilePassword CertificateCapi CertificateCapiFindType CapiStoreLocation Description Service Provider Identifier Url pointing to the backend Backend certificate Backend certificate CAPI identifier X509FindType for BackendCertificateCapi Certificate used to secure communication Password for CertificateFile CAPI identifier of Authentication Plugin certificate X509FindType for CertificateCapi StoreLocation for Capi certificates Page 2

3 Identifier Identifies the service (the client library) to the backend. This value can be choosen freely but has to match the configuration at the backend, as the backend uses this value to identify the specific configuration at the backend, including certificates used for the secure communication BackendUrl Url pointing to the root of the backend application BackendCertificateFile Directory path pointing to the filebased certificate (typically a cer file), used to encrypt and verify messages when communicating with the backend. Supports absolute or virtual path BackendCertificateCapi CAPI certificate identifier for the certificate used to encrypt messages when communication with the backend. The default behavior is to look for the Distinguished Name of the certificate BackendCertificateCapiFindType Lets you set the X509FindType when also using the BackendCertificateCapi parameter. All values of the X509FindType are usable, but the following values are usually preferred: X509FindType Description FindBySubjectDistinguishedName Full distinguished name from certificate (X509Certificate2 style) FindBySubjectName Find a substring in the certificate subject name FindByThumbprint Find by certificate Thumbprint (usually SHA1 hash) FindBySerialNumber Find by certificate serial number If more than one certificate is found using the selected search method, the first found is selected CertificateFile Directory path pointing to the filebased certificate (typically a p12 or ` pfx file), used to decrypt and sign messages when communicating with the backend. Supports absolute or virtual path CertificateFilePassword Password for the pfx/p12 file pointed to in the CertificateFile parameter CertificateCapi CAPI certificate identifier for the certificate used to encrypt messages when communicating with the backend. The default behavior is to look for the Distinguished Name of the certificate CertificateCapiFindType Lets you set the X509FindType when also using the CertificateCapi parameter. See BackendCertificateCapiFindType for possible values CapiStoreLocation StoreLocation enum: Page 3

4 public enum StoreLocation { CurrentUser = 1, LocalMachine = 2, } Default for this setting is StoreLocation.LocalMachine Configured certificates The client library and the backend communicates securely using the configured certificates. Only one of BackendCertificateFile and BackendCertificateCapi must be specified. Same applies for CertificateFile and CertificateCapi. 3 Logging No external logging framework is used in the client library but the client library supports and requires logging. This is done by requiring the registration of a logging method taking a message to be logged as a string parameter: //from Global.asax: protected void Application_Start(object sender, EventArgs e) { log4net.config.xmlconfigurator.configure(); var logger = LogManager.GetLogger("Signaturgruppen.AuthenticationPlugin"); AuthenticationPluginLogger.LoggerAction = logger.debug; } This is an example taken from our demo application where we demonstrate the registration of a Log4Net debug logger, which then receives all the log messages from the client library. If this is not configured the AuthenticationPluginLogger will throw an exception at runtime. The backend will log all required information regarding login, signing, validation, revocation checks etc. A full audit log are generated at the backend which supports the extended reporting requirements from DanID when using file or hardware based NemID flows The backend is also able to log the XMLDSig (XML-signatures) generated by the NemID flows. These are also avaiable through the API. The client logs are mainly for debugging purposes but we still require them. 4 HTML 5 Web Messaging and iframes The flow works by setting up an iframe and then communicating with the backend using the HTML 5 Web Messaging JavaScript API through an iframe. The client library generates the code needed to enable communication with the backend through an iframe. As an example, the following code snippet creates the signed parameters for the backend as well as the JavaScript needed for the communication var paramsgenerator = new NemIDOtpParamsGenerator(); Page 4

5 paramsgenerator.generatescriptandparametersfornemidframe("handleresult.aspx"); We refer to the demo for details on how this is used. The browser requirements for this setup are the same as for the NemID JavaScript client, thus if the users browser supports the NemID client, it supports Signaturgruppens Authentication Plugin. Page 5

6 5 Test setup Signaturgruppen has hosted a backend available when testing on The demo application available at is configured to this test backend when you start it the first time. It is possible to use the demo setup to get NemID up and running in your application(s) and test how NemID and our software works before any agreements with us or DanID has been made. 6 Client flows and services We support all NemID login and signing flows, which include the NemID JavaScript client using OTP cards (both Standard Mode and Limited Mode) and the OpenSign applet for key and hardware based login and signing flows. 6.1 CPR Services The client library supports the CPR services available through the NemID infrastructure. If you are a private service provider you are restricted to the CPR Match service, which lets you validate a given CPR paired with the Personal ID (PID) from a successfull NemID authentication flow CPR (non-private service providers) If you have a CPR agreement with DanID it is a simple configuration setting at the backend which enables the CPR service and sets the CPR in the response from the backend and makes it available through the NemIDValidationResult (see below). The CPR is encrypted and decrypted transparently using RSA-SHA CPR Match (private service providers) The CPR Match service is available at the backend as a RESTful service available transparently through the client library. A CPR Match agreement with DanID is required. There are two ways to call the CPR Match service using the client library. 1. The NemIDValidationResult.AuthenticationInfo object contains the method:pidcprmatch(string cpr), which returns true or false. (See below for more details on the result object). When a response is received from the backend, the PID from the user certificate is already part of the response, and thus only the CPR number is needed in order to verify if the PID matched the given CPR. 2. The CPR Match service is also avaible as a "pure" backend-to-backend service using the following var service = new PidCprMatchService(); var cprmatchespid = service.matchpidandcpr(string pid, string cpr); The MatchPidAndCpr(string pid, string cpr) method returns true or false. All communication is secured by https and signed and encrypted using RSA-SHA Sign _ Properties If you need to add additional sign properties to the resulting XMLDSig document, you can do so by adding the Page 6

7 Sign _ Properties property to the parametergenerator, as demonstrated here: var paramsgenerator = new NemIDOtpParamsGenerator(); paramsgenerator.setclientflowparameter("sign_properties", "testproperty1=testvalue1;testproperty2=testvalue2;"); 7 Backend response The response received from the backend through the iframe is validated using the client library, resulting in an object consisting of the validation result and all the information needed from the specific client flow. Following snippet of code creates a validator which parses and validates the response string received from the backend through the HTML5 WebMessaging API: var validator = new NemIDAuthenticationValidator(); NemIDValidationResult result = validator.validate(receivedresponse); The NemIDValidationResult object contains the validation result and all the data you need from the NemID authentication. An example is a NemID login flow, where the result object contains validation status and if successfull all the certificate info from the NemID user including: PID/RID and Common Name. See the demo for all relevant examples, including demonstration of how to use the CPR-MATCH service. 7.1 NemIDValidationResult In this section the API for the NemIDValidationResult class is described. We refer to an instance of NemIDValidationResult as "result" result.authenticationresult : BOOLEAN TRUE, if and only if, result.status equals Ok result.status : AuthenticationStatus public enum AuthenticationStatus { Ok, AuthenticationBackendError, ClientFlowCancel, ClientFlowError, AuthenticationPluginValidationError, } Ok In this case the communication and the flow requested was successfull. The user was authenticated successfully AuthenticationBackendError And error occured at the backend. In this case the returned message is not signed and a generic error message could be displayed to the user. This is most likely to be caused by configuration errors ClientFlowCancel In this scenario, the flow was cancelled, most often directly by the user. Page 7

8 ClientFlowError In this case, an error occured in the requested flow. Examples could be and error with the NemID client. In this case the errorcodes returned to the backend from the requested client flow is returned and should be logged. See examples of this in the demo application. As a minimum, you should log the message returned from the.getlogmessage() call on the validation result object AuthenticationPluginValidationError An error occured parsing or validating the response from the backend result.authenticationinfo Object containing the response from the NemID authentication. If AuthenticationStatus equals Ok, it contains all the certificate information such as PID/RID, common name, certificate distinguished name etc. If AuthenticationStatus equals ClientFlowError, the error code from the NemID flow is found in the ErrorCode property. The resulting XMLDSig is found in the SignedXml property, as a Base64 encoded string. 8 Flow overview To illustrate how the different parts work together, we provide a short overview of the overall flow here. All communication are done via https and are thus encrypted. 1. The client website opens an iframe to the backend and sends the generated and signed parameters to the backend through 2. The requested flow/client is started and generated parameters used. The user is interacting directly with the service inside the iframe using a secure connection. 3. As an example: The NemID client is started inside the iframe which transparently lets the user interact with the NemID client, as-if the client was hosted directly on the client website. 4. When the user has entered his credentials the response is validated and all required logs created at the backend. 5. A response is created and sent to the client website through the iframe using the HTML 5 web massaging API. 6. The response is validated using the client library, after which all required information is avaiable through the client library API. 7. All messages are signed and sensitive information is encrypted. Our library transparently validates and de-/encrypts the messages. All communication is done through and from the users browser. 9 Contact information Info Mail support@signaturgruppen.dk Phone Website Page 8

The SPS.Client consist of a single.net DLL (SPS.CLient.dll), henceforth referred to as the client library.

1 Introduction This document is the technical reference for Signaturgruppens SPS.Client library. The SPS.Client consist of a single.net DLL (SPS.CLient.dll), henceforth referred to as the client library.