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.sdk.rp.OIDCClientMetadata; 009 010 011/** 012 * Service Provider Interface (SPI) for handling self-issued JSON Web Token 013 * (JWT) bearer assertion grants. Returns the matching 014 * {@link SelfIssuedAssertionAuthorization authorisation} on success. 015 * 016 * <p>The handler should not specify access token lifetimes that exceed the 017 * validity period of the JWT assertion by a significant period. The issue of 018 * refresh tokens is not permitted. Clients can refresh an expired access token 019 * by requesting a new one using the same assertion, if it is still valid, or 020 * with a new assertion. 021 * 022 * <p>Implementations must be thread-safe. 023 * 024 * <p>Related specifications: 025 * 026 * <ul> 027 * <li>Assertion Framework for OAuth 2.0 Client Authentication and 028 * Authorization Grants (RFC 7521), section 4.1. 029 * <li>JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and 030 * Authorization Grants (RFC 7523), sections 2.1, 3 and 3.1. 031 * </ul> 032 */ 033public interface SelfIssuedJWTGrantHandler extends JWTGrantHandler { 034 035 036 /** 037 * Handles a self-issued JWT bearer assertion grant by a client 038 * registered with the Connect2id server. 039 * 040 * <p>This method is called for JWT assertion grants which fulfil all 041 * of the following conditions: 042 * 043 * <ol> 044 * <li>Are issued by a client which is registered with the 045 * Connect2id server, i.e. the JWT issuer (iss) assertion 046 * matches a registered client_id; 047 * <li>The client is registered for the 048 * {@code urn:ietf:params:oauth:grant-type:jwt-bearer} grant; 049 * <li>The client is successfully authenticated, by means of 050 * separate client authentication included in the token request 051 * (client_secret_basic, client_secret_post, client_secret_jwt 052 * or private_key_jwt), and / or with the JWT assertion grant 053 * itself; 054 * <li>The JWT MAC or signature was successfully verified using 055 * with a registered {@code client_secret} or {@code jwks} / 056 * {@code jwks_uri}; 057 * <li>The JWT audience (aud), expiration (exp) and not-before 058 * time (nbf) claims verify successfully. 059 * </ol> 060 * 061 * <p>If the requested scope is invalid, unknown, malformed, or exceeds 062 * the scope granted by the resource owner the handler must throw a 063 * {@link GeneralException} with an 064 * {@link com.nimbusds.oauth2.sdk.OAuth2Error#INVALID_SCOPE 065 * invalid_scope} error code. 066 * 067 * @param jwtClaimsSet The claims set included in the verified JWT 068 * assertion grant. The audience (aud), 069 * expiration (exp) and not-before time (nbf) 070 * claims are verified by the Connect2id server. 071 * The issuer (iss) claims will equal the 072 * client_id. Not {@code null}. 073 * @param scope The requested scope, {@code null} if not 074 * specified. 075 * @param clientID The identifier of the authenticated client. 076 * Not {@code null}. 077 * @param clientMetadata The OAuth 2.0 / OpenID Connect metadata for 078 * the client. Not {@code null}. 079 * 080 * @return The authorisation. 081 * 082 * @throws GeneralException If the grant is invalid, or another 083 * exception was encountered. 084 */ 085 SelfIssuedAssertionAuthorization processSelfIssuedGrant(final JWTClaimsSet jwtClaimsSet, 086 final Scope scope, 087 final ClientID clientID, 088 final OIDCClientMetadata clientMetadata) 089 throws GeneralException; 090}