Enable PKI authentication

Enable secure access to the StackRox Kubernetes Security Platform by using public key infrastructure (PKI) authentication.

If you use an enterprise certificate authority (CA) for authentication, you can configure the StackRox Kubernetes Security Platform to authenticate users by using their personal certificates.

To use PKI authentication with the StackRox Kubernetes Security Platform:

  • You must be running version 2.4.24 or newer of the StackRox Kubernetes Security Platform. If you are on an older version, see the Upgrade StackRox page for upgrade instructions.
  • You must already have a CA and end-user certificates.
  • You must configure a custom TLS server certificate for the StackRox Kubernetes Security Platform server. The certificate you use must be trusted within your organization.

After you configure PKI authentication, users and API clients can log in using their personal certificates. Users without certificates can still use other authentication options, including API tokens, the local administrator password, or other authentication providers. PKI authentication is available on the same port number as the Web UI, gRPC, and REST APIs.

Configure PKI authentication

You can configure PKI authentication by using the StackRox portal or the roxctl command-line interface (CLI).

To configure it by using the StackRox portal:

  1. Navigate to Platform Configuration > Access Control.
  2. Open the Auth Provider menu, select Add auth provider and then select User Certificates.
  3. In the Name box, specify a name for this authentication provider.
  4. Paste your root CA certificate in PEM format into the text box.
  5. (Optional) Change the Minimum access role and add role mappings by attributes.
  6. Select Save.

To configure it using roxctl:

  1. Run the following command:
    roxctl -e <hostname>:<port-number> central userpki create -c <ca-certificate-file> -r <default-role-name> <provider-name>

When you configure PKI authentication, by default, the StackRox Kubernetes Security Platform uses the same port for PKI, Web UI, gRPC, other Single sign-on (SSO) providers, and REST APIs. You can also configure a separate port for PKI authentication by using a YAML configuration file to configure and expose endpoints. See Configure endpoints for details.

Log in using client certificate

After configuration, users see a certificate prompt on the StackRox portal login page. The prompt only shows up if a client certificate trusted by the configured root CA is installed on user’s system.

To login using a client certificate:

  1. Open the StackRox portal.
  2. Select a certificate in the browser prompt.
  3. On the login page, select the authentication provider name option to log in with a certificate. (If you don’t want to log in by using the certificate, you can also log in by using the administrator password or another login method.)

Once you use a client certificate to log into the StackRox portal, you won’t be able to login with a different certificate unless you restart your browser.

Update authentication keys and certificates

To update your authentication keys and certificates:

  1. Create a new authentication provider as described in the Configure PKI authentication section.
  2. Copy the role mappings from your old authentication provider to the new authentication provider.
  3. Rename (or delete) the old authentication provider with the old root CA key.


We're happy to help! Reach out to us to discuss questions, issues, or feature requests.

© 2021 StackRox Inc. All rights reserved.