on 09-Aug-2019 09:25
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.
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:
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:
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.
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.
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.
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.
Hi,
Great article. I wonder if certificate can be used to retrieve token for REST API operations?
Piotr
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:
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
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.
Piotr