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