001/* 002 * Copyright 2026 Revetware LLC. 003 * 004 * Licensed under the Apache License, Version 2.0 (the "License"); 005 * you may not use this file except in compliance with the License. 006 * You may obtain a copy of the License at 007 * 008 * http://www.apache.org/licenses/LICENSE-2.0 009 * 010 * Unless required by applicable law or agreed to in writing, software 011 * distributed under the License is distributed on an "AS IS" BASIS, 012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 013 * See the License for the specific language governing permissions and 014 * limitations under the License. 015 */ 016 017package com.revetsec.oidc; 018 019import com.revetsec.oauth.OAuthObserver; 020import org.jspecify.annotations.NonNull; 021import javax.annotation.concurrent.ThreadSafe; 022 023/** 024 * Receives caller-thread OIDC events and the inherited OAuth/JOSE endpoint events. Hooks carry no tokens or claims. 025 * Hook failures are contained except for VirtualMachineError; implementations must be thread-safe and fast. 026 * 027 * @author <a href="https://www.revetkn.com">Mark Allen</a> 028 * @since 1.0.0 029 */ 030@ThreadSafe 031public interface OidcObserver extends OAuthObserver { 032 /** 033 * Returns a silent observer. 034 * @return the disabled observer 035 * @since 1.0.0 036 */ 037 static @NonNull OidcObserver disabledInstance() { return DisabledOidcObserver.INSTANCE; } 038 /** 039 * Called after a client successfully builds with an explicit compatibility mode. 040 * @param mode enabled mode; no credential is passed 041 * @since 1.0.0 042 */ 043 default void didEnableCompatibilityMode(@NonNull OidcCompatibilityMode mode) { } 044 /** 045 * Called when validation uses the mode, including when its signature or later checks fail. 046 * @param mode used mode; no credential or token is passed 047 * @since 1.0.0 048 */ 049 default void didUseCompatibilityMode(@NonNull OidcCompatibilityMode mode) { } 050 /** 051 * Called when an ID token or OIDC token response fails validation, before token release. 052 * @param exception the same fixed-message exception the caller receives 053 * @since 1.0.0 054 */ 055 default void didRejectIdToken(@NonNull OidcValidationException exception) { } 056 /** 057 * Called after successful OIDC validation. No identity or credential is passed. 058 * @since 1.0.0 059 */ 060 default void didCompleteAuthentication() { } 061 /** 062 * Called when a UserInfo response fails profile validation. No claims or credentials are passed. 063 * @param exception fixed-message rejection 064 * @since 1.0.0 065 */ 066 default void didRejectUserInfo(@NonNull OidcValidationException exception) { } 067 /** 068 * Called after the UserInfo subject matches the verified authentication. 069 * @param signed whether a signed response was validated 070 * @since 1.0.0 071 */ 072 default void didFetchUserInfo(@NonNull Boolean signed) { } 073 /** 074 * Called when refresh profile/continuity checks reject. No endpoint credential or rejected claim is passed. 075 * @param exception fixed-message rejection 076 * @since 1.0.0 077 */ 078 default void didRejectRefresh(@NonNull OidcValidationException exception) { } 079 /** 080 * Called after refresh tokens are released following all required ID-token checks. 081 * @param idTokenReturned whether a new verified ID token was returned 082 * @param refreshTokenReturned whether the endpoint supplied a replacement refresh token 083 * @since 1.0.0 084 */ 085 default void didRefreshTokens(@NonNull Boolean idTokenReturned, @NonNull Boolean refreshTokenReturned) { } 086 087 /** 088 * Called once after successful build selects the fixed Entra issuer policy. 089 * @since 1.0.0 090 */ 091 default void didEnableMicrosoftEntraMultiTenant() { } 092 /** 093 * Called when Entra ID-token validation or an authenticated UserInfo tenant check uses the selected policy, 094 * including rejected outcomes. No tenant or credential is supplied. 095 * @since 1.0.0 096 */ 097 default void didUseMicrosoftEntraMultiTenant() { } 098 099}