OpenID Connect 1.0 protocol (OIDC) reference

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, Sensu offers commercial support for single sign-on (SSO) 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, read Configure single sign-on (SSO) authentication.

OIDC configuration example

---
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: oidc

{
  "type": "oidc"
}

api_version: authentication/v2

{
  "api_version": "authentication/v2"
}

metadata:
  name: oidc_name

{
  "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:'

{
  "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: oidc_provider

{
  "name": "oidc_provider"
}

OIDC spec attributes

additional_scopes:
- groups
- email
- username

{
  "additional_scopes": [
    "groups",
    "email",
    "username"
  ]
}

client_id: 1c9ae3e6f3cc79c9f1786fcb22692d1f

{
  "client_id": "1c9ae3e6f3cc79c9f1786fcb22692d1f"
}

client_secret: a0f2a3c1dcd5b1cac71bf0c03f2ff1bd

{
  "client_secret": "a0f2a3c1dcd5b1cac71bf0c03f2ff1bd"
}

disable_offline_access: false

{
  "disable_offline_access": false
}

redirect_uri: http://sensu-backend.example.com:8080/api/enterprise/authentication/v2/oidc/callback

{
  "redirect_uri": "http://sensu-backend.example.com:8080/api/enterprise/authentication/v2/oidc/callback"
}

server: https://sensu.oidc.provider.example.com

{
  "server": "https://sensu.oidc.provider.example.com"
}

groups_claim: groups

{
  "groups_claim": "groups"
}

groups_prefix: 'okta:'

{
  "groups_prefix": "okta:"
}

username_claim: email

{
  "username_claim": "email"
}

username_prefix: 'okta:'

{
  "username_prefix": "okta:"
}

Refresh tokens

No matter which OIDC provider you use, make sure to enable refresh tokens during provider configuration. If you do not enable refresh tokens in your provider configuration, Sensu will log out of the web UI, the API, and sensuctl after 5 minutes.

Register an Okta application

To use Okta for authentication, register Sensu Go as an OIDC web application. Before you start, install Sensu Go with a valid commercial license and make sure you have access to the Okta Administrator Dashboard.

Follow the steps in this section to create an Okta application and configure an Okta OIDC provider in Sensu.

Create an Okta application

1. In the Okta Admin Console, navigate to Applications: click Applications > Applications.
2. Click Create App Integration.
3. In the Create a new app integration modal window:
   • Select the sign-in method OIDC - OpenID Connect.
   • Select the application type Web Application.
4. Click Next.
5. In the New Web App Integration dialog:
   • In the App integration name field, enter the app name. You can also upload a logo if desired.
   • Under Grant type, click to select Refresh Token in the Client acting on behalf of a user list.
   • In the Sign-in redirect URIs field, enter <api_url>/api/enterprise/authentication/v2/oidc/callback. Replace <api_url> with your API URL, including the API port 8080.
   • Under Assignments, click to select Skip group assignment for now.
6. Click Save.
7. Select the Sign On tab, scroll to the OpenID Connect ID Token section, and click Edit.
8. In the Groups claim filter section:
   • In the first field, enter groups
   • In the dropdown menu, select Matches regex
   • In the second field, enter .*
9. Click Save.
10. Select the Assignments tab and assign people and groups to your app.

Configure an Okta OIDC provider

To create your okta OIDC provider in Sensu:

1. For the additional_scopes configuration attribute, include groups and email.

2. For the client_id and client_secret values, use the Client ID and Client secret, respectively, listed under General > Client Credentials for your Okta application.

3. For the redirect_uri attribute, use the Sign-in redirect URIs value you entered in step 5 of Create an Okta application.

4. For the server value, use the Okta domain listed under General > General Settings in your Okta application.

5. Set the disable_offline_access attribute to your desired value (we recommend false).

6. Add your Okta 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.

7. Set the username_claim value to email.

8. Specify groups_prefix and username_prefix values if desired.

Your Okta OIDC provider configuration should be similar to this example:

---
type: oidc
api_version: authentication/v2
metadata:
  name: okta
spec:
  additional_scopes:
  - groups
  - email
  client_id: 4sd5jxiwxfvg82PoZ5d7
  client_secret: r78316494besnNCmtmEBnS47ee792f31bf6216
  redirect_uri: http://127.0.0.1:8080/api/enterprise/authentication/v2/oidc/callback
  server: https://dev-459543913.okta.com
  disable_offline_access: false
  groups_claim: groups
  username_claim: email
  groups_prefix: 'oidc:'
  username_prefix: 'oidc:'

{
  "type": "oidc",
  "api_version": "authentication/v2",
  "metadata": {
    "name": "okta"
  },
  "spec": {
    "additional_scopes": [
      "groups",
      "email"
    ],
    "client_id": "4sd5jxiwxfvg82PoZ5d7",
    "client_secret": "r78316494besnNCmtmEBnS47ee792f31bf6216",
    "redirect_uri": "http://127.0.0.1:8080/api/enterprise/authentication/v2/oidc/callback",
    "server": "https://dev-459543913.okta.com",
    "disable_offline_access": false,
    "groups_claim": "groups",
    "username_claim": "email",
    "groups_prefix": "oidc:",
    "username_prefix": "oidc:"
  }
}

Configure authorization for OIDC users

Configure authorization via role-based access control (RBAC) for your OIDC users and groups by creating roles (or cluster roles) and role bindings (or cluster role bindings) that map to the user and group names.

Use sensuctl to login with OIDC

1. Run sensuctl login oidc.

   NOTE: You can also use sensuctl configure and choose the OIDC authentication method to log in to sensuctl with OIDC.

2. If you are using a desktop, a browser will open to 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:

   https://<api_url>:8080/api/enterprise/authentication/v2/oidc/authorize

OIDC troubleshooting

This section lists common OIDC errors and describes possible solutions for each of them.

To troubleshoot any issue with OIDC authentication, start by increasing the log verbosity of sensu-backend to the debug log level. Most authentication and authorization errors are only displayed on the debug log level to avoid flooding the log files.

For provider-specific troubleshooting, read the Okta or PingFederate documentation.

bad request

After configuring OIDC access, if you receive a bad request error when you open the web UI, you may be using an incorrect port in the redirect URI.

Make sure the redirect URI uses the API port, 8080. Confirm that the redirect URI specified in your OIDC provider as well as in the redirect_uri attribute in your Sensu OIDC definition both use port 8080. For example, the URL http://127.0.0.1:8080/api/enterprise/authentication/v2/oidc/callback uses the correct port.

could not find the groups claim in the user's claims

If you see the following error when you open the web UI, the groups_claim value in your Sensu OIDC definition is incorrect:

{"message":"could not find the groups claim \"okta:groups\" in the user's claims: [\"sub\" \"email\" \"email_verified\"]","code":0}

Update your OIDC definition to specify groups as the value for the groups_claim attribute.

No namespaces or resources in the web UI after OIDC sign-in

You must configure RBAC authorization for your OIDC users and groups by creating roles (or cluster roles) and role bindings (or cluster role bindings) that map to the user and group names.

If you do not configure authorization, users will be able to log in with OIDC but will have no permissions, so they will not see any namespaces or resources in the web UI.

Inconsistent authentication

If you experience inconsistent authentication with OIDC sign-in, such as being unable to sign in after previously signing in successfully, you may have configured more than one OIDC authentication provider.

Run sensuctl auth list to make sure that you have only one authentication provider listed for type OIDC. If more than one OIDC authentication provider is listed, use sensuctl auth delete $NAME to remove the extra OIDC configuration by name.