Signature Appliance Local API C#: Authenticating signers via Kerberos

This recipe demonstrates how a user, authenticated via Kerberos to a web app hosted on IIS, can use the DocuSign Signature Appliance Local API to authenticate and sign a document.

API Recipe source files are available on GitHub.

Introduction

User authentication in a distributed system needs to be secure and easy to use and Kerberos is a popular distributed authentication system. Kerberos enables a single sign-on environment for the organization and its authorized users. At the technical level, authentication “impersonation” is when software is temporarily authenticated to act on behalf of a person. In this example, Kerberos is used in the background to enable the web app to impersonate the user (to act on the user’s behalf).

Authenticating with the DocuSign Signature Appliance

Software clients usually authenticate with the appliance APIs using a name/password pair. The Local API can also authenticate signers via the Security Support Provider Interface (SSPI). SSPI is a Microsoft Windows API for authentication and other security-related operations.

In our example, SSPI authentication will be enabled via the IIS web server and proper configuration with Kerberos.

Introduction to Kerberos

Kerberos is a computer network authentication protocol which uses “tickets” to enable nodes communicating over a non-secure network to prove their identity to one another in a secure manner: The client authenticates itself to the Authentication Server (AS) which forwards the username to a Key Distribution Center (KDC). The KDC issues a Ticket Granting Ticket (TGT), which is time stamped, encrypts it using the user’s password and returns the encrypted result to the user’s workstation. This is done infrequently, typically at user logon.

When the client needs to communicate with another node it sends the TGT to the Ticket Granting Service (TGS). After verifying the TGT is valid and the user is permitted to access the requested service, the TGS issues a Ticket and session keys, which are returned to the client. The client then sends the Ticket to the service server (SS) along with its service request.

The Kerberos Dance

The diagram demonstrates the sequence of events when a Kerberos authentication to a Signature Appliance is done from a Web application in an Active Directory environment:

  1. The signer’s web browser supplies a Kerberos service ticket to the web server.
  2. The web server, seeing the need to open a connection to a Signature Appliance using the end user’s credentials obtains the necessary ticket from the KDC on the Domain Controller.
  3. The KDC returns a ticket if the web server is permitted to delegate.
  4. The Web server opens the connection and sends the ticket obtained from the KDC to the Signature Appliance.
  5. The Signature Appliance permits the connection to be opened, or returns an error indicating that the user is not permitted login to the appliance.
  6. The Web server returns the web page to the end user.

To enable the six step “Kerberos dance” to succeed, each node in the process (Domain Controller, Web Server and the Signature Appliance) needs to be appropriately setup and configured as described below. The web application needs specific configuration settings too.

The Web Browser

As shown above, the signer’s web browser needs to pass a Kerberos service ticket to the web server. The SPNEGO mechanism is used for this purpose. SPNEGO was first developed for Internet Explorer and is included with IE by default. We suggest that you first use IE with this example.

Kerberos Authentication will not work in Chrome and Firefox browsers by default. To enable it, add SPNEGO to Chrome and Firefox browsers as needed.

DNS Entry is Required

Ensure that the URL of your Web Application has an A-Record in DNS. If not, you need to create one. A server that is joined to an Active Directory Domain should get an A-record created automatically, but you should ensure it is there.

Create an A-Record in DNS:

  1. Open DNS Management in Administrative Tools.
  2. Expand the forward lookup zones container.
  3. Right click on the zone (domain name) and click on new host (A or AAAA).
  4. Type in the name of the record, this is the URL of the Web Application (minus the domain part in a FQDN).
  5. Type in the IP Address of the Web Server.
  6. Click on “Add Host” and then “Done” and verify that the record has been created in the right pane.
  7. In a Command Prompt, ping the Web Application DNS name to make sure it responds.

Service Account

The service account is a domain user account that we will later use as an application pool identity for our web app.

  1. Open Active Directory Users and Computers Management in Administrative Tools.
  2. Open the Users container of the domain.
  3. Right click in the right pane “New User”
  4. Type in the name of the user and click “Next”.
  5. Type in a password and make sure that checkbox User must change password at next logon is unchecked. Also, it is recommended that you check Password never expires.
  6. Click on “Next” and then “Finish”.
  7. Right click on the user that has just been created in the list of all users and click on Properties.
  8. In the Delegation tab choose Trust this user for delegation to any service (Kerberos only) and click “OK”.

Note: If you can’t find the Delegation tab, complete the SPN section below first and then you should be able to see the Delegation tab and complete this step.

SPN (Service Principal Name)

When creating or setting up your SPN’s, you’ll need some basic information first--since you will be creating HTTP SPN’s you need a URL and a Service account name. If your Web Application has both a NetBIOS name and an FQDN, then you need to create a separate SPN for each.

  1. Start by opening a Command Prompt “Running as administrator”.
  2. List all SPNs already in Place for the Service Account, type:
    setSPN -L domain\serviceaccount[enter]
    e.g. setSPN -L arxps.com\IISKerbSvc
    Most likely, you get back nothing. This is ok. If you do get some registered SPN’s back, just make sure that they are not the same as the ones you are about to add.
  3. Create your own SPN’s for the service account paired with the Web Application and SPN type. To create this SPN type:
    setspn -S HTTP/mywebappurl domain\serviceaccount[enter]
    (e.g. setSPN -S HTTP/myWebApp arxps.com\IISKerbSvc)
  4. For good measure, also add an SPN for the FQDN:
    setspn -S HTTP/mywebappurl.domain.com domain\serviceaccount[enter]
    (e.g. setSPN -S HTTP/myWebApp.arxps.com arxps.com\IISKerbSvc)
  5. List the SPN’s again. You should see your new SPN’s.

Web Server

On the web server we will first configure the service account that we just created to run as a service.

  1. Open Local Security Policy in Administrative Tools.
  2. On the left pane expand Local Policies and click on User Rights Assignment
  3. On the right pane double-click Log on as a service and add the service account to the list.
  4. Do the same for the policy Act as part of the operating system.

Now we add the user account to the IIS users group:

  1. Open Computer Management in Administrative Tools.
  2. On the left pane expand the System Tools and Local Users and Groups nodes and click on Groups.
  3. Double-Click on IIS_IUSRS and add the service account to the list. (IIS_IUSRS is the group name in IIS7, if you use IIS6 look for IIS_WPG).

The next step is to set the service account as an application pool identity for the application pool that will be used by our web application.

  1. Open IIS Manager in Administrative Tools.
  2. In the Connections pane, expand the server node and click on Application Pools.
  3. On the Application Pools page, select the application pool for which you want to specify an identity, and then click Advanced Settings in the Actions pane.
  4. For the Identity property, click the button to open the Application Pool Identity dialog box.
  5. Select the Custom account option and click Set to open the Set Credentials dialog box. Then type the service account name in the User name (including the domain name as in the example below) and password.

The last modification is to configure the proper authentication settings in the IIS.

  1. In the IIS Manager, choose your site in the Connections pane.
  2. In Features View, double-click Authentication.
  3. On the Authentication page, select Windows Authentication.
  4. In the Actions pane, click Enable to use Windows authentication and ensure that only this authentication method is enabled.
  5. Click on Advanced Settings in the Actions pane
  6. Verify that Extended Protection is off and the Enable Kernel-mode authentication setting is unchecked.
  7. Click “Ok” to close the dialog window and click on Providers in the Actionspane.
  8. Verify that the first provider in Enabled Providers list is “Negotiate” or “Negotiate:Kerberos.” The default state as seen in the image below is fine as well.

DocuSign Signature Appliance Client and Server

Once the appliance is correctly installed as part of the Active Directory, it is ready to be used in Kerberos mode and there is nothing else to be done.

The appliance’s client software should be installed on the Web server machine and its default configuration is good. If you don’t use the default configurations, ensure that you are working in one of the following states:<

  1. Open the Signature Appliance Control Panel and click on Client Configuration. On the left pane expand Client and click on Appliances
  2. Set Appliance Parameters to be checked and Prompt for logon Method is either Auto or SSPI (AD-No Prompt).

Web Application

You can choose either of the following methods to impersonate the Authenticating User:

Every request to your Web App includes impersonation

To impersonate the authenticating user on every request for every page in an ASP.NET application, you include an <identity> tag in the Web.config file of your web app and set the impersonate attribute to true. For example:
<identity impersonate=“true” />

Only impersonate the user for specific sections of you code

To impersonate the authenticating user only when you run a particular section of code, you can use the following code snippet. This method requires that the authenticating user identity is of type WindowsIdentity.

System.Security.Principal.WindowsImpersonationContext impersonationContext;
impersonationContext = 
	((System.Security.Principal.WindowsIdentity)User.Identity).Impersonate();

// Insert your code that runs under the security context 
// of the authenticating user here

impersonationContext.Undo();

In the DocuSign Signature Appliance Local API, since SSPI mode is used for authentication, you should not call the SAPILogon function. Instead, the SAPILogoff function must be called with a null parameter at the end of the signing process. This will end the session with the appliance for the current authenticated user. For example:

SAPI.Logoff(null);

Well done!

If you followed the instructions your application should now be able to impersonate a windows user account to the signature appliance by using Kerberos authentication.

For your testing, it is recommended to use a clean machine and login with a domain user account that is a member of the signature appliance’s signers group.