Skip to content

Add documentation for JWT support over gRPC #11852

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
natebower merged 3 commits into from
Feb 9, 2026
Merged

Add documentation for JWT support over gRPC #11852

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
2f49bb1
Add gRPC JWT support.
finnegancarroll Feb 5, 2026
d03200a
Fix technical detail - gRPC with TLS != HTTPS necessarily.
finnegancarroll Feb 9, 2026
25b070c
Doc review
kolchfa-aws Feb 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions _security/authentication-backends/jwt.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -332,6 +332,18 @@ JWT authentication supports direct JWKS endpoint configuration starting with Ope
- When both `jwks_uri` and `signing_key` are configured, `jwks_uri` takes precedence and `signing_key` is ignored.


## Using JWT authentication with gRPC
**Introduced 3.5**
{: .label .label-purple }

JWT authentication is supported over the gRPC transport. The gRPC transport shares the same authentication domains as the HTTP layer, so JWT tokens are validated against the same authentication backend configuration. You can provide the same JWT headers over gRPC as you would when using the REST API.

When transmitting JWTs over gRPC, you must enable TLS. For information about configuring TLS for gRPC, see [Configuring TLS certificates for gRPC]({{site.url}}{{site.baseurl}}/security/configuration/tls/#configuring-tls-certificates-for-grpc).

Note the following limitations:

- Superuser authentication (client certificate authentication) is not supported over gRPC. Configuration changes requiring superuser privileges must use the REST API.
- Anonymous authentication is not supported over gRPC. Requests with anonymous authentication headers are rejected as unauthorized.

## Troubleshooting common issues

Expand Down
6 changes: 6 additions & 0 deletions _security/configuration/configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -152,6 +152,12 @@
The default `config/opensearch-security/config.yml` file included in your OpenSearch distribution contains many configuration examples. Use these examples as a starting point and customize them to your needs.


## Authentication and authorization over gRPC
**Introduced 3.5**
{: .label .label-purple }

When the Security plugin is enabled and not running in SSL-only mode, requests over gRPC are subject to authentication and authorization. The gRPC transport shares all authentication backends with the HTTP layer and respects the `http_enabled` setting in authentication domains. As of OpenSearch 3.5, only JWT authentication is supported over gRPC. For more information, see [Using JWT authentication with gRPC]({{site.url}}{{site.baseurl}}/security/authentication-backends/jwt/#using-jwt-authentication-with-grpc).

Check failure on line 159 in _security/configuration/configuration.md

View workflow job for this annotation

GitHub Actions / style-job 

[vale] reported by reviewdog 🐶
[OpenSearch.Spelling] Error: infor. If you are referencing a setting, variable, format, function, or repository, surround it with tic marks.

Raw Output:
{"message": "[OpenSearch.Spelling] Error: infor. If you are referencing a setting, variable, format, function, or repository, surround it with tic marks.", "location": {"path": "_security/configuration/configuration.md", "range": {"start": {"line": 159, "column": 359}}}, "severity": "ERROR"}

## Next steps

To learn about configuring the authentication backends, see the [Authentication backends]({{site.url}}{{site.baseurl}}/security/authentication-backends/) documentation. Alternatively, you can view documentation for a specific backend by using the links in the following list of topics:
Expand Down
3 changes: 0 additions & 3 deletions _security/configuration/tls.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -312,9 +312,6 @@ You should receive the following response:

## Configuring TLS certificates for gRPC

gRPC supports encryption in transit only. Trust stores and certificates configured as root CAs in PEM format are used only for the purpose of TLS client authorization. Role-based access is not available for gRPC endpoints.
{: .warning}

You can configure TLS on the optional gRPC transport in `opensearch.yml`. For more information about using the gRPC plugin, see [Enabling gRPC APIs]({{site.url}}{{site.baseurl}}/api-reference/grpc-apis/index/#grpc-settings).

### PEM key settings (X.509 PEM certificates and PKCS #8 keys)
Expand Down
Loading