Interface SelfIssuedSAML2GrantHandler

  • All Superinterfaces:
    GrantHandler, Lifecycle, SAML2GrantHandler

    @ThreadSafe
    public interface SelfIssuedSAML2GrantHandler
    extends SAML2GrantHandler
    Service Provider Interface (SPI) for handling self-issued SAML 2.0 bearer assertion grants. Returns the matching authorisation on success.

    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

      • processSelfIssuedGrant

        @Deprecated
        default SelfIssuedAssertionAuthorization processSelfIssuedGrant​(org.opensaml.saml.saml2.core.Assertion assertion,
                                                                        com.nimbusds.oauth2.sdk.Scope scope,
                                                                        com.nimbusds.oauth2.sdk.id.ClientID clientID,
                                                                        com.nimbusds.openid.connect.sdk.rp.OIDCClientMetadata clientMetadata)
                                                                 throws com.nimbusds.oauth2.sdk.GeneralException
        Deprecated.
        Handles a self-issued SAML 2.0 bearer assertion grant by a client registered with the Connect2id server.

        This method is called for SAML 2.0 assertion grants which fulfil all the following conditions:

        1. Are issued by a client which is registered with the Connect2id server, i.e. the assertion issuer matches a registered client_id;
        2. The client is registered for the urn:ietf:params:oauth:grant-type:saml2-bearer grant;
        3. The client is successfully authenticated, by means of separate client authentication included in the token request (client_secret_basic, client_secret_post, client_secret_jwt or private_key_jwt), and / or with the SAML 2.0 assertion grant itself;
        4. The SAML 2.0 assertion MAC or signature was successfully verified using with a registered client_secret or jwks / jwks_uri;
        5. The assertion audience, expiration and not-before time are verify successfully.

        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. The audience, expiration, not-before time and XML signature are verified by the Connect2id server. The issuer will equal the client_id. Not null.
        scope - The requested scope, null if not specified.
        clientID - The identifier of the authenticated client. Not null.
        clientMetadata - The OAuth 2.0 / OpenID Connect metadata for the client. Not null.
        Returns:
        The authorisation.
        Throws:
        com.nimbusds.oauth2.sdk.GeneralException - If the grant is invalid, or another exception was encountered.
      • processSelfIssuedGrant

        default SelfIssuedAssertionAuthorization processSelfIssuedGrant​(org.opensaml.saml.saml2.core.Assertion assertion,
                                                                        TokenRequestParameters tokenRequestParams,
                                                                        com.nimbusds.oauth2.sdk.id.ClientID clientID,
                                                                        com.nimbusds.openid.connect.sdk.rp.OIDCClientMetadata clientMetadata,
                                                                        InvocationContext invocationCtx)
                                                                 throws com.nimbusds.oauth2.sdk.GeneralException
        Handles a self-issued SAML 2.0 bearer assertion grant by a client registered with the Connect2id server.

        This method is called for SAML 2.0 assertion grants which fulfil all the following conditions:

        1. Are issued by a client which is registered with the Connect2id server, i.e. the assertion issuer matches a registered client_id;
        2. The client is registered for the urn:ietf:params:oauth:grant-type:saml2-bearer grant;
        3. The client is successfully authenticated, by means of separate client authentication included in the token request (client_secret_basic, client_secret_post, client_secret_jwt or private_key_jwt), and / or with the SAML 2.0 assertion grant itself;
        4. The SAML 2.0 assertion MAC or signature was successfully verified using with a registered client_secret or jwks / jwks_uri;
        5. The assertion audience, expiration and not-before time are verify successfully.

        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. The audience, expiration, not-before time and XML signature are verified by the Connect2id server. The issuer will equal the client_id. Not null.
        tokenRequestParams - The token request parameters, such as the requested scope. Not null.
        clientID - The identifier of the authenticated client. Not null.
        clientMetadata - The OAuth 2.0 / OpenID Connect metadata for the client. Not null.
        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.