Turn CRL checking on or off

Applies To: Windows Server 2003 R2

Certificate revocation list (CRL) checking is the process of searching for revoked certificates on a server. Active Directory Federation Services (ADFS) uses the Cryptographic Application Programming Interface (CAPI) to validate token-signing certificates and to verify that they have been revoked. In ADFS, CRL checking is used only for token-signing certificates. It is turned on by default for federation servers and ADFS-enabled Web servers.

You can use the script that is provided at the end of this topic to turn CRL checking on or off on a per-organization basis to meet your specific security requirements. Depending on how the script is configured, it can turn CRL verification on or off for the organization itself, which applies to both the federation server and the Web server, or for an account partner.

Using this script will not affect CRL settings for Secure Sockets Layer (SSL) certificates that are defined in Internet Information Services (IIS) Manager. The IIS metabase uses the MD_CERT_NO_REVOC_CHECK setting to validate SSL client authentication certificates and server authentication certificates that are sent to a Web server. This IIS setting is not used by clients to validate ADFS token-signing certificates or by ADFS servers to validate partner certificates. For more information about how to disable CRL checking for SSL certificates using IIS, see SSL and Certificates (IIS 6.0) (https://go.microsoft.com/fwlink/?LinkId=73717) on the Microsoft Web Site.

Before communication between an ADFS server and a Web browser client can occur, an SSL channel must be established between the ADFS server and the client. For more information about establishing an SSL channel, see SSL and Certificates (IIS 6.0) (https://go.microsoft.com/fwlink/?LinkId=73717) on the Microsoft Web Site.

For more information about certificate revocation, see Certificate Revocation and Status Checking (https://go.microsoft.com/fwlink/?linkid=27081) and RevocationFlags Enumeration (https://windowssdk.msdn.microsoft.com/en-us/library/system.web.security.singlesignon.revocationflags.aspx) on the Microsoft Web site.

The following table briefly describes the various arguments that are used in the script.

Script Text

'Option Explicit

Dim tpf ' Trust policy factory
Dim cf  ' Claim Factory

Dim tpFileName  ' Trust policy file name
Dim trUri       ' TrustRealm Uri
Dim revFlagsStr ' RevocationFlags enum in string form

Dim tp  ' TrustPolicy
Dim tr  ' TrustedRealm
Dim revFlags    ' RevocationFlags enum
Dim found       ' Did we find the realm in the trust policy?

'----------------------------------------
' Echo usage.
'----------------------------------------
Sub Usage()
    WScript.StdErr.WriteLine("Usage:")
    WScript.StdErr.WriteLine("TpCrlChk.vbs TrustPolicy.xml TrustRealmUri RevocationFlags")
    WScript.StdErr.WriteLine()
    WScript.StdErr.WriteLine("Arguments:")
    WScript.StdErr.WriteLine("TrustPolicy.xml - Full path to the trust policy file")
    WScript.StdErr.WriteLine("TrustRealmUri   - Uri of the trust realm whose setting must be changed")
    WScript.StdErr.WriteLine("RevocationFlags - One of the following:")
    WScript.StdErr.WriteLine("                      None")
    WScript.StdErr.WriteLine("                      CheckEndCert")
    WScript.StdErr.WriteLine("                      CheckEndCertCacheOnly")
    WScript.StdErr.WriteLine("                      CheckChain")
    WScript.StdErr.WriteLine("                      CheckChainCacheOnly")
    WScript.StdErr.WriteLine("                      CheckChainExcludeRoot")
    WScript.StdErr.WriteLine("                      CheckChainExcludeRootCacheOnly")
    WScript.Quit
End Sub


'----------------------------------------
' Fetch the RevocationFlags enum value.
'----------------------------------------
Function GetRevFlags(revFlagsStr)
    If (revFlagsStr = "None") Then
        GetRevFlags = 0
    ElseIf (revFlagsStr = "CheckEndCert") Then
        GetRevFlags = 1
    ElseIf (revFlagsStr = "CheckEndCertCacheOnly") Then
        GetRevFlags = 2
    ElseIf (revFlagsStr = "CheckChain") Then
        GetRevFlags = 3
    ElseIf (revFlagsStr = "CheckChainCacheOnly") Then
        GetRevFlags = 4
    ElseIf (revFlagsStr = "CheckChainExcludeRoot") Then
        GetRevFlags = 5
    ElseIf (revFlagsStr = "CheckChainExcludeRootCacheOnly") Then
        GetRevFlags = 6
    Else
        Call Usage()
    End If
End Function



'----------------------------------------
' Get the parameters.
'----------------------------------------

Dim ArgObj
Set ArgObj = WScript.Arguments

If (ArgObj.Count < 3) Then
    Call Usage()
End If

tpFileName = ArgObj.Item (0)
trUri      = ArgObj.Item(1)
revFlags   = GetRevFlags(ArgObj.Item(2))

'----------------------------------------
' Do the job.
'----------------------------------------

WScript.StdOut.WriteLine("Loading trust policy: " & tpFileName)

'
' Create factories
'
Set tpf = CreateObject("System.Web.Security.SingleSignOn.TrustPolicyFactory")
Set cf  = CreateObject("System.Web.Security.SingleSignOn.ClaimFactory")

'
' Load the TrustPolicy
'
Set tp  = tpf.Load(tpFileName, 0) ' initialize certs = false

'
' Find the realm and set the revocation flags
'
found = 0
If (tp.TrustPolicyEntryUri = trUri) Then
    '
    ' Hosted realm attributes
    '
    WScript.StdOut.WriteLine("Changing the setting for this Federation service: " & trUri)
    found = 1
    tp.VerificationMethod.RevocationCheckFlags = revFlags
Else
    '
    ' Trusted Realms
    '
    For Each tr in tp.TrustedRealms
        If (tr.TrustPolicyEntryUri = trUri) Then
            WScript.StdOut.WriteLine("Changing the setting for this Account partner: " & trUri)
            found = 1
            tr.VerificationMethod.RevocationCheckFlags = revFlags
            Exit For 'since the Uri is unique
        End If
    Next

    If (found = 0) Then
        WScript.StdOut.WriteLine("Error: " & trUri & " is neither this Federation Service nor an Account partner.")
        WScript.Quit
    End If

End If

'----------------------------------------
' Save the TrustPolicy
'----------------------------------------
WScript.StdOut.Write("Saving changed trust policy...")

tp.Write(tpFileName)

WScript.StdOut.WriteLine("done.")