Manual Chapter : OCSP Authentication

Applies To:

Show Versions Show Versions

BIG-IP APM

  • 13.1.3, 13.1.1, 13.1.0
Manual Chapter

About OCSP authentication

Access Policy Manager® (APM®) supports authenticating a client using Online Certificate Status Protocol (OCSP). OCSP is a mechanism used to retrieve the revocation status of an X.509 certificate by sending machine or user certificate information to a remote OCSP responder. This responder maintains up-to-date information about the certificate's revocation status. OCSP ensures that APM always obtains real-time revocation status during the certificate verification process.

Overview: Verifying machine certificate revocation status with OCSP

Access Policy Manager® supports using Online Certificate Status Protocol (OCSP) to verify the revocation status of a machine certificate.

You must have already configured the access profile to which you want to add OCSP authentication.

Task summary

Configuring an OCSP responder

Before you can specify a certificate authority file for an OCSP responder, you must import it in PEM format to the BIG-IP® system SSL certificate list.
Important: The OCSP responder does not work with a certificate authority file that is in DER encoding format. If you've got a certificate authority file in DER format, transform it to PEM format before you import it into the BIG-IP system.
Create an OCSP responder in Access Policy Manager® (APM®) when you want to obtain revocation status for a user or machine certificate as part of your access control strategy.
Note: You must create one OCSP responder object in APM for each external OCSP responder from which you intend to request status.
  1. On the Main tab, click Access > Authentication > OCSP Responder .
    The OCSP Responder servers screen opens.
  2. Click Create.
    The New Server properties screen opens.
  3. In the Name field, type a unique name for the authentication server.
  4. In the URL field, type the URL used to contact the OCSP service on the responder.
    You can skip this step if you did not select the Ignore AIA check box and all users have certificates with the correct AIA structure. (The Ignore AIA option is available when you select Advanced from the Configuration list; it is disabled by default.)
  5. Optional: From the Certificate Authority File list, select an SSL certificate.
  6. Click Finished.
    The new server displays on the list.
You can select this OCSP responder from an OCSP Auth access policy item.

Adding OCSP machine certificate verification to an access policy

Add an OCSP Auth action to an access policy when you want to verify the revocation status of a machine certificate as part of your authentication strategy.
Important: Before the OCSP Auth action runs, session variables must be populated with certificate data. Typically, a Machine Cert Auth action populates these variables. As an alternative, variable assignment is possible.
  1. On the Main tab, click Access > Profiles / Policies .
    The Access Profiles (Per-Session Policies) screen opens.
  2. In the Per-Session Policy column, click the Edit link for the access profile you want to configure.
    The visual policy editor opens the access policy in a separate screen.
  3. Click the (+) icon anywhere in the access policy to add a new item.
    Note: Only an applicable subset of access policy items is available for selection in the visual policy editor for any access profile type.
    A popup screen opens, listing predefined actions on tabs such as General Purpose, Authentication, and so on.
  4. Type mach in the search field, select Machine Cert Auth from the results, and click Add Item.
    Access Policy Manager® supports Machine Cert Auth for Mac and Windows-based clients.
    A Properties popup screen displays.
  5. Specify values for the Certificate Store Name, Certificate Store Location, and CA Profile fields.
  6. From the Save Certificate in a session variable, select Enabled.
    Important: If this setting is not enabled, the OCSP Auth action cannot use the data from the X.509 certificate that the Machine Cert Auth action receives.
  7. Click the (+) icon anywhere in the access policy to add a new item.
    Note: Only an applicable subset of access policy items is available for selection in the visual policy editor for any access profile type.
    A popup screen opens, listing predefined actions on tabs such as General Purpose, Authentication, and so on.
  8. Select OCSP Auth, and click Add item.
    A properties popup screen opens.
  9. From the OCSP Responder list, select an OCSP responder.
  10. From the Certificate Type list, select Machine.
  11. Click Save.
    The properties screen closes and the policy displays.
  12. Click Apply Access Policy to save your configuration.
Actions are added to the access policy.
To apply this access policy to network traffic, add the access profile to a virtual server.
Note: To ensure that logging is configured to meet your requirements, verify the log settings for the access profile.

Overview: Verifying user certificate revocation status with OCSP

Access Policy Manager® supports using Online Certificate Status Protocol (OCSP) to verify the revocation status of a user certificate.

You must have already configured the access profile to which you want to add OCSP authentication.

Task summary

Configuring an OCSP responder

Before you can specify a certificate authority file for an OCSP responder, you must import it in PEM format to the BIG-IP® system SSL certificate list.
Important: The OCSP responder does not work with a certificate authority file that is in DER encoding format. If you've got a certificate authority file in DER format, transform it to PEM format before you import it into the BIG-IP system.
Create an OCSP responder in Access Policy Manager® (APM®) when you want to obtain revocation status for a user or machine certificate as part of your access control strategy.
Note: You must create one OCSP responder object in APM for each external OCSP responder from which you intend to request status.
  1. On the Main tab, click Access > Authentication > OCSP Responder .
    The OCSP Responder servers screen opens.
  2. Click Create.
    The New Server properties screen opens.
  3. In the Name field, type a unique name for the authentication server.
  4. In the URL field, type the URL used to contact the OCSP service on the responder.
    You can skip this step if you did not select the Ignore AIA check box and all users have certificates with the correct AIA structure. (The Ignore AIA option is available when you select Advanced from the Configuration list; it is disabled by default.)
  5. Optional: From the Certificate Authority File list, select an SSL certificate.
  6. Click Finished.
    The new server displays on the list.
You can select this OCSP responder from an OCSP Auth access policy item.

Adding OCSP user certificate verification to an access policy

Add an OCSP authentication item to an access policy when you want to verify the revocation status of a user certificate as part of your authentication strategy.
Note: Before the OCSP Auth action runs, session variables must be populated with certificate data. Typically, in an access policy either a Client Cert Inspection or On-Demand Cert Auth action receives an X.509 certificate from a user and stores data in session variables that the OCSP Auth action uses. As an alternative for populating session variables, variable assignment is possible.
  1. On the Main tab, click Access > Profiles / Policies .
    The Access Profiles (Per-Session Policies) screen opens.
  2. In the Per-Session Policy column, click the Edit link for the access profile you want to configure.
    The visual policy editor opens the access policy in a separate screen.
  3. Click the (+) icon anywhere in the access policy to add a new item.
    Note: Only an applicable subset of access policy items is available for selection in the visual policy editor for any access profile type.
    A popup screen opens, listing predefined actions on tabs such as General Purpose, Authentication, and so on.
  4. From the Authentication tab, select either Client Cert Inspection or On-Demand Cert Auth, and click Add item.
    Client Cert Inspection checks the result of an SSL handshake request that occurs at the start of an SSL session. On Demand Cert Auth performs an SSL re-handshake and checks the result. The CRLDP and OCSP Auth actions require certificate information made available by one of these policy items.
  5. Click the (+) icon anywhere in the access policy to add a new item.
    Note: Only an applicable subset of access policy items is available for selection in the visual policy editor for any access profile type.
    A popup screen opens, listing predefined actions on tabs such as General Purpose, Authentication, and so on.
  6. Select OCSP Auth, and click Add item.
    A properties popup screen opens.
  7. From the OCSP Responder list, select an OCSP responder.
  8. From the Certificate Type list, select User.
  9. Click Save.
    The properties screen closes and the policy displays.
  10. Click Apply Access Policy to save your configuration.
To apply this access policy to network traffic, add the access profile to a virtual server.
Note: To ensure that logging is configured to meet your requirements, verify the log settings for the access profile.

Configuring a client SSL profile for OCSP

To configure this client SSL profile correctly, you need to know whether the access policy (that will be paired with this SSL profile on a virtual server) includes the Client Cert Inspection agent or the On-Demand Cert Auth agent.
You need a client SSL profile to use OCSP authentication to verify a user certificate from an access policy.
  1. On the Main tab, click Local Traffic > Profiles > SSL > Client .
    The Client SSL profile list screen opens.
  2. Click Create.
    The New Client SSL Profile screen opens.
  3. In the Name field, type a unique name for the profile.
  4. Select clientssl in the Parent Profile list.
  5. Scroll down to the Client Authentication area.
  6. Next to Client Authentication, select the Custom check box.
    The settings become available.
  7. From the Client Certificate list, select the option that is applicable to the item you selected when you edited the policy.
    • Select request if the Client Cert Inspection agent is used in the policy.
    • Select ignore if the On-Demand Cert Auth agent is used.
  8. From the Trusted Certificate Authorities list, select the Certificate Authority that issues the user certificates.
  9. From the Advertised Certificate Authorities list, select the advertised Certificate Authority file for client certificate authentication.
  10. Click Finished.
To put a client SSL profile into effect, you must add it to a virtual server.

Adding client-side SSL and access profiles to a virtual server

  1. On the Main tab, click Local Traffic > Virtual Servers .
    The Virtual Server List screen opens.
  2. Click the name of the virtual server you want to modify.
  3. For the SSL Profile (Client) setting, from the Available list, select the name of the Client SSL profile you previously created and move the name to the Selected list.
  4. In the Access Policy area, from the Access Profile list, select the access profile that you configured earlier.
  5. Click Update to save the changes.
The access policy and client-side SSL profiles are now associated with the virtual server.

OCSP session variables

When the OCSP Auth access policy item runs, it relies on information stored in session variables. Various access policy items can populate the session variables. This table lists the session variables and access policy items that can populate them.

Session variables for OCSP

Session Variable Source Description
session.ssl.cert.whole

Cert Inspection

On-Demand Cert Auth

Variable Assign

Provides the client certificate received from the user in PEM format. (Used for verifying the revocation status of a user certificate.)
session.ssl.cert.certissuer

Cert Inspection

On-Demand Cert Auth

Variable Assign

Provides the issuer certificate of the client certificate in PEM format. (Used for verifying the revocation status of a user certificate.)
session.check_machinecert.last.cert.cert

Machine Cert Auth

Variable Assign

Provides the encrypted text of the machine certificate. (Used for verifying the revocation status of a machine certificate.)
session.check_machinecert.last.cert.issuer.cert

Machine Cert Auth

Variable Assign

Provides the issuer certificate of the machine certificate. (Used for verifying the revocation status of a machine certificate.)

OCSP authentication troubleshooting tips

You might run into problems with OCSP authentication in some instances. Follow these tips to try to resolve any issues you might encounter.

OCSP auth and query troubleshooting

Possible error messages Possible explanations and corrective actions
No AAA server associated with the agent Make sure that a valid OCSP responder configuration is assigned to the OCSP agent in the access policy.
User/Issuer certificate not found for the session The user/issuer certificate session variables are missing. For a user certificate, make sure that either the Client Cert Inspection agent or On-Demand Cert Auth agent is configured in the access policy, or, use a variable assignment agent to create session variables. For a machine certificate, make sure that the Machine Cert Auth agent is configured or use variable assignment to create the session variables.
Failure to connect to OCSP responder (BIO callback failure) Make sure that the OCSP responder is up and running and reachable from the BIG-IP® system.
Error parsing the OCSP response (invalid response) Indicates that no valid basic response was found in the OCSP response. Check the configuration on the remote OCSP responder.
Error signing OCSP request Make sure that the signing certificate and key are valid.
No valid nonce found in the response This happens when the nonce setting is enabled on the OCSP responder configuration and the received OCSP response does not contain a valid nonce. Check the remote OCSP responder connection and setting.
Nonce verification failed This happens when the nonce received in the response does not match with the nonce sent in the request. Make sure that the connection from BIG-IP system to OCSP responder is secure.
Failure to verify response Make sure that the OCSP responder has a valid CA and verify other certificate settings.
Status times invalid Make sure that the BIG-IP system and OCSP responder clocks are in sync.
OCSP response - Cert with serial number 'x' has been revoked Indicates that the status of the user, or machine, certificate is revoked.
Failed to add cert to OCSP request Indicates a failure in creating the OCSP request; either the supplied user/issuer certificates are not valid or the CertID digest configured in the OCSP responder setting is not valid.
Failed to initialize OCSP Auth Module This might indicate that the certificate authority file that was imported into the BIG-IP® system is in DER encoding format. Transform the certificate authority file from DER to PEM encoding format and import it again.