Configure an OIDC Identity Provider in StackRox

Configure StackRox to use your OpenID Connect (OIDC) Identity Provider.

Follow the instructions here to integrate an OpenID Connect Identity Provider with the StackRox Kubernetes Security Platform.

Prerequisites

To complete these steps:

  • you must have already configured an application in your Identity Provider, such as G Suite.
  • you must have appropriate permissions to configure identity providers in the StackRox Kubernetes Security Platform.

Configure StackRox

To configure an OpenID Connect integration:

  1. On the StackRox portal, navigate to Platform Configuration > Access Control.

  2. Open the Auth Provider menu, select Add auth provider and select OpenID Connect.

  3. Fill out the details for:

    • Integration Name: A user-friendly name to identify this authentication provider. For example, “Auth0” or “G Suite.” The integration name is shown on the login page to help users select the right sign-in option.
    • Callback Mode: Select HTTP POST (default). An alternative mode (called Fragment), designed around the limitations of Single Page Applications (SPAs), is also available. We only support Fragment mode for legacy integrations, and don’t recommended selecting it for new integrations.
    • Issuer: The root URL of your Identity Provider, for example https://accounts.google.com for G Suite. Refer to your Identity Provider documentation for more information.

    If you are using the StackRox Kubernetes Security Platform version 3.0.49 and newer, for Issuer you can:

    • prefix your root URL with https+insecure:// to skip TLS validation. This configuration is insecure and we don’t recommended it. Only use it for testing purposes.
    • specify query strings (for example, ?key1=value1&key2=value2) along with the root URL. The StackRox Kubernetes Security Platform appends the value of Issuer as is to the authorization endpoint. You can use it to customize your provider’s login screen. For example, you can optimize the GSuite login screen to a specific hosted domain by using the hd parameter, or pre-select an authentication method in PingFederate by using the pfidpadapterid parameter.
    • Client ID: The OIDC Client ID for your configured project.

      OIDC identity providers usually assign a Client ID and a Client Secret to a project.

      • For the StackRox Kubernetes Security Platform version 3.0.38 and older, you only need the ID, and not the secret.
      • For the StackRox Kubernetes Security Platform version 3.0.39 and newer, you can specify a client secret.
  4. Choose a Minimum access role for users accessing StackRox using this Identity Provider. Leave the Minimum access role set to Admin while you complete setup. Later, you can return to the Access Control page to set up more tailored access rules based on user metadata from the Identity Provider.

  5. Select Save.

  6. Complete a test login to make sure your integration is working.

Specify a client secret

The StackRox Kubernetes Security Platform version 3.0.39 and newer supports the OAuth 2.0 Authorization Code Grant authentication flow when you specify a client secret. When you use this authentication flow the StackRox Kubernetes Security Platform uses a refresh token to keep users logged in beyond the token expiration time configured in your OIDC identity provider.

When users log out, the StackRox Kubernetes Security Platform deletes the refresh token from the client-side. Additionally, if your identity provider API supports refresh token revocation, the StackRox Kubernetes Security Platform also sends a request to your identity provider to revoke the refresh token.

You can specify a client secret when you configure StackRox to integrate with an OIDC identity provider.

  • You can’t use a Client Secret with the Fragment Callback mode.
  • You can’t edit configurations for existing authentication providers, and you must create a new OIDC integration in the StackRox Kubernetes Security Platform if you want to use a Client Secret.

If you don’t specify a client secret, the StackRox Kubernetes Security Platform uses the OAuth 2.0 Implicit Grant authentication flow.

We recommend you to use a client secret when connecting with an OIDC identity provider. If you don’t want to use a Client Secret, you must select Do not use Client Secret (not recommended).

Verify configuration

For version 3.0.44 and newer

Before you verify the configuration of your Identity Provider integration:

  1. Verify that you are on the Access Control view and you’ve selected the Auth Provider Rules tab.
  2. Under the Auth Providers section, make sure that you’ve selected the authentication provider for which you want to verify the configuration.

To verify your Identity Provider integration:

  1. Select Test Login from the Auth Provider section header. The Test Login page opens in a new browser tab.
  2. Sign in with your credentials.
    • On success, the StackRox Kubernetes Security Platform shows the User ID and User Attributes the Identity Provider sent for the credentials you’ve used to log in.
    • On failure, the StackRox Kubernetes Security Platform shows a message describing why the Identity Provider’s response couldn’t be processed.
  3. Close the Test Login browser tab. If your new provider doesn’t function correctly, check and update your configuration.

Once you log in using your Identity Provider, your configuration is complete.

You can reconfigure role-based access control permissions for each Identity Provider by navigating to Platform Configuration > Access Control.

For version 3.0.43 and older

To verify the configuration of your Identity Provider integration, select Log Out from the top right corner, then choose your new provider from the menu and sign in.

If your new provider doesn’t function correctly, log in using the administrator password or another Identity Provider.

Once you log in using your Identity Provider, your configuration is complete.

You can reconfigure role-based access control permissions for each Identity Provider by navigating to Platform Configuration > Access Control.

Questions?

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

© 2021 StackRox Inc. All rights reserved.