Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 15 additions & 7 deletions docs/LOCAL_TESTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,8 +32,8 @@ Logs go to `.local-run/<app>.log`. Run the smoke check before testing by hand; i
| AS admin | `admin` / `admin` at http://localhost:9999/login | A passkey is enrolled at first login (`/webauthn/register`), by design. Override with `ESPI_BOOTSTRAP_ADMIN_USERNAME` / `ESPI_BOOTSTRAP_ADMIN_PASSWORD_HASH`. |
| DC admin | `admin` / `admin` | Sandbox custodian user (dev/test profiles only). |
| DC customer | `customer` / `customer` | Owns the sample UsagePoint (see "Sample data"). `local` profile only. |
| TP admin | `admin` / `admin` at http://localhost:8082/ThirdParty/login | TP administrator (`ROLE_CUSTODIAN`); also opens the H2 console at `/ThirdParty/h2-console/`. `local` profile only. |
| TP customer | `customer` / `customer` | TP customer (`ROLE_USER`); sees the Data Access Authorization cards. `local` profile only. |
| TP admin | `admin` / `admin` at http://localhost:8082/ThirdParty/login | TP administrator (`ROLE_CUSTODIAN`); obtains the TP's client access token on the admin page, and opens the H2 console at `/ThirdParty/h2-console/`. `local` profile only. |
| TP customer | `customer` / `customer` | TP customer (`ROLE_USER`); authorizes the TP at the DC from the Data Access Authorization cards (see "Customer flow"). `local` profile only. |

## OAuth clients (AS)

Expand Down Expand Up @@ -106,12 +106,20 @@ On the `local` profile the DC seeds a small, deterministic ESPI dataset at start

The schema values follow the most common shapes in the Green Button CMD certification test feeds. Every identifying value is synthetic (`example.com`, `555-01xx`, `SAMPLE-…` numbers).

## Customer flow (TP → AS → DC → TP)

1. Sign in to the TP as `customer` / `customer` at http://localhost:8082/ThirdParty/login.
2. On the TP home page, choose **Authorize Monthly Access** (or Daily). The TP sends you to the AS, which hands the login and consent to the DC.
3. At the DC, sign in as `customer` / `customer` and approve the requested data on the Authorization Screen.
4. You return to the TP home page, still signed in to the TP, with "The Data Custodian authorized this Third Party". **Your authorizations** lists the scope, the access token's expiry, and the `resourceURI`, `authorizationURI` and `customerResourceURI` from the token response.

The TP stores each token in its own ESPI `authorizations` table (Spring Security `oauth2Client`, #146), so the tokens survive a TP restart only on `dev-mysql` / `dev-postgresql`; on `local` the H2 database is in memory.

The TP administrator (`admin` / `admin`) can obtain the TP's own client access token (client_credentials, `FB=34_35`) from the **Client Access Token** card on the admin page; it shows the scope, expiry, the first characters of the token only, and the token response's `authorizationURI`, `resourceURI` (energy usage Bulk) and `customerResourceURI` (Customer PII Bulk, when applicable). The AS does not return these URIs for client_credentials tokens yet (#202).

## Known limitations

The customer flow does not complete yet. Open blockers, in the order they are hit (see the roadmap, #255):
The customer flow stops after the token is stored. Open items (see the roadmap, #255):

- **#249:** the TP has no user login page.
- **#232:** the AS → DC delegation (`/authorize/delegate`) drops the authorization parameters and returns 400.
- **#146 / #202:** the TP's token handling and the resource URIs in the token response.
- **#197 / #89:** the TP cannot yet read and display the DC's feeds.
- **#211:** a customer narrowing the requested data at consent gets `invalid_scope`.
- **#202:** the AS's token-response URIs: `customerResourceURI` is gated on FB 54–62 instead of FB_51, a refresh re-provisions the subscription, and the `FB=34_35` client access token carries no `authorizationURI`, `resourceURI` (energy usage Bulk) or `customerResourceURI` (Customer PII Bulk).
Original file line number Diff line number Diff line change
Expand Up @@ -230,6 +230,13 @@ public class AuthorizationEntity extends IdentifiedObject {
@Column(name = "correlation_id", length = 256, unique = true)
private String correlationId;

/**
* Third Party only (#146): the Spring OAuth2 client registration that obtained this
* Authorization's tokens (e.g. {@code datacustodian-monthly}). Not in the ESPI XSD; never exported.
*/
@Column(name = "client_registration_id", length = 100)
private String clientRegistrationId;

/**
* Retail customer who granted this authorization.
* Many authorizations can belong to one customer.
Expand Down Expand Up @@ -509,6 +516,7 @@ public String toString() {
"customerResourceURI = " + getCustomerResourceURI() + ", " +
"thirdParty = " + getThirdParty() + ", " +
"correlationId = " + getCorrelationId() + ", " +
"clientRegistrationId = " + getClientRegistrationId() + ", " +
"description = " + getDescription() + ", " +
"created = " + getCreated() + ", " +
"updated = " + getUpdated() + ", " +
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -106,6 +106,7 @@ public interface AuthorizationMapper {
@Mapping(target = "retailCustomer", ignore = true) // Complex mapping, handle separately
@Mapping(target = "subscriptions", ignore = true) // Aggregate children, managed via the subscription lifecycle
@Mapping(target = "correlationId", ignore = true) // AS back-channel bookkeeping (#202), not in the XSD
@Mapping(target = "clientRegistrationId", ignore = true) // Third Party bookkeeping (#146), not in the XSD
AuthorizationEntity toEntity(AuthorizationDto dto);

}
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,24 @@ public interface AuthorizationRepository extends JpaRepository<AuthorizationEnti

Optional<AuthorizationEntity> findByState(String state);

/**
* Third Party token store (#146): the Authorization a TP customer obtained through one OAuth2
* client registration (authorization_code). Newest first, in case of duplicates.
*/
Optional<AuthorizationEntity> findFirstByClientRegistrationIdAndRetailCustomer_UsernameOrderByUpdatedDesc(
String clientRegistrationId, String username);

/**
* Third Party token store (#146): the TP's own client access token (client_credentials), which
* belongs to the Third Party, not to a customer.
*/
Optional<AuthorizationEntity> findFirstByClientRegistrationIdAndRetailCustomerIsNullOrderByUpdatedDesc(
String clientRegistrationId);

/** Third Party token store (#146): every Authorization a TP customer obtained, newest first. */
List<AuthorizationEntity> findAllByRetailCustomer_UsernameAndClientRegistrationIdIsNotNullOrderByUpdatedDesc(
String username);

/** Back-channel idempotency lookup (#202): the Authorization provisioned for an AS grant. */
Optional<AuthorizationEntity> findByCorrelationId(String correlationId);

Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
/*
* OpenESPI Authorization client registration id (#146)
*
* Copyright (c) 2018-2026 Green Button Alliance, Inc.
* Licensed under the Apache License, Version 2.0
*
* The Third Party stores each token it obtains from a Data Custodian (access and refresh token,
* scope, resourceURI, authorizationURI, customerResourceURI) in its own authorizations table. A TP
* customer may hold one Authorization per Spring OAuth2 client registration (for example
* datacustodian-monthly and datacustodian-daily, which ask for different scopes), so the row records
* which registration obtained it.
*
* Additive and vendor-neutral (MySQL, PostgreSQL, H2): nullable, so existing rows and the Data
* Custodian's Authorizations (which never set it) are unaffected. Not part of the ESPI standard:
* Third Party bookkeeping, never exported in XML.
*/

ALTER TABLE authorizations ADD COLUMN client_registration_id VARCHAR(100);

CREATE INDEX idx_authorization_client_registration_id ON authorizations (client_registration_id);
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@
* ({@code ThirdParty_Admin_Access} by default). Endpoint access is read-only
* ({@code management.endpoint.*.access} in application.yml).</p>
*
* <p>Ordered first so actuator requests never reach the {@code oauth2Login} chain in
* <p>Ordered first so actuator requests never reach the browser (form login) chain in
* {@link SecurityConfiguration}, which would redirect them to the login page.</p>
*/
@Configuration
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,21 @@

package org.greenbuttonalliance.espi.thirdparty.config;

import org.greenbuttonalliance.espi.common.domain.usage.RetailCustomerEntity;
import org.greenbuttonalliance.espi.common.repositories.usage.AuthorizationRepository;
import org.greenbuttonalliance.espi.common.repositories.usage.RetailCustomerRepository;
import org.greenbuttonalliance.espi.common.service.EspiIdGeneratorService;
import org.greenbuttonalliance.espi.thirdparty.oauth.EspiAuthorizationOAuth2AuthorizedClientService;
import org.greenbuttonalliance.espi.thirdparty.oauth.EspiTokenResponseParameters;
import org.greenbuttonalliance.espi.thirdparty.oauth.TpCustomerAuthorizationRequestResolver;
import org.greenbuttonalliance.espi.thirdparty.security.RetailCustomerUserDetailsService;
import org.springframework.security.oauth2.client.endpoint.OAuth2AccessTokenResponseClient;
import org.springframework.security.oauth2.client.endpoint.OAuth2AuthorizationCodeGrantRequest;
import org.springframework.security.oauth2.client.endpoint.OAuth2ClientCredentialsGrantRequest;
import org.springframework.security.oauth2.client.endpoint.OAuth2RefreshTokenGrantRequest;
import org.springframework.security.oauth2.client.endpoint.RestClientAuthorizationCodeTokenResponseClient;
import org.springframework.security.oauth2.client.endpoint.RestClientClientCredentialsTokenResponseClient;
import org.springframework.security.oauth2.client.endpoint.RestClientRefreshTokenTokenResponseClient;
import org.greenbuttonalliance.espi.thirdparty.security.ReturnToAuthenticationSuccessHandler;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
Expand Down Expand Up @@ -74,8 +88,7 @@ public PasswordEncoder customerPasswordEncoder() {
* {@link #customerPasswordEncoder()}, whatever other {@code PasswordEncoder} beans exist. As an
* {@code AuthenticationProvider} bean it becomes the global (parent) provider, so it must not also
* be added to a chain with {@code http.authenticationProvider(...)}: a second copy re-checks every
* failed login (two lookups, two BCrypt checks). Not {@code http.authenticationManager(...)}
* either: that would drop the provider {@code oauth2Login} registers on the chain.
* failed login (two lookups, two BCrypt checks).
*/
@Bean
public DaoAuthenticationProvider customerAuthenticationProvider(RetailCustomerUserDetailsService userDetailsService) {
Expand All @@ -85,17 +98,26 @@ public DaoAuthenticationProvider customerAuthenticationProvider(RetailCustomerUs
}

/**
* Two separate steps (#249): a TP customer or administrator first signs in to the Third Party
* with {@code formLogin} against the TP's own accounts ({@link #customerAuthenticationProvider});
* {@code oauth2Login} is then used from the home page only to authorize the TP at a Data
* Custodian, never to sign in to the TP.
* Two separate steps (#249, #146): a TP customer or administrator signs in to the Third Party
* with {@code formLogin} against the TP's own accounts ({@link #customerAuthenticationProvider}).
* A signed-in TP customer then authorizes the TP at a Data Custodian with {@code oauth2Client}:
* it completes the authorization-code grant and stores the token for the TP customer, without
* ever signing anyone in or changing who is signed in ({@code oauth2Login} replaced the customer's
* sign-in with the Data Custodian's, and signed in visitors who had no TP account).
*/
@Bean
public SecurityFilterChain filterChain(HttpSecurity http,
@Value("${spring.h2.console.path:/h2-console}") String h2ConsolePath)
@Value("${spring.h2.console.path:/h2-console}") String h2ConsolePath,
ClientRegistrationRepository clientRegistrationRepository,
OAuth2AccessTokenResponseClient<OAuth2AuthorizationCodeGrantRequest>
authorizationCodeTokenResponseClient)
throws Exception {
http
.authorizeHttpRequests(authz -> authz
// Starting a Data Custodian authorization is for a signed-in TP customer only (an
// anonymous visitor goes to the login page first; see TpCustomerAuthorizationRequestResolver).
.requestMatchers(TpCustomerAuthorizationRequestResolver.AUTHORIZATION_BASE_URI + "/**",
"/oauth2/authorize/**").hasAuthority(RetailCustomerEntity.ROLE_USER)
// Public pages (Terms of Service and Usage Policy are linked from the navbar, About from
// the footer)
.requestMatchers("/", "/home", "/login", "/about", "/TermsOfService", "/UsagePolicy", "/error",
Expand All @@ -121,13 +143,15 @@ public SecurityFilterChain filterChain(HttpSecurity http,
.failureUrl("/login?error")
.permitAll()
)
.oauth2Login(oauth2 -> oauth2
.loginPage("/login")
.defaultSuccessUrl("/", true)
// A refused or failed Data Custodian authorization is not a TP sign-in failure:
// send the customer home with its own message, not to the login page's
// "Invalid username or password".
.failureUrl("/?authorization_error")
// The Data Custodian redirects back to {baseUrl}/login/oauth2/code/{registrationId} (the
// redirect URIs the AS registers). OAuth2AuthorizationCodeGrantFilter exchanges the code and
// then redirects to that path again, with ?error=... if consent was refused or the exchange
// failed; OAuth2ClientController turns that into the home page's message.
.oauth2Client(client -> client
.authorizationCodeGrant(grant -> grant
.authorizationRequestResolver(new TpCustomerAuthorizationRequestResolver(clientRegistrationRepository))
.accessTokenResponseClient(authorizationCodeTokenResponseClient)
)
)
.logout(logout -> logout
.logoutUrl("/logout")
Expand Down Expand Up @@ -156,18 +180,63 @@ public SecurityFilterChain filterChain(HttpSecurity http,
}

/**
* OAuth2 Authorized Client Manager for handling OAuth2 flows.
* Supports authorization_code, refresh_token flows with automatic token refresh.
* The Third Party's Data Custodian tokens live in its ESPI {@code authorizations} table, with the
* token response's ESPI URIs (#146), not in Spring's in-memory store.
*/
@Bean
public EspiAuthorizationOAuth2AuthorizedClientService authorizedClientService(
ClientRegistrationRepository clientRegistrationRepository,
AuthorizationRepository authorizationRepository,
RetailCustomerRepository retailCustomerRepository,
EspiIdGeneratorService espiIdGeneratorService,
EspiTokenResponseParameters espiTokenResponseParameters) {
return new EspiAuthorizationOAuth2AuthorizedClientService(clientRegistrationRepository,
authorizationRepository, retailCustomerRepository, espiIdGeneratorService, espiTokenResponseParameters);
}

/** Hands each token response's ESPI URIs from the token-response clients to the token store. */
@Bean
public EspiTokenResponseParameters espiTokenResponseParameters() {
return new EspiTokenResponseParameters();
}

/** authorization_code token exchange, keeping the response's ESPI URIs for the token store. */
@Bean
public OAuth2AccessTokenResponseClient<OAuth2AuthorizationCodeGrantRequest> authorizationCodeTokenResponseClient(
EspiTokenResponseParameters espiTokenResponseParameters) {
return espiTokenResponseParameters.capturing(new RestClientAuthorizationCodeTokenResponseClient());
}

/** refresh_token exchange, keeping the response's ESPI URIs (if it repeats them) for the token store. */
@Bean
public OAuth2AccessTokenResponseClient<OAuth2RefreshTokenGrantRequest> refreshTokenTokenResponseClient(
EspiTokenResponseParameters espiTokenResponseParameters) {
return espiTokenResponseParameters.capturing(new RestClientRefreshTokenTokenResponseClient());
}

/** client_credentials exchange (the TP's client access token), keeping any ESPI URIs for the token store. */
@Bean
public OAuth2AccessTokenResponseClient<OAuth2ClientCredentialsGrantRequest> clientCredentialsTokenResponseClient(
EspiTokenResponseParameters espiTokenResponseParameters) {
return espiTokenResponseParameters.capturing(new RestClientClientCredentialsTokenResponseClient());
}

/**
* Obtains and refreshes Data Custodian tokens: a customer's (authorization_code, refreshed with
* its refresh token) and the TP's client access token (client_credentials).
*/
@Bean
public OAuth2AuthorizedClientManager authorizedClientManager(
ClientRegistrationRepository clientRegistrationRepository,
OAuth2AuthorizedClientRepository authorizedClientRepository) {
OAuth2AuthorizedClientRepository authorizedClientRepository,
OAuth2AccessTokenResponseClient<OAuth2RefreshTokenGrantRequest> refreshTokenTokenResponseClient,
OAuth2AccessTokenResponseClient<OAuth2ClientCredentialsGrantRequest> clientCredentialsTokenResponseClient) {

OAuth2AuthorizedClientProvider authorizedClientProvider =
OAuth2AuthorizedClientProviderBuilder.builder()
.authorizationCode()
.refreshToken()
.refreshToken(refresh -> refresh.accessTokenResponseClient(refreshTokenTokenResponseClient))
.clientCredentials(client -> client.accessTokenResponseClient(clientCredentialsTokenResponseClient))
.build();

DefaultOAuth2AuthorizedClientManager authorizedClientManager =
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -17,19 +17,20 @@
*
*/

package org.greenbuttonalliance.espi.thirdparty.web.custodian;
package org.greenbuttonalliance.espi.thirdparty.oauth;

import org.greenbuttonalliance.espi.thirdparty.web.CustodianHomeController;
import org.junit.jupiter.api.Test;
/** The Spring OAuth2 client registration ids the Third Party uses with the Data Custodian (application.yml). */
public final class DataCustodianRegistrations {

import static org.junit.jupiter.api.Assertions.assertEquals;
/** authorization_code: a TP customer's monthly usage data. */
public static final String MONTHLY = "datacustodian-monthly";

/** authorization_code: a TP customer's daily usage data. */
public static final String DAILY = "datacustodian-daily";

public class CustodianHomeControllerTests {
/** client_credentials: the TP's client access token (ESPI Authorization and Bulk APIs). */
public static final String CLIENT_ACCESS = "datacustodian-admin";

@Test
public void index_displaysCustodianHomeView() throws Exception {
CustodianHomeController controller = new CustodianHomeController();
assertEquals("custodian/home", controller.index());
private DataCustodianRegistrations() {
}
}
Loading
Loading