Manual Chapter : OCSP Authentication

Applies To:

Show Versions Show Versions

BIG-IP APM

  • 15.0.1, 15.0.0
Manual Chapter

OCSP Authentication

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

Configure 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.
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.
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. 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.

Add 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.
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.
    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
    .
    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.
    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 then 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.
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

Configure 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.
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.
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. 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.

Add 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.
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.
    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.
    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 then 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.
This adds OCSP authentication of a user certificate to an access policy.
To apply this access policy to network traffic, add the access profile to a virtual server.
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

You associate the client SSL and access profiles with the virtual server so that the BIG-IP system handles client-side SSL traffic as specified, and so that Access Policy Managercan apply the access profile to incoming traffic.
  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.