001package com.nimbusds.openid.connect.provider.spi.grants; 002 003 004import net.jcip.annotations.ThreadSafe; 005import org.opensaml.saml.saml2.core.Assertion; 006 007import com.nimbusds.oauth2.sdk.GeneralException; 008import com.nimbusds.oauth2.sdk.Scope; 009import com.nimbusds.oauth2.sdk.id.ClientID; 010import com.nimbusds.openid.connect.provider.spi.InvocationContext; 011import com.nimbusds.openid.connect.sdk.rp.OIDCClientMetadata; 012 013 014/** 015 * Service Provider Interface (SPI) for handling self-issued SAML 2.0 bearer 016 * assertion grants. Returns the matching 017 * {@link SelfIssuedAssertionAuthorization authorisation} on success. 018 * 019 * <p>The handler should not specify access token lifetimes that exceed the 020 * validity period of the SAML 2.0 assertion by a significant period. The issue 021 * of refresh tokens is not permitted. Clients can refresh an expired access 022 * token by requesting a new one using the same assertion, if it is still 023 * valid, or with a new assertion. 024 * 025 * <p>Implementations must be thread-safe. 026 * 027 * <p>Related specifications: 028 * 029 * <ul> 030 * <li>Assertion Framework for OAuth 2.0 Client Authentication and 031 * Authorization Grants (RFC 7521), section 4.1. 032 * <li>Security Assertion Markup Language (SAML) 2.0 Profile for OAuth 2.0 033 * Client Authentication and Authorization Grants (RFC 7522), sections 034 * 2.1, 3 and 3.1. 035 * </ul> 036 */ 037@ThreadSafe 038public interface SelfIssuedSAML2GrantHandler extends SAML2GrantHandler { 039 040 041 /** 042 * Handles a self-issued SAML 2.0 bearer assertion grant by a client 043 * registered with the Connect2id server. 044 * 045 * <p>This method is called for SAML 2.0 assertion grants which fulfil 046 * all the following conditions: 047 * 048 * <ol> 049 * <li>Are issued by a client which is registered with the 050 * Connect2id server, i.e. the assertion issuer matches a 051 * registered client_id; 052 * <li>The client is registered for the 053 * {@code urn:ietf:params:oauth:grant-type:saml2-bearer} grant; 054 * <li>The client is successfully authenticated, by means of 055 * separate client authentication included in the token request 056 * (client_secret_basic, client_secret_post, client_secret_jwt 057 * or private_key_jwt), and / or with the SAML 2.0 assertion 058 * grant itself; 059 * <li>The SAML 2.0 assertion MAC or signature was successfully 060 * verified using with a registered {@code client_secret} or 061 * {@code jwks} / {@code jwks_uri}; 062 * <li>The assertion audience, expiration and not-before time are 063 * verify successfully. 064 * </ol> 065 * 066 * <p>If the requested scope is invalid, unknown, malformed, or exceeds 067 * the scope granted by the resource owner the handler must throw a 068 * {@link GeneralException} with an 069 * {@link com.nimbusds.oauth2.sdk.OAuth2Error#INVALID_SCOPE 070 * invalid_scope} error code. 071 * 072 * @param assertion The SAML 2.0 assertion. The audience, 073 * expiration, not-before time and XML signature 074 * are verified by the Connect2id server. 075 * The issuer will equal the client_id. Not 076 * {@code null}. 077 * @param scope The requested scope, {@code null} if not 078 * specified. 079 * @param clientID The identifier of the authenticated client. 080 * Not {@code null}. 081 * @param clientMetadata The OAuth 2.0 / OpenID Connect metadata for 082 * the client. Not {@code null}. 083 * 084 * @return The authorisation. 085 * 086 * @throws GeneralException If the grant is invalid, or another 087 * exception was encountered. 088 */ 089 @Deprecated 090 default SelfIssuedAssertionAuthorization processSelfIssuedGrant(final Assertion assertion, 091 final Scope scope, 092 final ClientID clientID, 093 final OIDCClientMetadata clientMetadata) 094 throws GeneralException { 095 096 return null; 097 } 098 099 100 /** 101 * Handles a self-issued SAML 2.0 bearer assertion grant by a client 102 * registered with the Connect2id server. 103 * 104 * <p>This method is called for SAML 2.0 assertion grants which fulfil 105 * all the following conditions: 106 * 107 * <ol> 108 * <li>Are issued by a client which is registered with the 109 * Connect2id server, i.e. the assertion issuer matches a 110 * registered client_id; 111 * <li>The client is registered for the 112 * {@code urn:ietf:params:oauth:grant-type:saml2-bearer} grant; 113 * <li>The client is successfully authenticated, by means of 114 * separate client authentication included in the token request 115 * (client_secret_basic, client_secret_post, client_secret_jwt 116 * or private_key_jwt), and / or with the SAML 2.0 assertion 117 * grant itself; 118 * <li>The SAML 2.0 assertion MAC or signature was successfully 119 * verified using with a registered {@code client_secret} or 120 * {@code jwks} / {@code jwks_uri}; 121 * <li>The assertion audience, expiration and not-before time are 122 * verify successfully. 123 * </ol> 124 * 125 * <p>If the requested scope is invalid, unknown, malformed, or exceeds 126 * the scope granted by the resource owner the handler must throw a 127 * {@link GeneralException} with an 128 * {@link com.nimbusds.oauth2.sdk.OAuth2Error#INVALID_SCOPE 129 * invalid_scope} error code. 130 * 131 * @param assertion The SAML 2.0 assertion. The audience, 132 * expiration, not-before time and XML 133 * signature are verified by the Connect2id 134 * server. The issuer will equal the 135 * client_id. Not {@code null}. 136 * @param tokenRequestParams The token request parameters, such as the 137 * requested scope. Not {@code null}. 138 * @param clientID The identifier of the authenticated client. 139 * Not {@code null}. 140 * @param clientMetadata The OAuth 2.0 / OpenID Connect metadata for 141 * the client. Not {@code null}. 142 * @param invocationCtx The invocation context. Not {@code null}. 143 * 144 * @return The authorisation. 145 * 146 * @throws GeneralException If the grant is invalid, or another 147 * exception was encountered. 148 */ 149 default SelfIssuedAssertionAuthorization processSelfIssuedGrant(final Assertion assertion, 150 final TokenRequestParameters tokenRequestParams, 151 final ClientID clientID, 152 final OIDCClientMetadata clientMetadata, 153 final InvocationContext invocationCtx) 154 throws GeneralException { 155 156 return processSelfIssuedGrant(assertion, tokenRequestParams.getScope(), clientID, clientMetadata); 157 } 158}