Configuration.h

Go to the documentation of this file.

/*
 * Copyright(c) Sophist Solutions, Inc. 1990-2025.  All rights reserved
 */
#ifndef _Stroika_Frameworks_Auth_OAuth_Configuration_h_
#define _Stroika_Frameworks_Auth_OAuth_Configuration_h_ 1
 
#include "Stroika/Frameworks/StroikaPreComp.h"
 
#include "Stroika/Foundation/Characters/String.h"
#include "Stroika/Foundation/Common/Common.h"
#include "Stroika/Foundation/Common/GUID.h"
#include "Stroika/Foundation/Containers/KeyedCollection.h"
#include "Stroika/Foundation/Containers/Sequence.h"
#include "Stroika/Foundation/DataExchange/ObjectVariantMapper.h"
#include "Stroika/Foundation/IO/Network/URI.h"
 
/**
 *  \file
 *
 *  \note Code-Status:  <a href="Code-Status.md#Alpha">Alpha</a>
 */
 
namespace Stroika::Frameworks::Auth::OAuth {
 
    using namespace Stroika::Foundation;
 
    using Characters::String;
    using Containers::KeyedCollection;
    using Containers::Sequence;
    using Containers::Set;
    using IO::Network::URI;
 
    using DataExchange::ObjectVariantMapper;
 
    /**
     *  Documentation about these concepts:
     *      google  - https://developers.google.com/identity/protocols/oauth2/web-server#httprest
     *              - https://developers.google.com/identity/protocols/oauth2/javascript-implicit-flow
     */
 
    /**
     *  Documentation where to get/register application IDs
     *      google  - https://console.cloud.google.com/apis/credentials
     *      azure   - https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade
     *              - https://learn.microsoft.com/en-us/azure/active-directory-b2c/client-credentials-grant-flow?pivots=b2c-user-flow#app-registration-overview
     */
 
    /**
     *  \brief sometimes called ClientID, and sometimes called applicationID
     *  
     *  \note though this is often a GUID, it cannot be assumed to be a GUID (google for example, doesn't use GUIDs).
     */
    using ApplicationIDType = String;
 
    /**
     * often require things like no #/fragments
     */
    using RedirectURLType = URI;
 
    /**
     *  \brief Track configuration data about stuff that differentiates different
     *         OAuth providers - what URLs to use, base url, relative off that URLs for login/upgrade token/refresh etc.
     *         ALL very prelim at this stage.
     *
     *      see javascript frameworks - for doing auth2 - convert token to access token etc...
     *      stuff to fetch 'keys' like I vaguely remember from openid... to validate JWTs...\
     * 
     * 
     * 
     *      @todo - create API structure so can fill in details on this via fetch of https://accounts.google.com/.well-known/openid-configuration
     *          read docs on that - and meaning of various parts - and list here etc...
     * 
     *          probably use more optional<URI> on these....
     */
    class ProviderConfiguration {
    public:
        /**
         *  name used to join between ProviderConfiguration and ClientConfiguration::fProvider
         */
        String name;
 
        /**
         *  EG https://accounts.google.com/.well-known/openid-configuration
         *     https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration
         *     https://account.apple.com/.well-known/openid-configuration
         *     https://www.facebook.com/.well-known/openid-configuration
         *     https://dev-84941762.okta.com/.well-known/openid-configuration?client_id=0oa5km1v306LXN57y5d7
         * 
         *  \see https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata
         *  \see https://openid.net/specs/openid-connect-rpinitiated-1_0.html
         * 
         *  \note - this ID may or may not end in '/.well-known/openid-configuration'; however, even if it
         *          doesn't, that is implicitly appended before fetching the configuration data.
         */
        optional<URI> openid_configuration_uri;
 
        /**
         *  Same as authorization_endpoint from openid_configuration_uri
         */
        optional<URI> auth_uri;
 
        /**
         *  Same as token_endpoint from openid_configuration_uri
         *      \note facebook doesn't appear to support this - so I guess just use id_token and (what flow)???
         */
        optional<URI> token_uri;
 
        /**
         *  if missing, try FetchAdditionsFromOpenIDConfigurationURI (), or hopefully get id_token from GetToken() api.
         */
        optional<URI> userinfo_endpoint;
 
        /**
         *  GOOGLE uses this but I cannot find docs - https://accounts.google.com/.well-known/openid-configuration
         */
        optional<URI> revocation_endpoint;
 
        /**
         *  Same as jwks_uri from openid_configuration_uri
         */
        optional<URI> auth_provider_x509_cert_url;
 
        /**
         *  Fetch the data from the openid_configuration_uri, and use it to augment the fields
         *  of this structure, and return the updated record (replacing items that conflict).
         * 
         *  This can be used to fill in a Provider configuration when all you have is the URL for openid-configuration
         *
         *  \par Example Usage
         *      \code
         *          ProviderConfiguration providerConfig = 
         *              ProviderConfiguration{.name = "MyOKTAAccount", .openid_configuration_uri = "https://dev-84941762.okta.com/.well-known/openid-configuration?client_id=0oa5km1v306LXN57y5d7"}
         *              .FetchAdditionsFromOpenIDConfigurationURI ();
         *      \endcode
         */
        nonvirtual ProviderConfiguration FetchAdditionsFromOpenIDConfigurationURI () const;
 
        /**
         */
        nonvirtual bool operator== (const ProviderConfiguration& rhs) const = default;
 
#if qCompilerAndStdLib_explicitly_defaulted_threeway_warning_Buggy
        DISABLE_COMPILER_CLANG_WARNING_START ("clang diagnostic ignored \"-Wdefaulted-function-deleted\"")
#endif
        /**
         */
        nonvirtual auto operator<=> (const ProviderConfiguration& rhs) const = default;
 
#if qCompilerAndStdLib_explicitly_defaulted_threeway_warning_Buggy
        DISABLE_COMPILER_CLANG_WARNING_END ("clang diagnostic ignored \"-Wdefaulted-function-deleted\"")
#endif
 
        static const ObjectVariantMapper kMapper;
 
        nonvirtual String ToString () const;
    };
 
    namespace Private_ {
        using My_Extractor_ = decltype ([] (const ProviderConfiguration& t) -> String { return t.name; });
        using My_Traits_    = Containers::KeyedCollection_DefaultTraits<ProviderConfiguration, String, My_Extractor_>;
    }
    /**
     *  A list of definitions for configurations.
     * 
     *  @todo provide predefined one inside this framework, and allow it to be updated/revised in applications.
     *  REFERENED IMPLICITLY in ClientConfiguration
     */
    using ProvidersConfigurations = KeyedCollection<ProviderConfiguration, String, Private_::My_Traits_>;
 
    /**
     *  a predefined set of configurations, but you may need to update/roll your own, as this could get out of date.
     */
    extern const ProvidersConfigurations kDefaultProviderConfigurations;
 
    /**
     *  \note logically, we want to aggregate ProviderConfiguration inside ClientConfiguration, but
     *        since it can generally be static and unchanged, we keep it separate, and just link up/reference by 'name'
     */
    struct ClientConfiguration {
        String fProvider; // refers to some element of ProvidersConfigurationType
 
        /**
         *  This value is sometimes referred to in OAUTH as ClientID
         */
        ApplicationIDType fApplicationID;
 
        /**
         *  List of acceptable redirect URLs allowed in (which flows) authorization_code acquisition; only one will be actually used
         *  in the authentication_code request.
         */
        Sequence<RedirectURLType> fRedirectURLs;
 
        /**
         *  List of acceptable scopes requested. Some subset (often all) will be requested at in the authentication_code request.
         */
        Set<String> fScopes;
 
        /**
         *  This is used in some places, and must be hidden in others (so optional).
         */
        optional<String> fClientSecret;
 
        static const ObjectVariantMapper kMapper;
 
        /**
         */
        nonvirtual bool operator== (const ClientConfiguration& rhs) const = default;
 
        /**
         */
        nonvirtual auto operator<=> (const ClientConfiguration& rhs) const;
 
        /**
         */
        nonvirtual String ToString () const;
    };
 
    /**
     *  \par Example Usage
     *      \code
     *          {
     *              { .fProvider = "google", .fApplicationID = "003...", .fRedirectURLs = ["http://localhost"], .fScopes = ["openid"] },
     *              { .fProvider = "apple", .fApplicationID = "003...", .fRedirectURLs = ["http://localhost"], .fScopes = ["openid"] },
     *              { .fProvider = "twitter", .fApplicationID = "003...", .fRedirectURLs = ["http://localhost"], .fScopes = ["openid"] },
     *              { .fProvider = "facebook", .fApplicationID = "003...", .fRedirectURLs = ["http://localhost"], .fScopes = ["openid"] },
     *          }
     *      \endcode
     */
    using ClientConfigurations = Sequence<ClientConfiguration>;
 
}
 
/*
 ********************************************************************************
 ***************************** Implementation Details ***************************
 ********************************************************************************
 */
#include "Configuration.inl"
 
#endif /*_Stroika_Frameworks_Auth_OAuth_Configuration_h_*/