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