com.authlete.jakarta.spi.BackchannelAuthenticationCompleteRequestHandlerSpi Maven / Gradle / Ivy
/*
* Copyright (C) 2019 Authlete, Inc.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
* either express or implied. See the License for the specific
* language governing permissions and limitations under the
* License.
*/
package com.authlete.jakarta.spi;
import java.net.URI;
import com.authlete.common.dto.BackchannelAuthenticationCompleteResponse;
import com.authlete.common.dto.Property;
import com.authlete.common.dto.BackchannelAuthenticationCompleteRequest.Result;
/**
* Service Provider Interface to work with {@link
* com.authlete.jakarta.BackchannelAuthenticationCompleteRequestHandler
* BackchannelAuthenticationCompleteRequestHandler}.
*
*
* An implementation of this interface must be given to the constructor
* of {@link com.authlete.jakarta.BackchannelAuthenticationCompleteRequestHandler
* BackchannelAuthenticationCompleteRequestHandler} class.
*
*
* @since 2.13
*
* @author Hideki Ikeda
*/
public interface BackchannelAuthenticationCompleteRequestHandlerSpi
{
/**
* Get the result of end-user authentication and authorization.
*
* @return
* The result of end-user authentication and authorization.
*/
Result getResult();
/**
* Get the subject (= unique identifier) of the end-user.
* It must consist of only ASCII letters and its length
* must not exceed 100.
*
*
* In a typical case, the subject is a primary key or another
* unique ID of the record that represents the end-user in
* your user database.
*
*
* @return
* The subject (= unique identifier) of the end-user.
*/
String getUserSubject();
/**
* Get the time when the end-user was authenticated.
*
*
* This method is called only when {@link #getResult()}
* has returned {@link com.authlete.common.dto.BackchannelAuthenticationCompleteRequest.Result#AUTHORIZED
* AUTHORIZED}.
*
*
* @return
* The time when the end-user authentication occurred.
* The number of seconds since Unix epoch (1970-01-01).
* Return 0 if the time is unknown.
*/
long getUserAuthenticatedAt();
/**
* Get the authentication context class reference (ACR) that was
* satisfied when the end-user was authenticated.
*
*
* If you don't know what ACR is, return {@code null}.
*
*
*
* This method is called only when {@link #getResult()}
* has returned {@link com.authlete.common.dto.BackchannelAuthenticationCompleteRequest.Result#AUTHORIZED
* AUTHORIZED}.
*
*
* @return
* The authentication context class reference (ACR) that
* was satisfied when the end-user was authenticated.
*/
String getAcr();
/**
* Get the value of a claim of the user.
*
*
* This method may be called multiple times. Note that
* this method is called only when {@link #getResult()}
* has returned {@link com.authlete.common.dto.BackchannelAuthenticationCompleteRequest.Result#AUTHORIZED
* AUTHORIZED}.
*
*
*
* @param claimName
* A claim name such as {@code name} and {@code family_name}.
* Standard claim names are listed in "5.1. Standard Claims" of OpenID
* Connect Core 1.0. Java constant values that represent the
* standard claims are listed in {@link com.authlete.common.types.StandardClaims
* StandardClaims} class. The value of {@code claimName} does NOT
* contain a language tag.
*
* @return
* The claim value. {@code null} if the claim value of the claim
* is not available.
*/
Object getUserClaim(String claimName);
/**
* Get extra properties to associate with an access token.
*
*
* This method is expected to return an array of extra properties.
* The following is an example that returns an array containing one
* extra property.
*
*
*
* @Override
* public {@link Property}[] getProperties()
* {
* return new {@link Property}[] {
* new {@link Property#Property(String, String)
* Property}("example_parameter", "example_value")
* };
* }
*
*
*
* Extra properties returned from this method will appear as top-level entries
* in a JSON response from an authorization server as shown in 5.1. Successful Response
* in RFC 6749.
*
*
*
* Note that there is an upper limit on the total size of extra properties.
* On the server side, the properties will be (1) converted to a multidimensional
* string array, (2) converted to JSON, (3) encrypted by AES/CBC/PKCS5Padding, (4)
* encoded by base64url, and then stored into the database. The length of the
* resultant string must not exceed 65,535 in bytes. This is the upper limit, but
* we think it is big enough.
*
*
* @return
* Extra properties. If {@code null} is returned, any extra property will
* not be associated.
*/
Property[] getProperties();
/**
* Get scopes to be associated with the access token. If this method returns
* a non-null value, the set of scopes will be used instead of the scopes
* specified in the original backchannel authentication request.
*
* @return
* Scopes to replace the scopes specified in the original
* backchannel authentication request with. When {@code null} is
* returned from this method, replacement is not performed.
*/
String[] getScopes();
/**
* Send a notification to the client notification endpoint as described in
* CIBA Core specification.
*
*
* Note that the specification defines how the Open ID provider deals with
* responses from the client notification endpoint. The following is an excerpt
* from "10.2. Ping Callback" and "10.3.1. Successful Token Delivery" of the specification.
*
*
* For valid requests, the Client Notification Endpoint SHOULD respond with
* an HTTP 204 No Content. The OP SHOULD also accept responses with HTTP 200
* OK and any body in the response SHOULD be ignored.
* The Client MUST NOT return an HTTP 3xx code. The OP MUST NOT follow redirects.
*
* How the OP handles HTTP error codes in the ranges of 4xx and 5xx is out-of-scope
* of this specification. Administrative action is likely to be needed in
* these cases.
*
*
*
* @param info
* An object having information required to send a notification to
* the client notification endpoint.
*/
void sendNotification(BackchannelAuthenticationCompleteResponse info);
/**
* Get the description of the error. This corresponds to the
* {@code error_description} property in the response to the client.
*
* @return
* The description of the error.
*
* @since 2.15
*/
String getErrorDescription();
/**
* Get the URI of a document which describes the error in detail. This
* corresponds to the {@code error_uri} property in the response to the
* client.
*
* @return
* The URI of a document which describes the error in detail.
*
* @since 2.15
*/
URI getErrorUri();
}