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