[iam] clean up oidc.proto

Author: AlexTugarev

components/public-api/gitpod/experimental/v1/oidc.proto

@@ -8,24 +8,60 @@ import "google/protobuf/timestamp.proto";
 
 import "gitpod/experimental/v1/pagination.proto";
 
+
+// Configuration of an OpenID client.
+//
+// For the metadata describing the configuration of OIDC providers, cf.
+// https://openid.net/specs/openid-connect-discovery-1_0.html
+message OIDCClientConfig {
+  // ID is the unique identifier for the OIDC Config.
+  // Read only.
+  string id = 1;
+
+  OIDCConfig oidc_config = 2;
+
+  OAuth2Config oauth2_config = 3;
+  // Optional.
+  bool oauth_only = 4;
+
+  // List of the JWS signing algorithms (alg values) supported by the OP for the
+  // ID Token to encode the Claims in a JWT. The algorithm RS256 MUST be
+  // included.
+  // Optional.
+  repeated string id_token_signing_alg_values_supported = 5;
+
+  // Time when the config was created.
+  // Read-only.
+  google.protobuf.Timestamp creation_time = 6;
+
+  // Describes the status of this configuration item.
+  // Read-only.
+  OIDCClientConfigStatus status = 7;
+}
+
+// The OIDC specific part of the client configuration.
 message OIDCConfig {
   // URL using the https scheme with no query or fragment component that the
-  // OIDC provider asserts as its Issuer Identifier. Required.
+  // OIDC provider asserts as its Issuer Identifier.
+  // Required.
   string issuer = 1;
 
   // A KeySet that can validate the id_token (JSON web token)
   // Either one is required.
   string jwks = 2;
   string jwks_url = 3;
 
+  // Provider specific parameters to control the behavior of the consent screen.
   // Optional.
   ConsentScreenHints hints = 4;
 
-  // If set, the default claim mapping is overriden.
+  // Optional overrides for key mapping to be applied when extracting claims from id_tokens.
+  // Should only be set, if an override is required.
   // Optional.
   ClaimMappingOverride override_claim_mapping = 5;
 }
 
+// Provider specific parameters to control the behavior of the consent screen.
 message ConsentScreenHints {
   // Control options for the consent screen.
   // Optional.
@@ -37,6 +73,7 @@ message ConsentScreenHints {
   string login_hint = 3;
 }
 
+// Optional overrides for key mapping to be applied when extracting claims from id_tokens.
 message ClaimMappingOverride {
   // Optional.
   string claim_email_key = 1;
@@ -46,10 +83,12 @@ message ClaimMappingOverride {
   string claim_username_key = 3;
 }
 
+// The OAuth2 specific part of the client configuration.
 message OAuth2Config {
   // Required.
   string client_id = 1;
-  // Required.
+  // Required for creation/updates.
+  // Empty on read.
   string client_secret = 2;
   // Required.
   string authorization_endpoint = 3;
@@ -59,52 +98,29 @@ message OAuth2Config {
   repeated string scopes_supported = 5;
 
   // Source for additional claims for the token.
+  // Additional keys may be used to control the extraction of a profile.
   // Required.
   string userinfo_endpoint = 6;
 
+  // Keys of the userinfo result to extract a profile from.
   // Optional.
   UserInfoKeys userinfo_keys = 7;
 }
 
+// Description of keys of a userinfo result.
 message UserInfoKeys {
   // Optional.
   string userinfo_id_key = 1;
   // Optional.
   string userinfo_name_key = 2;
 }
 
-// Configuration of an OpenID provider instance.
-//
-// For the metadata describing the configuration of OIDC providers, cf.
-// https://openid.net/specs/openid-connect-discovery-1_0.html
-message OIDCClientConfig {
-  // ID is the unique identifier for the OIDC Config.
-  // Read only.
-  string id = 1;
-
-  OIDCConfig oidc_config = 2;
-
-  OAuth2Config oauth2_config = 3;
-  // Optional.
-  bool oauth_only = 4;
-
-  // List of the JWS signing algorithms (alg values) supported by the OP for the
-  // ID Token to encode the Claims in a JWT. The algorithm RS256 MUST be
-  // included. Optional.
-  repeated string id_token_signing_alg_values_supported = 5;
-
-  // Time when the config was created.
-  // Read-only.
-  google.protobuf.Timestamp creation_time = 6;
-
-  // Read-only.
-  OIDCClientStatus status = 7;
-}
-
-message OIDCClientStatus {
+// The status of an OIDC client configuration.
+message OIDCClientConfigStatus {
   //
 }
 
+
 service OIDCService {
   // Creates a new OIDC client configuration.
   rpc CreateClientConfig(CreateClientConfigRequest)
@@ -118,11 +134,11 @@ service OIDCService {
   rpc ListClientConfigs(ListClientConfigsRequest)
       returns (ListClientConfigsResponse) {};
 
-  // Updates modifiable properties of an existing OIDC provider configuration.
+  // Updates modifiable properties of an existing OIDC client configuration.
   rpc UpdateClientConfig(UpdateClientConfigRequest)
       returns (UpdateClientConfigResponse) {};
 
-  // Removes a OIDC provider configuration by ID.
+  // Removes a OIDC client configuration by ID.
   rpc DeleteClientConfig(DeleteClientConfigRequest)
       returns (DeleteClientConfigResponse) {};
 }