salvo_oapi/swagger_ui/oauth.rs
1//! Implements Swagger UI [oauth configuration](https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/oauth2.md) options.
2
3use std::collections::HashMap;
4
5use serde::Serialize;
6
7/// Object used to alter Swagger UI oauth settings.
8///
9/// # Examples
10///
11/// ```
12/// # use salvo_oapi::swagger_ui::oauth;
13/// let config = oauth::Config::new()
14/// .client_id("client-id")
15/// .use_pkce_with_authorization_code_grant(true);
16/// ```
17#[non_exhaustive]
18#[derive(Default, Clone, Debug, Serialize)]
19#[serde(rename_all = "camelCase")]
20pub struct Config {
21 /// oauth client_id the Swagger UI is using for auth flow.
22 #[serde(skip_serializing_if = "Option::is_none")]
23 pub client_id: Option<String>,
24
25 /// oauth client_secret the Swagger UI is using for auth flow.
26 #[serde(skip_serializing_if = "Option::is_none")]
27 pub client_secret: Option<String>,
28
29 /// oauth realm the Swagger UI is using for auth flow.
30 /// realm query parameter (for oauth1) added to authorizationUrl and tokenUrl.
31 #[serde(skip_serializing_if = "Option::is_none")]
32 pub realm: Option<String>,
33
34 /// oauth app_name the Swagger UI is using for auth flow.
35 /// application name, displayed in authorization popup.
36 #[serde(skip_serializing_if = "Option::is_none")]
37 pub app_name: Option<String>,
38
39 /// oauth scope_separator the Swagger UI is using for auth flow.
40 /// scope separator for passing scopes, encoded before calling, default value is a space (encoded value %20).
41 #[serde(skip_serializing_if = "Option::is_none")]
42 pub scope_separator: Option<String>,
43
44 /// oauth scopes the Swagger UI is using for auth flow.
45 /// [`Vec<String>`] of initially selected oauth scopes, default is empty.
46 #[serde(skip_serializing_if = "Option::is_none")]
47 pub scopes: Option<Vec<String>>,
48
49 /// oauth additional_query_string_params the Swagger UI is using for auth flow.
50 /// [`HashMap<String, String>`] of additional query parameters added to authorizationUrl and tokenUrl
51 #[serde(skip_serializing_if = "Option::is_none")]
52 pub additional_query_string_params: Option<HashMap<String, String>>,
53
54 /// oauth use_basic_authentication_with_access_code_grant the Swagger UI is using for auth flow.
55 /// Only activated for the accessCode flow. During the authorization_code request to the tokenUrl,
56 /// pass the [Client Password](https://tools.ietf.org/html/rfc6749#section-2.3.1) using the HTTP Basic Authentication scheme
57 /// (Authorization header with Basic base64encode(client_id + client_secret)).
58 /// The default is false
59 #[serde(skip_serializing_if = "Option::is_none")]
60 pub use_basic_authentication_with_access_code_grant: Option<bool>,
61
62 /// oauth use_pkce_with_authorization_code_grant the Swagger UI is using for auth flow.
63 /// Only applies to authorizatonCode flows. [Proof Key for Code Exchange](https://tools.ietf.org/html/rfc7636)
64 /// brings enhanced security for OAuth public clients.
65 /// The default is false
66 #[serde(skip_serializing_if = "Option::is_none")]
67 pub use_pkce_with_authorization_code_grant: Option<bool>,
68}
69
70impl Config {
71 /// Create a new [`Config`] for oauth auth flow.
72 ///
73 /// # Examples
74 ///
75 /// ```
76 /// # use salvo_oapi::swagger_ui::oauth;
77 /// let config = oauth::Config::new();
78 /// ```
79 pub fn new() -> Self {
80 Self { ..Default::default() }
81 }
82
83 /// Add client_id into [`Config`].
84 ///
85 /// Method takes one argument which exposes the client_id to the user.
86 ///
87 /// # Examples
88 ///
89 /// ```
90 /// # use salvo_oapi::swagger_ui::oauth;
91 /// let config = oauth::Config::new()
92 /// .client_id("client-id");
93 /// ```
94 pub fn client_id(mut self, client_id: &str) -> Self {
95 self.client_id = Some(String::from(client_id));
96
97 self
98 }
99
100 /// Add client_secret into [`Config`].
101 ///
102 /// Method takes one argument which exposes the client_secret to the user.
103 /// 🚨 Never use this parameter in your production environment.
104 /// It exposes crucial security information. This feature is intended for dev/test environments only. 🚨
105 ///
106 /// # Examples
107 ///
108 /// ```
109 /// # use salvo_oapi::swagger_ui::oauth;
110 /// let config = oauth::Config::new()
111 /// .client_secret("client-secret");
112 /// ```
113 pub fn client_secret(mut self, client_secret: &str) -> Self {
114 self.client_secret = Some(String::from(client_secret));
115
116 self
117 }
118
119 /// Add realm into [`Config`].
120 ///
121 /// Method takes one argument which exposes the realm to the user.
122 /// realm query parameter (for oauth1) added to authorizationUrl and tokenUrl.
123 ///
124 /// # Examples
125 ///
126 /// ```
127 /// # use salvo_oapi::swagger_ui::oauth;
128 /// let config = oauth::Config::new()
129 /// .realm("realm");
130 /// ```
131 pub fn realm(mut self, realm: &str) -> Self {
132 self.realm = Some(String::from(realm));
133
134 self
135 }
136
137 /// Add app_name into [`Config`].
138 ///
139 /// Method takes one argument which exposes the app_name to the user.
140 /// application name, displayed in authorization popup.
141 ///
142 /// # Examples
143 ///
144 /// ```
145 /// # use salvo_oapi::swagger_ui::oauth;
146 /// let config = oauth::Config::new()
147 /// .app_name("app-name");
148 /// ```
149 pub fn app_name(mut self, app_name: &str) -> Self {
150 self.app_name = Some(String::from(app_name));
151
152 self
153 }
154
155 /// Add scope_separator into [`Config`].
156 ///
157 /// Method takes one argument which exposes the scope_separator to the user.
158 /// scope separator for passing scopes, encoded before calling, default value is a space (encoded value %20).
159 ///
160 /// # Examples
161 ///
162 /// ```
163 /// # use salvo_oapi::swagger_ui::oauth;
164 /// let config = oauth::Config::new()
165 /// .scope_separator(",");
166 /// ```
167 pub fn scope_separator(mut self, scope_separator: &str) -> Self {
168 self.scope_separator = Some(String::from(scope_separator));
169
170 self
171 }
172
173 /// Add scopes into [`Config`].
174 ///
175 /// Method takes one argument which exposes the scopes to the user.
176 /// [`Vec<String>`] of initially selected oauth scopes, default is empty.
177 ///
178 /// # Examples
179 ///
180 /// ```
181 /// # use salvo_oapi::swagger_ui::oauth;
182 /// let config = oauth::Config::new()
183 /// .scopes(vec![String::from("openid")]);
184 /// ```
185 pub fn scopes(mut self, scopes: Vec<String>) -> Self {
186 self.scopes = Some(scopes);
187
188 self
189 }
190
191 /// Add additional_query_string_params into [`Config`].
192 ///
193 /// Method takes one argument which exposes the additional_query_string_params to the user.
194 /// [`HashMap<String, String>`] of additional query parameters added to authorizationUrl and tokenUrl
195 ///
196 /// # Examples
197 ///
198 /// ```
199 /// # use salvo_oapi::swagger_ui::oauth;
200 /// # use std::collections::HashMap;
201 /// let config = oauth::Config::new()
202 /// .additional_query_string_params(HashMap::from([(String::from("a"), String::from("1"))]));
203 /// ```
204 pub fn additional_query_string_params(mut self, additional_query_string_params: HashMap<String, String>) -> Self {
205 self.additional_query_string_params = Some(additional_query_string_params);
206
207 self
208 }
209
210 /// Add use_basic_authentication_with_access_code_grant into [`Config`].
211 ///
212 /// Method takes one argument which exposes the use_basic_authentication_with_access_code_grant to the user.
213 /// Only activated for the accessCode flow. During the authorization_code request to the tokenUrl,
214 /// pass the [Client Password](https://tools.ietf.org/html/rfc6749#section-2.3.1) using the HTTP Basic Authentication scheme
215 /// (Authorization header with Basic base64encode(client_id + client_secret)).
216 /// The default is false
217 ///
218 /// # Examples
219 ///
220 /// ```
221 /// # use salvo_oapi::swagger_ui::oauth;
222 /// let config = oauth::Config::new()
223 /// .use_basic_authentication_with_access_code_grant(true);
224 /// ```
225 pub fn use_basic_authentication_with_access_code_grant(
226 mut self,
227 use_basic_authentication_with_access_code_grant: bool,
228 ) -> Self {
229 self.use_basic_authentication_with_access_code_grant = Some(use_basic_authentication_with_access_code_grant);
230
231 self
232 }
233
234 /// Add use_pkce_with_authorization_code_grant into [`Config`].
235 ///
236 /// Method takes one argument which exposes the use_pkce_with_authorization_code_grant to the user.
237 /// Only applies to authorizatonCode flows. [Proof Key for Code Exchange](https://tools.ietf.org/html/rfc7636)
238 /// brings enhanced security for OAuth public clients.
239 /// The default is false
240 ///
241 /// # Examples
242 ///
243 /// ```
244 /// # use salvo_oapi::swagger_ui::oauth;
245 /// let config = oauth::Config::new()
246 /// .use_pkce_with_authorization_code_grant(true);
247 /// ```
248 pub fn use_pkce_with_authorization_code_grant(mut self, use_pkce_with_authorization_code_grant: bool) -> Self {
249 self.use_pkce_with_authorization_code_grant = Some(use_pkce_with_authorization_code_grant);
250
251 self
252 }
253}