enterprise/authentication/v2

COMMERCIAL FEATURE: Access authentication providers for single sign-on (SSO) in the packaged Sensu Go distribution. For more information, read Get started with commercial features.

NOTE: Requests to enterprise/authentication/v2 API endpoints require you to authenticate with a Sensu API key or access token. The code examples in this document use the environment variable $SENSU_API_KEY to represent a valid API key in API requests.

Get active authentication provider configurations

The /authproviders API endpoint provides HTTP GET access to authentication provider configuration in Sensu.

Example

The following example queries the /authproviders API endpoint for the authentication provider configurations in Sensu:

curl -X GET \
http://127.0.0.1:8080/api/enterprise/authentication/v2/authproviders \
-H "Authorization: Key $SENSU_API_KEY"

The request results in a successful HTTP/1.1 200 OK response and a JSON array that contains the authentication provider configurations:

[
  {
    "type": "oidc",
    "api_version": "authentication/v2",
    "metadata": {
      "name": "oidc_auth",
      "created_by": "admin"
    },
    "spec": {
      "additional_scopes": [
        "groups",
        "email"
      ],
      "client_id": "xxxxxxxxxxxxxxxxxxxx",
      "client_secret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "disable_offline_access": false,
      "groups_claim": "groups",
      "groups_prefix": "oidc:",
      "redirect_uri": "http://sensu-backend.example.com:8080/api/enterprise/authentication/v2/oidc/callback",
      "server": "https://oidc.example.com:9031",
      "username_claim": "email",
      "username_prefix": "oidc:"
    }
  },
  {
    "type": "ldap",
    "api_version": "authentication/v2",
    "metadata": {
      "name": "openldap",
      "created_by": "admin"
    },
    "spec": {
      "groups_prefix": "",
      "servers": [
        {
          "binding": {
            "password": "YOUR_PASSWORD",
            "user_dn": "cn=binder,dc=acme,dc=org"
          },
          "client_cert_file": "",
          "client_key_file": "",
          "default_upn_domain": "",
          "group_search": {
            "attribute": "member",
            "base_dn": "dc=acme,dc=org",
            "name_attribute": "cn",
            "object_class": "groupOfNames"
          },
          "host": "127.0.0.1",
          "insecure": false,
          "port": 636,
          "security": "tls",
          "trusted_ca_file": "",
          "user_search": {
            "attribute": "uid",
            "base_dn": "dc=acme,dc=org",
            "name_attribute": "cn",
            "object_class": "person"
          }
        }
      ],
      "username_prefix": ""
    }
  }
]

API Specification

/authproviders (GET)
description Returns the list of active authentication providers.
example url http://hostname:8080/api/enterprise/authentication/v2/authproviders
query parameters types: Defines which type of authentication provider to retrieve. Join with & to retrieve multiple types: ?types=AD&types=OIDC.
pagination This endpoint supports pagination using the limit and continue query parameters. Read the API overview for details.
response type Array
response codes
  • Success: 200 (OK)
  • Error: 500 (Internal Server Error)
output 
[
  {
    "type": "oidc",
    "api_version": "authentication/v2",
    "metadata": {
      "name": "oidc_auth",
      "created_by": "admin"
    },
    "spec": {
      "additional_scopes": [
        "groups",
        "email"
      ],
      "client_id": "xxxxxxxxxxxxxxxxxxxx",
      "client_secret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "disable_offline_access": false,
      "groups_claim": "groups",
      "groups_prefix": "oidc:",
      "redirect_uri": "http://sensu-backend.example.com:8080/api/enterprise/authentication/v2/oidc/callback",
      "server": "https://oidc.example.com:9031",
      "username_claim": "email",
      "username_prefix": "oidc:"
    }
  },
  {
    "type": "ldap",
    "api_version": "authentication/v2",
    "metadata": {
      "name": "openldap",
      "created_by": "admin"
    },
    "spec": {
      "groups_prefix": "",
      "servers": [
        {
          "binding": {
            "password": "YOUR_PASSWORD",
            "user_dn": "cn=binder,dc=acme,dc=org"
          },
          "client_cert_file": "",
          "client_key_file": "",
          "default_upn_domain": "",
          "group_search": {
            "attribute": "member",
            "base_dn": "dc=acme,dc=org",
            "name_attribute": "cn",
            "object_class": "groupOfNames"
          },
          "host": "127.0.0.1",
          "insecure": false,
          "port": 636,
          "security": "tls",
          "trusted_ca_file": "",
          "user_search": {
            "attribute": "uid",
            "base_dn": "dc=acme,dc=org",
            "name_attribute": "cn",
            "object_class": "person"
          }
        }
      ],
      "username_prefix": ""
    }
  }
]

Get the configuration for a specific authentication provider

The /authproviders/:name API endpoint provides HTTP GET access to the authentication provider configuration for a specific :name.

Example

In the following example, an HTTP GET request is submitted to the /authproviders/:name API endpoint to retrieve the openldap authenthication provider configuration:

curl -X GET \
http://127.0.0.1:8080/api/enterprise/authentication/v2/authproviders/openldap \
-H "Authorization: Key $SENSU_API_KEY" \
-H 'Content-Type: application/json'

The request will return a successful HTTP/1.1 200 OK response and a JSON map that contains the requested authentication provider :name definition (in this example, openldap):

{
  "type": "ldap",
  "api_version": "authentication/v2",
  "metadata": {
    "name": "openldap",
    "created_by": "admin"
  },
  "spec": {
    "groups_prefix": "",
    "servers": [
      {
        "binding": {
          "password": "YOUR_PASSWORD",
          "user_dn": "cn=binder,dc=acme,dc=org"
        },
        "client_cert_file": "",
        "client_key_file": "",
        "default_upn_domain": "",
        "group_search": {
          "attribute": "member",
          "base_dn": "dc=acme,dc=org",
          "name_attribute": "cn",
          "object_class": "groupOfNames"
        },
        "host": "127.0.0.1",
        "insecure": false,
        "port": 636,
        "security": "tls",
        "trusted_ca_file": "",
        "user_search": {
          "attribute": "uid",
          "base_dn": "dc=acme,dc=org",
          "name_attribute": "cn",
          "object_class": "person"
        }
      }
    ],
    "username_prefix": ""
  }
}

API Specification

/authproviders/:name (GET)
description Returns the configuration for an authentication provider for the specified configured provider name.
example url http://hostname:8080/api/enterprise/authentication/v2/authproviders/openldap
response type Map
response codes
  • Success: 200 (OK)
  • Missing: 404 (Not Found)
  • Error: 500 (Internal Server Error)
output 
{
  "type": "ldap",
  "api_version": "authentication/v2",
  "metadata": {
    "name": "openldap",
    "created_by": "admin"
  },
  "spec": {
    "groups_prefix": "",
    "servers": [
      {
        "binding": {
          "password": "YOUR_PASSWORD",
          "user_dn": "cn=binder,dc=acme,dc=org"
        },
        "client_cert_file": "",
        "client_key_file": "",
        "default_upn_domain": "",
        "group_search": {
          "attribute": "member",
          "base_dn": "dc=acme,dc=org",
          "name_attribute": "cn",
          "object_class": "groupOfNames"
        },
        "host": "127.0.0.1",
        "insecure": false,
        "port": 636,
        "security": "tls",
        "trusted_ca_file": "",
        "user_search": {
          "attribute": "uid",
          "base_dn": "dc=acme,dc=org",
          "name_attribute": "cn",
          "object_class": "person"
        }
      }
    ],
    "username_prefix": ""
  }
}

Create or update the configuration for a specific authentication provider

The /authproviders/:name API endpoint provides HTTP PUT access to create or update the authentication provider configuration for a specific :name.

Example

In the following example, an HTTP PUT request is submitted to the /authproviders/:name API endpoint to create the openldap authenthication provider:

curl -X PUT \
-H "Authorization: Key $SENSU_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
  "Type": "ldap",
  "api_version": "authentication/v2",
  "spec": {
    "servers": [
      {
        "host": "127.0.0.1",
        "binding": {
          "user_dn": "cn=binder,dc=acme,dc=org",
          "password": "YOUR_PASSWORD"
        },
        "group_search": {
          "base_dn": "dc=acme,dc=org"
        },
        "user_search": {
          "base_dn": "dc=acme,dc=org"
        }
      }
    ]
  },
  "metadata": {
    "name": "openldap"
  }
}' \
http://127.0.0.1:8080/api/enterprise/authentication/v2/authproviders/openldap

The request will return a successful HTTP/1.1 201 Created response.

API Specification

/authproviders/:name (PUT)
description Creates or updates the authentication provider configuration for the specified name. Read the authentication guide for more information about supported providers.
example url http://hostname:8080/api/enterprise/authentication/v2/authproviders/openldap
payload 
{
  "Type": "ldap",
  "api_version": "authentication/v2",
  "spec": {
    "servers": [
      {
        "host": "127.0.0.1",
        "binding": {
          "user_dn": "cn=binder,dc=acme,dc=org",
          "password": "YOUR_PASSWORD"
        },
        "group_search": {
          "base_dn": "dc=acme,dc=org"
        },
        "user_search": {
          "base_dn": "dc=acme,dc=org"
        }
      }
    ]
  },
  "metadata": {
    "name": "openldap"
  }
}
payload parameters All attributes shown in the example payload are required. For more information about configuring authentication providers, read the authentication guide.
response codes
  • Success: 200 (OK)
  • Malformed: 400 (Bad Request)
  • Error: 500 (Internal Server Error)

Delete the configuration for a specific authentication provider

The /authproviders/:name API endpoint provides HTTP DELETE access to delete the authentication provider configuration from Sensu for a specific :name.

Example

The following example shows a request to the /authproviders/:name API endpoint to delete the configuration for the authentication provider openldap, resulting in a successful HTTP/1.1 204 No Content response:

curl -X DELETE \
-H "Authorization: Key $SENSU_API_KEY" \
http://127.0.0.1:8080/api/core/v2/namespaces/default/authproviders/openldap

API Specification

/authproviders/:name (DELETE)
description Deletes the authentication provider configuration from Sensu for the specified name.
example url http://hostname:8080/api/enterprise/authentication/v2/authproviders/openldap
response codes
  • Success: 204 (No Content)
  • Missing: 404 (Not Found)
  • Error: 500 (Internal Server Error)