001package com.nimbusds.openid.connect.provider.spi.grants; 002 003 004import com.nimbusds.oauth2.sdk.GeneralException; 005import com.nimbusds.oauth2.sdk.Scope; 006import com.nimbusds.oauth2.sdk.id.ClientID; 007import com.nimbusds.openid.connect.sdk.rp.OIDCClientMetadata; 008import org.opensaml.saml2.core.Assertion; 009 010 011/** 012 * Service Provider Interface (SPI) for handling SAML 2.0 bearer assertion 013 * grants issued by a third-party security token service. Returns the matching 014 * {@link ThirdPartyAssertionAuthorization authorisation} on success. Must 015 * throw a {@link GeneralException} with an 016 * {@link com.nimbusds.oauth2.sdk.OAuth2Error#INVALID_GRANT invalid_grant} 017 * error code if the SAML 2.0 assertion is invalid. 018 * 019 * <p>The passed SAML 2.0 assertion is signed or MAC protected, and must be 020 * validated by the handler. 021 * 022 * <p>The handler should not specify access token lifetimes that exceed the 023 * validity period of the SAML 2.0 assertion by a significant period. The issue 024 * of refresh tokens is not permitted. Clients can refresh an expired access 025 * token by requesting a new one using the same assertion, if it is still 026 * valid, or with a new assertion. 027 * 028 * <p>Implementations must be thread-safe. 029 * 030 * <p>Related specifications: 031 * 032 * <ul> 033 * <li>Assertion Framework for OAuth 2.0 Client Authentication and 034 * Authorization Grants (RFC 7521), section 4.1. 035 * <li>Security Assertion Markup Language (SAML) 2.0 Profile for OAuth 2.0 036 * Client Authentication and Authorization Grants (RFC 7522), sections 037 * 2.1, 3 and 3.1. 038 * </ul> 039 */ 040public interface ThirdPartySAML2GrantHandler extends SAML2GrantHandler { 041 042 043 /** 044 * Handles a SAML 2.0 assertion grant issued by a third-party security 045 * token service. The grant handler must validate the assertion, using 046 * a previously agreed method to resolve the client's MAC or signature 047 * key. 048 * 049 * <p>The following client authentication / identification cases may be 050 * handled: 051 * 052 * <ol> 053 * <li><strong>Confidential client: </strong> 054 * If the client is confidential and has provided valid 055 * authentication (client_secret_basic, client_secret_post, 056 * client_secret_jwt or private_key_jwt) the 057 * {@code confidentialClient} flag will be {@code true}. The 058 * client_id and metadata arguments will be set. 059 * <li><strong>Public client: </strong> 060 * If the client is public and has a provided its registered 061 * {@code client_id} using the optional token request 062 * parameter, the {@code confidentialClient} flag will be 063 * {@code false} and the client metadata will be set. 064 * <li><strong>Handler must resolve client_id from SAML 2.0 assertion: </strong> 065 * If no client authentication or {@code client_id} is passed 066 * with the token request, the client information arguments 067 * will be {@code null} and the {@code confidentialClient} flag 068 * will be {@code false}. The grant handler must resolve the 069 * {@code client_id} for the authorisation result from details 070 * of the SAML 2.0 assertion. If such a use case is not 071 * supported or permitted the grant handler should throw a 072 * {@link GeneralException} with an 073 * {@link com.nimbusds.oauth2.sdk.OAuth2Error#INVALID_REQUEST 074 * invalid_request} error. 075 * </ol> 076 * 077 * <p>If the SAML 2.0 assertion is invalid the handler must throw a 078 * {@link GeneralException} with an 079 * {@link com.nimbusds.oauth2.sdk.OAuth2Error#INVALID_GRANT 080 * invalid_grant} error code. 081 * 082 * <p>If the requested scope is invalid, unknown, malformed, or exceeds 083 * the scope granted by the resource owner the handler must throw a 084 * {@link GeneralException} with an 085 * {@link com.nimbusds.oauth2.sdk.OAuth2Error#INVALID_SCOPE 086 * invalid_scope} error code. 087 * 088 * @param assertion The SAML 2.0 assertion, to be validated by 089 * the handler. Not {@code null}. 090 * @param scope The requested scope, {@code null} if not 091 * specified. 092 * @param clientID The client identifier, {@code null} if not 093 * specified or if no client authentication 094 * was provided. 095 * @param confidentialClient {@code true} if the client is confidential 096 * and has been authenticated, else 097 * {@code false}. 098 * @param clientMetadata The OAuth 2.0 / OpenID Connect client 099 * metadata, {@code null} if no 100 * {@code client_id} or client authentication 101 * was provided. 102 * 103 * @return The authorisation. 104 * 105 * @throws GeneralException If the grant is invalid, or another 106 * exception was encountered. 107 */ 108 ThirdPartyAssertionAuthorization processThirdPartyGrant(final Assertion assertion, 109 final Scope scope, 110 final ClientID clientID, 111 final boolean confidentialClient, 112 final OIDCClientMetadata clientMetadata) 113 throws GeneralException; 114}