Package com.nimbusds.openid.connect.provider.spi.grants

Interface ThirdPartyJWTGrantHandler

  • All Superinterfaces:
    GrantHandler, JWTGrantHandler, Lifecycle
    @ThreadSafe
public interface ThirdPartyJWTGrantHandler
extends JWTGrantHandler
    Service Provider Interface (SPI) for handling JSON Web Token (JWT) assertion grants issued by a third-party security token service. Returns the matching authorisation on success. Must throw a GeneralException with an invalid_grant error code if the JWT assertion is invalid.

    The passed JWT assertion can be an instance of:

    • SignedJWT -- Signed or MAC protected with JWS;
    • EncryptedJWT -- Encrypted with JWE;
    • JWEObject -- Signed or MAC protected with JWS, then encrypted with JWE.

    The handler should not specify access token lifetimes that exceed the validity period of the JWT assertion by a significant period. The issue of refresh tokens is not permitted. Clients can refresh an expired access token by requesting a new one using the same assertion, if it is still valid, or with a new assertion.

    Implementations must be thread-safe.

    Related specifications:

    • Assertion Framework for OAuth 2.0 Client Authentication and Authorization Grants (RFC 7521), section 4.1.
    • JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants (RFC 7523), sections 2.1, 3 and 3.1.

    • Method Detail

      • processThirdPartyGrant

        ThirdPartyAssertionAuthorization processThirdPartyGrant​(com.nimbusds.jose.JOSEObject jwtAssertion,
                                                        com.nimbusds.oauth2.sdk.Scope scope,
                                                        com.nimbusds.oauth2.sdk.id.ClientID clientID,
                                                        boolean confidentialClient,
                                                        com.nimbusds.openid.connect.sdk.rp.OIDCClientMetadata clientMetadata)
                                                 throws com.nimbusds.oauth2.sdk.GeneralException
        Handles a JWT bearer assertion grant issued by a third-party security token service (STS). The grant handler must verify the JWT assertion, using a previously agreed method to resolve the client's MAC or signature key.

        The following client authentication / identification cases may be handled:

        1. Confidential client: If the client is confidential and has provided valid authentication (client_secret_basic, client_secret_post, client_secret_jwt or private_key_jwt) the confidentialClient flag will be true. The client_id and metadata arguments will be set.
        2. Public client: If the client is public and has a provided its registered client_id using the optional token request parameter, the confidentialClient flag will be false and the client metadata will be set.
        3. Handler must resolve client_id from JWT claims: If no client authentication or client_id is passed with the token request, the client information arguments will be null and the confidentialClient flag will be false. The grant handler must resolve the client_id for the authorisation result from claims of the JWT assertion. If such a use case is not supported or permitted the grant handler should throw a GeneralException with an invalid_request error.

        If the JWT assertion is invalid the handler must throw a GeneralException with an invalid_grant error code.

        If the requested scope is invalid, unknown, malformed, or exceeds the scope granted by the resource owner the handler must throw a GeneralException with an invalid_scope error code.

        Parameters:
        jwtAssertion - The JWT assertion, to be verified / decrypted by the handler. Can be a signed JWT, an encrypted JWT, or a signed and encrypted (nested) JWT. Not null.
        scope - The requested scope, null if not specified.
        clientID - The client identifier, null if not specified or if no client authentication was provided.
        confidentialClient - true if the client is confidential and has been authenticated, else false.
        clientMetadata - The OAuth 2.0 / OpenID Connect client metadata, null if no client_id or client authentication was provided.
        Returns:
        The authorisation.
        Throws:
        com.nimbusds.oauth2.sdk.GeneralException - If the grant is invalid, or another exception was encountered.