1 package com.guinetik.rr.auth;
2
3 import com.guinetik.rr.http.RocketHeaders;
4
5 /**
6 * Interface for authentication strategies used by RocketRest.
7 *
8 * <p>Authentication strategies encapsulate the logic for different authentication methods,
9 * from simple bearer tokens to complex OAuth 2.0 flows. Implementations are pluggable
10 * and can be configured via {@link com.guinetik.rr.RocketRestConfig}.
11 *
12 * <h2>Available Implementations</h2>
13 * <ul>
14 * <li>{@link NoAuthStrategy} - No authentication</li>
15 * <li>{@link BasicAuthStrategy} - HTTP Basic authentication</li>
16 * <li>{@link BearerTokenStrategy} - Bearer token authentication</li>
17 * <li>{@link OAuth2ClientCredentialsStrategy} - OAuth 2.0 client credentials flow</li>
18 * <li>{@link OAuth2PasswordStrategy} - OAuth 2.0 password grant flow</li>
19 * <li>{@link OAuth2AssertionStrategy} - OAuth 2.0 assertion/SAML flow</li>
20 * </ul>
21 *
22 * <h2>Using Strategies</h2>
23 * <pre class="language-java"><code>
24 * // Via factory (recommended)
25 * AuthStrategy bearer = AuthStrategyFactory.createBearerToken("my-token");
26 * AuthStrategy basic = AuthStrategyFactory.createBasicAuth("user", "pass");
27 * AuthStrategy oauth = AuthStrategyFactory.createOAuth2ClientCredentials(
28 * "client-id", "client-secret", "https://auth.example.com/token"
29 * );
30 *
31 * // Configure in RocketRestConfig
32 * RocketRestConfig config = RocketRestConfig.builder("https://api.example.com")
33 * .authStrategy(bearer)
34 * .build();
35 * </code></pre>
36 *
37 * <h2>Custom Strategy Implementation</h2>
38 * <pre class="language-java"><code>
39 * public class CustomAuthStrategy implements AuthStrategy {
40 * {@literal @}Override
41 * public AuthType getType() {
42 * return AuthType.BEARER_TOKEN;
43 * }
44 *
45 * {@literal @}Override
46 * public RocketHeaders applyAuthHeaders(RocketHeaders headers) {
47 * headers.set("X-Custom-Auth", computeAuthValue());
48 * return headers;
49 * }
50 *
51 * {@literal @}Override
52 * public boolean needsTokenRefresh() {
53 * return isTokenExpired();
54 * }
55 *
56 * {@literal @}Override
57 * public boolean refreshCredentials() {
58 * return fetchNewToken();
59 * }
60 * }
61 * </code></pre>
62 *
63 * @author guinetik <guinetik@gmail.com>
64 * @see AuthStrategyFactory
65 * @see com.guinetik.rr.RocketRestConfig
66 * @since 1.0.0
67 */
68 public interface AuthStrategy {
69
70 /**
71 * Enum representing different authentication types.
72 */
73 enum AuthType {
74 NONE,
75 BEARER_TOKEN,
76 BASIC,
77 OAUTH_CLIENT_CREDENTIALS,
78 OAUTH_IDP,
79 OAUTH_PASSWORD,
80 OAUTH_ASSERTION
81 }
82
83 /**
84 * Returns the auth type of this strategy.
85 * @return the authentication type
86 */
87 AuthType getType();
88
89 /**
90 * Applies authentication headers to an existing HttpHeader object.
91 * @param headers the current HttpHeader to update
92 * @return the updated HttpHeader
93 */
94 RocketHeaders applyAuthHeaders(RocketHeaders headers);
95
96 /**
97 * Indicates whether this strategy needs a token refresh.
98 * @return true if token refresh is required
99 */
100 boolean needsTokenRefresh();
101
102 /**
103 * Handles refreshing the authentication credentials for strategies that support it.
104 * @return true if the credentials were successfully refreshed
105 * @throws TokenRefreshException if the refresh operation fails
106 */
107 boolean refreshCredentials();
108 }