jakarta.security.auth.message.callback.CallerPrincipalCallback Maven / Gradle / Ivy

Go to download

Show more of this group Show more artifacts with this name
Show all versions of jakarta.authentication-api Show documentation

Jakarta Authentication defines a general low-level SPI for authentication mechanisms, which are controllers that interact with a caller and a container's environment to obtain the caller's credentials, validate these, and pass an authenticated identity (such as name and groups) to the container. Jakarta Authentication consists of several profiles, with each profile telling how a specific container (such as Jakarta Servlet) can integrate with- and adapt to this SPI.

There is a newer version: 3.1.0

Show newest version

/*
 * Copyright (c) 1997, 2020 Oracle and/or its affiliates and others.
 * All rights reserved.
 *
 * This program and the accompanying materials are made available under the
 * terms of the Eclipse Public License v. 2.0, which is available at
 * http://www.eclipse.org/legal/epl-2.0.
 *
 * This Source Code may also be made available under the following Secondary
 * Licenses when the conditions for such availability set forth in the
 * Eclipse Public License v. 2.0 are satisfied: GNU General Public License,
 * version 2 with the GNU Classpath Exception, which is available at
 * https://www.gnu.org/software/classpath/license.html.
 *
 * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
 */

package jakarta.security.auth.message.callback;

import java.security.Principal;
import javax.security.auth.Subject;
import javax.security.auth.callback.Callback;

/**
 * Callback for setting the container's caller (or remote user) principal.
 * 
 * 
 * This callback is intended to be called by a serverAuthModule during its validateRequest
 * processing.
 *
 */
public class CallerPrincipalCallback implements Callback {

    private Subject subject;
    private Principal principal;
    private String name;

    /**
     * Create a CallerPrincipalCallback to set the container's representation of the caller principal
     * 
     * 

     * The CallbackHandler must use the argument Principal to establish the caller principal associated with
     * the invocation being processed by the container. When the argument Principal is null, the handler must
     * establish the container's representation of the unauthenticated caller principal.
     * 
     * 

     * The handler may perform principal mapping of non-null argument Principal values, but it must be possible
     * to configure the handler such that it establishes the non-null argument Principal as the caller
     * principal.
     *
     * @param subject The Subject in which the container will distinguish the caller identity.
     *
     * @param principal The Principal that will be distinguished as the caller principal. This value may be null.
     */
    public CallerPrincipalCallback(Subject subject, Principal principal) {
        this.subject = subject;
        this.principal = principal;
    }

    /**
     * Create a CallerPrincipalCallback to set the container's representation of the caller principal.
     * 
     * 

     * The CallbackHandler must use the name argument to establish the caller principal associated with the
     * invocation being processed by the container. When the name argument is null, the handler must establish
     * the container's representation of the unauthenticated caller principal (which may or may not be equal to null,
     * depending on the requirements of the container type).
     * 
     * 

     * The handler may perform principal mapping of non-null values of name, but it must be possible to
     * configure the handler such that it establishes the non-null argument value as the value returned when
     * getName is called on the established principal.
     *
     * @param subject The Subject in which the container will distinguish the caller identity.
     *
     * @param name The String value that will be returned when getName() is called on the principal established
     * as the caller principal or null.
     */
    public CallerPrincipalCallback(Subject subject, String name) {
        this.subject = subject;
        this.name = name;
    }

    /**
     * Get the Subject in which the handler will distinguish the caller principal
     *
     * @return The subject.
     */
    public Subject getSubject() {
        return subject;
    }

    /**
     * Get the caller principal.
     * 
     * 

     * When the values returned by this method and the getName methods are null, the handler must establish the container's
     * representation of the unauthenticated caller principal within the Subject.
     *
     * @return The principal or null.
     */
    public Principal getPrincipal() {
        return principal;
    }

    /**
     * Get the caller principal name.
     * 
     * 
     * When the values returned by this method and the getPrincipal methods are null, the handler must establish the
     * container's representation of the unauthenticated caller principal within the Subject.
     *
     * @return The principal name or null.
     */
    public String getName() {
        return name;
    }
}