javax.security.enterprise.identitystore.IdentityStore Maven / Gradle / Ivy
Show all versions of jakarta.security.enterprise-api Show documentation
/*
* Copyright (c) 2015, 2018 Oracle and/or its affiliates. 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 javax.security.enterprise.identitystore;
import static java.lang.invoke.MethodType.methodType;
import static java.util.Collections.emptySet;
import static javax.security.enterprise.identitystore.CredentialValidationResult.NOT_VALIDATED_RESULT;
import static javax.security.enterprise.identitystore.IdentityStore.ValidationType.PROVIDE_GROUPS;
import static javax.security.enterprise.identitystore.IdentityStore.ValidationType.VALIDATE;
import java.lang.invoke.MethodHandles;
import java.util.EnumSet;
import java.util.Set;
import javax.security.auth.message.module.ServerAuthModule;
import javax.security.enterprise.CallerPrincipal;
import javax.security.enterprise.authentication.mechanism.http.HttpAuthenticationMechanism;
import javax.security.enterprise.credential.Credential;
/**
* IdentityStore is a mechanism for validating a caller's credentials
* and accessing a caller's identity attributes. It can be used by an
* authentication mechanism, such as a Jakarta Security {@link HttpAuthenticationMechanism}
* or a Jakarta Authentication {@link ServerAuthModule}.
*
* Stores which do only validation or only group lookup are allowed.
*
* An IdentityStore obtains identity data from a persistent store,
* such as a database, LDAP server, or file.
*/
public interface IdentityStore {
/**
* Default set of validation types. Contains {@code VALIDATE} and {@code PROVIDE_GROUPS}.
*/
Set DEFAULT_VALIDATION_TYPES = EnumSet.of(VALIDATE, PROVIDE_GROUPS);
/**
* Validates the given credential.
*
* As a convenience, a default implementation is provided that looks up an overload of this method
* that has, as its one and only parameter, a subclass of {@link Credential}. Here is an example of what
* an implementation of this interface looks like with such an overloaded method:
*
{@code
public class ExampleIdentityStore implements IdentityStore {
public CredentialValidationResult validate(UsernamePasswordCredential usernamePasswordCredential) {
// Implementation ...
return INVALID_RESULT;
}
}
* }
*
* Note that the overloaded method is only called when the actual type passed into this method will exactly match
* the parameter type of the overloaded method. There's no attempt being done to find the most specific overloaded method
* such as specified in JLS 15.2.
*
* This method returns a {@link CredentialValidationResult} representing the result of the validation attempt:
* whether it succeeded or failed, and, for a successful validation, the {@link CallerPrincipal}, and possibly
* groups or other attributes, of the caller.
*
* @param credential The credential to validate.
* @return The validation result.
*/
default CredentialValidationResult validate(Credential credential) {
try {
return CredentialValidationResult.class.cast(
MethodHandles.lookup()
.bind(this, "validate", methodType(CredentialValidationResult.class, credential.getClass()))
.invoke(credential));
} catch (NoSuchMethodException e) {
return NOT_VALIDATED_RESULT;
} catch (Throwable e) {
throw new IllegalStateException(e);
}
}
/**
* Returns groups for the caller, who is identified by the {@link CallerPrincipal}
* (and potentially other values) found in the {@code validationResult} parameter.
*
* Callers (i.e., {@link IdentityStoreHandler}s) should have
* {@link IdentityStorePermission} permission to invoke this method.
* Implementations should check for this permission before doing any work:
*
{@code
SecurityManager security = System.getSecurityManager();
if (security != null) {
security.checkPermission(new IdentityStorePermission("getGroups");
}
* }
*
* @param validationResult The {@link CredentialValidationResult} returned
* by a previous call to {@link #validate(Credential)}.
* @return The {@link Set} of groups found for the caller, if any, or an empty {@link Set} otherwise.
* @throws SecurityException May be thrown if the calling code does not have {@link IdentityStorePermission}.
*/
default Set getCallerGroups(CredentialValidationResult validationResult) {
return emptySet();
}
/**
* Determines the order of invocation for multiple {@link IdentityStore}s.
* Stores with a lower priority value are consulted first.
*
* @return The priority value. Lower values indicate higher priorities.
*/
default int priority() {
return 100;
}
/**
* Determines the type of validation the {@link IdentityStore} should be used for.
* By default, its used for credential validation AND providing groups.
*
* Implementations of this API should not return a direct reference
* to a {@link Set} used internally to represent an {@link IdentityStore}'s validation types,
* unless it is an immutable {@link Set}. Callers of the API should be aware that
* the returned {@link Set} may be immutable, or a copy, and that, in any case,
* it should not be modified by the caller.
*
* @return {@link Set} containing the validation types enabled for the {@link IdentityStore}.
*/
default Set validationTypes() {
return DEFAULT_VALIDATION_TYPES;
}
/**
* Determines the type of validation (operations) that should be done by this store.
* NOTE: This does not set or determine what the {@link IdentityStore} is capable of,
* but only what the store is configured to be used for.
*/
enum ValidationType {
/**
* Only validation is performed, so no groups, are taken from this store.
**/
VALIDATE,
/**
* Only groups for a principal, possibly established by another IdentityStore, are taken from this store.
*/
PROVIDE_GROUPS
}
}