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.

  • Field Summary

    Fields inherited from interface com.nimbusds.openid.connect.provider.spi.grants.JWTGrantHandler

    GRANT_TYPE

  • Method Summary

    Modifier and Type
    Method
    Description
    default ThirdPartyAssertionAuthorization
    processThirdPartyGrant(com.nimbusds.jose.JOSEObject jwtAssertion, @Nullable com.nimbusds.oauth2.sdk.Scope scope, @Nullable com.nimbusds.oauth2.sdk.id.ClientID clientID, boolean confidentialClient, @Nullable com.nimbusds.openid.connect.sdk.rp.OIDCClientMetadata clientMetadata)
    Deprecated.
    default ThirdPartyAssertionAuthorization
    processThirdPartyGrant(com.nimbusds.jose.JOSEObject jwtAssertion, TokenRequestParameters tokenRequestParams, @Nullable com.nimbusds.oauth2.sdk.id.ClientID clientID, boolean confidentialClient, @Nullable com.nimbusds.openid.connect.sdk.rp.OIDCClientMetadata clientMetadata, InvocationContext invocationCtx)
    Handles a JWT bearer assertion grant issued by a third-party security token service (STS).

    Methods inherited from interface com.nimbusds.openid.connect.provider.spi.grants.JWTGrantHandler

    getGrantType

    Methods inherited from interface com.nimbusds.openid.connect.provider.spi.Lifecycle

    init, isEnabled, shutdown

  • Method Details

    • processThirdPartyGrant

      @Deprecated default ThirdPartyAssertionAuthorization processThirdPartyGrant(com.nimbusds.jose.JOSEObject jwtAssertion, @Nullable com.nimbusds.oauth2.sdk.Scope scope, @Nullable com.nimbusds.oauth2.sdk.id.ClientID clientID, boolean confidentialClient, @Nullable com.nimbusds.openid.connect.sdk.rp.OIDCClientMetadata clientMetadata) throws com.nimbusds.oauth2.sdk.GeneralException
      Deprecated.
      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.

    • processThirdPartyGrant

      default ThirdPartyAssertionAuthorization processThirdPartyGrant(com.nimbusds.jose.JOSEObject jwtAssertion, TokenRequestParameters tokenRequestParams, @Nullable com.nimbusds.oauth2.sdk.id.ClientID clientID, boolean confidentialClient, @Nullable com.nimbusds.openid.connect.sdk.rp.OIDCClientMetadata clientMetadata, InvocationContext invocationCtx) 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.
      tokenRequestParams - The token request parameters, such as the requested scope. Not null.
      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.
      invocationCtx - The invocation context. Not null.
      Returns:
      The authorisation.
      Throws:
      com.nimbusds.oauth2.sdk.GeneralException - If the grant is invalid, or another exception was encountered.