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

Interface ThirdPartyJWTGrantHandler

All Superinterfaces:

GrantHandler, JWTGrantHandler, Lifecycle

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

Methods

Modifier and Type	Method and Description
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) 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.GrantHandler

getGrantType

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

init, isEnabled, shutdown

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.