001package com.nimbusds.openid.connect.provider.spi.grants; 002 003 004import com.nimbusds.jose.JOSEObject; 005 006import com.nimbusds.oauth2.sdk.GeneralException; 007import com.nimbusds.oauth2.sdk.Scope; 008import com.nimbusds.oauth2.sdk.id.ClientID; 009import com.nimbusds.openid.connect.sdk.rp.OIDCClientMetadata; 010 011 012/** 013 * Service Provider Interface (SPI) for handling JSON Web Token (JWT) assertion 014 * grants issued by a third-party security token service. Returns the matching 015 * {@link ThirdPartyAssertionAuthorization authorisation} on success. Must 016 * throw a {@link GeneralException} with an 017 * {@link com.nimbusds.oauth2.sdk.OAuth2Error#INVALID_GRANT invalid_grant} 018 * error code if the JWT assertion is invalid. 019 * 020 * <p>The passed JWT assertion can be an instance of: 021 * 022 * <ul> 023 * <li>{@link com.nimbusds.jwt.SignedJWT} -- Signed or MAC protected with 024 * JWS; 025 * <li>{@link com.nimbusds.jwt.EncryptedJWT} -- Encrypted with JWE; 026 * <li>{@link com.nimbusds.jose.JWEObject} -- Signed or MAC protected with 027 * JWS, then encrypted with JWE. 028 * </ul> 029 * 030 * <p>The handler should not specify access token lifetimes that exceed the 031 * validity period of the JWT assertion by a significant period. The issue of 032 * refresh tokens is not permitted. Clients can refresh an expired access token 033 * by requesting a new one using the same assertion, if it is still valid, or 034 * with a new assertion. 035 * 036 * <p>Implementations must be thread-safe. 037 * 038 * <p>Related specifications: 039 * 040 * <ul> 041 * <li>Assertion Framework for OAuth 2.0 Client Authentication and 042 * Authorization Grants (RFC 7521), section 4.1. 043 * <li>JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and 044 * Authorization Grants (RFC 7523), sections 2.1, 3 and 3.1. 045 * </ul> 046 */ 047public interface ThirdPartyJWTGrantHandler extends JWTGrantHandler { 048 049 050 /** 051 * Handles a JWT bearer assertion grant issued by a third-party 052 * security token service (STS). The grant handler must verify the JWT 053 * assertion, using a previously agreed method to resolve the client's 054 * MAC or signature key. 055 * 056 * <p>The following client authentication / identification cases may be 057 * handled: 058 * 059 * <ol> 060 * <li><strong>Confidential client: </strong> 061 * If the client is confidential and has provided valid 062 * authentication (client_secret_basic, client_secret_post, 063 * client_secret_jwt or private_key_jwt) the 064 * {@code confidentialClient} flag will be {@code true}. The 065 * client_id and metadata arguments will be set. 066 * <li><strong>Public client: </strong> 067 * If the client is public and has a provided its registered 068 * {@code client_id} using the optional token request 069 * parameter, the {@code confidentialClient} flag will be 070 * {@code false} and the client metadata will be set. 071 * <li><strong>Handler must resolve client_id from JWT claims: </strong> 072 * If no client authentication or {@code client_id} is passed 073 * with the token request, the client information arguments 074 * will be {@code null} and the {@code confidentialClient} flag 075 * will be {@code false}. The grant handler must resolve the 076 * {@code client_id} for the authorisation result from claims 077 * of the JWT assertion. If such a use case is not supported or 078 * permitted the grant handler should throw a 079 * {@link GeneralException} with an 080 * {@link com.nimbusds.oauth2.sdk.OAuth2Error#INVALID_REQUEST 081 * invalid_request} error. 082 * </ol> 083 * 084 * <p>If the JWT assertion is invalid the handler must throw a 085 * {@link GeneralException} with an 086 * {@link com.nimbusds.oauth2.sdk.OAuth2Error#INVALID_GRANT 087 * invalid_grant} error code. 088 * 089 * <p>If the requested scope is invalid, unknown, malformed, or exceeds 090 * the scope granted by the resource owner the handler must throw a 091 * {@link GeneralException} with an 092 * {@link com.nimbusds.oauth2.sdk.OAuth2Error#INVALID_SCOPE 093 * invalid_scope} error code. 094 * 095 * @param jwtAssertion The JWT assertion, to be verified / 096 * decrypted by the handler. Can be a signed 097 * JWT, an encrypted JWT, or a signed and 098 * encrypted (nested) JWT. Not {@code null}. 099 * @param scope The requested scope, {@code null} if not 100 * specified. 101 * @param clientID The client identifier, {@code null} if not 102 * specified or if no client authentication 103 * was provided. 104 * @param confidentialClient {@code true} if the client is confidential 105 * and has been authenticated, else 106 * {@code false}. 107 * @param clientMetadata The OAuth 2.0 / OpenID Connect client 108 * metadata, {@code null} if no 109 * {@code client_id} or client authentication 110 * was provided. 111 * 112 * @return The authorisation. 113 * 114 * @throws GeneralException If the grant is invalid, or another 115 * exception was encountered. 116 */ 117 ThirdPartyAssertionAuthorization processThirdPartyGrant(final JOSEObject jwtAssertion, 118 final Scope scope, 119 final ClientID clientID, 120 final boolean confidentialClient, 121 final OIDCClientMetadata clientMetadata) 122 throws GeneralException; 123}