001package com.nimbusds.openid.connect.provider.spi.grants; 002 003 004import net.jcip.annotations.ThreadSafe; 005 006import com.nimbusds.jwt.JWTClaimsSet; 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 JSON Web Token 016 * (JWT) bearer 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 JWT assertion by a significant period. The issue of 021 * refresh tokens is not permitted. Clients can refresh an expired access token 022 * by requesting a new one using the same assertion, if it is still valid, or 023 * 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>JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and 033 * Authorization Grants (RFC 7523), sections 2.1, 3 and 3.1. 034 * </ul> 035 */ 036@ThreadSafe 037public interface SelfIssuedJWTGrantHandler extends JWTGrantHandler { 038 039 040 /** 041 * Handles a self-issued JWT bearer assertion grant by a client 042 * registered with the Connect2id server. 043 * 044 * <p>This method is called for JWT assertion grants which fulfil all 045 * the following conditions: 046 * 047 * <ol> 048 * <li>Are issued by a client which is registered with the 049 * Connect2id server, i.e. the JWT issuer (iss) assertion 050 * matches a registered client_id; 051 * <li>The client is registered for the 052 * {@code urn:ietf:params:oauth:grant-type:jwt-bearer} grant; 053 * <li>The client is successfully authenticated, by means of 054 * separate client authentication included in the token request 055 * (client_secret_basic, client_secret_post, client_secret_jwt 056 * or private_key_jwt), and / or with the JWT assertion grant 057 * itself; 058 * <li>The JWT MAC or signature was successfully verified using 059 * with a registered {@code client_secret} or {@code jwks} / 060 * {@code jwks_uri}; 061 * <li>The JWT audience (aud), expiration (exp) and not-before 062 * time (nbf) claims verify successfully. 063 * </ol> 064 * 065 * <p>If the requested scope is invalid, unknown, malformed, or exceeds 066 * the scope granted by the resource owner the handler must throw a 067 * {@link GeneralException} with an 068 * {@link com.nimbusds.oauth2.sdk.OAuth2Error#INVALID_SCOPE 069 * invalid_scope} error code. 070 * 071 * @param jwtClaimsSet The claims set included in the verified JWT 072 * assertion grant. The audience (aud), 073 * expiration (exp) and not-before time (nbf) 074 * claims are verified by the Connect2id server. 075 * The issuer (iss) claims will equal the 076 * client_id. Not {@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 JWTClaimsSet jwtClaimsSet, 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 JWT bearer assertion grant by a client 102 * registered with the Connect2id server. 103 * 104 * <p>This method is called for JWT assertion grants which fulfil all 105 * the following conditions: 106 * 107 * <ol> 108 * <li>Are issued by a client which is registered with the 109 * Connect2id server, i.e. the JWT issuer (iss) assertion 110 * matches a registered client_id; 111 * <li>The client is registered for the 112 * {@code urn:ietf:params:oauth:grant-type:jwt-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 JWT assertion grant 117 * itself; 118 * <li>The JWT MAC or signature was successfully verified using 119 * with a registered {@code client_secret} or {@code jwks} / 120 * {@code jwks_uri}; 121 * <li>The JWT audience (aud), expiration (exp) and not-before 122 * time (nbf) claims 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 jwtClaimsSet The claims set included in the verified 132 * JWT assertion grant. The audience (aud), 133 * expiration (exp) and not-before time (nbf) 134 * claims are verified by the Connect2id 135 * server. The issuer (iss) claims will equal 136 * the client_id. Not {@code null}. 137 * @param tokenRequestParams The token request parameters, such as the 138 * requested scope. Not {@code null}. 139 * @param clientID The identifier of the authenticated client. 140 * Not {@code null}. 141 * @param clientMetadata The OAuth 2.0 / OpenID Connect metadata 142 * for the client. Not {@code null}. 143 * @param invocationCtx The invocation context. Not {@code null}. 144 * 145 * @return The authorisation. 146 * 147 * @throws GeneralException If the grant is invalid, or another 148 * exception was encountered. 149 */ 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}