Configure OpenID Connect 1.0 protocol (OIDC) authentication to access Sensu

COMMERCIAL FEATURE: Access authentication providers in the packaged Sensu Go distribution. For more information, see Get started with commercial features.

Sensu requires username and password authentication to access the web UI, API, and sensuctl command line tool.

In addition to the built-in basic authentication provider, Sensu offers commercial support for authentication using the OpenID Connect 1.0 protocol (OIDC) on top of the OAuth 2.0 protocol. The Sensu OIDC provider is tested with Okta and PingFederate.

For general information about configuring authentication providers, see Use an authentication provider.

WARNING: Defining multiple OIDC providers can lead to inconsistent authentication behavior. Use sensuctl auth list to verify that only one authentication provider of type OIDC is defined. If more than one OIDC auth provider configuration is listed, use sensuctl auth delete $NAME to remove the extra OIDC configurations by name.

OIDC configuration examples

---
type: oidc
api_version: authentication/v2
metadata:
  name: oidc_name
spec:
  additional_scopes:
  - groups
  - email
  client_id: a8e43af034e7f2608780
  client_secret: b63968394be6ed2edb61c93847ee792f31bf6216
  disable_offline_access: false
  redirect_uri: http://127.0.0.1:8080/api/enterprise/authentication/v2/oidc/callback
  server: https://oidc.example.com:9031
  groups_claim: groups
  groups_prefix: 'oidc:'
  username_claim: email
  username_prefix: 'oidc:'
{
   "type": "oidc",
   "api_version": "authentication/v2",
   "metadata": {
      "name": "oidc_name"
   },
   "spec": {
      "additional_scopes": [
         "groups",
         "email"
      ],
      "client_id": "a8e43af034e7f2608780",
      "client_secret": "b63968394be6ed2edb61c93847ee792f31bf6216",
      "disable_offline_access": false,
      "redirect_uri": "http://sensu-backend.example.com:8080/api/enterprise/authentication/v2/oidc/callback",
      "server": "https://oidc.example.com:9031",
      "groups_claim": "groups",
      "groups_prefix": "oidc:",
      "username_claim": "email",
      "username_prefix": "oidc:"
   }
}

OIDC specification

OIDC top-level attributes

type
description Top-level attribute that specifies the sensuctl create resource type. For OIDC configuration, the type should always be oidc.
required true
type String
example
"type": "oidc"
api_version
description Top-level attribute that specifies the Sensu API group and version. For OIDC configuration, the api_version should always be authentication/v2.
required true
type String
example
"api_version": "authentication/v2"
metadata
description Top-level collection of metadata about the OIDC configuration. The metadata map is always at the top level of the OIDC definition. This means that in wrapped-json and yaml formats, the metadata scope occurs outside the spec scope.
required true
type Map of key-value pairs
example
"metadata": {
  "name": "oidc_name"
  }
}
spec
description Top-level map that includes the OIDC spec attributes.
required true
type Map of key-value pairs
example
"spec": {
  "additional_scopes": [
    "groups",
    "email"
    ],
  "client_id": "a8e43af034e7f2608780",
  "client_secret": "b63968394be6ed2edb61c93847ee792f31bf6216",
  "disable_offline_access": false,
  "redirect_uri": "http://sensu-backend.example.com:8080/api/enterprise/authentication/v2/oidc/callback",
  "server": "https://oidc.example.com:9031",
  "groups_claim": "groups",
  "groups_prefix": "oidc:",
  "username_claim": "email",
  "username_prefix": "oidc:"
  }
}

OIDC metadata attribute

name
description A unique string used to identify the OIDC configuration. The metadata.name cannot contain special characters or spaces (validated with Go regex \A[\w\.\-]+\z).
required true
type String
example
"name": "oidc_name"

OIDC spec attributes

additional_scopes
description Scopes to include in the claims, in addition to the default openid scope.

NOTE: For most providers, you’ll want to include groups, email and username in this list.

required false
type Array
example
"additional_scopes": ["groups", "email", "username"]
client_id
description The OIDC provider application Client ID.
required true
type String
example
"client_id": "1c9ae3e6f3cc79c9f1786fcb22692d1f"
client_secret
description The OIDC provider application Client Secret.
required true
type String
example
"client_secret": "a0f2a3c1dcd5b1cac71bf0c03f2ff1bd"
disable_offline_access
description If true, the OIDC provider cannot include the offline_access scope in the authentication request. Otherwise, false.

We recommend setting disable_offline_access to false. If set to true, OIDC providers cannot return a refresh token that allows users to refresh their access tokens, and users will be logged out after 5 minutes.
required true
default false
type Boolean
example
"disable_offline_access": false
redirect_uri
description Redirect URL to provide to the OIDC provider. Requires /api/enterprise/authentication/v2/oidc/callback

NOTE: Only required for certain OIDC providers, such as Okta.

required false
type String
example
"redirect_uri": "http://sensu-backend.example.com:8080/api/enterprise/authentication/v2/oidc/callback"
server
description The location of the OIDC server you wish to authenticate against.

NOTE: If you configure with http, the connection will be insecure.

required true
type String
example
"server": "https://sensu.oidc.provider.example.com"
groups_claim
description The claim to use to form the associated RBAC groups.

NOTE: The value held by the claim must be an array of strings.

required false
type String
example
 "groups_claim": "groups" 
groups_prefix
description The prefix added to all OIDC groups. Sensu appends the groups_prefix with a colon. For example, for the groups_prefix okta and the group dev, the resulting group name in Sensu is okta:dev. Use the groups_prefix when integrating OIDC groups with Sensu RBAC role bindings and cluster role bindings.
required false
type String
example
"groups_prefix": "okta"
username_claim
description The claim to use to form the final RBAC user name.
required false
type String
example
"username_claim": "person"
username_prefix
description The prefix added to all OIDC usernames. Sensu appends the username_prefix with a colon. For example, for the username_prefix okta and the user alice, the resulting username in Sensu is okta:alice. Use the username_prefix when integrating OIDC users with Sensu RBAC role bindings and cluster role bindings. Users do not need to provide the username_prefix when logging in to Sensu.
required false
type String
example
"username_prefix": "okta"

Register an OIDC application

To use OIDC for authentication, register Sensu Go as an OIDC application. Use the instructions listed in this section to register an OIDC application for Sensu Go based on your OIDC provider.

Okta

Requirements

  • Access to the Okta Administrator Dashboard
  • Sensu Go 5.12.0 or later (plus a valid commercial license for Sensu Go versions 5.12.0 through 5.14.2)

Create an Okta application

NOTE: These instructions are based on the Okta Classic UI. The steps may be different if you are using the Okta Developer Console.

  1. In the Okta Administrator Dashboard, start the wizard:
    select Applications > Add Application > Create New App.
  2. In the Platform dropdown, select Web.
  3. In the Sign on method section, select OpenID Connect.
  4. Click Create.
  5. In the Create OpenID Connect Integration window:
    • GENERAL SETTINGS section: in the Application name field, enter the app name. You can also upload a logo in the if desired.
    • CONFIGURE OPENID CONNECT section: in the Login redirect URIs field, enter API_URL/api/enterprise/authentication/v2/oidc/callback (replace API_URL with your API URL).
  6. Click Save.
  7. Select the General tab and click Edit.
  8. In the Allowed grant types section, click to select the box next to Refresh Token.
  9. Click Save.
  10. Select the Sign On tab.
  11. In the OpenID Connect ID Token section, click Edit.
  12. In the Groups claim filter section:
    • In the first field, enter groups
    • In the dropdown menu, select matches regex
    • In the second field, enter .*
  13. Click Save.
  14. (Optional) Select the Assignments tab to assign people and groups to your app.

OIDC provider configuration

  1. Add the additional_scopes configuration attribute in the OIDC scope and set the value to [ "groups" ]:

    • "additional_scopes": [ "groups" ]
  2. Add the groups to the groups_claim string. For example, if you have an Okta group groups and you set the groups_prefix to okta:, you can set up RBAC objects to mention group okta:groups as needed:

    • "groups_claim": "okta:groups"
  3. Add the redirect_uri configuration attribute in the OIDC scope and set the value to the Redirect URI configured at step 3 of Create an Okta application:

    • "redirect_uri": "API_URL/api/enterprise/authentication/v2/oidc/callback"

Sensuctl login with OIDC

  1. Run sensuctl login oidc.

  2. If you are using a desktop, a browser will open to OIDC provider and allow you to authenticate and log in. If a browser does not open, launch a browser to complete the login via your OIDC provider at following URL: