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

Interface ThirdPartySAML2GrantHandler

  • All Superinterfaces:
    GrantHandler, Lifecycle, SAML2GrantHandler
    @ThreadSafe
public interface ThirdPartySAML2GrantHandler
extends SAML2GrantHandler
    Service Provider Interface (SPI) for handling SAML 2.0 bearer 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 SAML 2.0 assertion is invalid.

    The passed SAML 2.0 assertion is signed or MAC protected, and must be validated by the handler.

    The handler should not specify access token lifetimes that exceed the validity period of the SAML 2.0 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.
    • Security Assertion Markup Language (SAML) 2.0 Profile for OAuth 2.0 Client Authentication and Authorization Grants (RFC 7522), sections 2.1, 3 and 3.1.

    • Method Detail

      • processThirdPartyGrant

        ThirdPartyAssertionAuthorization processThirdPartyGrant​(org.opensaml.saml.saml2.core.Assertion assertion,
                                                        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 SAML 2.0 assertion grant issued by a third-party security token service. The grant handler must validate the 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 SAML 2.0 assertion: 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 details of the SAML 2.0 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 SAML 2.0 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:
        assertion - The SAML 2.0 assertion, to be validated by the handler. 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.