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.sdk.rp.OIDCClientMetadata; 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 * of 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 / OpenID Connect metadata for 081 * the client. 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 SelfIssuedAssertionAuthorization processSelfIssuedGrant(final JWTClaimsSet jwtClaimsSet, 089 final Scope scope, 090 final ClientID clientID, 091 final OIDCClientMetadata clientMetadata) 092 throws GeneralException; 093}