001/*-
002 * #%L
003 * Smile CDR - CDR
004 * %%
005 * Copyright (C) 2016 - 2025 Smile CDR, Inc.
006 * %%
007 * All rights reserved.
008 * #L%
009 */
010package ca.cdr.api.security;
011
012import ca.cdr.api.annotations.CdrPublicAPI;
013import ca.cdr.api.model.json.OpenIdTokenResponse;
014import ca.uhn.fhir.rest.server.exceptions.InternalErrorException;
015
016/**
017 * Interface for the client authentication service to handle token acquisition from an
018 * OpenID Connect (OIDC) Identity Provider using client-specific configurations.
019 * <p>
020 * This interface provides a method to request and retrieve an authorization token
021 * based on the provided authentication state. It is intended to support various
022 * authorization flows, as defined by the OIDC and SMART on FHIR standards.
023 */
024@CdrPublicAPI
025public interface IClientAuthSvc {
026
027        /**
028         * Retrieves an authorization token from an OpenID Connect (OIDC) Identity Provider
029         * using the given authentication state. If the token cannot be retrieved due to
030         * an authentication failure or another error, this method throws an appropriate exception.
031         * <p>
032         * @param theState The authentication state containing client credentials and configuration
033         *                 necessary to obtain the authorization token.
034         * @return An {@link OpenIdTokenResponse} object containing the authorization token
035         *         and related information such as expiration time and token type.
036         * @throws IllegalArgumentException If required authentication parameters are missing or invalid.
037         * @throws InternalErrorException If the authorization request fails, such as receiving
038         *                                       an error response from the authorization server.
039         */
040        OpenIdTokenResponse getAuthTokenOrThrow(ClientAuthState theState);
041}