feat(v3alpha): web key resource (#8262)

# Which Problems Are Solved

Implement a new API service that allows management of OIDC signing web
keys.
This allows users to manage rotation of the instance level keys. which
are currently managed based on expiry.

The API accepts the generation of the following key types and
parameters:

- RSA keys with 2048, 3072 or 4096 bit in size and:
  - Signing with SHA-256 (RS256)
  - Signing with SHA-384 (RS384)
  - Signing with SHA-512 (RS512)
- ECDSA keys with
  - P256 curve
  - P384 curve
  - P512 curve
- ED25519 keys

# How the Problems Are Solved

Keys are serialized for storage using the JSON web key format from the
`jose` library. This is the format that will be used by OIDC for
signing, verification and publication.

Each instance can have a number of key pairs. All existing public keys
are meant to be used for token verification and publication the keys
endpoint. Keys can be activated and the active private key is meant to
sign new tokens. There is always exactly 1 active signing key:

1. When the first key for an instance is generated, it is automatically
activated.
2. Activation of the next key automatically deactivates the previously
active key.
3. Keys cannot be manually deactivated from the API
4. Active keys cannot be deleted

# Additional Changes

- Query methods that later will be used by the OIDC package are already
implemented. Preparation for #8031
- Fix indentation in french translation for instance event
- Move user_schema translations to consistent positions in all
translation files

# Additional Context

- Closes #8030
- Part of #7809

---------

Co-authored-by: Elio Bischof <elio@zitadel.com>

proto/zitadel/feature/v2/instance.proto

@@ -58,6 +58,13 @@ message SetInstanceFeaturesRequest{
       description: "Improves performance of specified execution paths.";
     }
   ];
+
+  optional bool web_key = 8 [
+    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+      example: "true";
+      description: "Enable the webkey/v3alpha API. The first time this feature is enabled, web keys are generated and activated.";
+    }
+  ];
 }
 
 message SetInstanceFeaturesResponse {
@@ -129,4 +136,11 @@ message GetInstanceFeaturesResponse {
       description: "Improves performance of specified execution paths.";
     }
   ];
+
+  FeatureFlag web_key = 9 [
+    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+      example: "true";
+      description: "Enable the webkey/v3alpha API. The first time this feature is enabled, web keys are generated and activated.";
+    }
+  ];
 }

proto/zitadel/feature/v2beta/instance.proto

@@ -58,6 +58,13 @@ message SetInstanceFeaturesRequest{
       description: "Improves performance of specified execution paths.";
     }
   ];
+
+  optional bool web_key = 8 [
+    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+      example: "true";
+      description: "Enable the webkey/v3alpha API. The first time this feature is enabled, web keys are generated and activated.";
+    }
+  ];
 }
 
 message SetInstanceFeaturesResponse {
@@ -129,4 +136,11 @@ message GetInstanceFeaturesResponse {
       description: "Improves performance of specified execution paths.";
     }
   ];
+
+  FeatureFlag web_key = 9 [
+    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+      example: "true";
+      description: "Enable the webkey/v3alpha API. The first time this feature is enabled, web keys are generated and activated.";
+    }
+  ];
 }

proto/zitadel/resources/webkey/v3alpha/config.proto

@@ -0,0 +1,41 @@
+syntax = "proto3";
+
+package zitadel.resources.webkey.v3alpha;
+
+import "validate/validate.proto";
+
+option go_package = "github.com/zitadel/zitadel/pkg/grpc/resources/webkey/v3alpha;webkey";
+
+message WebKeyRSAConfig {
+  enum RSABits {
+    RSA_BITS_UNSPECIFIED = 0;
+    RSA_BITS_2048 = 1;
+    RSA_BITS_3072 = 2;
+    RSA_BITS_4096 = 3;
+  }
+
+  enum RSAHasher {
+    RSA_HASHER_UNSPECIFIED = 0;
+    RSA_HASHER_SHA256 = 1;
+    RSA_HASHER_SHA384 = 2;
+    RSA_HASHER_SHA512 = 3;
+  }
+
+  // bit size of the RSA key
+  RSABits bits = 1 [(validate.rules).enum = {defined_only: true, not_in: [0]}];
+  // signing algrithm used
+  RSAHasher hasher = 2 [(validate.rules).enum = {defined_only: true, not_in: [0]}];
+}
+
+message WebKeyECDSAConfig {
+  enum ECDSACurve {
+    ECDSA_CURVE_UNSPECIFIED = 0;
+    ECDSA_CURVE_P256 = 1;
+    ECDSA_CURVE_P384 = 2;
+    ECDSA_CURVE_P512 = 3;
+  }
+
+  ECDSACurve curve = 1 [(validate.rules).enum = {defined_only: true, not_in: [0]}];
+}
+
+message WebKeyED25519Config {}

proto/zitadel/resources/webkey/v3alpha/key.proto

@@ -0,0 +1,31 @@
+syntax = "proto3";
+
+package zitadel.resources.webkey.v3alpha;
+
+import "google/protobuf/timestamp.proto";
+import "zitadel/resources/webkey/v3alpha/config.proto";
+import "zitadel/resources/object/v3alpha/object.proto";
+
+option go_package = "github.com/zitadel/zitadel/pkg/grpc/resources/webkey/v3alpha;webkey";
+
+enum WebKeyState {
+  STATE_UNSPECIFIED = 0;
+  STATE_INITIAL = 1;
+  STATE_ACTIVE = 2;
+  STATE_INACTIVE = 3;
+  STATE_REMOVED = 4;
+}
+
+message GetWebKey {
+  zitadel.resources.object.v3alpha.Details details = 1;
+  WebKey config = 2;
+  WebKeyState state = 3;
+}
+
+message WebKey {
+  oneof config {
+    WebKeyRSAConfig rsa = 6;
+    WebKeyECDSAConfig ecdsa = 7;
+    WebKeyED25519Config ed25519 = 8;
+  }
+}

proto/zitadel/resources/webkey/v3alpha/webkey_service.proto

@@ -0,0 +1,278 @@
+syntax = "proto3";
+
+package zitadel.resources.webkey.v3alpha;
+
+import "google/api/annotations.proto";
+import "google/api/field_behavior.proto";
+import "protoc-gen-openapiv2/options/annotations.proto";
+import "validate/validate.proto";
+
+import "zitadel/protoc_gen_zitadel/v2/options.proto";
+
+import "zitadel/resources/webkey/v3alpha/key.proto";
+import "zitadel/resources/object/v3alpha/object.proto";
+import "zitadel/object/v3alpha/object.proto";
+
+option go_package = "github.com/zitadel/zitadel/pkg/grpc/resources/webkey/v3alpha;webkey";
+
+option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_swagger) = {
+  info: {
+    title: "Web key Service";
+    version: "3.0-preview";
+    description: "This API is intended to manage web keys for a ZITADEL instance, used to sign and validate OIDC tokens. This project is in preview state. It can AND will continue breaking until a stable version is released.";
+    contact:{
+      name: "ZITADEL"
+      url: "https://zitadel.com"
+      email: "hi@zitadel.com"
+    }
+    license: {
+      name: "Apache 2.0",
+      url: "https://github.com/zitadel/zitadel/blob/main/LICENSE";
+    };
+  };
+  schemes: HTTPS;
+  schemes: HTTP;
+
+  consumes: "application/json";
+  produces: "application/json";
+
+  consumes: "application/grpc";
+  produces: "application/grpc";
+
+  consumes: "application/grpc-web+proto";
+  produces: "application/grpc-web+proto";
+
+  host: "${ZITADEL_DOMAIN}";
+  base_path: "/resources/v3alpha/web_keys";
+
+  external_docs: {
+    description: "Detailed information about ZITADEL",
+    url: "https://zitadel.com/docs"
+  }
+  security_definitions: {
+    security: {
+      key: "OAuth2";
+      value: {
+        type: TYPE_OAUTH2;
+        flow: FLOW_ACCESS_CODE;
+        authorization_url: "$CUSTOM-DOMAIN/oauth/v2/authorize";
+        token_url: "$CUSTOM-DOMAIN/oauth/v2/token";
+        scopes: {
+          scope: {
+            key: "openid";
+            value: "openid";
+          }
+          scope: {
+            key: "urn:zitadel:iam:org:project:id:zitadel:aud";
+            value: "urn:zitadel:iam:org:project:id:zitadel:aud";
+          }
+        }
+      }
+    }
+  }
+  security: {
+    security_requirement: {
+      key: "OAuth2";
+      value: {
+        scope: "openid";
+        scope: "urn:zitadel:iam:org:project:id:zitadel:aud";
+      }
+    }
+  }
+  responses: {
+    key: "403";
+    value: {
+      description: "Returned when the user does not have permission to access the resource.";
+      schema: {
+        json_schema: {
+          ref: "#/definitions/rpcStatus";
+        }
+      }
+    }
+  }
+  responses: {
+    key: "404";
+    value: {
+      description: "Returned when the resource does not exist.";
+      schema: {
+        json_schema: {
+          ref: "#/definitions/rpcStatus";
+        }
+      }
+    }
+  }
+};
+
+service ZITADELWebKeys {
+  rpc CreateWebKey(CreateWebKeyRequest) returns (CreateWebKeyResponse) {
+    option (google.api.http) = {
+      post: "/"
+      body: "key"
+    };
+
+    option (zitadel.protoc_gen_zitadel.v2.options) = {
+      auth_option: {
+        permission: "iam.web_key.write"
+      }
+      http_response: {
+        success_code: 201
+      }
+    };
+
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      summary: "Generate a web key pair for the instance";
+      description: "Generate a private and public key pair. The private key can be used to sign OIDC tokens after activation. The public key can be used to valite OIDC tokens."
+      responses: {
+        key: "200"
+        value: {
+          description: "OK";
+        }
+      };
+    };
+  }
+  
+  rpc ActivateWebKey(ActivateWebKeyRequest) returns (ActivateWebKeyResponse) {
+    option (google.api.http) = {
+      post: "/{id}/_activate"
+    };
+
+    option (zitadel.protoc_gen_zitadel.v2.options) = {
+      auth_option: {
+        permission: "iam.web_key.write"
+      }
+      http_response: {
+        success_code: 200
+      }
+    };
+
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      summary: "Activate a signing key for the instance";
+      description: "Switch the active signing web key. The previously active key will be deactivated."
+      responses: {
+        key: "200"
+        value: {
+          description: "OK";
+        }
+      };
+    };
+  }
+  
+  rpc DeleteWebKey(DeleteWebKeyRequest) returns (DeleteWebKeyResponse) {
+    option (google.api.http) = {
+      delete: "/{id}"
+    };
+
+    option (zitadel.protoc_gen_zitadel.v2.options) = {
+      auth_option: {
+        permission: "iam.web_key.delete"
+      }
+      http_response: {
+        success_code: 200
+      }
+    };
+
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      summary: "Generate a web key pair for the instance";
+      description: "Delete a web key. Only inactive keys can be deleted. Once a key is deleted, any tokens signed by this key will be invalid."
+      responses: {
+        key: "200"
+        value: {
+          description: "OK";
+        }
+      };
+    };
+  }
+  
+  rpc ListWebKeys(ListWebKeysRequest) returns (ListWebKeysResponse) {
+    option (google.api.http) = {
+      get: "/"
+    };
+
+    option (zitadel.protoc_gen_zitadel.v2.options) = {
+      auth_option: {
+        permission: "iam.web_key.read"
+      }
+      http_response: {
+        success_code: 200
+      }
+    };
+
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      summary: "Generate a web key pair for the instance";
+      description: "List web key details for the instance"
+      responses: {
+        key: "200"
+        value: {
+          description: "OK";
+        }
+      };
+    };
+  }
+}
+
+message CreateWebKeyRequest {
+  optional zitadel.object.v3alpha.Instance instance = 1 [
+    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+      default: "\"domain from HOST or :authority header\""
+    }
+  ];
+  WebKey key = 2;
+}
+
+message CreateWebKeyResponse {
+  zitadel.resources.object.v3alpha.Details details = 1;
+}
+
+message ActivateWebKeyRequest {
+  optional zitadel.object.v3alpha.Instance instance = 1 [
+    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+      default: "\"domain from HOST or :authority header\""
+    }
+  ];
+  string id = 2 [
+    (validate.rules).string = {min_len: 1, max_len: 200},
+    (google.api.field_behavior) = REQUIRED,
+    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+      min_length: 1,
+      max_length: 200,
+      example: "\"69629026806489455\"";
+    }
+  ];
+}
+
+message ActivateWebKeyResponse {
+  zitadel.resources.object.v3alpha.Details details = 1;
+}
+
+message DeleteWebKeyRequest {
+  optional zitadel.object.v3alpha.Instance instance = 1 [
+    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+      default: "\"domain from HOST or :authority header\""
+    }
+  ];
+  string id = 2 [
+    (validate.rules).string = {min_len: 1, max_len: 200},
+    (google.api.field_behavior) = REQUIRED,
+    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+      min_length: 1,
+      max_length: 200,
+      example: "\"69629026806489455\"";
+    }
+  ];
+}
+
+message DeleteWebKeyResponse {
+  zitadel.resources.object.v3alpha.Details details = 1;
+}
+
+message ListWebKeysRequest {
+  optional zitadel.object.v3alpha.Instance instance = 1 [
+    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+      default: "\"domain from HOST or :authority header\""
+    }
+  ];
+}
+
+message ListWebKeysResponse {
+  repeated GetWebKey web_keys = 1;
+}