From 3f07648c964127621329c8162c97949e5dfb18f5 Mon Sep 17 00:00:00 2001 From: Nick Rimmer Date: Sun, 6 Apr 2025 00:36:21 +0200 Subject: [PATCH 1/2] Default names, description and examples added --- .../BasicAuthService.cs | 8 +- .../AuthCode/OAuth2AuthCodeService.cs | 78 ++++++++++++++++--- .../Implicit/OAuth2ImplicitService.cs | 58 ++++++++++++-- .../EnvironmentValuesProvider.cs | 4 +- .../UserValuesProvider.cs | 1 + .../Models/ValuesProviderSettings.cs | 4 +- 6 files changed, 130 insertions(+), 23 deletions(-) diff --git a/src/Extensions/RestApia.Extensions.Auth.Basic/BasicAuthService.cs b/src/Extensions/RestApia.Extensions.Auth.Basic/BasicAuthService.cs index 0f4eae3..fd162a7 100644 --- a/src/Extensions/RestApia.Extensions.Auth.Basic/BasicAuthService.cs +++ b/src/Extensions/RestApia.Extensions.Auth.Basic/BasicAuthService.cs @@ -13,13 +13,15 @@ public class BasicAuthService: IAuthValuesProvider { private static readonly ValuesProviderSettings Settings = new () { - Title = "Basic Authorization", + Title = "Basic Authentication", + DefaultName = "Basic Auth", + Description = "Provide your login ID and password. This application will take these details and include them in the request header using the Basic Authentication standard.", CanBeReloaded = true, DisableCachingResults = true, ReservedValues = [ - new () { Name = nameof(BasicAuthSettings.Name), Description = "User name", IsRequired = true, Placeholder = "User" }, - new () { Name = nameof(BasicAuthSettings.Password), Description = "User Password", Placeholder = "secret" }, + new () { Name = nameof(BasicAuthSettings.Name), Description = "Login identifier or username", IsRequired = true, Placeholder = "user" }, + new () { Name = nameof(BasicAuthSettings.Password), Description = "Your secret password", Placeholder = "password" }, ], }; diff --git a/src/Extensions/RestApia.Extensions.Auth.OAuth2/AuthCode/OAuth2AuthCodeService.cs b/src/Extensions/RestApia.Extensions.Auth.OAuth2/AuthCode/OAuth2AuthCodeService.cs index aa1b1ac..fa309a7 100644 --- a/src/Extensions/RestApia.Extensions.Auth.OAuth2/AuthCode/OAuth2AuthCodeService.cs +++ b/src/Extensions/RestApia.Extensions.Auth.OAuth2/AuthCode/OAuth2AuthCodeService.cs @@ -12,13 +12,15 @@ using RestApia.Shared.Extensions.ValuesProviderService.Models; namespace RestApia.Extensions.Auth.OAuth2.AuthCode; -public class OAuth2AuthCodeService: IAuthValuesProvider +public class OAuth2AuthCodeService : IAuthValuesProvider { private static readonly HttpClient AccessTokenHttpClient = new (); private static readonly ValuesProviderSettings Settings = new () { Title = "OAuth2: Auth Code", + DefaultName = "OAuth2 Auth Code", + Description = "A window will open, taking you to the service provider's page to log in and grant permission. The provider will then issue a JWT token, which will be automatically used as the Bearer authorization header.", CanBeReloaded = true, ReservedValues = @@ -26,14 +28,14 @@ public class OAuth2AuthCodeService: IAuthValuesProvider new () { Name = nameof(OAuth2AuthCodeSettings.AuthUrl), - Description = "Authorization URL", + Description = "Authorization endpoint", IsRequired = true, Placeholder = "https://example.com/oauth2/authorize", }, new () { Name = nameof(OAuth2AuthCodeSettings.TokenUrl), - Description = "Access Token URL", + Description = "Access token endpoint", IsRequired = true, Placeholder = "https://example.com/oauth2/token", }, @@ -41,7 +43,7 @@ public class OAuth2AuthCodeService: IAuthValuesProvider new () { Name = nameof(OAuth2AuthCodeSettings.RedirectUrl), - Description = "Redirect URL", + Description = "Callback URL after authorization", IsRequired = true, Placeholder = "https://example.com/oauth2/callback", }, @@ -49,7 +51,7 @@ public class OAuth2AuthCodeService: IAuthValuesProvider new () { Name = nameof(OAuth2AuthCodeSettings.ClientId), - Description = "Client ID", + Description = "Your application's public identifier", IsRequired = true, Placeholder = Guid.Empty.ToString(), }, @@ -57,14 +59,14 @@ public class OAuth2AuthCodeService: IAuthValuesProvider new () { Name = nameof(OAuth2AuthCodeSettings.ClientSecret), - Description = "Client Secret", + Description = "Your application's secret key", Placeholder = "****************", }, new () { Name = nameof(OAuth2AuthCodeSettings.SendMethod), - Description = "Credentials sending method", + Description = "How to send client credentials", Placeholder = "header or body", ExpectedValues = [string.Empty, null, "header", "body"], // empty string is }, @@ -72,36 +74,88 @@ public class OAuth2AuthCodeService: IAuthValuesProvider new () { Name = nameof(OAuth2AuthCodeSettings.Scopes), - Description = "Scopes", + Description = "Requested permissions", Placeholder = "email; profile", }, new () { Name = nameof(OAuth2AuthCodeSettings.Audience), - Description = "Audience", + Description = "Target resource server", Placeholder = "https://example.com/api", }, new () { Name = nameof(OAuth2AuthCodeSettings.State), - Description = "State", + Description = "Optional security token", }, new () { Name = nameof(OAuth2AuthCodeSettings.Resource), - Description = "Resource", + Description = "Specific resource to access", }, new () { Name = nameof(OAuth2AuthCodeSettings.Origin), - Description = "Origin", + Description = "The origin of the request", Placeholder = "https://example.com", }, ], + + Examples = new Dictionary + { + { + "Default", string.Join("\n", [ + "AuthUrl: https://your-auth-provider.com/oauth2/authorize", + "TokenUrl: https://your-auth-provider.com/oauth2/token", + "RedirectUrl: https://localhost/auth_callback", + "ClientId: your_client_id", + "ClientSecret: your_client_secret", + ]) + }, + { + "Azure - Entra Id", string.Join("\n", [ + "// Usually defined as environment variables", + "// host: https://localhost:1234", + "// EntraId.Client: 019607db-89cd-7b36-a6ba-005cafd23fd2", + "// EntraId.Secret: your_entra_id_client_secret", + "// EntraId.Scopes: api://restapia-demo/Test", + string.Empty, + "// values", + "EntraId.TenantId: 019606ad-ba48-77dd-b008-9354e8bd9d7d", + string.Empty, + "// settings", + "AuthUrl: https://login.microsoftonline.com/{{EntraId.TenantId}}/oauth2/v2.0/authorize", + "TokenUrl: https://login.microsoftonline.com/{{EntraId.TenantId}}/oauth2/v2.0/token", + "RedirectUrl: {{host}}/oauth2-callback", + "ClientId: {{EntraId.Client}}", + "ClientSecret: {{EntraId.Secret}}", + "Scopes: {{EntraId.Scopes}}", + "SendMethod: body", // Or "header", depending on Entra ID configuration + ]) + }, + { + "Google OAuth 2.0", string.Join("\n", [ + "// Usually defined as environment variables", + "// host: https://localhost:1234", + "// Google.Client: your_google_client_id", + "// Google.Secret: your_google_client_secret", + "// Google.Scopes: https://www.googleapis.com/auth/userinfo.profile https://www.googleapis.com/auth/userinfo.email", + string.Empty, + "// settings", + "AuthUrl: https://accounts.google.com/o/oauth2/v2/auth", + "TokenUrl: https://oauth2.googleapis.com/token", + "RedirectUrl: {{host}}/oauth2-callback", + "ClientId: {{Google.Client}}", + "ClientSecret: {{Google.Secret}}", + "Scopes: {{Google.Scopes}}", + "SendMethod: body", + ]) + }, + }, }; private readonly ILogger _logger; diff --git a/src/Extensions/RestApia.Extensions.Auth.OAuth2/Implicit/OAuth2ImplicitService.cs b/src/Extensions/RestApia.Extensions.Auth.OAuth2/Implicit/OAuth2ImplicitService.cs index b53df28..c08b05f 100644 --- a/src/Extensions/RestApia.Extensions.Auth.OAuth2/Implicit/OAuth2ImplicitService.cs +++ b/src/Extensions/RestApia.Extensions.Auth.OAuth2/Implicit/OAuth2ImplicitService.cs @@ -10,18 +10,20 @@ using RestApia.Shared.Extensions.ValuesProviderService.Models; namespace RestApia.Extensions.Auth.OAuth2.Implicit; -public class OAuth2ImplicitService: IAuthValuesProvider +public class OAuth2ImplicitService : IAuthValuesProvider { private static readonly ValuesProviderSettings Settings = new () { Title = "OAuth2: Implicit", + DefaultName = "OAuth2 Implicit", + Description = "A window will open, taking you to the service provider to grant permission. Upon approval, an access token will be directly provided and automatically used as the Bearer authorization header.", CanBeReloaded = true, ReservedValues = [ new () { Name = nameof(OAuth2ImplicitSettings.AuthUrl), - Description = "Authorization URL", + Description = "Authorization endpoint URL", IsRequired = true, Placeholder = "https://example.com/oauth2/authorize", }, @@ -29,7 +31,7 @@ public class OAuth2ImplicitService: IAuthValuesProvider new () { Name = nameof(OAuth2ImplicitSettings.RedirectUrl), - Description = "Redirect URL", + Description = "Callback URL after authorization", IsRequired = true, Placeholder = "https://example.com/oauth2/callback", }, @@ -37,7 +39,7 @@ public class OAuth2ImplicitService: IAuthValuesProvider new () { Name = nameof(OAuth2ImplicitSettings.ClientId), - Description = "Client ID", + Description = "Your application's public identifier", IsRequired = true, Placeholder = Guid.Empty.ToString(), }, @@ -45,17 +47,61 @@ public class OAuth2ImplicitService: IAuthValuesProvider new () { Name = nameof(OAuth2ImplicitSettings.Scopes), - Description = "Scopes", + Description = "Permissions your application requests", Placeholder = "email; profile", }, new () { Name = nameof(OAuth2ImplicitSettings.Audience), - Description = "Audience", + Description = "Target resource server", Placeholder = "https://example.com/api", }, ], + Examples = new Dictionary + { + { + "Default", string.Join("\n", [ + "AuthUrl: https://your-auth-provider.com/authorize", + "RedirectUrl: https://localhost/auth_callback", + "ClientId: 00000000-0000-0000-0000-000000000000", + ]) + }, + { + "Azure - Entra Id", string.Join("\n", [ + "// Usually defined as environment variables", + "// host: https://localhost:1234", + "// EntraId.Client: 019607db-89cd-7b36-a6ba-005cafd23fd2", + "// EntraId.Scopes: api://restapia-demo/Test", + string.Empty, + "// values", + "EntraId.TenantId: 019606ad-ba48-77dd-b008-9354e8bd9d7d", + string.Empty, + "// settings", + "AuthUrl: https://login.microsoftonline.com/{{EntraId.TenantId}}/oauth2/v2.0/authorize", + "RedirectUrl: {{host}}/oauth2-callback", + "ClientId: {{EntraId.Client}}", + "Scopes: {{EntraId.Scopes}}", + ]) + }, + { + "AWS", string.Join("\n", [ + "// Usually defined as environment variables", + "// host: https://localhost:1234", + "// AWS.Client: 019607db-89cd-7b36-a6ba-005cafd23fd2", + "// AWS.Scopes: openid", + string.Empty, + "// values", + "AWS.Prefix: restapia-auth", + string.Empty, + "// settings", + "AuthUrl: https://{{AWS.Prefix}}.auth.us-east-1.amazoncognito.com/oauth2/authorize", + "RedirectUrl: {{host}}/oauth2-callback", + "ClientId: {{AWS.Client}}", + "Scopes: {{AWS.Scopes}}", + ]) + }, + }, }; private readonly ILogger _logger; diff --git a/src/Extensions/RestApia.Extensions.ValuesProvider.CollectionValuesProvider/EnvironmentValuesProvider.cs b/src/Extensions/RestApia.Extensions.ValuesProvider.CollectionValuesProvider/EnvironmentValuesProvider.cs index a290a54..d03fcc9 100644 --- a/src/Extensions/RestApia.Extensions.ValuesProvider.CollectionValuesProvider/EnvironmentValuesProvider.cs +++ b/src/Extensions/RestApia.Extensions.ValuesProvider.CollectionValuesProvider/EnvironmentValuesProvider.cs @@ -9,7 +9,9 @@ public class EnvironmentValuesProvider: IEnvironmentValuesProvider // no reserved values or custom controls public ValuesProviderSettings GetProviderSettings() => new () { - Title = "User Values", + Title = "Environment Values", + DefaultName = "DEV", + Description = "Environments help you keep your API interactions organized by separating configurations for different stages or versions of the APIs you are using", CanBeReloaded = false, DisableCachingResults = true, HelpPageUrl = "https://github.com/RestApia/RestApia.Shared/tree/main/src/Extensions/RestApia.Extensions.ValuesProvider.CollectionValuesProvider", diff --git a/src/Extensions/RestApia.Extensions.ValuesProvider.CollectionValuesProvider/UserValuesProvider.cs b/src/Extensions/RestApia.Extensions.ValuesProvider.CollectionValuesProvider/UserValuesProvider.cs index 2443f8a..4efe068 100644 --- a/src/Extensions/RestApia.Extensions.ValuesProvider.CollectionValuesProvider/UserValuesProvider.cs +++ b/src/Extensions/RestApia.Extensions.ValuesProvider.CollectionValuesProvider/UserValuesProvider.cs @@ -10,6 +10,7 @@ public class UserValuesProvider: IUserValuesProvider public ValuesProviderSettings GetProviderSettings() => new () { Title = "User Values", + DefaultName = "Global values", CanBeReloaded = false, DisableCachingResults = true, HelpPageUrl = "https://github.com/RestApia/RestApia.Shared/tree/main/src/Extensions/RestApia.Extensions.ValuesProvider.CollectionValuesProvider", diff --git a/src/RestApia.Shared/Extensions/ValuesProviderService/Models/ValuesProviderSettings.cs b/src/RestApia.Shared/Extensions/ValuesProviderService/Models/ValuesProviderSettings.cs index 931a8a1..b945d6d 100644 --- a/src/RestApia.Shared/Extensions/ValuesProviderService/Models/ValuesProviderSettings.cs +++ b/src/RestApia.Shared/Extensions/ValuesProviderService/Models/ValuesProviderSettings.cs @@ -3,11 +3,13 @@ public record ValuesProviderSettings { public required string Title { get; init; } + public required string DefaultName { get; init; } = string.Empty; public bool CanBeReloaded { get; init; } public bool DisableCachingResults { get; init; } public string HelpPageUrl { get; init; } = string.Empty; - public string DefaultName { get; init; } = string.Empty; + public string Description { get; init; } = string.Empty; public IReadOnlyCollection ReservedValues { get; init; } = []; + public IReadOnlyDictionary Examples { get; init; } = new Dictionary(); } From f8360f0fdf0902dc175df7fb00c5b527facfa928 Mon Sep 17 00:00:00 2001 From: Nick Rimmer Date: Sun, 6 Apr 2025 00:53:38 +0200 Subject: [PATCH 2/2] descriptions added --- .../RestApia.Extensions.Auth.Basic/BasicAuthService.cs | 2 +- .../AuthCode/OAuth2AuthCodeService.cs | 2 +- .../Implicit/OAuth2ImplicitService.cs | 2 +- .../EnvironmentValuesProvider.cs | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/src/Extensions/RestApia.Extensions.Auth.Basic/BasicAuthService.cs b/src/Extensions/RestApia.Extensions.Auth.Basic/BasicAuthService.cs index fd162a7..a0f78ba 100644 --- a/src/Extensions/RestApia.Extensions.Auth.Basic/BasicAuthService.cs +++ b/src/Extensions/RestApia.Extensions.Auth.Basic/BasicAuthService.cs @@ -15,7 +15,7 @@ public class BasicAuthService: IAuthValuesProvider { Title = "Basic Authentication", DefaultName = "Basic Auth", - Description = "Provide your login ID and password. This application will take these details and include them in the request header using the Basic Authentication standard.", + Description = "Provide your login ID and password. RestApia will take these details and include them in the request header using the Basic Authentication standard.", CanBeReloaded = true, DisableCachingResults = true, ReservedValues = diff --git a/src/Extensions/RestApia.Extensions.Auth.OAuth2/AuthCode/OAuth2AuthCodeService.cs b/src/Extensions/RestApia.Extensions.Auth.OAuth2/AuthCode/OAuth2AuthCodeService.cs index fa309a7..1449054 100644 --- a/src/Extensions/RestApia.Extensions.Auth.OAuth2/AuthCode/OAuth2AuthCodeService.cs +++ b/src/Extensions/RestApia.Extensions.Auth.OAuth2/AuthCode/OAuth2AuthCodeService.cs @@ -20,7 +20,7 @@ public class OAuth2AuthCodeService : IAuthValuesProvider { Title = "OAuth2: Auth Code", DefaultName = "OAuth2 Auth Code", - Description = "A window will open, taking you to the service provider's page to log in and grant permission. The provider will then issue a JWT token, which will be automatically used as the Bearer authorization header.", + Description = "A window will open, taking you to the service provider's page to log in and grant permission. Credentials provider will then issue a JWT token, which will be automatically used as Bearer authorization header.", CanBeReloaded = true, ReservedValues = diff --git a/src/Extensions/RestApia.Extensions.Auth.OAuth2/Implicit/OAuth2ImplicitService.cs b/src/Extensions/RestApia.Extensions.Auth.OAuth2/Implicit/OAuth2ImplicitService.cs index c08b05f..894f53e 100644 --- a/src/Extensions/RestApia.Extensions.Auth.OAuth2/Implicit/OAuth2ImplicitService.cs +++ b/src/Extensions/RestApia.Extensions.Auth.OAuth2/Implicit/OAuth2ImplicitService.cs @@ -16,7 +16,7 @@ public class OAuth2ImplicitService : IAuthValuesProvider { Title = "OAuth2: Implicit", DefaultName = "OAuth2 Implicit", - Description = "A window will open, taking you to the service provider to grant permission. Upon approval, an access token will be directly provided and automatically used as the Bearer authorization header.", + Description = "A window will open, taking you to the service provider to grant permission. Upon approval, an access token will be directly provided and automatically used as Bearer authorization header.", CanBeReloaded = true, ReservedValues = [ diff --git a/src/Extensions/RestApia.Extensions.ValuesProvider.CollectionValuesProvider/EnvironmentValuesProvider.cs b/src/Extensions/RestApia.Extensions.ValuesProvider.CollectionValuesProvider/EnvironmentValuesProvider.cs index d03fcc9..6c4e8d2 100644 --- a/src/Extensions/RestApia.Extensions.ValuesProvider.CollectionValuesProvider/EnvironmentValuesProvider.cs +++ b/src/Extensions/RestApia.Extensions.ValuesProvider.CollectionValuesProvider/EnvironmentValuesProvider.cs @@ -11,7 +11,7 @@ public class EnvironmentValuesProvider: IEnvironmentValuesProvider { Title = "Environment Values", DefaultName = "DEV", - Description = "Environments help you keep your API interactions organized by separating configurations for different stages or versions of the APIs you are using", + Description = "Environments help you keep your API interactions organized by separating configurations for different stages or versions of the APIs you are using. You can create multiple environments, each with its own set of values, headers and cookies.", CanBeReloaded = false, DisableCachingResults = true, HelpPageUrl = "https://github.com/RestApia/RestApia.Shared/tree/main/src/Extensions/RestApia.Extensions.ValuesProvider.CollectionValuesProvider",