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.

  • Field Summary

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

    GRANT_TYPE

  • Method Summary

    Modifier and Type
    Method
    Description
    default ThirdPartyAssertionAuthorization
    processThirdPartyGrant(org.opensaml.saml.saml2.core.Assertion assertion, @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(org.opensaml.saml.saml2.core.Assertion assertion, 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 SAML 2.0 assertion grant issued by a third-party security token service.

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

    init, isEnabled, shutdown

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

    getGrantType

  • Method Details

    • processThirdPartyGrant

      @Deprecated default ThirdPartyAssertionAuthorization processThirdPartyGrant(org.opensaml.saml.saml2.core.Assertion assertion, @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 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.

    • processThirdPartyGrant

      default ThirdPartyAssertionAuthorization processThirdPartyGrant(org.opensaml.saml.saml2.core.Assertion assertion, 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 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.
      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.