diff --git a/README.md b/README.md index a33ec55..de948ee 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ - Authenticate HTTP requests with JWT tokens via middleware that can be configured via YAML/JSON file or environment variables. - Authorize HTTP requests with JWT tokens by verifying access based on the roles in the JWT claims. - Fetch and cache JSON Web Key Sets (JWKS) from Identity Providers (IDP). -- Introspect Access Tokens via the OAuth 2.0 Token Introspection endpoint. +- Introspect Access Tokens via OAuth 2.0 Token Introspection endpoint. - Fetch and cache Access Tokens from Identity Providers (IDP). - Provides primitives for testing authentication and authorization in HTTP services. @@ -26,8 +26,8 @@ import ( ) type Claims struct { - jwtgo.RegisteredClaims - Scope []AccessPolicy `json:"scope,omitempty"` + jwtgo.RegisteredClaims + Scope []AccessPolicy `json:"scope,omitempty"` // ... } @@ -100,14 +100,14 @@ import ( ) type IntrospectionResult struct { - Active bool `json:"active"` - TokenType string `json:"token_type,omitempty"` - jwt.Claims + Active bool `json:"active"` + TokenType string `json:"token_type,omitempty"` + jwt.Claims } ``` The Token Introspection endpoint may be configured statically or obtained from the OpenID Connect Discovery response (GET /.well-known/openid-configuration request for the issuer URL). -In the case of the static configuration, gRPC could be used instead of HTTP for the introspection request (see [idp_token.proto](./idptoken/idp_token.proto) for details). +In case of the static configuration, gRPC could be used instead of HTTP for the introspection request (see [idp_token.proto](./idptoken/idp_token.proto) for details). `NewTokenIntrospector()` function creates an introspector that can be used to introspect access tokens. @@ -149,7 +149,7 @@ func main() { accessToken, err := provider.GetToken(ctx) if err != nil { log.Fatalf("failed to get access token: %v", err) - } + } // ... } ``` diff --git a/examples/token-introspection/README.md b/examples/token-introspection/README.md index 8d0f81e..2fba418 100644 --- a/examples/token-introspection/README.md +++ b/examples/token-introspection/README.md @@ -72,4 +72,37 @@ Hi, admin2 Service logs: ``` {"level":"info","time":"2024-10-07T10:48:24.885616+03:00","msg":"response completed in 0.003s","pid":84516,"request_id":"","int_request_id":"","trace_id":"","method":"GET","uri":"/admin","remote_addr":"127.0.0.1:51527","content_length":0,"user_agent":"curl/8.7.1","remote_addr_ip":"127.0.0.1","remote_addr_port":51527,"duration_ms":2,"duration":2866,"status":200,"bytes_sent":10} -``` \ No newline at end of file +``` + +## Static HTTP and gRPC introspection endpoint configuration + +By default, the introspection endpoint is obtained from the OpenID Connect Discovery response. The library will use the endpoint specified in the `introspection_endpoint` field in the /.well-known/openid-configuration response body. +But it can be configured statically as well. It could be useful in multiple cases: +- When the introspection endpoint is not supported by the IDP. +- Not JWT token is used for authentication (e.g., opaque token). +- When we want to have a single point of introspection for all tokens. +- When performance is critical, and we want to use persistent gRPC connection. + +To configure the static introspection endpoint, add the following configuration to the `config.yaml` file: + +```yaml +introspection: + endpoint: +``` + +Additionally, the introspection can be configured to use gRPC instead of HTTP for the introspection request. +If `grps.tls.enabled` is set to `true`, the introspection request will be made over a secure connection. +If `grps.tls.client_cert` and `grps.tls.client_key` are set, the introspection request will be made with client authentication (mutual TLS). + +```yaml +introspection: + grpc: + target: + tls: + enabled: true + caCert: + clientCert: + clientKey: +``` + +Static endpoint configuration has higher priority than the dynamic one. \ No newline at end of file