dashboard.proto

syntax = "proto3";
package admin.gloo.solo.io;

import "extproto/ext.proto";
import "github.com/solo-io/solo-apis/api/gloo.solo.io/common/v2/approval_state.proto";
import "google/protobuf/duration.proto";
import "google/protobuf/empty.proto";
import "google/protobuf/wrappers.proto";

option go_package = "github.com/solo-io/solo-apis/client-go/admin.gloo.solo.io/v2";

option (extproto.hash_all) = true;
option (extproto.equal_all) = true;
option (extproto.clone_all) = true;

// `Dashboard` describes the settings for the Gloo Mesh Enterprise dashboard.
// Currently, this resource is only used to secure the Gloo Mesh Enterprise Dashboard by
// requiring authentication with an OpenID Connect identity provider.
// Users accessing the dashboard will be required to authenticate with the OIDC provider
// and all requests to retrieve data from the API will also be authenticated.
//
// The following example sets up OIDC authentication:
//```yaml
// apiVersion: admin.gloo.solo.io/v2
// kind: Dashboard
// metadata:
//   name: settings
//   namespace: gloo-mesh
// spec:
//   authn:
//     oidc:
//       appUrl: https://localhost:8080
//       clientId: $CLIENT_ID
//       clientSecretName: dashboard
//       issuerUrl: https://accounts.google.com
//    ```
message DashboardSpec {
  message AuthnConfig {
    oneof backend {
      OidcConfig oidc = 1;
    }
  }
  message AuthzConfig {
    oneof backend {
      // Enable multi cluster RBAC. When this is enabled, Gloo Mesh Enterprise will use RBAC resources
      // from managed clusters to determine if users are allowed to see resources in the dashbaord.
      // For this to work, the dashboard and the kubernetes clusters need to have the same identity
      // source (i.e. OIDC with the same user and group claims).
      // When using OIDC, make sure to configure the userMapping field.
      MultiClusterRbac multi_cluster_rbac = 1;
    }
  }

  // Configuration used to authenticate incoming requests.
  AuthnConfig authn = 1;
  // Configuration used to authorize incoming requests.
  AuthzConfig authz = 2;
}

message MultiClusterRbac {

}

message SessionConfig {
  message CookieSession {}

  message RedisSession {
    // address of the redis. can be address:port or unix://path/to/unix.sock
    string host = 1;

    // db to use. can leave unset for db 0.
    int32 db = 2;

    // size of the connection pool. can leave unset for default.
    // defaults to 10 connections per every CPU
    int32 pool_size = 3;

    // Key prefix inside redis
    string key_prefix = 4;

    // Cookie name to set and store the session id. If empty the default "__session" is used.
    string cookie_name = 5;

    // When set, refresh expired id-tokens using the refresh-token. Defaults to true.
    // Explicitly set to false to disable refreshing.
    google.protobuf.BoolValue allow_refreshing = 6;
  }

  message CookieOptions {
    // Max age of the cookie. If unset, the default of 30 days will be
    // used. To disable expiration, set explicitly to 0.
    google.protobuf.UInt32Value max_age = 1;

    // Use an insecure cookie.
    // Should only be used for testing and in trusted environments.
    bool not_secure = 2;

    // Path of the cookie. Defaults to "/", set to "" to disable the
    // option.
    google.protobuf.StringValue path = 3;

    // Domain of the cookie.
    string domain = 4;
  }

  // Set-Cookie options
  CookieOptions cookie_options = 1;

  oneof backend {
    // Store all session data in the cookie itself
    CookieSession cookie = 2;

    // Store the session data in a Redis instance.
    RedisSession redis = 3;
  }
}

message OidcConfig {
  // The client ID from the issuer
  string client_id = 1;

  // The client secret from the issuer
  string client_secret_name = 2;

  // The url of the issuer. We will look for OIDC information in:
  //   {{ issuerURL }}/.well-known/openid-configuration
  string issuer_url = 3;

  // Extra query parameters to apply to the authorization request to the
  // identity provider. For example, using the [PKCE flow](https://www.oauth.com/oauth2-servers/pkce/authorization-request/) by
  // setting `code_challenge` and `code_challenge_method`.
  map<string, string> auth_endpoint_query_params = 4;

  // Extra query parameters to apply to the token request to the identity
  // provider. For example, using the [PKCE flow](https://www.oauth.com/oauth2-servers/pkce/authorization-request/) by
  // setting `code_challenge` and `code_challenge_method`.
  map<string, string> token_endpoint_query_params = 5;

  // URL to redirect to after successful auth.
  string app_url = 6;

  // Path to handle the OIDC callback.
  string callback_path = 7;

  // Path used to logout. If not provided, logout will be disabled.
  string logout_path = 8;

  // Scopes to request in addition to 'openid'.
  repeated string scopes = 9;

  // Configuration for session storage.
  SessionConfig session = 10;

  // OIDC configuration is discovered at
  // <issuerUrl>/.well-known/openid-configuration The discovery override
  // defines any properties that should override
  // [this discovery configuration](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata).
  message DiscoveryOverride {
    // URL of the provider authorization endpoint.
    string auth_endpoint = 1;

    // URL of the provider token endpoint.
    string token_endpoint = 2;

    // URL of the provider JSON web key set.
    string jwks_uri = 3;

    // List of scope values that the provider supports.
    repeated string scopes = 4;

    // List of response types that the provider supports.
    repeated string response_types = 5;

    // List of subject identifier types that the provider supports.
    repeated string subjects = 6;

    // List of json web signature signing algorithms that the provider
    // supports for encoding claims in a JWT.
    repeated string id_token_algs = 7;

    // List of client authentication methods supported by the provider
    // token endpoint.
    repeated string auth_methods = 8;

    // List of claim types that the provider supports.
    repeated string claims = 9;
  }

  // Ensure that certain values are set regardless of what the OIDC
  // provider returns.
  DiscoveryOverride discovery_override = 11;

  // How often to poll the OIDC issuer for new configuration.
  // For information about the value format, see the [Google protocol buffer documentation](https://developers.google.com/protocol-buffers/docs/reference/csharp/class/google/protobuf/well-known-types/duration).
  google.protobuf.Duration discovery_poll_interval = 12;

  // If a user executes a request with a key that is not found in the
  // JWKS, it could be that the keys have rotated on the remote source,
  // and not yet in the local cache. This policy lets you define the
  // behavior for how to refresh the local cache during a request where an
  // invalid key is provided
  JwksOnDemandCacheRefreshPolicy jwks_cache_refresh_policy = 13;

  // If set, the ID token will used to infer user identity, that can be used to make 
  // authorization decisions.
  // If empty, no authorization will be made.
  UserMapping user_mapping = 14;

  // A name of a config map containing root cert to use when talking with
  // the OIDC provider. The config map must contain the a key named "ca.crt" with PEM encoded
  // CA.
  string ca_cert_configmap_name = 15;
}

// The [json web key set (JWKS)](https://tools.ietf.org/html/rfc7517) is
// discovered at an interval from a remote source. When keys rotate in
// the remote source, there may be a delay in the local source picking
// up those new keys. Therefore, a user could execute a request with a
// token that has been signed by a key in the remote JWKS, but the local
// cache doesn't have the key yet. The request would fail because the
// key isn't contained in the local set. Since most IdPs publish key
// keys in their remote JWKS before they are used, this is not an issue
// most of the time. This policy lets you define the behavior for when a
// user has a token with a key not yet in the local cache.
message JwksOnDemandCacheRefreshPolicy {
  oneof policy {
    // Never refresh the local JWKS cache on demand. If a key is not
    // in the cache, it is assumed to be malicious. This is the
    // default policy since we assume that IdPs publish keys before
    // they rotate them, and frequent polling finds the newest keys.
    // For information about the value format, see the [Google protocol buffer documentation](https://developers.google.com/protocol-buffers/docs/reference/csharp/class/google/protobuf/well-known-types/empty).
    google.protobuf.Empty never = 1;

    // If a key is not in the cache, fetch the most recent keys from
    // the IdP and update the cache. NOTE: This should only be done
    // in trusted environments, since missing keys will each trigger
    // a request to the IdP. Using this in an environment exposed to
    // the internet will allow malicious agents to execute a DDoS
    // attack by spamming protected endpoints with tokens signed by
    // invalid keys.
    // For information about the value format, see the [Google protocol buffer documentation](https://developers.google.com/protocol-buffers/docs/reference/csharp/class/google/protobuf/well-known-types/empty).
    google.protobuf.Empty always = 2;

    // If a key is not in the cache, fetch the most recent keys from
    // the IdP and update the cache. This value sets the number of
    // requests to the IdP per polling interval. If that limit is
    // exceeded, we will stop fetching from the IdP for the
    // remainder of the polling interval.
    uint32 max_idp_req_per_polling_interval = 3;
  }
}

// Settings to make sure the identity derivied from the ID token matches
// the kubernetes identity.
message UserMapping {
  // The JWT field to use as the user's username.
  string username_claim = 1;

  // If specified, causes claims mapping to username to be prefix with
  // the provided value. A value "oidc:" would result in usernames like "oidc:john".
  string username_prefix = 2;

  // If specified, causes the OIDCAuthenticator to try to populate the user's
  // groups with an ID Token field. If the GroupsClaim field is present in an ID Token the value
  // must be a string or list of strings.
  string  groups_claim = 3;

  // If specified, causes claims mapping to group names to be prefixed with the
  // value. A value "oidc:" would result in groups like "oidc:engineering" and "oidc:marketing".
  string groups_prefix = 4;
}

message DashboardStatus {

  // The most recent generation observed in the Dashboard metadata.
  // If the `observedGeneration` does not match `metadata.generation`, Gloo Mesh has not processed the most
  // recent version of this resource.
  int64 observed_generation = 1;

  // The state of the overall resource.
  // It will only show accepted if no processing errors encountered.
  .common.gloo.solo.io.ApprovalState state = 2;

  // Any errors encountered while processing Settings object.
  repeated string errors = 3;
}