Documentation

Use this guide to enable certificate authentication via SSL in SecureAuth IdP realm(s). 

This configuration initiates a begin site that forces the browser to request a certificate before the end user provides any information (client-side certificate) to enable access to the target resource (application, VPN, IdM tool, etc.) 



Prerequisites

  • Have a valid certificate that is used to access the realm configured for certificate authentication via SSL. You can use any of the following certificates: 
    • Certificates generated by SecureAuth IdP
    • Issued certificates – If your organization has their own issued certificates, make sure it meets the validation requirements in the next section, Certificate validation requirements and realm configuration options 
    • Smart card certificates – If you have a smart card certificate, then the certificate chain must be imported from the card issuer to the SecureAuth IdP appliance
  • On SecureAuth IdP version 9.1 and later, create a new realm or edit an existing realm to which SSL certificate authentication is applied in the SecureAuth IdP Web Admin.
  • Before setting up a realm for certificate authentication via SSL, configure the following tabs in the Web Admin:
    • Overview – define the realm and SMTP connections 
    • Data – integrate an enterprise directory with SecureAuth IdP
    • Workflow – define the user login process for accessing the target resource 
    • Multi-Factor Methods  – define the Multi-Factor Authentication methods used to access the target (if any)
    • Post Authentication  – define the target resource or post authentication action
    • Logs  – enable or disable the the logs for this realm



Certificate validation requirements and realm configuration options

This section is required only if your organization wants to use their own issued certificates instead of SecureAuth IdP-generated certificates.  The SecureAuth IdP has a stock out-of-the-box (OOTB) validation scheme to validate security certificates. 

To ensure that certificates can be validated by SecureAuth IdP, see the following requirements to tailor your issued certificates. You can use your issued certificates if there are no expectations to modify the cSSL.aspx.vb file, as long as the issued certificates meet the following requirements. 

Certificate requirements for OOTB validation (Non-customization option)
  • The issued certificate needs to have a Subject field containing the Company Name of the client.  This value must match the shipped value defined on the System Info tab (Classic IdP Experience) in the License Info section, in the Company Name field. 
    Ideally, this value in the Subject field can be paired to the "O" ("Organization") attribute of the Subject field. For example:

O = Company Name

  • The same aforementioned Subject field needs to have the "CN" ("Common Name") attribute containing a value to which the SecureAuth IdP uses to validate the user. 
    This is usually the sAMAccountName value (the User ID) of the user that the SecureAuth IdP validates against the Active Directory. Alternatively, it can also be an email or a UPN. In the following example for an Active Directory configuration, any of the following values are valid: 

CN = jsmith (user ID)

CN = jsmith@secureauth.com (for emails)

CN = jsmith@secureauth.local (for UPN; assuming enterprise user or employee who is an active Domain User)

At this point, the SearchFilter setting in SecureAuth IdP can be adjusted to accommodate searchability. The CN value should match the "Issued to" value of the certificate. 


The following describes how the default validation scheme works in SecureAuth IdP:

  1. In SecureAuth IdP, it checks whether the Company Name value in the Subject field of the certificate matches the defined Company Name from the License Info section on the System Info tab. 
    • When a match is found, it proceeds to the next step. Otherwise validation fails when a match is not found. 
  2. Then, the SecureAuth IdP checks whether the value of the CN attribute in the Subject field of the certificate matches the user information in the data store
    • When a match is found, it proceeds with the remainder of the login workflow to authenticate the user into the resource. Otherwise, validation fails when a match is not found. 



If your organization has issued certificates using a defined format for most of your end user base, then it requires a customization option. To accommodate defined certificates for validation by SecureAuth IdP, it requires code changes to .dll or .vb files. Contact SecureAuth Support to customize the issuing certificate realm. 

To apply your defined certificates in the realm, make the following configurations. 

Modify the cSSL.aspx file (Customization option)
  1. On the SecureAuth IdP appliance, go to the folder for the realm that is configured to work with your defined certificates. For example, D:\SecureAuth\SecureAuth20. 
  2. Find the cSSL.aspx file and make the following edits: 
    1. Change CodeBehind to CodeFile

    2. Change Inherits="MFC.WebApp.SecureAuth.cSSL" to Inherits="cSSL"
      For example, the result of these edits might appear as: CodeFile="cSSL.aspx.vb" Inherits="cSSL". See the following example. 

  3. Save your changes.
  4. To validate and extract user information required for the certificate environment, find and edit the cSSL.aspx.vb file. 

    Contact SecureAuth Support for assistance in customizing the cSSL.aspx.vb file. 



Realm configuration for certificate authentication via SSL 

These configuration steps are for the realm to which certificate authentication via SSL applies. 

  1. Go to the Workflow tab. 
  2. In the Custom Identity Consumer section, set the following:

    Receive TokenSet to Token.
    Require Begin SiteSet to True.
    Begin SiteSet to Client Side SSL.
    Begin Site URLThis field is autopopulated with cSSL.aspx.

  3. Click Save.



Internet Information Services (IIS) Manager configuration

  1. Go to the Internet Information Services (IIS) Manager
  2. Under Sites > Default Web Site, select the realm to which the SSL certificate is applied (for example, SecureAuth3). 
  3. Click SSL Settings and set the following: 

    Require SSLSelect the check box. 
    Client certificatesChoose the Require option. 



Sample end user workflow

  1. When the end user attempts to access the certificate authentication via SSL realm, the SSL certificate Begin Site opens. 
  2. From the Begin Site, the end user is immediately prompted for a certificate. 
  3. A list of certificates are retrieved, from which the end user selects the appropriate certificate. 
  4. The end user is redirected to the SecureAuth IdP, and follows the workflow of the SSL certificate realm and then to the target resource. 



Troubleshooting and common issues


Using Certificate Revocation List (CRL)

If using a separate Certificate Revocation List (CRL) rather than SecureAuth IdP, then make sure the SecureAuth IdP appliance can access the CRL to check the validity of certificates.

403 Errors

If you are getting 403 errors, then check the IIS logs to view the sub error code to further troubleshoot. For example:

  • 403.7 – No certificate provided
  • 407.17 – Certificate was revoked