config.proto

// Copyright 2024 Tetrate
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto3";

package authservice.config.v1.oidc;

import "google/protobuf/duration.proto";
import "google/protobuf/struct.proto";
import "validate/validate.proto";

// Defines how a token obtained through an OIDC flow is forwarded to services.
message TokenConfig {

  // The name of the header that Authservice adds to the request when forwarding to services.
  // The value of this header will contain the `preamble` and the token.
  // This value is case-insensitive, as http header names are case-insensitive.
  // Note that this value must be `Authorization` for the
  // [Istio Authentication Policy](https://istio.io/docs/tasks/security/authn-policy/)
  // to inspect the token.
  // Required.
  string header = 1 [(validate.rules).string.min_len = 1];

  // The authentication scheme of the token.
  // For example, when the preamble is `Bearer` and `header` is `Authorization`, the following
  // header will be added to the request to the service: `Authorization: Bearer ID_TOKEN_VALUE`.
  // Note that this value must be `Bearer`, case-sensitive, when header is `Authorization`.
  // Optional.
  string preamble = 2;
}

// When specified, the Authservice will use the configured Redis server to store session data
message RedisConfig {

  // The Redis server uri, e.g. "tcp://127.0.0.1:6379"
  string server_uri = 1 [(validate.rules).string.min_len = 1];
}

// When specified, the Authservice will destroy the Authservice session when a request is
// made to the configured path.
message LogoutConfig {

  // A http request path that the Authservice matches against to initiate logout.
  // Whenever a request is made to that path, the Authservice will remove the Authservice-specific
  // cookies and respond with a redirect to the configured `redirect_uri`. Removing the cookies
  // causes the user to be unauthenticated in future requests.
  // If the service application has its own logout controller, then it may be desirable to have its
  // logout controller redirect to this path. If the service application does not need its own logout
  // controller, then the application's logout button/link's href can GET or POST directly to this path.
  // Required.
  string path = 1 [(validate.rules).string.min_len = 1];

  // A URI specifying the destination to which the Authservice will redirect any request made to the
  // logout `path`. For example, it may be desirable to redirect the logged out user to the homepage
  // of the service application, or to the
  // [logout endpoint of the OIDC Provider](https://openid.net/specs/openid-connect-session-1_0.html#RPLogout).
  // As with all redirects, the user's browser will perform a GET to this URI.
  // Required when the OIDC discovery is not used or when the OIDC discovery does not provide the
  // `end_session_endpoint`.
  string redirect_uri = 2;
}

// The configuration of an OpenID Connect filter that can be used to retrieve identity and access tokens
// via the standard authorization code grant flow from an OIDC Provider.
message OIDCConfig {
  // The OIDC Provider's [issuer identifier](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfig).
  // If this is set, the endpoints will be dynamically retrieved from the OIDC Provider's configuration endpoint.
  string configuration_uri = 19;

  // The OIDC Provider's [authorization endpoint](https://openid.net/specs/openid-connect-core-1_0.html#AuthorizationEndpoint).
  // Required if `configuration_uri` is not set.
  string authorization_uri = 1;

  // The OIDC Provider's [token endpoint](https://openid.net/specs/openid-connect-core-1_0.html#TokenEndpoint).
  // Required if `configuration_uri` is not set.
  string token_uri = 2;

  // This value will be used as the `redirect_uri` param of the authorization code grant
  // [Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest).
  // This URL must be one of the Redirection URI values for the Client pre-registered at the OIDC provider.
  // Note: The Istio gateway's VirtualService must be prepared to ensure that this URL will get routed to
  // the service so that the Authservice can intercept the request and handle it
  // (see [example](https://github.com/istio-ecosystem/authservice/blob/master/bookinfo-example/config/bookinfo-gateway.yaml)).
  // Required.
  string callback_uri = 3 [(validate.rules).string.min_len = 1];

  // This message defines a setting to allow asynchronous retrieval and update of the JWK for
  // JWT validation at regular intervals.
  message JwksFetcherConfig {
    // Request URI that has the JWKs.
    // Required if `configuration_uri` is not set.
    string jwks_uri = 1;

    // Request interval to check whether new JWKs are available. If not specified,
    // default to 1200 seconds, 20min.
    // Optional.
    uint32 periodic_fetch_interval_sec = 2;

    // If set to true, the verification of the destination certificate will be skipped when
    // making a request to the JWKs URI. This option is useful when you want to use a
    // self-signed certificate for testing purposes, but basically should not be set to
    // true in any other cases.
    // Optional.
    // Deprecated: Use the one from the OIDCConfig instead.
    google.protobuf.Value skip_verify_peer_cert = 3 [deprecated = true];
  }

  oneof jwks_config {
    // The JSON JWKS response from the OIDC provider’s `jwks_uri` URI which can be found in
    // the OIDC provider's
    // [configuration response](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfigurationResponse).
    // Note that this JSON value must be escaped when embedded in a json configmap
    // (see [example](https://github.com/istio-ecosystem/authservice/blob/master/bookinfo-example/config/authservice-configmap-template.yaml)).
    // Used during token verification.
    string jwks = 4;

    // Configuration to allow JWKs to be retrieved and updated asynchronously at regular intervals.
    JwksFetcherConfig jwks_fetcher = 17;
  }

  // The OIDC client ID assigned to the filter to be used in the
  // [Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest).
  // Required.
  string client_id = 5 [(validate.rules).string.min_len = 1];

  // This message defines a reference to a Kubernetes Secret resource.
  message SecretReference {
    // The namespace of the referenced Secret, if not set, default to "default" namespace.
    string namespace = 1;

    // The name of the referenced Secret.
    string name = 2 [(validate.rules).string.min_len = 1];
  }

  oneof client_secret_config {
    option(validate.required) = true;
    // The OIDC client secret assigned to the filter to be used in the
    // [Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest).
    // This field keeps the client secret in plain text. Recommend to use `client_secret_ref` instead
    // when running in a Kubernetes cluster.
    string client_secret = 6 [(validate.rules).string.min_len = 1];

    // The Kubernetes secret that contains the OIDC client secret assigned to the filter to be used in the
    // [Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest).
    //
    // This is an Opaque secret. The client secret should be stored in the key "client-secret".
    // This filed is only valid when running in a Kubernetes cluster.
    SecretReference client_secret_ref = 21;
  }

  // Additional scopes passed to the OIDC Provider in the
  // [Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest).
  // The `openid` scope is always sent to the OIDC Provider, and does not need to be specified here.
  // Required, but an empty array is allowed.
  repeated string scopes = 7;

  // A unique identifier of the Authservice's browser cookies. Can be any string.
  // Needed when multiple services in the same domain are each protected by
  // their own Authservice, in which case each service's Authservice should have
  // a unique value to avoid cookie name conflicts. Also needed when an Authservice
  // is configured with multiple `oidc` filters (across multiple `chains`), each
  // sharing a Redis server for their session storage, to avoid having those
  // `oidc` filters read/write the same sessions in Redis.
  // Optional.
  string cookie_name_prefix = 8;

  // The configuration for adding ID Tokens as headers to requests forwarded to a service.
  // Required.
  TokenConfig id_token = 9 [(validate.rules).message.required = true];

  // The configuration for adding Access Tokens as headers to requests forwarded to a service.
  // Optional.
  TokenConfig access_token = 10;

  // When specified, the Authservice will destroy the Authservice session when a request is
  // made to the configured path.
  // Optional.
  LogoutConfig logout = 11;

  // The Authservice associates obtained OIDC tokens with a session ID in a session store.
  // It also stores some temporary information during the login process into the session store,
  // which will be removed when the user finishes the login.
  // This configuration option sets the number of seconds since a user's session with the Authservice has started
  // until that session should expire.
  // When configured to `0`, which is the default value, the session will never timeout based on the time
  // that it was started, but can still timeout due to being idle.
  // When both `absolute_session_timeout` and `idle_session_timeout` are zero, then sessions will never
  // expire. These settings do not affect how quickly the OIDC tokens contained inside the user's session expire.
  // Optional.
  uint32 absolute_session_timeout = 12;

  // The Authservice associates obtained OIDC tokens with a session ID in a session store.
  // It also stores some temporary information during the login process into the session store,
  // which will be removed when the user finishes the login.
  // This configuration option sets the number of seconds since the most recent incoming request from that user
  // until the user's session with the Authservice should expire.
  // When configured to `0`, which is the default value, session expiration will not consider idle time,
  // but can still consider timeout based on maximum absolute time since added.
  // When both `absolute_session_timeout` and `idle_session_timeout` are zero, then sessions will never
  // expire. These settings do not affect how quickly the OIDC tokens contained inside the user's session expire.
  // Optional.
  uint32 idle_session_timeout = 13;

  // When specified, the Authservice will trust the specified Certificate Authority when performing HTTPS calls to
  // the OIDC Identity Provider.
  oneof trusted_ca_config {
    // String PEM-encoded certificate authority to trust when performing HTTPS calls to the OIDC Identity Provider.
    // Optional.
    string trusted_certificate_authority = 14;

    // The file path to the PEM-encoded certificate authority to trust when performing HTTPS calls to the OIDC Identity Provider.
    // Optional.
    string trusted_certificate_authority_file = 20;
  }

  // The duration between refreshes of the trusted certificate authority if `trusted_certificate_authority_file` is set.
  // Unset or 0 (the default) disables the refresh, useful is no rotation is expected.
  // Is a String that ends in `s` to indicate seconds and is preceded by the number of seconds, e.g. `120s` (represents 2 minutes).
  // Optional.
  google.protobuf.Duration trusted_certificate_authority_refresh_interval = 22;

  // The Authservice makes two kinds of direct network connections directly to the OIDC Provider.
  // Both are POST requests to the configured `token_uri` of the OIDC Provider.
  // The first is to exchange the authorization code for tokens, and the other is to use the
  // refresh token to obtain new tokens. Configure the `proxy_uri` when
  // both of these requests should be made through a web proxy. The format of `proxy_uri` is
  // `http://proxyserver.example.com:8080`, where `:<port_number>` is optional.
  // Userinfo (usernames and passwords) in the `proxy_uri` setting are not yet supported.
  // The `proxy_uri` should always start with `http://`.
  // The Authservice will upgrade the connection to the OIDC provider to HTTPS using
  // an HTTP CONNECT request to the proxy server. The proxy server will see the hostname and port number
  // of the OIDC provider in plain text in the CONNECT request, but all other communication will occur
  // over an encrypted HTTPS connection negotiated directly between the Authservice and
  // the OIDC provider. See also the related `trusted_certificate_authority` configuration option.
  // Optional.
  string proxy_uri = 15;

  // When specified, the Authservice will use the configured Redis server to store session data.
  // Optional.
  RedisConfig redis_session_store_config = 16;

  // If set to true, the verification of the destination certificate will be skipped when
  // making a request to the Token Endpoint. This option is useful when you want to use a
  // self-signed certificate for testing purposes, but basically should not be set to true
  // in any other cases.
  // Optional.
  google.protobuf.Value skip_verify_peer_cert = 18; // keep this field out from the trusted_ca_config one of for backward compatibility.
}