Configure OpenID Connect 1.0 protocol (OIDC) authentication
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 |
|
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 |
|
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 |
|
spec | |
---|---|
description | Top-level map that includes the OIDC spec attributes. |
required | true |
type | Map of key-value pairs |
example |
|
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 |
|
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 |
required | false |
type | Array |
example |
|
client_id | |
---|---|
description | The OIDC provider application Client ID .
NOTE: Requires registering an application in the OIDC provider. |
required | true |
type | String |
example |
|
client_secret | |
---|---|
description | The OIDC provider application Client Secret .
NOTE: Requires registering an application in the OIDC provider. |
required | true |
type | String |
example |
|
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 |
|
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 |
|
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 |
|
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_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 |
|
username_claim | |
---|---|
description | The claim to use to form the final RBAC user name. |
required | false |
type | String |
example |
|
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 |
|
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.
- In the Okta Administrator Dashboard, start the wizard:
selectApplications
>Add Application
>Create New App
. - In the Platform dropdown, select
Web
. - In the Sign on method section, select
OpenID Connect
. - Click Create.
- 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
(replaceAPI_URL
with your API URL).
- Click Save.
- Select the General tab and click Edit.
- In the Allowed grant types section, click to select the box next to Refresh Token.
- Click Save.
- Select the Sign On tab.
- In the OpenID Connect ID Token section, click Edit.
- In the Groups claim filter section:
- In the first field, enter
groups
- In the dropdown menu, select
matches regex
- In the second field, enter
.*
- In the first field, enter
- Click Save.
- (Optional) Select the Assignments tab to assign people and groups to your app.
OIDC provider configuration
-
Add the
additional_scopes
configuration attribute in the OIDC scope and set the value to[ "groups" ]
:"additional_scopes": [ "groups" ]
-
Add the
groups
to thegroups_claim
string. For example, if you have an Okta groupgroups
and you set thegroups_prefix
tookta:
, you can set up RBAC objects to mention groupokta:groups
as needed:"groups_claim": "okta:groups"
-
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
-
Run
sensuctl login oidc
. -
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:- https://sensu-backend.example.com:8080/api/enterprise/authentication/v2/oidc/authorize