001package com.nimbusds.openid.connect.provider.spi.grants; 002 003 004import com.nimbusds.jwt.JWTClaimsSet; 005import com.nimbusds.oauth2.sdk.GeneralException; 006import com.nimbusds.oauth2.sdk.Scope; 007import com.nimbusds.oauth2.sdk.id.ClientID; 008import com.nimbusds.openid.connect.provider.spi.InvocationContext; 009import com.nimbusds.openid.connect.sdk.rp.OIDCClientMetadata; 010import net.jcip.annotations.ThreadSafe; 011 012 013/** 014 * Service Provider Interface (SPI) for handling self-issued JSON Web Token 015 * (JWT) bearer assertion grants. Returns the matching 016 * {@link SelfIssuedAssertionAuthorization authorisation} on success. 017 * 018 * <p>The handler should not specify access token lifetimes that exceed the 019 * validity period of the JWT assertion by a significant period. The issue of 020 * refresh tokens is not permitted. Clients can refresh an expired access token 021 * by requesting a new one using the same assertion, if it is still valid, or 022 * with a new assertion. 023 * 024 * <p>Implementations must be thread-safe. 025 * 026 * <p>Related specifications: 027 * 028 * <ul> 029 * <li>Assertion Framework for OAuth 2.0 Client Authentication and 030 * Authorization Grants (RFC 7521), section 4.1. 031 * <li>JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and 032 * Authorization Grants (RFC 7523), sections 2.1, 3 and 3.1. 033 * </ul> 034 */ 035@ThreadSafe 036public interface SelfIssuedJWTGrantHandler extends JWTGrantHandler { 037 038 039 /** 040 * Handles a self-issued JWT bearer assertion grant by a client 041 * registered with the Connect2id server. 042 * 043 * <p>This method is called for JWT assertion grants which fulfil all 044 * the following conditions: 045 * 046 * <ol> 047 * <li>Are issued by a client which is registered with the 048 * Connect2id server, i.e. the JWT issuer (iss) assertion 049 * matches a registered client_id; 050 * <li>The client is registered for the 051 * {@code urn:ietf:params:oauth:grant-type:jwt-bearer} grant; 052 * <li>The client is successfully authenticated, by means of 053 * separate client authentication included in the token request 054 * (client_secret_basic, client_secret_post, client_secret_jwt 055 * or private_key_jwt), and / or with the JWT assertion grant 056 * itself; 057 * <li>The JWT MAC or signature was successfully verified using 058 * with a registered {@code client_secret} or {@code jwks} / 059 * {@code jwks_uri}; 060 * <li>The JWT audience (aud), expiration (exp) and not-before 061 * time (nbf) claims verify successfully. 062 * </ol> 063 * 064 * <p>If the requested scope is invalid, unknown, malformed, or exceeds 065 * the scope granted by the resource owner the handler must throw a 066 * {@link GeneralException} with an 067 * {@link com.nimbusds.oauth2.sdk.OAuth2Error#INVALID_SCOPE 068 * invalid_scope} error code. 069 * 070 * @param jwtClaimsSet The claims set included in the verified JWT 071 * assertion grant. The audience (aud), 072 * expiration (exp) and not-before time (nbf) 073 * claims are verified by the Connect2id server. 074 * The issuer (iss) claims will equal the 075 * client_id. Not {@code null}. 076 * @param scope The requested scope, {@code null} if not 077 * specified. 078 * @param clientID The identifier of the authenticated client. 079 * Not {@code null}. 080 * @param clientMetadata The OAuth 2.0 client / OpenID relying party 081 * metadata. Not {@code null}. 082 * 083 * @return The authorisation. 084 * 085 * @throws GeneralException If the grant is invalid, or another 086 * exception was encountered. 087 */ 088 @Deprecated 089 default SelfIssuedAssertionAuthorization processSelfIssuedGrant(final JWTClaimsSet jwtClaimsSet, 090 final Scope scope, 091 final ClientID clientID, 092 final OIDCClientMetadata clientMetadata) 093 throws GeneralException { 094 095 return null; 096 } 097 098 099 /** 100 * Handles a self-issued JWT bearer assertion grant by a client 101 * registered with the Connect2id server. 102 * 103 * <p>This method is called for JWT assertion grants which fulfil all 104 * the following conditions: 105 * 106 * <ol> 107 * <li>Are issued by a client which is registered with the 108 * Connect2id server, i.e. the JWT issuer (iss) assertion 109 * matches a registered client_id; 110 * <li>The client is registered for the 111 * {@code urn:ietf:params:oauth:grant-type:jwt-bearer} grant; 112 * <li>The client is successfully authenticated, by means of 113 * separate client authentication included in the token request 114 * (client_secret_basic, client_secret_post, client_secret_jwt 115 * or private_key_jwt), and / or with the JWT assertion grant 116 * itself; 117 * <li>The JWT MAC or signature was successfully verified using 118 * with a registered {@code client_secret} or {@code jwks} / 119 * {@code jwks_uri}; 120 * <li>The JWT audience (aud), expiration (exp) and not-before 121 * time (nbf) claims verify successfully. 122 * </ol> 123 * 124 * <p>If the requested scope is invalid, unknown, malformed, or exceeds 125 * the scope granted by the resource owner the handler must throw a 126 * {@link GeneralException} with an 127 * {@link com.nimbusds.oauth2.sdk.OAuth2Error#INVALID_SCOPE 128 * invalid_scope} error code. 129 * 130 * @param jwtClaimsSet The claims set included in the verified 131 * JWT assertion grant. The audience (aud), 132 * expiration (exp) and not-before time (nbf) 133 * claims are verified by the Connect2id 134 * server. The issuer (iss) claims will equal 135 * the 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 client / OpenID relying party 141 * metadata. 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 @Deprecated 150 default SelfIssuedAssertionAuthorization processSelfIssuedGrant(final JWTClaimsSet jwtClaimsSet, 151 final TokenRequestParameters tokenRequestParams, 152 final ClientID clientID, 153 final OIDCClientMetadata clientMetadata, 154 final InvocationContext invocationCtx) 155 throws GeneralException { 156 157 return processSelfIssuedGrant(jwtClaimsSet, tokenRequestParams.getScope(), clientID, clientMetadata); 158 } 159 160 161 /** 162 * Handles a self-issued JWT bearer assertion grant by a client 163 * registered with the Connect2id server. 164 * 165 * <p>This method is called for JWT assertion grants which fulfil all 166 * the following conditions: 167 * 168 * <ol> 169 * <li>Are issued by a client which is registered with the 170 * Connect2id server, i.e. the JWT issuer (iss) assertion 171 * matches a registered client_id; 172 * <li>The client is registered for the 173 * {@code urn:ietf:params:oauth:grant-type:jwt-bearer} grant; 174 * <li>The client is successfully authenticated, by means of 175 * separate client authentication included in the token request 176 * (client_secret_basic, client_secret_post, client_secret_jwt 177 * or private_key_jwt), and / or with the JWT assertion grant 178 * itself; 179 * <li>The JWT MAC or signature was successfully verified using 180 * with a registered {@code client_secret} or {@code jwks} / 181 * {@code jwks_uri}; 182 * <li>The JWT audience (aud), expiration (exp) and not-before 183 * time (nbf) claims verify successfully. 184 * </ol> 185 * 186 * <p>If the requested scope is invalid, unknown, malformed, or exceeds 187 * the scope granted by the resource owner the handler must throw a 188 * {@link GeneralException} with an 189 * {@link com.nimbusds.oauth2.sdk.OAuth2Error#INVALID_SCOPE 190 * invalid_scope} error code. 191 * 192 * @param jwtClaimsSet The claims set included in the verified 193 * JWT assertion grant. The audience (aud), 194 * expiration (exp) and not-before time (nbf) 195 * claims are verified by the Connect2id 196 * server. The issuer (iss) claims will equal 197 * the client_id. Not {@code null}. 198 * @param tokenRequestParams The token request parameters, such as the 199 * requested scope. Not {@code null}. 200 * @param clientID The identifier of the authenticated client. 201 * Not {@code null}. 202 * @param clientMetadata The OAuth 2.0 client / OpenID relying party 203 * metadata. Not {@code null}. 204 * @param handlerCtx The handler context. Not {@code null}. 205 * 206 * @return The authorisation. 207 * 208 * @throws GeneralException If the grant is invalid, or another 209 * exception was encountered. 210 */ 211 default SelfIssuedAssertionAuthorization processSelfIssuedGrant(final JWTClaimsSet jwtClaimsSet, 212 final TokenRequestParameters tokenRequestParams, 213 final ClientID clientID, 214 final OIDCClientMetadata clientMetadata, 215 final GrantHandlerContext handlerCtx) 216 throws GeneralException { 217 218 return processSelfIssuedGrant(jwtClaimsSet, tokenRequestParams, clientID, clientMetadata, (InvocationContext) handlerCtx); 219 } 220}