package ca.cdr.test.app.clients;
/*-
 * #%L
 * Smile CDR - CDR
 * %%
 * Copyright (C) 2016 - 2026 Smile CDR, Inc.
 * %%
 * All rights reserved.
 * #L%
 */

import com.google.gson.Gson;
import com.google.gson.JsonElement;
import com.google.gson.JsonObject;
import jakarta.annotation.Nonnull;
import jakarta.annotation.Nullable;
import org.apache.commons.codec.binary.Base64;
import org.apache.http.client.utils.URLEncodedUtils;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.http.HttpHeaders;
import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;
import org.springframework.web.client.RestClient;
import org.springframework.web.client.RestClientException;
import org.springframework.util.LinkedMultiValueMap;
import org.springframework.util.MultiValueMap;
import org.springframework.web.util.UriComponentsBuilder;
import tools.jackson.databind.JsonNode;

import java.io.IOException;
import java.net.URI;
import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;
import java.util.Arrays;
import java.util.List;
import java.util.Objects;

import static org.apache.commons.lang3.StringUtils.isNotBlank;

// Created by Claude Sonnet 4

/**
 * A client for performing SMART on FHIR OAuth 2.0 authorization flows.
 * 
 * <p>This client provides methods to interact with SMART on FHIR OAuth 2.0 endpoints
 * and supports the following OAuth 2.0 flows:</p>
 * <ul>
 *   <li><strong>Authorization Code Flow</strong> - For web applications requiring user consent</li>
 *   <li><strong>Client Credentials Flow</strong> - For backend services, authenticating with a
 *       client secret or a signed JWT assertion</li>
 *   <li><strong>Refresh Token Flow</strong></li>
 *   <li><strong>Token Introspection</strong> and <strong>OpenID Connect discovery</strong></li>
 * </ul>
 * 
 * <p>The client handles HTTP communication with the SMART authorization server,
 * form-based authentication, CSRF token management, and token exchange operations.</p>
 * 
 * <h3>Thread Safety:</h3>
 * <p>This client is not thread-safe. Each thread should use its own instance
 * or external synchronization should be applied.</p>
 * 
 * @author Claude Sonnet 4
 * @see <a href="http://hl7.org/fhir/smart-app-launch/">SMART App Launch Framework</a>
 * @see <a href="https://tools.ietf.org/html/rfc6749">OAuth 2.0 Authorization Framework</a>
 */
public class OutboundSmartClient {
        private static final Logger ourLog = LoggerFactory.getLogger(OutboundSmartClient.class);

        private static final String CLIENT_ASSERTION_TYPE_JWT_BEARER =
                "urn:ietf:params:oauth:client-assertion-type:jwt-bearer";
        private static final String GRANT_TYPE_JWT_BEARER = "urn:ietf:params:oauth:grant-type:jwt-bearer";

        private final RestClient myRestClient;
        private final String mySmartRootUrl;

        /**
         * Creates a new OutboundSmartClient instance.
         * 
         * @param theRestClient the REST client to use for HTTP communication with the SMART server.
         *                      This client should be configured with appropriate timeouts, SSL settings,
         *                      and cookie management as needed for the target SMART server.
         * @param theSmartRootUrl the root URL of the SMART authorization server (e.g., "https://auth.example.com"),
         *                        including any context path. This should not include trailing slashes or
         *                        specific endpoints. When it has a context path, {@code theRestClient}'s base
         *                        URL must end in a slash so that request paths resolve beneath it.
         *                        Its message converters are replaced by ones that read JSON with Jackson 3.
         * @throws NullPointerException if either parameter is null
         */
        public OutboundSmartClient(@Nonnull RestClient theRestClient, @Nonnull String theSmartRootUrl) {
                myRestClient = Objects.requireNonNull(theRestClient, "theRestClient must not be null")
                                .mutate()
                                .configureMessageConverters(ClientMessageConverters::configure)
                                .build();
                mySmartRootUrl = Objects.requireNonNull(theSmartRootUrl, "theSmartRootUrl must not be null");
        }
        /**
         * Exchanges an authorization code for an access token with flexible client authentication.
         * 
         * <p>This method provides full control over how the client secret is transmitted to the
         * authorization server. It supports both HTTP Basic authentication (in the Authorization header)
         * and form parameter authentication (in the request body).</p>
         * 
         * <p>The method constructs a form-encoded POST request to the token endpoint with the
         * authorization code and other required parameters. The response is parsed to extract
         * the access token.</p>
         * 
         * @param theClientId the OAuth 2.0 client identifier. Must not be null.
         * @param theClientSecret the client secret. If null, no client authentication is performed.
         * @param theCode the authorization code to exchange. Must not be null.
         * @param secret_as_param if true, the client secret is sent as a form parameter (client_secret);
         *                        if false, the client secret is sent via HTTP Basic authentication
         *                        in the Authorization header. This parameter is ignored if theClientSecret is null.
         * @return the access token as a string
         * @throws IOException if the token exchange request fails or if the response cannot be parsed
         * @see <a href="https://tools.ietf.org/html/rfc6749#section-4.1.3">RFC 6749 Section 4.1.3</a>
         */
        public String exchangeCodeWithSecret(
                String theClientId, String theClientSecret, String theCode, String theRedirectUri, boolean secret_as_param) throws IOException {
                
                // Validate required parameters
                if (theClientId == null || theClientId.trim().isEmpty()) {
                        throw new IllegalArgumentException("theClientId must not be null or empty");
                }
                if (theCode == null || theCode.trim().isEmpty()) {
                        throw new IllegalArgumentException("theCode must not be null or empty");
                }
                
                // Build form data string directly
                String formData = "code=" + theCode +
                        "&grant_type=authorization_code" +
                        "&redirect_uri="+ URLEncoder.encode(theRedirectUri) +
                        "&client_id=" + theClientId;

                // Build the request
                RestClient.RequestBodySpec requestSpec = myRestClient
                        .post()
                        .uri("/oauth/token")
                        .contentType(MediaType.APPLICATION_FORM_URLENCODED);

                // Add authorization header if needed
                if (isNotBlank(theClientSecret)) {
                        if (secret_as_param) {
                                formData += "&client_secret=" + theClientSecret;
                        } else {
                                String auth = "Basic " + Base64.encodeBase64String(
                                        (theClientId + ":" + theClientSecret).getBytes(StandardCharsets.UTF_8));
                                requestSpec.header("Authorization", auth);
                        }
                }

                // Execute the request and process response
                String respString = requestSpec
                        .body(formData)
                        .retrieve()
                        .body(String.class);

                ourLog.debug("Resp: {}", respString);

                JsonObject respObj = new Gson().fromJson(respString, JsonObject.class);

                // Safely extract access_token
                JsonElement accessTokenElement = respObj.get("access_token");
                if (accessTokenElement == null || accessTokenElement.isJsonNull()) {
                        throw new IOException("access_token not found in response");
                }
                return accessTokenElement.getAsString();
        }

        /**
         * Refreshes an access token using a refresh token.
         * 
         * <p>When an access token expires, a refresh token (if available) can be used to obtain
         * a new access token without requiring the user to re-authorize the application.
         * This method performs the token refresh operation.</p>
         * 
         * <p>The authorization server may issue a new refresh token along with the new access token,
         * and the old refresh token should be considered invalid.</p>
         * 
         * @param theClientId the OAuth 2.0 client identifier. Must match the original client that
         *                    obtained the refresh token. Must not be null or empty.
         * @param theClientSecret the OAuth 2.0 client secret, sent with HTTP Basic authentication. May be
         *                        null for a public client, which sends {@code client_id} as a form
         *                        parameter instead.
         * @param theRefreshToken the refresh token obtained from a previous token request.
         *                        Must not be null or empty.
         * @return JSON document as a string containing the new access token and potentially a new
         *         refresh token. Typical response includes: access_token, token_type, expires_in,
         *         refresh_token (optional), scope. {@link AccessTokenResponse#fromJson(JsonNode)} reads it.
         * @throws IllegalArgumentException if required parameters are null or empty
         * @see <a href="https://tools.ietf.org/html/rfc6749#section-6">RFC 6749 Section 6</a>
         */
        @Nonnull
        public String refreshToken(
                        @Nonnull String theClientId,
                        @Nullable String theClientSecret,
                        @Nonnull String theRefreshToken) {
                requireNotBlank(theClientId, "theClientId");
                requireNotBlank(theRefreshToken, "theRefreshToken");

                MultiValueMap<String, String> form = new LinkedMultiValueMap<>();
                form.add("grant_type", "refresh_token");
                form.add("refresh_token", theRefreshToken);
                if (theClientSecret == null) {
                        form.add("client_id", theClientId);
                }
                return Objects.requireNonNull(
                        postForm("oauth/token", form, theClientSecret == null ? null : theClientId, theClientSecret)
                                .body(String.class));
        }

        /**
         * Obtains an access token with the client credentials grant, authenticating with a client
         * secret sent via HTTP Basic authentication.
         *
         * @param theClientId the OAuth 2.0 client identifier
         * @param theClientSecret the client secret
         * @param theScopes the scopes to request; none leaves the {@code scope} parameter out
         * @return the token endpoint's response
         * @see <a href="https://tools.ietf.org/html/rfc6749#section-4.4">RFC 6749 Section 4.4</a>
         */
        @Nonnull
        public AccessTokenResponse clientCredentials(
                        @Nonnull String theClientId, @Nonnull String theClientSecret, @Nullable String... theScopes) {
                requireNotBlank(theClientId, "theClientId");
                requireNotBlank(theClientSecret, "theClientSecret");

                MultiValueMap<String, String> form = new LinkedMultiValueMap<>();
                form.add("grant_type", "client_credentials");
                addScope(form, theScopes);
                return tokenResponse(postForm("oauth/token", form, theClientId, theClientSecret));
        }

        /**
         * Obtains an access token with the client credentials grant, authenticating with a signed JWT
         * client assertion, as SMART Backend Services clients do. This client only transports the
         * assertion: building and signing it is the caller's job.
         *
         * @param theClientId the OAuth 2.0 client identifier, sent as {@code client_id}
         * @param theSignedJwtAssertion the signed JWT, sent as {@code client_assertion}
         * @param theScopes the scopes to request; none leaves the {@code scope} parameter out
         * @return the token endpoint's response
         * @see <a href="https://datatracker.ietf.org/doc/html/rfc7523#section-2.2">RFC 7523 Section 2.2</a>
         */
        @Nonnull
        public AccessTokenResponse clientCredentialsWithAssertion(
                        @Nonnull String theClientId, @Nonnull String theSignedJwtAssertion, @Nullable String... theScopes) {
                requireNotBlank(theClientId, "theClientId");
                requireNotBlank(theSignedJwtAssertion, "theSignedJwtAssertion");

                MultiValueMap<String, String> form = new LinkedMultiValueMap<>();
                form.add("grant_type", "client_credentials");
                form.add("client_id", theClientId);
                form.add("client_assertion_type", CLIENT_ASSERTION_TYPE_JWT_BEARER);
                form.add("client_assertion", theSignedJwtAssertion);
                addScope(form, theScopes);
                return tokenResponse(postForm("oauth/token", form, null, null));
        }

        @Nonnull
        public AccessTokenResponse jwtBearerWithAssertion(
                        @Nonnull String theAuthorizationGrant, @Nonnull String theSignedJwtAssertion, @Nullable String... theScopes) {
                requireNotBlank(theAuthorizationGrant, "theAuthorizationGrant");
                requireNotBlank(theSignedJwtAssertion, "theSignedJwtAssertion");

                MultiValueMap<String, String> form = new LinkedMultiValueMap<>();
                form.add("grant_type", GRANT_TYPE_JWT_BEARER);
                form.add("assertion", theAuthorizationGrant);
                form.add("client_assertion_type", CLIENT_ASSERTION_TYPE_JWT_BEARER);
                form.add("client_assertion", theSignedJwtAssertion);
                addScope(form, theScopes);
                return tokenResponse(postForm("oauth/token", form, null, null));
        }

        /**
         * Asks the server whether a token is active, authenticating as a client with HTTP Basic
         * authentication.
         *
         * @param theToken the access or refresh token to introspect
         * @param theClientId the client to authenticate as
         * @param theClientSecret that client's secret
         * @return the introspection response, whose {@code active} member says whether the token is live
         * @see <a href="https://datatracker.ietf.org/doc/html/rfc7662">RFC 7662</a>
         */
        @Nonnull
        public JsonNode introspect(
                        @Nonnull String theToken, @Nonnull String theClientId, @Nonnull String theClientSecret) {
                requireNotBlank(theToken, "theToken");
                requireNotBlank(theClientId, "theClientId");
                requireNotBlank(theClientSecret, "theClientSecret");

                MultiValueMap<String, String> form = new LinkedMultiValueMap<>();
                form.add("token", theToken);
                return Objects.requireNonNull(
                        postForm("oauth/token/introspect", form, theClientId, theClientSecret).body(JsonNode.class));
        }

        /**
         * Fetches the server's OpenID Connect discovery document.
         *
         * @return the contents of {@code .well-known/openid-configuration}
         */
        @Nonnull
        public JsonNode openIdConfiguration() {
                return Objects.requireNonNull(
                        myRestClient.get().uri(".well-known/openid-configuration").retrieve().body(JsonNode.class));
        }

        private RestClient.ResponseSpec postForm(
                        String theUri,
                        MultiValueMap<String, String> theForm,
                        @Nullable String theBasicUser,
                        @Nullable String theBasicPassword) {
                return myRestClient
                        .post()
                        .uri(theUri)
                        .contentType(MediaType.APPLICATION_FORM_URLENCODED)
                        .accept(MediaType.APPLICATION_JSON)
                        .headers(headers -> {
                                if (theBasicUser != null && theBasicPassword != null) {
                                        headers.set(HttpHeaders.AUTHORIZATION, basicAuth(theBasicUser, theBasicPassword));
                                }
                        })
                        .body(theForm)
                        .retrieve();
        }

        private static AccessTokenResponse tokenResponse(RestClient.ResponseSpec theResponse) {
                return AccessTokenResponse.fromJson(Objects.requireNonNull(theResponse.body(JsonNode.class)));
        }

        private void addScope(MultiValueMap<String, String> theForm, String[] theScopes) {
                if (theScopes != null && theScopes.length > 0) {
                        theForm.add("scope", buildScopeString(theScopes));
                }
        }

        private static String basicAuth(String theUser, String thePassword) {
                return "Basic " + Base64.encodeBase64String((theUser + ":" + thePassword).getBytes(StandardCharsets.UTF_8));
        }

        private static void requireNotBlank(String theValue, String theName) {
                if (theValue == null || theValue.trim().isEmpty()) {
                        throw new IllegalArgumentException(theName + " must not be null or empty");
                }
        }

        /**
         * Performs the complete OAuth 2.0 authorization code flow including user login.
         * 
         * <p>This method orchestrates the entire authorization code flow by:</p>
         * <ol>
         *   <li>Obtaining an authorization code through the authorization endpoint</li>
         *   <li>Exchanging the authorization code for an access token</li>
         * </ol>
         * 
         * <p>The method handles both confidential clients (with secret) and public clients (without secret).</p>
         * 
         * @param clientId the OAuth 2.0 client identifier. Must not be null.
         * @param redirectUri the redirect URI for receiving the authorization code. Must not be null.
         * @param theScopes array of requested OAuth 2.0 scopes. Must not be null.
         * @param state the state parameter for CSRF protection. May be null.
         * @param theSecret the client secret. If null, the client is treated as public.
         * @return the access token as a string
         * @throws IOException if any HTTP communication or response parsing fails
         * @see #getAuthorizationCode(String, String, String[], String, String, String)
         * @see #exchangeCode(String, String, String)
         * @see #exchangeCodeWithSecret(String, String,String,  String, boolean)
         */
        public String performAuthorizationCodeFlow(String clientId, String redirectUri, String[] theScopes, String state, String theSecret, String theUsername, String thePassword) throws IOException {
                String code = getAuthorizationCode(clientId, redirectUri, theScopes, state, theUsername, thePassword);
                String token;
                if (theSecret != null) {
                        token = exchangeCodeWithSecret(clientId, theSecret, code, redirectUri, true);
                } else {
                        token = exchangeCode(clientId, code, redirectUri);
                }
                return token;
        }

        /**
         * Attempts to access an authorization URL and handles the redirect to the login screen.
         * 
         * <p>This method makes a GET request to the authorization endpoint and expects to receive
         * a redirect response (302/303) that points to the login screen. This is part of the normal
         * OAuth 2.0 flow when the user is not yet authenticated.</p>
         * 
         * @param theRequestUrl the authorization URL to request. Must not be null.
         * @return the login screen URL extracted from the Location header of the redirect response
         * @throws IOException if the request URL doesn't redirect to the expected signin location
         * @throws RestClientException if the response is not a redirect (302/303) or if the Location header is missing
         */
        public String authorizeBeforeLogin(String theRequestUrl) throws IOException {
                String signinLocation ="";

                ResponseEntity<String> retrieve = myRestClient
                        .get()
                        .uri(theRequestUrl)
                        .retrieve().toEntity(String.class);

                if (retrieve.getStatusCode().value() == 302 || retrieve.getStatusCode().value() == 303) {
                        URI uri = retrieve.getHeaders().getLocation();
                        if (uri != null) {
                                signinLocation = uri.toString();
                                if (!signinLocation.startsWith(mySmartRootUrl + "/signin")) {
                                        throw new IOException("Expected redirect to signin but got: " + signinLocation);
                                }
                        }
                } else {
                        throw new RestClientException("Expected 3XX redirect but got " + retrieve.getStatusCode());
                }
                return signinLocation;
        }
        /**
         * Obtains an authorization code through the OAuth 2.0 authorization flow.
         * 
         * <p>This method performs the first part of the authorization code flow:</p>
         * <ol>
         *   <li>Constructs the authorization URL with the provided parameters</li>
         *   <li>Follows redirects to the login screen</li>
         *   <li>Performs login</li>
         *   <li>Completes the authorization and extracts the authorization code</li>
         * </ol>
         * 
         * <p>The authorization code can then be exchanged for tokens using 
         * {@link #exchangeCode(String, String,String )} or related methods.</p>
         * 
         * @param clientId the OAuth 2.0 client identifier. Must not be null.
         * @param redirectUri the redirect URI for receiving the authorization code. Must not be null.
         * @param theScopes array of requested OAuth 2.0 scopes. Must not be null.
         * @param state the state parameter for CSRF protection. May be null.
         * @return the authorization code as a string
         * @throws IOException if any HTTP communication fails or if the authorization code cannot be extracted
         * @see #performAuthorizationCodeFlow(String, String, String[], String, String, String, String)
         */
        public String getAuthorizationCode(String clientId, String redirectUri, String[] theScopes, String state, String theUsername, String thePassword) throws IOException {
                String scopes = buildScopeString(theScopes);

                String requestUrl = UriComponentsBuilder.fromPath("/oauth/authorize")
                        .queryParam("response_type", "code")
                        .queryParam("scope", scopes)
                        .queryParam("client_id", clientId)
                        .queryParam("state", state)
                        .queryParam("redirect_uri", redirectUri)
                        .toUriString();

                //First, attempt the authorize call, and get bounced.
                authorizeBeforeLogin(requestUrl);

                String nextUrl = loginWithPassword(theUsername ,thePassword);
                return authorizeAfterLogin(nextUrl);
        }

        /**
         * Builds a space-separated scope string from an array of scopes.
         * 
         * <p>This utility method converts an array of OAuth 2.0 scope strings into a single
         * space-separated string as required by the OAuth 2.0 specification.</p>
         * 
         * @param theScopes array of OAuth 2.0 scopes. Must not be null.
         * @return space-separated scope string, or empty string if no scopes provided
         */
        public String buildScopeString(String[] theScopes) {
                List<String> scopeList = Arrays.stream(theScopes).toList();
                String scopes = "";

                if (!scopeList.isEmpty()) {
                        scopes = String.join(" ", scopeList);
                }
                return scopes;
        }

        /**
         * Exchanges an authorization code for an access token (public client).
         * 
         * <p>This is a convenience method for public clients that don't have a client secret.
         * It delegates to {@link #exchangeCodeWithSecret(String, String, String, String)} with
         * a null client secret.</p>
         * 
         * @param theClientId the OAuth 2.0 client identifier. Must not be null.
         * @param theCode the authorization code to exchange. Must not be null.
         * @return the access token as a string
         * @throws IOException if the token exchange request fails
         * @see #exchangeCodeWithSecret(String, String, String, String)
         */
        public String exchangeCode(String theClientId, String theCode, String theRedirectUri) throws IOException {
                return exchangeCodeWithSecret(theClientId, null, theCode, theRedirectUri);
        }

        /**
         * Exchanges an authorization code for an access token using HTTP Basic authentication.
         * 
         * <p>This is a convenience method that delegates to 
         * {@link #exchangeCodeWithSecret(String, String, String, String, boolean)} with
         * the secret_as_param flag set to false, meaning the client secret will be sent
         * in the Authorization header using HTTP Basic authentication.</p>
         * 
         * @param theClientId the OAuth 2.0 client identifier. Must not be null.
         * @param theClientSecret the client secret. If null, no authentication is performed.
         * @param theCode the authorization code to exchange. Must not be null.
         * @return the access token as a string
         * @throws IOException if the token exchange request fails
         * @see #exchangeCodeWithSecret(String, String,String, String, boolean)
         */
        public String exchangeCodeWithSecret(String theClientId, String theClientSecret, String theCode, String theRedirectUri)
                throws IOException {
                return exchangeCodeWithSecret(theClientId, theClientSecret, theCode,theRedirectUri, false);
        }

        /**
         * Completes the authorization step and extracts the authorization code from the redirect.
         * 
         * <p>This method makes a request to the authorization URL (after user login) and expects
         * to receive a redirect response containing the authorization code. The authorization code
         * is extracted from the callback URL in the Location header.</p>
         * 
         * @param theAuthorizeUrl the authorization URL to request (typically received after login). Must not be null.
         * @return the authorization code extracted from the redirect URL
         * @throws IOException if the authorization code cannot be found in the redirect URL
         * @throws RestClientException if the response is not a redirect (302/303) or if the Location header is missing
         * @see #extractCodeFromUrl(String)
         */
        public String authorizeAfterLogin(String theAuthorizeUrl) throws IOException {
                String code;
                ResponseEntity<String> resp = myRestClient
                        .get()
                        .uri(theAuthorizeUrl)
                        .retrieve()
                        .toEntity(String.class);
                theAuthorizeUrl = expectRedirectAndGetLocationHeaderValue(resp);
                code = extractCodeFromUrl(theAuthorizeUrl);
                return code;
        }

        private String expectRedirectAndGetLocationHeaderValue(ResponseEntity<String> resp) {
                if (!(resp.getStatusCode().value() == 302 || resp.getStatusCode().value() == 303)) {
                        throw new RestClientException("Expected redirect response (302/303) but got: " + resp.getStatusCode().value());
                }
                URI uri = resp.getHeaders().getLocation();
                if (uri != null) {
                        return uri.toString();
                } else {
                        throw new RestClientException("During redirect, the Location header was missing!");
                }
        }

        /**
         * Extracts the authorization code from a callback URL.
         * 
         * <p>This utility method parses the authorization code from the "code" query parameter
         * in an OAuth 2.0 callback URL. This is typically used when processing the redirect
         * response from the authorization server.</p>
         * 
         * @param theUrl the callback URL containing the authorization code parameter. Must not be null.
         * @return the authorization code value
         * @throws IOException if the authorization code parameter is not found in the URL
         */
        public static String extractCodeFromUrl(String theUrl) throws IOException {
                if (theUrl == null || theUrl.trim().isEmpty()) {
                        throw new IllegalArgumentException("theUrl must not be null or empty");
                }
                
                String code;
                int start = theUrl.indexOf("code=");
                if (start == -1) {
                        throw new IOException("Could not find authorization code in redirect URL: " + theUrl);
                }
                
                int codeStart = start + "code=".length();
                int end = theUrl.indexOf('&', start);
                if (end == -1) {
                        // No more parameters after code, use end of string
                        end = theUrl.length();
                }
                
                code = theUrl.substring(codeStart, end);
                return code;
        }

        /**
         * Fetches the login screen and extracts the CSRF token.
         * 
         * <p>This method retrieves the SMART login page and parses the HTML to extract
         * the CSRF token required for form-based authentication. The CSRF token is
         * embedded in a hidden form field and is required to prevent cross-site request forgery attacks.</p>
         * 
         * @return the CSRF token extracted from the login screen HTML
         * @throws IOException if an error occurs while fetching the login screen or if the expected
         *                     login page content is not found
         * @see WebTestUtil#extractCsrfToken(String)
         */
        private String fetchCsrfTokenFromLoginScreen() throws IOException {
                String respString = myRestClient
                        .get()
                        .uri("/signin")
                        .retrieve()
                        .body(String.class);

                ourLog.debug("Response: {}", respString);
                if (respString == null || !respString.contains("<title>Login to SMART Application</title>")) {
                        throw new IOException("Response does not contain expected login page title");
                }

                return WebTestUtil.extractCsrfToken(respString);
        }

        /**
         * Performs form-based login with username and password credentials.
         * 
         * <p>This method handles the complete login process:</p>
         * <ol>
         *   <li>Fetches the login page and extracts the CSRF token</li>
         *   <li>Submits the login form with credentials and CSRF token</li>
         *   <li>Follows the redirect response to get the next URL in the flow</li>
         * </ol>
         * 
         * @param theUser the username for authentication. Must not be null.
         * @param thePassword the password for authentication. Must not be null.
         * @return the URL to redirect to after successful login (typically the authorization endpoint)
         * @throws IOException if the login request fails or if the expected redirect response is not received
         * @throws RestClientException if the HTTP response status is not a redirect (302/303)
         */
        public String loginWithPassword(String theUser, String thePassword) throws IOException {
                String csrfToken = fetchCsrfTokenFromLoginScreen();
                String formData = "username=" + theUser + "&password=" + thePassword + "&_csrf=" + csrfToken;

                ResponseEntity<String> response = myRestClient
                        .post()
                        .uri("/authenticate")
                        .contentType(MediaType.APPLICATION_FORM_URLENCODED)
                        .body(formData)
                        .retrieve()
                        .toEntity(String.class);

                return expectRedirectAndGetLocationHeaderValue(response);
        }
}