- java.lang.Object
-
- javax.security.auth.Subject
-
- All Implemented Interfaces:
- Serializable
public final class Subject extends Object implements Serializable
A
Subject
represents a grouping of related information for a single entity, such as a person. Such information includes the Subject's identities as well as its security-related attributes (passwords and cryptographic keys, for example).Subjects may potentially have multiple identities. Each identity is represented as a
Principal
within theSubject
. Principals simply bind names to aSubject
. For example, aSubject
that happens to be a person, Alice, might have two Principals: one which binds "Alice Bar", the name on her driver license, to theSubject
, and another which binds, "999-99-9999", the number on her student identification card, to theSubject
. Both Principals refer to the sameSubject
even though each has a different name.A
Subject
may also own security-related attributes, which are referred to as credentials. Sensitive credentials that require special protection, such as private cryptographic keys, are stored within a private credentialSet
. Credentials intended to be shared, such as public key certificates or Kerberos server tickets are stored within a public credentialSet
. Different permissions are required to access and modify the different credential Sets.To retrieve all the Principals associated with a
Subject
, invoke thegetPrincipals
method. To retrieve all the public or private credentials belonging to aSubject
, invoke thegetPublicCredentials
method orgetPrivateCredentials
method, respectively. To modify the returnedSet
of Principals and credentials, use the methods defined in theSet
class. For example:Subject subject; Principal principal; Object credential; // add a Principal and credential to the Subject subject.getPrincipals().add(principal); subject.getPublicCredentials().add(credential);
This
Subject
class implementsSerializable
. While the Principals associated with theSubject
are serialized, the credentials associated with theSubject
are not. Note that thejava.security.Principal
class does not implementSerializable
. Therefore all concretePrincipal
implementations associated with Subjects must implementSerializable
.- See Also:
Principal
,DomainCombiner
, Serialized Form
-
-
Constructor Summary
Constructors Constructor and Description Subject()
Create an instance of aSubject
with an emptySet
of Principals and empty Sets of public and private credentials.Subject(boolean readOnly, Set<? extends Principal> principals, Set<?> pubCredentials, Set<?> privCredentials)
Create an instance of aSubject
with Principals and credentials.
-
Method Summary
Methods Modifier and Type Method and Description static <T> T
doAs(Subject subject, PrivilegedAction<T> action)
Perform work as a particularSubject
.static <T> T
doAs(Subject subject, PrivilegedExceptionAction<T> action)
Perform work as a particularSubject
.static <T> T
doAsPrivileged(Subject subject, PrivilegedAction<T> action, AccessControlContext acc)
Perform privileged work as a particularSubject
.static <T> T
doAsPrivileged(Subject subject, PrivilegedExceptionAction<T> action, AccessControlContext acc)
Perform privileged work as a particularSubject
.boolean
equals(Object o)
Compares the specified Object with thisSubject
for equality.Set<Principal>
getPrincipals()
Return theSet
of Principals associated with thisSubject
.<T extends Principal>
Set<T>getPrincipals(Class<T> c)
Return aSet
of Principals associated with thisSubject
that are instances or subclasses of the specifiedClass
.Set<Object>
getPrivateCredentials()
Return theSet
of private credentials held by thisSubject
.<T> Set<T>
getPrivateCredentials(Class<T> c)
Return aSet
of private credentials associated with thisSubject
that are instances or subclasses of the specifiedClass
.Set<Object>
getPublicCredentials()
Return theSet
of public credentials held by thisSubject
.<T> Set<T>
getPublicCredentials(Class<T> c)
Return aSet
of public credentials associated with thisSubject
that are instances or subclasses of the specifiedClass
.static Subject
getSubject(AccessControlContext acc)
Get theSubject
associated with the providedAccessControlContext
.int
hashCode()
Returns a hashcode for thisSubject
.boolean
isReadOnly()
Query whether thisSubject
is read-only.void
setReadOnly()
Set thisSubject
to be read-only.String
toString()
Return the String representation of thisSubject
.
-
-
-
Constructor Detail
-
Subject
public Subject()
Create an instance of aSubject
with an emptySet
of Principals and empty Sets of public and private credentials.The newly constructed Sets check whether this
Subject
has been set read-only before permitting subsequent modifications. The newly created Sets also prevent illegal modifications by ensuring that callers have sufficient permissions.To modify the Principals Set, the caller must have
AuthPermission("modifyPrincipals")
. To modify the public credential Set, the caller must haveAuthPermission("modifyPublicCredentials")
. To modify the private credential Set, the caller must haveAuthPermission("modifyPrivateCredentials")
.
-
Subject
public Subject(boolean readOnly, Set<? extends Principal> principals, Set<?> pubCredentials, Set<?> privCredentials)
Create an instance of aSubject
with Principals and credentials.The Principals and credentials from the specified Sets are copied into newly constructed Sets. These newly created Sets check whether this
Subject
has been set read-only before permitting subsequent modifications. The newly created Sets also prevent illegal modifications by ensuring that callers have sufficient permissions.To modify the Principals Set, the caller must have
AuthPermission("modifyPrincipals")
. To modify the public credential Set, the caller must haveAuthPermission("modifyPublicCredentials")
. To modify the private credential Set, the caller must haveAuthPermission("modifyPrivateCredentials")
.- Parameters:
readOnly
- true if theSubject
is to be read-only, and false otherwise.principals
- theSet
of Principals to be associated with thisSubject
.pubCredentials
- theSet
of public credentials to be associated with thisSubject
.privCredentials
- theSet
of private credentials to be associated with thisSubject
.- Throws:
NullPointerException
- if the specifiedprincipals
,pubCredentials
, orprivCredentials
arenull
.
-
-
Method Detail
-
setReadOnly
public void setReadOnly()
Set thisSubject
to be read-only.Modifications (additions and removals) to this Subject's
Principal
Set
and credential Sets will be disallowed. Thedestroy
operation on this Subject's credentials will still be permitted.Subsequent attempts to modify the Subject's
Principal
and credential Sets will result in anIllegalStateException
being thrown. Also, once aSubject
is read-only, it can not be reset to being writable again.- Throws:
SecurityException
- if the caller does not have permission to set thisSubject
to be read-only.
-
isReadOnly
public boolean isReadOnly()
Query whether thisSubject
is read-only.- Returns:
- true if this
Subject
is read-only, false otherwise.
-
getSubject
public static Subject getSubject(AccessControlContext acc)
Get theSubject
associated with the providedAccessControlContext
.The
AccessControlContext
may contain many Subjects (from nesteddoAs
calls). In this situation, the most recentSubject
associated with theAccessControlContext
is returned.- Parameters:
acc
- theAccessControlContext
from which to retrieve theSubject
.- Returns:
- the
Subject
associated with the providedAccessControlContext
, ornull
if noSubject
is associated with the providedAccessControlContext
. - Throws:
SecurityException
- if the caller does not have permission to get theSubject
.NullPointerException
- if the providedAccessControlContext
isnull
.
-
doAs
public static <T> T doAs(Subject subject, PrivilegedAction<T> action)
Perform work as a particularSubject
.This method first retrieves the current Thread's
AccessControlContext
viaAccessController.getContext
, and then instantiates a newAccessControlContext
using the retrieved context along with a newSubjectDomainCombiner
(constructed using the providedSubject
). Finally, this method invokesAccessController.doPrivileged
, passing it the providedPrivilegedAction
, as well as the newly constructedAccessControlContext
.- Parameters:
subject
- theSubject
that the specifiedaction
will run as. This parameter may benull
.action
- the code to be run as the specifiedSubject
.- Returns:
- the value returned by the PrivilegedAction's
run
method. - Throws:
NullPointerException
- if thePrivilegedAction
isnull
.SecurityException
- if the caller does not have permission to invoke this method.
-
doAs
public static <T> T doAs(Subject subject, PrivilegedExceptionAction<T> action) throws PrivilegedActionException
Perform work as a particularSubject
.This method first retrieves the current Thread's
AccessControlContext
viaAccessController.getContext
, and then instantiates a newAccessControlContext
using the retrieved context along with a newSubjectDomainCombiner
(constructed using the providedSubject
). Finally, this method invokesAccessController.doPrivileged
, passing it the providedPrivilegedExceptionAction
, as well as the newly constructedAccessControlContext
.- Parameters:
subject
- theSubject
that the specifiedaction
will run as. This parameter may benull
.action
- the code to be run as the specifiedSubject
.- Returns:
- the value returned by the
PrivilegedExceptionAction's
run
method. - Throws:
PrivilegedActionException
- if thePrivilegedExceptionAction.run
method throws a checked exception.NullPointerException
- if the specifiedPrivilegedExceptionAction
isnull
.SecurityException
- if the caller does not have permission to invoke this method.
-
doAsPrivileged
public static <T> T doAsPrivileged(Subject subject, PrivilegedAction<T> action, AccessControlContext acc)
Perform privileged work as a particularSubject
.This method behaves exactly as
Subject.doAs
, except that instead of retrieving the current Thread'sAccessControlContext
, it uses the providedAccessControlContext
. If the providedAccessControlContext
isnull
, this method instantiates a newAccessControlContext
with an empty collection of ProtectionDomains.- Parameters:
subject
- theSubject
that the specifiedaction
will run as. This parameter may benull
.action
- the code to be run as the specifiedSubject
.acc
- theAccessControlContext
to be tied to the specified subject and action.- Returns:
- the value returned by the PrivilegedAction's
run
method. - Throws:
NullPointerException
- if thePrivilegedAction
isnull
.SecurityException
- if the caller does not have permission to invoke this method.
-
doAsPrivileged
public static <T> T doAsPrivileged(Subject subject, PrivilegedExceptionAction<T> action, AccessControlContext acc) throws PrivilegedActionException
Perform privileged work as a particularSubject
.This method behaves exactly as
Subject.doAs
, except that instead of retrieving the current Thread'sAccessControlContext
, it uses the providedAccessControlContext
. If the providedAccessControlContext
isnull
, this method instantiates a newAccessControlContext
with an empty collection of ProtectionDomains.- Parameters:
subject
- theSubject
that the specifiedaction
will run as. This parameter may benull
.action
- the code to be run as the specifiedSubject
.acc
- theAccessControlContext
to be tied to the specified subject and action.- Returns:
- the value returned by the
PrivilegedExceptionAction's
run
method. - Throws:
PrivilegedActionException
- if thePrivilegedExceptionAction.run
method throws a checked exception.NullPointerException
- if the specifiedPrivilegedExceptionAction
isnull
.SecurityException
- if the caller does not have permission to invoke this method.
-
getPrincipals
public Set<Principal> getPrincipals()
Return theSet
of Principals associated with thisSubject
. EachPrincipal
represents an identity for thisSubject
.The returned
Set
is backed by this Subject's internalPrincipal
Set
. Any modification to the returnedSet
affects the internalPrincipal
Set
as well.- Returns:
- The
Set
of Principals associated with thisSubject
.
-
getPrincipals
public <T extends Principal> Set<T> getPrincipals(Class<T> c)
Return aSet
of Principals associated with thisSubject
that are instances or subclasses of the specifiedClass
.The returned
Set
is not backed by this Subject's internalPrincipal
Set
. A newSet
is created and returned for each method invocation. Modifications to the returnedSet
will not affect the internalPrincipal
Set
.- Parameters:
c
- the returnedSet
of Principals will all be instances of this class.- Returns:
- a
Set
of Principals that are instances of the specifiedClass
. - Throws:
NullPointerException
- if the specifiedClass
isnull
.
-
getPublicCredentials
public Set<Object> getPublicCredentials()
Return theSet
of public credentials held by thisSubject
.The returned
Set
is backed by this Subject's internal public CredentialSet
. Any modification to the returnedSet
affects the internal public CredentialSet
as well.- Returns:
- A
Set
of public credentials held by thisSubject
.
-
getPrivateCredentials
public Set<Object> getPrivateCredentials()
Return theSet
of private credentials held by thisSubject
.The returned
Set
is backed by this Subject's internal private CredentialSet
. Any modification to the returnedSet
affects the internal private CredentialSet
as well.A caller requires permissions to access the Credentials in the returned
Set
, or to modify theSet
itself. ASecurityException
is thrown if the caller does not have the proper permissions.While iterating through the
Set
, aSecurityException
is thrown if the caller does not have permission to access a particular Credential. TheIterator
is nevertheless advanced to next element in theSet
.- Returns:
- A
Set
of private credentials held by thisSubject
.
-
getPublicCredentials
public <T> Set<T> getPublicCredentials(Class<T> c)
Return aSet
of public credentials associated with thisSubject
that are instances or subclasses of the specifiedClass
.The returned
Set
is not backed by this Subject's internal public CredentialSet
. A newSet
is created and returned for each method invocation. Modifications to the returnedSet
will not affect the internal public CredentialSet
.- Parameters:
c
- the returnedSet
of public credentials will all be instances of this class.- Returns:
- a
Set
of public credentials that are instances of the specifiedClass
. - Throws:
NullPointerException
- if the specifiedClass
isnull
.
-
getPrivateCredentials
public <T> Set<T> getPrivateCredentials(Class<T> c)
Return aSet
of private credentials associated with thisSubject
that are instances or subclasses of the specifiedClass
.The caller must have permission to access all of the requested Credentials, or a
SecurityException
will be thrown.The returned
Set
is not backed by this Subject's internal private CredentialSet
. A newSet
is created and returned for each method invocation. Modifications to the returnedSet
will not affect the internal private CredentialSet
.- Parameters:
c
- the returnedSet
of private credentials will all be instances of this class.- Returns:
- a
Set
of private credentials that are instances of the specifiedClass
. - Throws:
NullPointerException
- if the specifiedClass
isnull
.
-
equals
public boolean equals(Object o)
Compares the specified Object with thisSubject
for equality. Returns true if the given object is also a Subject and the twoSubject
instances are equivalent. More formally, twoSubject
instances are equal if theirPrincipal
andCredential
Sets are equal.- Overrides:
equals
in classObject
- Parameters:
o
- Object to be compared for equality with thisSubject
.- Returns:
- true if the specified Object is equal to this
Subject
. - Throws:
SecurityException
- if the caller does not have permission to access the private credentials for thisSubject
, or if the caller does not have permission to access the private credentials for the providedSubject
.- See Also:
Object.hashCode()
,HashMap
-
toString
public String toString()
Return the String representation of thisSubject
.
-
hashCode
public int hashCode()
Returns a hashcode for thisSubject
.- Overrides:
hashCode
in classObject
- Returns:
- a hashcode for this
Subject
. - Throws:
SecurityException
- if the caller does not have permission to access this Subject's private credentials.- See Also:
Object.equals(java.lang.Object)
,System.identityHashCode(java.lang.Object)
-
-
Nederlandse vertaling
U hebt gevraagd om deze site in het Nederlands te bezoeken. Voor nu wordt alleen de interface vertaald, maar nog niet alle inhoud.Als je me wilt helpen met vertalingen, is je bijdrage welkom. Het enige dat u hoeft te doen, is u op de site registreren en mij een bericht sturen waarin u wordt gevraagd om u toe te voegen aan de groep vertalers, zodat u de gewenste pagina's kunt vertalen. Een link onderaan elke vertaalde pagina geeft aan dat u de vertaler bent en heeft een link naar uw profiel.
Bij voorbaat dank.
Document heeft de 11/06/2005 gemaakt, de laatste keer de 04/03/2020 gewijzigd
Bron van het afgedrukte document:https://www.gaudry.be/nl/java-api-rf-javax/security/auth/Subject.html
De infobrol is een persoonlijke site waarvan de inhoud uitsluitend mijn verantwoordelijkheid is. De tekst is beschikbaar onder CreativeCommons-licentie (BY-NC-SA). Meer info op de gebruiksvoorwaarden en de auteur.
Referenties
Deze verwijzingen en links verwijzen naar documenten die geraadpleegd zijn tijdens het schrijven van deze pagina, of die aanvullende informatie kunnen geven, maar de auteurs van deze bronnen kunnen niet verantwoordelijk worden gehouden voor de inhoud van deze pagina.
De auteur Deze site is als enige verantwoordelijk voor de manier waarop de verschillende concepten, en de vrijheden die met de referentiewerken worden genomen, hier worden gepresenteerd. Vergeet niet dat u meerdere broninformatie moet doorgeven om het risico op fouten te verkleinen.