001package com.nimbusds.openid.connect.provider.spi.grants; 002 003 004import com.nimbusds.oauth2.sdk.GeneralException; 005import com.nimbusds.oauth2.sdk.Scope; 006import com.nimbusds.oauth2.sdk.id.ClientID; 007import com.nimbusds.openid.connect.sdk.rp.OIDCClientMetadata; 008import org.opensaml.saml.saml2.core.Assertion; 009 010 011/** 012 * Service Provider Interface (SPI) for handling self-issued SAML 2.0 bearer 013 * assertion grants. Returns the matching 014 * {@link SelfIssuedAssertionAuthorization authorisation} on success. 015 * 016 * <p>The handler should not specify access token lifetimes that exceed the 017 * validity period of the SAML 2.0 assertion by a significant period. The issue 018 * of refresh tokens is not permitted. Clients can refresh an expired access 019 * token by requesting a new one using the same assertion, if it is still 020 * valid, or with a new assertion. 021 * 022 * <p>Implementations must be thread-safe. 023 * 024 * <p>Related specifications: 025 * 026 * <ul> 027 * <li>Assertion Framework for OAuth 2.0 Client Authentication and 028 * Authorization Grants (RFC 7521), section 4.1. 029 * <li>Security Assertion Markup Language (SAML) 2.0 Profile for OAuth 2.0 030 * Client Authentication and Authorization Grants (RFC 7522), sections 031 * 2.1, 3 and 3.1. 032 * </ul> 033 */ 034public interface SelfIssuedSAML2GrantHandler extends SAML2GrantHandler { 035 036 037 /** 038 * Handles a self-issued SAML 2.0 bearer assertion grant by a client 039 * registered with the Connect2id server. 040 * 041 * <p>This method is called for SAML 2.0 assertion grants which fulfil 042 * all of the following conditions: 043 * 044 * <ol> 045 * <li>Are issued by a client which is registered with the 046 * Connect2id server, i.e. the assertion issuer matches a 047 * registered client_id; 048 * <li>The client is registered for the 049 * {@code urn:ietf:params:oauth:grant-type:saml2-bearer} grant; 050 * <li>The client is successfully authenticated, by means of 051 * separate client authentication included in the token request 052 * (client_secret_basic, client_secret_post, client_secret_jwt 053 * or private_key_jwt), and / or with the SAML 2.0 assertion 054 * grant itself; 055 * <li>The SAML 2.0 assertion MAC or signature was successfully 056 * verified using with a registered {@code client_secret} or 057 * {@code jwks} / {@code jwks_uri}; 058 * <li>The assertion audience, expiration and not-before time are 059 * verify successfully. 060 * </ol> 061 * 062 * <p>If the requested scope is invalid, unknown, malformed, or exceeds 063 * the scope granted by the resource owner the handler must throw a 064 * {@link GeneralException} with an 065 * {@link com.nimbusds.oauth2.sdk.OAuth2Error#INVALID_SCOPE 066 * invalid_scope} error code. 067 * 068 * @param assertion The SAML 2.0 assertion. The audience, 069 * expiration, not-before time and XML signature 070 * are verified by the Connect2id server. 071 * The issuer will equal the client_id. Not 072 * {@code null}. 073 * @param scope The requested scope, {@code null} if not 074 * specified. 075 * @param clientID The identifier of the authenticated client. 076 * Not {@code null}. 077 * @param clientMetadata The OAuth 2.0 / OpenID Connect metadata for 078 * the client. Not {@code null}. 079 * 080 * @return The authorisation. 081 * 082 * @throws GeneralException If the grant is invalid, or another 083 * exception was encountered. 084 */ 085 SelfIssuedAssertionAuthorization processSelfIssuedGrant(final Assertion assertion, 086 final Scope scope, 087 final ClientID clientID, 088 final OIDCClientMetadata clientMetadata) 089 throws GeneralException; 090}