BIG-IQ Client Certificate (PKI) Authentication

Radu_Litiu · ‎09-Aug-2019

Beginning with version 7.0.0, BIG-IQ allows users to authenticate to the GUI using a signed SSL client certificate instead of a username and password.

Client certificate authentication works in conjunction with an external authentication provider. The BIG-IQ verifies the user's identity by validating the client certificate against a list of trusted CAs (certificate authorities), and optionally checking the certificate for revocation against the configured certificate revocation list (CRL). Then it extracts the username from the certificate and uses it to query an external server (directory) for group membership information for the user, which is used to determine the user's authorization to access various features of the BIG-IQ.

Set up client certificate authentication

On the BIG-IQ, client certificate authentication works in conjunction with an Active Directory or an LDAP authentication provider. Prior to setting up certificate authentication, make sure you have the following:

External Active Directory or LDAP server
X.509 client certificates for the users to be authenticated. Additional client certificates can be generated at any later time.
All the X.509 issuing CA certificates (root and intermediate) for the client certificates
Certificate Revocation Lists (CRLs) for all the revoked certificates, if applicable

Additionally, you have to have a good understanding of the structure (attributes) of the client certificates you are going to use, as well as of your directory schema. The login name of the user will be extracted from the certificate, and then it will be used to find the user in the directory.

Prior to enabling client certificate authentication, the user must set up either an Active Directory or an LDAP authentication provider (use the documentation corresponding to your BIG-IQ version). To avoid being locked out of BIG-IQ, before enabling client certificate authentication, make sure the settings are correct by clicking the Test button at the bottom of the authentication provider properties screen. A successful test ensures BIG-IQ can successfully connect to the remote directory and search users in the directory.

Also, make sure to set up the necessary user groups corresponding to directory groups and to put them in the appropriate roles. Whether the user is authenticated using a certificate or using user/password, access to various areas of the BIG-IQ will be granted according to the RBAC settings on the groups the user is a member of.

Following that, check the Enable Client Certificate Authentication check-box. This opens up a new area of the screen, with the following settings:

CA Certificate - upload a file containing the X.509 CA certificate(s) that sign and validate the user-provided SSL client certificates used to authenticate. This can contain one or several issuing CA certificates, including both root and intermediate certificates.
Note: To successfully validate a client certificate issued by an intermediate CA, all the intermediate CA certificates leading up to as well as the root CA must be present in the CA certificate file.
Certificate Username Attribute - the attribute value to extract from the client certificate, containing the username (or user identifier). The value extracted can be either the exact username or a longer string for which the username is just a substring.
The BIG-IQ supports the following certificate attributes:
Common Name in the Subject Name (Subject CN)
The following attributes in the Subject Alternative Name (SAN😞
Directory Name
DNS Name
Email
IP Address
Registered ID
URI
Other Name (BIG-IQ only supports userPrincipalName in Other Name)

If the certificate contains multiple attributes with the same name, e.g., multiple Other Name attributes under the SAN, the username corresponding to the Other Name Certificate Username Attribute will be the concatenation of all the matching attribute values, space-separated.
Certificate Username Filter - an optional regex filter used to extract the exact username from the value of the Certificate Username Attribute in the certificate. If this filter is not specified, the entire attribute value is used as a username.
Directory User Search Filter - a search filter used to find users in the directory, based on the username extracted from the certificate, and after applying the optional Certificate Username Filter. The LDAP search query is obtained by replacing the {username} token in the filter with the actual username.
For the Certificate Revocation List, you can optionally upload a file containing one or more X.509 CRLs, one for each issuing CA. If more certificates are revoked at a later time, the CRL file needs to be re-generated and re-uploaded to keep the CRLs known to the BIG-IQ up-to-date. All the client certificates in the CRL file will fail validation, therefore the corresponding users will be denied access.
Note: CRLs have a Next update field. If current time is past the Next update time of the CRL set on the authentication provider, the CRL is considered obsolete, therefore all the client certificates will fail validation.
Make sure to update the CRL prior to its expiration at the Next update time.
Check the Enable Local Authentication Fallback check-box if you want BIG-IQ to be able to authenticate users against the local authentication provider in addition to certificate authentication.
Even though in the end the BIG-IQ administrator may want to only allow certificate authentication, we recommend that she enables local authentication fallback at first, until she has verified certificate authentication works correctly. This would prevent being accidentally locked out of BIG-IQ due to incorrect settings or mismatched client and CA certificates.

Example 1:

Assume the client certificate has the following subject:

Subject: C=US, ST=Washington, L=Seattle, O=ACME Corp, OU=Engineering, CN=John Doe/emailAddress=j.doe@acme.com

Assume the directory entry corresponding to the user contains the following attributes:

dn: CN=John Doe,OU=Users,OU=North America,DC=olympus,DC=F5Net,DC=com
CN=John Doe

Using the Certificate Username Attribute Common Name extracts the username John Doe.
Either don’t enter a Certificate Username Filter or set it to “.+” (match all characters in the input). The resulting username after applying the filter is John Doe.

Using the Directory User Search Filter cn={username} yields the search expression: cn=John Doe. This query retrieves the above directory entry corresponding to user John Doe.

Example 2:

Assume the client certificate has the following entries under the Subject Alternative Name (SAN):

otherName.1 = 1.3.6.1.4.1.311.20.2.3;UTF8:JOHN.DOE.J.III.1042156825
otherName.2 = 1.3.6.1.4.1.311.20.2.3;UTF8:j.doe@acme.com
otherName.3 = 1.3.6.1.5.5.7.8.7;IA5STRING:_mail.example.com

Assume the directory entry corresponding to the user contains the following attributes:

userPrincipalName: 1042156825@acme.com
mail: J.Doe@us.acme.com

Using the Certificate Username Attribute Other Name extracts the username string (userPrincipalName only, OID =1.3.6.1.4.1.311.20.2.3😞 JOHN.DOE.J.III.1042156821 j.doe@acme.com

Using the Certificate Username Filter “[0-9]*” we extract the string 1042156825. That username (or rather user identifier) will be substituted in the Directory User Search Filter.

Using the Directory User Search Filter userPrincipalName={username}@acme.com yields the search expression: userPrincipalName=1042156825@acme.com. This query retrieves the above directory entry corresponding to user John Doe.

Alternatively, using the Certificate Username Filter “[A-Za-z0-9.]+(?=@acme.com)” we extract the string (username) j.doe. That username will be substituted in the Directory User Search Filter.

Using the Directory User Search Filter mail={username}@us.acme.com yields the search expression: mail=j.doe@us.acme.com. This query retrieves the above directory entry corresponding to user John Doe.

Log in to BIG-IQ GUI using a client certificate

Prior to authenticating to BIG-IQ, import the SSL client certificate into the web browser. The imported file must contain both the X.509 certificate and the associated private key. It is a PKCS#12 file, having the extension .p12 or .pfx. If the file is password-protected, you need to enter the password when importing the certificate. You will also need to provide the private key’s password, if applicable. For stronger security, we recommend that both the private key and the PKCS#12 bundle are password-protected.
Note: The certificate import user workflow varies slightly across browsers and across operating systems. The certificate import functionality is usually located in the browser preferences/settings, under Privacy & Security > Certificates > Your Certificates.
In the browser address bar, enter a BIG-IQ URI. That first request in unauthenticated. There will be no login page, just a blank page. The browser will prompt the user to select one of the certificates from the browser's personal certificate store. Only the certificates that could potentially be successfully validated by the BIG-IQ, i.e., whose issuers are trusted by the BIG-IQ, will be displayed. In the browser, you can eventually view the certificate details, i.e., their subject, issuer, etc.
Select the desired client certificate from the list.
If the fallback mechanism to allow local user/password authentication is enabled, the user may choose not to send a client certificate, case in which the browser will display the login screen, prompting the user to enter a user/password combination, which will be used to authenticate against the local auth provider.
If local authentication fallback is disabled and the user chooses not to send a client certificate, or if there is no certificate that could potentially be successfully validated by the BIG-IQ, authentication will fail.
The first step in certificate authentication consists of the BIG-IQ successfully validating the certificate presented by the browser. If the certificate has been issued by one of the trusted CAs, is not expired, and it has not been revoked, certificate validation succeeds.
If certificate validation fails for various reasons, the browser request returns a 400 code (SSL certificate error).
Next, the BIG-IQ extracts the username from the certificate, according to the Certificate Username Attribute and Certificate Username Filter settings. Then it looks up the user in the directory, by executing the search query corresponding to the Directory User Search Filter setting. If the user is found in the directory, the BIG-IQ retrieves the user properties, including the groups the user is a member of. Access to various areas of the BIG-IQ is granted according to the RBAC permissions on the groups the user is a member of.
If the authentication is successful, the user is taken to the splash page, or alternatively to the last visited page if the user has previously logged in to the BIG-IQ.

To log out after authenticating with the client certificate presented by the browser, or to log in using a different certificate, the user will have to close the browser session to clear the SSL session established between the browser and the BIG-IQ.

To prevent future logins using the same browser and certificate, the user will have to remove the certificate from the browser.

Recover from BIG-IQ lockout

After enabling client certificate authentication, there might be some unfortunate situations when the user is locked out of BIG-IQ. Reasons include incorrect settings on the authentication provider, invalid, expired, or revoked certificates, and expired CRLs.

To get out of that bad situation, if fallback to local authentication is enabled, when the browser prompts the user to choose a certificate to authenticate, choose to not send a certificate (click the Cancel button). The browser will display the BIG-IQ login screen, prompting the user to enter a user/password combination to log in. After logging in as an administrator using the local authentication provider, fix the problem that has caused the lockout, then resume using certificate authentication.

If fallback to local authentication is disabled, ssh into the BIG-IQ. At the shell prompt, run the following command:

client-cert-auth -x

This will reset the BIG-IQ authentication to the default username/password authentication using the local authentication provider. It will also delete the authentication provider that has caused the lockout.

dragonflymr · ‎04-Sep-2019

Hi,

Great article. I wonder if certificate can be used to retrieve token for REST API operations?

Piotr

Radu_Litiu · ‎04-Sep-2019

Hi Piotr,

This article is about client cert auth to the GUI. We have published another article about client cert auth to the API, including retrieving the auth token:

https://clouddocs.f5.com/products/big-iq/mgmt-api/v0.0/ApiReferences/bigiq_public_api_ref/r_auth_log...

In the example, we use curl to make the auth call. If you use another REST client, there is probably a different way to provide the client’s private key and the corresponding X.509 certificate on the auth call.

Please l.m.k. if this works for you.

--Radu

dragonflymr · ‎05-Sep-2019

Hi,

Thanks a lot for pointing me to this info. It's exactly what I need. Sorry for asking this question in context of GUI authentication.