iSharkFly-Docs/opensearch-docs-cn
1
0
Fork 0
mirror of https://github.com/iSharkFly-Docs/opensearch-docs-cn synced 2025-02-18 10:14:52 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add documentation for jwt_clock_skew_tolerance_seconds setting that resolves authentication errors (#3251)

Browse Source 
* fix#3220 auth fail from clock skew

Signed-off-by: cwillum <cwmmoore@amazon.com>

* fix#3220 auth fail from clock skew

Signed-off-by: cwillum <cwmmoore@amazon.com>

* fix#3220 auth fail from clock skew

Signed-off-by: cwillum <cwmmoore@amazon.com>

* fix#3220 auth fail from clock skew

Signed-off-by: cwillum <cwmmoore@amazon.com>

* fix#3220 auth fail from clock skew

Signed-off-by: cwillum <cwmmoore@amazon.com>

* fix#3220 auth fail from clock skew

Signed-off-by: cwillum <cwmmoore@amazon.com>

---------

Signed-off-by: cwillum <cwmmoore@amazon.com>
This commit is contained in:
Chris Moore 2023-03-28 13:48:18 -07:00 committed by GitHub
parent 93544235f0
commit 15d324d30c
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 98 additions and 63 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

56
_security/authentication-backends/openid-connect.md
View File

@ -7,26 +7,26 @@ nav_order: 50
# OpenID Connect
The security plugin can integrate with identify providers that use the OpenID Connect standard. This feature enables the following:
The Security plugin can integrate with identify providers that use the OpenID Connect standard. This feature enables the following:
* Automatic configuration
Point the security plugin to the metadata of your identity provider (IdP), and the security plugin uses that data for configuration.
Point the Security plugin to the metadata of your identity provider (IdP), and the Security plugin uses that data for configuration.
* Automatic key fetching
The security plugin automatically retrieves the public key for validating the JSON web tokens (JWTs) from the JSON web key set (JWKS) endpoint of your IdP. You don't have to configure keys or shared secrets in `config.yml`.
The Security plugin automatically retrieves the public key for validating the JSON Web Tokens (JWTs) from the JSON Web Key Set (JWKS) endpoint of your IdP. You don't have to configure keys or shared secrets in `config.yml`.
* Key rollover
You can change the keys used for signing the JWTs directly in your IdP. If the security plugin detects an unknown key, it tries to retrieve it from the IdP. This rollover is transparent to the user.
You can change the keys used for signing the JWTs directly in your IdP. If the Security plugin detects an unknown key, it tries to retrieve it from the IdP. This rollover is transparent to the user.
* OpenSearch Dashboards as single sign-on or as one option among multiple authentication types in the Dashboards sign-in window.
## Configure OpenID Connect integration
To integrate with an OpenID IdP, set up an authentication domain and choose `openid` as the HTTP authentication type. JSON web tokens already contain all required information to verify the request, so set `challenge` to `false` and `authentication_backend` to `noop`.
To integrate with an OpenID IdP, set up an authentication domain and choose `openid` as the HTTP authentication type. JWTs already contain all of the information required to verify the request, so set `challenge` to `false` and `authentication_backend` to `noop`.
This is the minimal configuration:
@ -50,7 +50,7 @@ The following table shows the configuration parameters.
Name | Description
:--- | :---
`openid_connect_url` | The URL of your IdP where the security plugin can find the OpenID Connect metadata/configuration settings. This URL differs between IdPs. Required.
`openid_connect_url` | The URL of your IdP where the Security plugin can find the OpenID Connect metadata/configuration settings. This URL differs between IdPs. Required.
`jwt_header` | The HTTP header that stores the token. Typically the `Authorization` header with the `Bearer` schema: `Authorization: Bearer <token>`. Optional. Default is `Authorization`.
`jwt_url_parameter` | If the token is not transmitted in the HTTP header, but as an URL parameter, define the name of the parameter here. Optional.
`subject_key` | The key in the JSON payload that stores the user's name. If not defined, the [subject](https://tools.ietf.org/html/rfc7519#section-4.1.2) registered claim is used. Most IdP providers use the `preferred_username` claim. Optional.
@ -59,7 +59,7 @@ Name | Description
## OpenID Connect URL
OpenID Connect specifies various endpoints for integration purposes. The most important endpoint is `well-known`, which lists endpoints and other configuration options for the security plugin.
OpenID Connect specifies various endpoints for integration purposes. The most important endpoint is `well-known`, which lists endpoints and other configuration options for the Security plugin.
The URL differs between IdPs, but usually ends in `/.well-known/openid-configuration`.
@ -69,7 +69,7 @@ Keycloak example:
http(s)://<server>:<port>/auth/realms/<realm>/.well-known/openid-configuration
```
The main information that the security plugin needs is `jwks_uri`. This URI specifies where the IdP's public keys in JWKS format can be found. For example:
The main information that the Security plugin needs is `jwks_uri`. This URI specifies where the IdP's public keys in JWKS format can be found. For example:
```
jwks_uri: "https://keycloak.example.com:8080/auth/realms/master/protocol/openid-connect/certs"
@ -100,9 +100,27 @@ For more information about IdP endpoints, see the following:
- [IBM OpenID Connect](https://www.ibm.com/support/knowledgecenter/en/SSEQTP_8.5.5/com.ibm.websphere.wlp.doc/ae/rwlp_oidc_endpoint_urls.html)
## Time disparity compensation for JWT validation
Occasionally you may find that the clock times between the authentication server and the OpenSearch node are not perfectly synchronized. When this is the case, even by a few seconds, the system that either issues or receives a JWT may try to validate `nbf` (not before) and `exp` (expiration) claims and fail to authenticate the user due to the time disparity.
By default, Security allows for a window of 30 seconds to compensate for possible misalignment between server clock times. To set a custom value for this feature and override the default, you can add the `jwt_clock_skew_tolerance_seconds` setting to the `config.yml`:
```yml
http_authenticator:
type: openid
challenge: false
config:
subject_key: preferred_username
roles_key: roles
openid_connect_url: https://keycloak.example.com:8080/auth/realms/master/.well-known/openid-configuration
jwt_clock_skew_tolerance_seconds: 20
```
## Fetching public keys
When an IdP generates and signs a JSON web token, it must add the ID of the key to the JWT header. For example:
When an IdP generates and signs a JWT, it must add the ID of the key to the JWT header. For example:
```
{
@ -114,12 +132,12 @@ When an IdP generates and signs a JSON web token, it must add the ID of the key
As per the [OpenID Connect specification](https://openid.net/specs/openid-connect-messages-1_0-20.html), the `kid` (key ID) is mandatory. Token verification does not work if an IdP fails to add the `kid` field to the JWT.
If the security plugin receives a JWT with an unknown `kid`, it visits the IdP's `jwks_uri` and retrieves all available, valid keys. These keys are used and cached until a refresh is triggered by retrieving another unknown key ID.
If the Security plugin receives a JWT with an unknown `kid`, it visits the IdP's `jwks_uri` and retrieves all available, valid keys. These keys are used and cached until a refresh is triggered by retrieving another unknown key ID.
## Key rollover and multiple public keys
The security plugin can maintain multiple valid public keys at once. The OpenID specification does not allow for a validity period of public keys, so a key is valid until it has been removed from the list of valid keys in your IdP and the list of valid keys has been refreshed.
The Security plugin can maintain multiple valid public keys at once. The OpenID specification does not allow for a validity period of public keys, so a key is valid until it has been removed from the list of valid keys in your IdP and the list of valid keys has been refreshed.
If you want to roll over a key in your IdP, follow these best practices:
@ -127,7 +145,7 @@ If you want to roll over a key in your IdP, follow these best practices:
Your IdP uses this new key over the old key.
- Upon first appearance of the new `kid` in a JWT, the security plugin refreshes the key list.
- Upon first appearance of the new `kid` in a JWT, the Security plugin refreshes the key list.
At this point, both the old key and the new key are valid. Tokens signed with the old key are also still valid.
@ -138,7 +156,7 @@ If you have to immediately change your public key, you can also delete the old k
## TLS settings
To prevent man-in-the-middle attacks, you should secure the connection between the security plugin and your IdP with TLS.
To prevent man-in-the-middle attacks, you should secure the connection between the Security plugin and your IdP with TLS.
### Enabling TLS
@ -181,15 +199,15 @@ config:
```
Name | Description
:--- | :---
`pemtrustedcas_filepath` | Absolute path to the PEM file containing the root CAs of your IdP.
`pemtrustedcas_content` | The root CA content of your IdP. Cannot be used if `pemtrustedcas_filepath` is set.
| Name | Description |
| :--- | :--- |
| `pemtrustedcas_filepath` | Absolute path to the PEM file containing the root CAs of your IdP. |
| `pemtrustedcas_content` | The root CA content of your IdP. Cannot be used if `pemtrustedcas_filepath` is set. |
### TLS client authentication
To use TLS client authentication, configure the PEM certificate and private key the security plugin should send for TLS client authentication (or its content):
To use TLS client authentication, configure the PEM certificate and private key the Security plugin should send for TLS client authentication (or its content):
```yml
config:
@ -239,7 +257,7 @@ Name | Description
## (Advanced) DoS protection
To help protect against denial-of-service (DoS) attacks, the security plugin only allows a maximum number of new key IDs in a certain span of time. If the number of new key IDs exceeds this threshold, the security plugin returns HTTP status code 503 (Service Unavailable) and refuses to query the IdP. By default, the security plugin does not allow for more than 10 unknown key IDs within 10 seconds. The following table shows how to modify these settings.
To help protect against denial-of-service (DoS) attacks, the Security plugin only allows a maximum number of new key IDs in a certain span of time. If the number of new key IDs exceeds this threshold, the Security plugin returns HTTP status code 503 (Service Unavailable) and refuses to query the IdP. By default, the Security plugin does not allow for more than 10 unknown key IDs within 10 seconds. The following table shows how to modify these settings.
Name | Description
:--- | :---

35
_security/authentication-backends/saml.md
View File

@ -10,9 +10,9 @@ redirect_from:
# SAML
The security plugin supports user authentication through SAML single sign-on. The security plugin implements the web browser SSO profile of the SAML 2.0 protocol.
The Security plugin supports user authentication through SAML single sign-on. The Security plugin implements the web browser SSO profile of the SAML 2.0 protocol.
This profile is meant for use with web browsers. It is not a general-purpose way of authenticating users against the security plugin, so its primary use case is to support OpenSearch Dashboards single sign-on.
This profile is meant for use with web browsers. It is not a general-purpose way of authenticating users against the Security plugin, so its primary use case is to support OpenSearch Dashboards single sign-on.
## Docker example
@ -93,7 +93,7 @@ authc:
## Identity provider metadata
A SAML identity provider (IdP) provides a SAML 2.0 metadata file describing the IdP's capabilities and configuration. The security plugin can read IdP metadata either from a URL or a file. The choice that you make depends on your IdP and your preferences. The SAML 2.0 metadata file is required.
A SAML identity provider (IdP) provides a SAML 2.0 metadata file describing the IdP's capabilities and configuration. The Security plugin can read IdP metadata either from a URL or a file. The choice that you make depends on your IdP and your preferences. The SAML 2.0 metadata file is required.
Name | Description
:--- | :---
@ -110,6 +110,21 @@ Name | Description
`idp.entity_id` | The entity ID of your IdP. Required.
`sp.entity_id` | The entity ID of the service provider. Required.
## Time disparity compensation for JWT validation
Occasionally you may find that the clock times between the authentication server and the OpenSearch node are not perfectly synchronized. When this is the case, even by a few seconds, the system that either issues or receives a JSON Web Token (JWT) may try to validate `nbf` (not before) and `exp` (expiration) claims and fail to authenticate the user due to the time disparity.
By default, OpenSearch Security allows for a window of 30 seconds to compensate for possible misalignment between server clock times. To set a custom value for this feature and override the default, you can add the `jwt_clock_skew_tolerance_seconds` setting to the `config.yml`.
```yml
http_authenticator:
type: saml
challenge: true
config:
idp:
metadata_file: okta.xml
jwt_clock_skew_tolerance_seconds: 20
```
## OpenSearch Dashboards settings
@ -152,7 +167,7 @@ Name | Description
## Request signing
Requests from the security plugin to the IdP can optionally be signed. Use the following settings to configure request signing.
Requests from the Security plugin to the IdP can optionally be signed. Use the following settings to configure request signing.
Name | Description
:--- | :---
@ -161,7 +176,7 @@ Name | Description
`sp.signature_private_key_filepath` | Path to the private key. The file must be placed under the OpenSearch `config` directory, and the path must be specified relative to that same directory.
`sp.signature_algorithm` | The algorithm used to sign the requests. See the next table for possible values.
The security plugin supports the following signature algorithms.
The Security plugin supports the following signature algorithms.
Algorithm | Value
:--- | :---
@ -174,18 +189,18 @@ RSA_SHA512 | http://www.w3.org/2001/04/xmldsig-more#rsa-sha512;
## Logout
Usually, IdPs provide information about their individual logout URL in their SAML 2.0 metadata. If this is the case, the security plugin uses them to render the correct logout link in OpenSearch Dashboards. If your IdP does not support an explicit logout, you can force a re-login when the user visits OpenSearch Dashboards again.
Usually, IdPs provide information about their individual logout URL in their SAML 2.0 metadata. If this is the case, the Security plugin uses them to render the correct logout link in OpenSearch Dashboards. If your IdP does not support an explicit logout, you can force a re-login when the user visits OpenSearch Dashboards again.
Name | Description
:--- | :---
`sp.forceAuthn` | Force a re-login even if the user has an active session with the IdP.
Currently, the security plugin supports only the `HTTP-Redirect` logout binding. Make sure this is configured correctly in your IdP.
Currently, the Security plugin supports only the `HTTP-Redirect` logout binding. Make sure this is configured correctly in your IdP.
## Exchange key settings
SAML, unlike other protocols, is not meant to be used for exchanging user credentials with each request. The security plugin trades the SAML response for a lightweight JSON web token that stores the validated user attributes. This token is signed by an exchange key that you can choose freely. Note that when you change this key, all tokens signed with it become invalid immediately.
SAML, unlike other protocols, is not meant to be used for exchanging user credentials with each request. The Security plugin trades the SAML response for a lightweight JWT that stores the validated user attributes. This token is signed by an exchange key of your choice. Note that when you change this key, all tokens signed with it become invalid immediately.
Name | Description
:--- | :---
@ -250,7 +265,7 @@ Name | Description
### Client authentication
The security plugin can use TLS client authentication when fetching the IdP metadata. If enabled, the security plugin sends a TLS client certificate to the IdP for each metadata request. Use the following keys to configure client authentication.
The Security plugin can use TLS client authentication when fetching the IdP metadata. If enabled, the Security plugin sends a TLS client certificate to the IdP for each metadata request. Use the following keys to configure client authentication.
Name | Description
:--- | :---
@ -299,7 +314,7 @@ authc:
## OpenSearch Dashboards configuration
Because most of the SAML-specific configuration is done in the security plugin, just activate SAML in your `opensearch_dashboards.yml` by adding the following:
Because most of the SAML-specific configuration is done in the Security plugin, just activate SAML in your `opensearch_dashboards.yml` by adding the following:
```yml
opensearch_security.auth.type: "saml"

70
_security/configuration/configuration.md
View File

@ -7,9 +7,9 @@ nav_order: 5
# Configuring the Security backend
One of the first steps to using the security plugin is to decide on an authentication backend, which handles [steps 2-3 of the authentication flow]({{site.url}}{{site.baseurl}}/security/authentication-backends/authc-index/#authentication-flow). The plugin has an internal user database, but many people prefer to use an existing authentication backend, such as an LDAP server, or some combination of the two.
One of the first steps to using the Security plugin is to decide on an authentication backend, which handles [steps 2-3 of the authentication flow]({{site.url}}{{site.baseurl}}/security/authentication-backends/authc-index/#authentication-flow). The plugin has an internal user database, but many people prefer to use an existing authentication backend, such as an LDAP server, or some combination of the two.
The main configuration file for authentication and authorization backends is `config/opensearch-security/config.yml`. It defines how the security plugin retrieves the user credentials, how it verifies these credentials, and how to fetch additional roles from backend systems (optional).
The main configuration file for authentication and authorization backends is `config/opensearch-security/config.yml`. It defines how the Security plugin retrieves the user credentials, how it verifies these credentials, and how to fetch additional roles from backend systems (optional).
`config.yml` has three main parts:
@ -41,7 +41,7 @@ xff: # optional section
trustedProxies: <string> # Regex pattern
```
If you disable anonymous authentication, the security plugin won't initialize if you have not provided at least one `authc`.
If you disable anonymous authentication, the Security plugin won't initialize if you have not provided at least one `authc`.
## Authentication
@ -61,7 +61,7 @@ The `authc` section has the following format:
An entry in the `authc` section is called an *authentication domain*. It specifies where to get the user credentials and against which backend they should be authenticated.
You can use more than one authentication domain. Each authentication domain has a name (for example, `basic_auth_internal`), `enabled` flags, and an `order`. The order makes it possible to chain authentication domains together. The security plugin uses them in the order that you provide. If the user successfully authenticates with one domain, the security plugin skips the remaining domains.
You can use more than one authentication domain. Each authentication domain has a name (for example, `basic_auth_internal`), `enabled` flags, and an `order`. The order makes it possible to chain authentication domains together. The Security plugin uses them in the order that you provide. If the user successfully authenticates with one domain, the Security plugin skips the remaining domains.
`http_authenticator` specifies which authentication method that you want to use on the HTTP layer.
@ -78,8 +78,8 @@ http_authenticator:
These are the allowed values for `type`:
- `basic`: HTTP basic authentication. No additional configuration is needed.
- `kerberos`: Kerberos authentication. Additional, [Kerberos-specific configuration](#kerberos) is needed.
- `jwt`: JSON web token authentication. Additional, [JWT-specific configuration](#json-web-token) is needed.
- `kerberos`: Kerberos authentication. Additional [Kerberos-specific configuration](#kerberos) is needed.
- `jwt`: JSON Web Token (JWT) authentication. Additional [JWT-specific configuration](#json-web-token) is needed.
- `clientcert`: Authentication through a client TLS certificate. This certificate must be trusted by one of the root CAs in the truststore of your nodes.
After setting an HTTP authenticator, you must specify against which backend system you want to authenticate the user:
@ -100,7 +100,7 @@ These are the possible values for `type`:
## Authorization
After the user has been authenticated, the security plugin can optionally collect additional roles from backend systems. The authorization configuration has the following format:
After the user has been authenticated, the Security plugin can optionally collect additional roles from backend systems. The authorization configuration has the following format:
```yml
authz:
@ -136,16 +136,16 @@ http_authenticator:
challenge: true
```
In most cases, you set the `challenge` flag to `true`. The flag defines the behavior of the security plugin if the `Authorization` field in the HTTP header is not set.
In most cases, you set the `challenge` flag to `true`. The flag defines the behavior of the Security plugin if the `Authorization` field in the HTTP header is not set.
If `challenge` is set to `true`, the security plugin sends a response with status `UNAUTHORIZED` (401) back to the client. If the client is accessing the cluster with a browser, this triggers the authentication dialog box, and the user is prompted to enter a user name and password.
If `challenge` is set to `true`, the Security plugin sends a response with status `UNAUTHORIZED` (401) back to the client. If the client is accessing the cluster with a browser, this triggers the authentication dialog box, and the user is prompted to enter a user name and password.
If `challenge` is set to `false` and no `Authorization` header field is set, the security plugin does not send a `WWW-Authenticate` response back to the client, and authentication fails. You might want to use this setting if you have another challenge `http_authenticator` in your configured authentication domains. One such scenario is when you plan to use basic authentication and Kerberos together.
If `challenge` is set to `false` and no `Authorization` header field is set, the Security plugin does not send a `WWW-Authenticate` response back to the client, and authentication fails. You might want to use this setting if you have another challenge `http_authenticator` in your configured authentication domains. One such scenario is when you plan to use basic authentication and Kerberos together.
### Kerberos
Kerberos authentication does not work with OpenSearch Dashboards. To track OpenSearch's progress in adding support for Kerberos in OpenSearch Dashboards, see [issue #907](https://github.com/opensearch-project/security-dashboards-plugin/issues/907) in the Dashboard's Security Plugin repository.
Kerberos authentication does not work with OpenSearch Dashboards. To track OpenSearch's progress in adding support for Kerberos in OpenSearch Dashboards, see [issue #907](https://github.com/opensearch-project/security-dashboards-plugin/issues/907) in the Dashboard's Security plugin repository.
{: .warning }
Due to the nature of Kerberos, you must define some settings in `opensearch.yml` and some in `config.yml`.
@ -159,9 +159,9 @@ plugins.security.kerberos.acceptor_keytab_filepath: 'eskeytab.tab'
- `plugins.security.kerberos.krb5_filepath` defines the path to your Kerberos configuration file. This file contains various settings regarding your Kerberos installation, for example, the realm names, hostnames, and ports of the Kerberos key distribution center (KDC).
- `plugins.security.kerberos.acceptor_keytab_filepath` defines the path to the keytab file, which contains the principal that the security plugin uses to issue requests against Kerberos.
- `plugins.security.kerberos.acceptor_keytab_filepath` defines the path to the keytab file, which contains the principal that the Security plugin uses to issue requests against Kerberos.
- `plugins.security.kerberos.acceptor_principal: 'HTTP/localhost'` defines the principal that the security plugin uses to issue requests against Kerberos. This value must be present in the keytab file.
- `plugins.security.kerberos.acceptor_principal: 'HTTP/localhost'` defines the principal that the Security plugin uses to issue requests against Kerberos. This value must be present in the keytab file.
Due to security restrictions, the keytab file must be placed in `config` or a subdirectory, and the path in `opensearch.yml` must be relative, not absolute.
{: .note }
@ -188,13 +188,13 @@ A typical Kerberos authentication domain in `config.yml` looks like this:
Authentication against Kerberos through a browser on an HTTP level is achieved using SPNEGO. Kerberos/SPNEGO implementations vary, depending on your browser and operating system. This is important when deciding if you need to set the `challenge` flag to `true` or `false`.
As with [HTTP Basic Authentication](#http-basic), this flag determines how the security plugin should react when no `Authorization` header is found in the HTTP request or if this header does not equal `negotiate`.
As with [HTTP Basic Authentication](#http-basic), this flag determines how the Security plugin should react when no `Authorization` header is found in the HTTP request or if this header does not equal `negotiate`.
If set to `true`, the security plugin sends a response with status code 401 and a `WWW-Authenticate` header set to `negotiate`. This tells the client (browser) to resend the request with the `Authorization` header set. If set to `false`, the security plugin cannot extract the credentials from the request, and authentication fails. Setting `challenge` to `false` thus makes sense only if the Kerberos credentials are sent in the initial request.
If set to `true`, the Security plugin sends a response with status code 401 and a `WWW-Authenticate` header set to `negotiate`. This tells the client (browser) to resend the request with the `Authorization` header set. If set to `false`, the Security plugin cannot extract the credentials from the request, and authentication fails. Setting `challenge` to `false` thus makes sense only if the Kerberos credentials are sent in the initial request.
As the name implies, setting `krb_debug` to `true` will output Kerberos-specific debugging messages to `stdout`. Use this setting if you encounter problems with your Kerberos integration.
If you set `strip_realm_from_principal` to `true`, the security plugin strips the realm from the user name.
If you set `strip_realm_from_principal` to `true`, the Security plugin strips the realm from the user name.
#### Authentication backend
@ -202,9 +202,9 @@ If you set `strip_realm_from_principal` to `true`, the security plugin strips th
Because Kerberos/SPNEGO authenticates users on an HTTP level, no additional `authentication_backend` is needed. Set this value to `noop`.
### JSON web token
### JSON Web Token
JSON web tokens (JWTs) are JSON-based access tokens that assert one or more claims. They are commonly used to implement single sign-on (SSO) solutions and fall in the category of token-based authentication systems:
JWTs are JSON-based access tokens that assert one or more claims. They are commonly used to implement single sign-on (SSO) solutions and fall in the category of token-based authentication systems:
1. A user logs in to an authentication server by providing credentials (for example, a user name and password).
1. The authentication server validates the credentials.
@ -214,9 +214,9 @@ JSON web tokens (JWTs) are JSON-based access tokens that assert one or more clai
1. The user sends the access token alongside every request to the service that it wants to use.
1. The service verifies the token and grants or denies access.
A JSON web token is self-contained in the sense that it carries all necessary information to verify a user within itself. The tokens are base64-encoded, signed JSON objects.
A JWT is self-contained in the sense that it carries within itself all of the information necessary to verify a user. The tokens are base64-encoded, signed JSON objects.
JSON web tokens consist of three parts:
JWTs consist of three parts:
1. Header
1. Payload
@ -239,9 +239,9 @@ In this case, the header states that the message was signed using HMAC-SHA256.
#### Payload
The payload of a JSON web token contains the so-called [JWT Claims](https://self-issued.info/docs/draft-ietf-oauth-json-web-token.html#RegisteredClaimName). A claim can be any piece of information about the user that the application that created the token has verified.
The payload of a JWT contains the [JWT claims](https://auth0.com/docs/secure/tokens/json-web-tokens/json-web-token-claims). A claim can be any piece of information about the user that the application that created the token has verified.
The specification defines a set of standard claims with reserved names ("registered claims"). These include, for example, the token issuer, the expiration date, or the creation date.
The specification defines a set of standard claims with reserved names, referred to as [registered claims](https://www.iana.org/assignments/jwt/jwt.xhtml#claims). Some examples of these claims include token issuer (iss), expiration time (exp), and subject (sub).
Public claims, on the other hand, can be created freely by the token issuer. They can contain arbitrary information, such as the user name and the roles of the user.
@ -258,7 +258,7 @@ Public claims, on the other hand, can be created freely by the token issuer. The
#### Signature
The issuer of the token calculates the signature of the token by applying a cryptographic hash function on the base64-encoded header and payload. These three parts are then concatenated using periods to form a complete JSON web token:
The issuer of the token calculates the signature of the token by applying a cryptographic hash function on the base64-encoded header and payload. These three parts are then concatenated using periods to form a complete JWT:
```
encoded = base64UrlEncode(header) + "." + base64UrlEncode(payload)
@ -272,9 +272,9 @@ eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJsb2dnZWRJbkFzIjoiYWRtaW4iLCJpYXQiOjE0MjI
```
## Configure JSON web tokens
## Configure JWTs
If you use JSON web token as your only authentication method, disable the user cache by setting `plugins.security.cache.ttl_minutes: 0`.
If you use a JWT as your only authentication method, disable the user cache by setting `plugins.security.cache.ttl_minutes: 0`.
{: .warning }
Set up an authentication domain and choose `jwt` as the HTTP authentication type. Because the tokens already contain all required information to verify the request, `challenge` must be set to `false` and `authentication_backend` to `noop`.
@ -293,6 +293,7 @@ jwt_auth_domain:
jwt_url_parameter: null
subject_key: null
roles_key: null
jwt_clock_skew_tolerance_seconds: 20
authentication_backend:
I type: noop
```
@ -306,13 +307,14 @@ Name | Description
`jwt_url_parameter` | If the token is not transmitted in the HTTP header, but as an URL parameter, define the name of this parameter here.
`subject_key` | The key in the JSON payload that stores the user name. If not set, the [subject](https://tools.ietf.org/html/rfc7519#section-4.1.2) registered claim is used.
`roles_key` | The key in the JSON payload that stores the user's roles. The value of this key must be a comma-separated list of roles.
`jwt_clock_skew_tolerance_seconds` | Sets a window of time, in seconds, to prevent authentication failures due to a misalignment between the JWT authentication server and OpenSearch node clock times. Security sets 30 seconds as the default. Use this setting to apply a custom value.
Because JSON web tokens are self-contained and the user is authenticated on the HTTP level, no additional `authentication_backend` is needed. Set this value to `noop`.
Because JWTs are self-contained and the user is authenticated at the HTTP level, no additional `authentication_backend` is needed. Set this value to `noop`.
### Symmetric key algorithms: HMAC
Hash-based message authentication codes (HMACs) are a group of algorithms that provide a way of signing messages by means of a shared key. The key is shared between the authentication server and the security plugin. It must be configured as a base64-encoded value in the `signing_key` setting:
Hash-based message authentication codes (HMACs) are a group of algorithms that provide a way of signing messages by means of a shared key. The key is shared between the authentication server and the Security plugin. It must be configured as a base64-encoded value in the `signing_key` setting:
```yml
jwt_auth_domain:
@ -325,7 +327,7 @@ jwt_auth_domain:
### Asymmetric key algorithms: RSA and ECDSA
RSA and ECDSA are asymmetric encryption and digital signature algorithms and use a public/private key pair to sign and verify tokens. This means that they use a private key for signing the token, while the security plugin needs to know only the public key to verify it.
RSA and ECDSA are asymmetric encryption and digital signature algorithms and use a public/private key pair to sign and verify tokens. This means that they use a private key for signing the token, while the Security plugin needs to know only the public key to verify it.
Because you cannot issue new tokens with the public key---and because you can make valid assumptions about the creator of the token---RSA and ECDSA are considered more secure than using HMAC.
@ -342,12 +344,12 @@ jwt_auth_domain:
...
```
The security plugin automatically detects the algorithm (RSA/ECDSA), and if necessary you can break the key into multiple lines.
The Security plugin automatically detects the algorithm (RSA/ECDSA), and if necessary you can break the key into multiple lines.
### Bearer authentication for HTTP requests
The most common way of transmitting a JSON web token in an HTTP request is to add it as an HTTP header with the bearer authentication schema:
The most common way of transmitting a JWT in an HTTP request is to add it as an HTTP header with the bearer authentication schema:
```
Authorization: Bearer <JWT>
@ -355,12 +357,12 @@ Authorization: Bearer <JWT>
The default name of the header is `Authorization`. If required by your authentication server or proxy, you can also use a different HTTP header name using the `jwt_header` configuration key.
As with HTTP basic authentication, you should use HTTPS instead of HTTP when transmitting JSON web tokens in HTTP requests.
As with HTTP basic authentication, you should use HTTPS instead of HTTP when transmitting JWTs in HTTP requests.
### URL parameters for HTTP requests
Although the most common way to transmit JWTs in HTTP requests is to use a header field, the security plugin also supports parameters. Configure the name of the `GET` parameter using the following key:
Although the most common way to transmit JWTs in HTTP requests is to use a header field, the Security plugin also supports parameters. Configure the name of the `GET` parameter using the following key:
```yml
config:
@ -384,7 +386,7 @@ The following registered claims are validated automatically:
### Supported formats and algorithms
The security plugin supports digitally signed, compact JSON web tokens with all standard algorithms:
The Security plugin supports digitally signed, compact JWTs with all standard algorithms:
```
HS256: HMAC using SHA-256
@ -403,7 +405,7 @@ ES512: ECDSA using P-521 and SHA-512
## Troubleshooting common issues
This section details how to troubleshoot common issues with your security plugin configuration.
This section details how to troubleshoot common issues with your Security plugin configuration.
#### Correct iat