Date: Fri, 29 Mar 2024 06:42:02 +0000 (UTC) Message-ID: <900017810.7563.1711694522090@ip-10-10-7-29.ec2.internal> Subject: Exported From Confluence MIME-Version: 1.0 Content-Type: multipart/related; boundary="----=_Part_7562_1810440626.1711694522088" ------=_Part_7562_1810440626.1711694522088 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable Content-Location: file:///C:/exported.html
This version of the Subject API distribution contains a configurable JND= I source adapter and a configurable JDBC source adapter. In addition, the G= rouper distribution contains a source adapter (the GrouperSourceAdapter) th= at presents Grouper groups as subjects. Third parties may write their own s= ource adapters; however, in this version of the Subject API it may be neces= sary to modify Subject API source code beyond merely implementing the Sourc= e and Subject interfaces.
Subject API v0.2.1 Javadoc<= /p>
Below is the structure of the Subject API v0.2.1 'sources.xml' configura= tion file. Following that, its elements and attributes are described in det= ail.
<sour= ces> <source adapterClass=3D"aClassRef"/> <id>sourceId</id> <name>sourceDisplayName</name> <type>subjectType</type> <init-param> <param-name>various</param-name> <param-value>site-specific</param-value> </init-param> ... <attribute>attributeType</attribute> ... <search> <searchType>searchSubject, searchSubjectByIdentifier, or search</s= earchType> <param> <param-name>JNDI or JDBC specific params</param-name> <param-value>back-end specific declarations</param-value> </param> ... </searchType> </search> ... </source> ... </sources>
A sources.xml file contains a single sources element wi= th one or more subordinate source elements.
Each source element configures one instance of a source= adapter. Its adapterClass attribute is the name of the ja= va class configured by this element.
A string identifying this identity source. This value is the value of th= e sourceId attribute of every subject resolved from this source.
NOTE: A Subject API caller need only persist the source= Id and subjectId of a subject in order to be able to resolve its attributes= later. It is important that the sourceId values be stable over time so tha= t the pair (sourceId, subjectId) continue to refer to the same subject. Hen= ce, a wise deployer will spend some time to determine a good scheme for ass= igning sourceId values before making initial production use of the Subject = API.
A displayable name for this identity source.
The type of subject presented by this source adapter instance. In v0.2.1= this is limited to one of 'person', 'group', and 'application'.
Note: The notion of type in the Subject API will be rem= oved in v1.0. Grouper and Signet, in particular, either do not now or in up= coming releases will not make special use of a subject type as signaled by = the Subject API. Subject API callers should instead identify any caller-spe= cific special handling of subjects by the sourceId or by other attributes o= f subject objects.
The JDBC and JNDI source adapters each require distinct parameter declar= ations to set up connections to back-end stores. They share three other par= ameters that declare which back-end attributes or columns will be presented= as the Subject object's distinguished attributes.
The form of these parameter declarations is
<init= -param> <param-name>parameter_name</param-name> <param-value>parameter_value</param-value> </init-param>
The parameters required for each source adapter class and descriptions o= f each follow. The GrouperSourceAdapter requires no parameters.
adapterClass |
parameter name |
parameter value |
---|---|---|
JDBCSourceAdapter |
dbDriver |
JDBC driver classname |
JDBCSourceAdapter |
dbURL |
JDBC URL for the database |
JDBCSourceAdapter |
dbUser |
database user |
JDBCSourceAdapter |
dbPwd |
database user's password |
JDBCSourceAdapter |
maxActive |
refer to Apache Commons DB= CP documentation |
JDBCSourceAdapter |
maxIdle |
refer to Apache Commons DB= CP documentation |
JDBCSourceAdapter |
maxWait |
refer to Apache Commons DB= CP documentation |
JNDISourceAdapter |
INITIAL_CONTEXT_FACTORY |
A string specific to the java you are using. = For Sun's java it is "com.sun.jndi.ldap.LdapCtxFactory". See the JNDI documentation |
JNDISourceAdapter |
PROVIDER_URL |
The LDAP URL of the LDAP server to connect to= . |
JNDISourceAdapter |
SECURITY_AUTHENTICATION |
See the list of a= llowable values |
JNDISourceAdapter |
SECURITY_PRINCIPAL |
The DN to BIND as to the LDAP server specifie= d in the PROVIDER_URL. |
JNDISourceAdapter |
SECURITY_CREDENTIALS |
A hashed password, clear-text password, key, = certificate, whatever you use to authenticate the SECURITY_PRINCIPAL to the= LDAP server at the PROVIDER_URL. |
Both |
SubjectID_AttributeType |
The name of the attribute or column whose val= ue is the subjectId. |
Both |
Name_AttributeType |
The name of the attribute or column whose val= ue is the subject's name. |
Both |
Description_AttributeType |
The name of the attribute or column whose val= ue is the subject's description. |
The JNDI source adapter will limit the set of attributes returned in an = LDAP search to those listed in attribute elements. If ther= e are no attribute elements, then all attributes visible t= o the SECURITY_PRINCIPAL will be presented to the calling program.
The Subject API defines three methods used to select or search for subje= cts. There must be one search element for each of these th= ree methods.
Identifies the Source interface method configured by this search= element, as given in the table below. The parameter set for each = search element defines how the selection or search is to b= e carried out against the back-end identity store, and which columns or att= ributes will be used as attributes of the subject objects that are returned= . The string "%TERM%" should be used in search filters or WHERE clauses - i= t is replaced by the selection criterion or search term presented to the co= rresponding method.
searchType value |
Source interface method |
%TERM% is ... |
What the search should accomplish |
---|---|---|---|
searchSubject |
getSubject |
a subjectId value |
Select the unique record or entry with subjec= tId=3D%TERM%, or none if %TERM% is no subject's subjectId. |
searchSubjectByIdentifier |
getSubjectByIdentifier |
the value of an identifying attribute |
Select the unique record or entry which has %= TERM% for the value of one of its identifying columns or attributes, or non= e if %TERM% is not the value of any subject's identifying column or attribu= te. |
search |
search |
a string |
Select all records or entries in which the %T= ERM% causes a match. |
The "getSubject" method is used to select a specific subject from the ba= ck-end identity store, for example, to show the name and department of a pe= rson belonging to a group.
The "getSubjectByIdentifier" method enables identifying a subject by mea= ns of a column or attribute different from that used as the subjectId. For = example, if a UI user authenticates with a loginId, but the subjectId is an= opaque registryId, this method is used to identify the subject given their= loginId.
The "search" method is used to help a UI user select the subject they wa= nt from a list. It is typically implemented as a substring search on severa= l non-identifying columns or attributes such as lastname, firstname, and de= partment. The results of a search are displayed in a checkbox list to the U= I user.
The value of this element is a (possibly compound) SQL statement. Before= being executed, all occurrences of the %TERM% variable in the SQL statemen= t are replaced with the corresponding method's argument. The SQL statement = should return exactly one table with zero or more rows. Each row correspond= s to exactly one subject, and the column names of the returned table are us= ed as the attribute names of the subject objects created for each row. The = set of rows is assumed to be the set of all subjects meeting the selection = or search criterion of the containing search element. The = sql element is only used for configuring the JDBCSourceAda= pter.
These elements are only used for configuring the JNDISourceAdapter. They=
correspond to the various parts of an LDAP URL of the same name. Thus, =
the filter element defines a boolean search filter, the base and scope specify the portion of the D=
irectory Information Tree to be searched, and zero or more attribut=
e element values form the list of attributes to be returned with e=
ach matching entry.
The scope element MUST contain one of the values "OBJEC= T_SCOPE", "ONELEVEL_SCOPE", or "SUBTREE_SCOPE", which corresponds to an RFC= 2255 scope parameter of "0", "1", or "2", respectively.
The base element is the DN (distinguished name) of an e= ntry in the directory which is the root of the portion of the Directory Inf= ormation Tree to be searched.
<sour= ces> <!-- Group Subject Resolver --> <source adapterClass=3D"edu.internet2.middleware.grouper.GrouperSourceAd= apter"> <id>g:gsa</id> <name>Grouper: Group Source Adapter</name> <type>group</type> </source> <!-- Example JDBC Person Resolver --> <source adapterClass=3D"edu.internet2.middleware.subject.provider.JDBCSo= urceAdapter"> <id>uc</id> <name>Bogus UC People</name> <type>person</type> <init-param> <param-name>maxActive</param-name> <param-value>16</param-value> </init-param> <init-param> <param-name>maxIdle</param-name> <param-value>16</param-value> </init-param> <init-param> <param-name>maxWait</param-name> <param-value>-1</param-value> </init-param> <init-param> <param-name>dbDriver</param-name> <param-value>org.hsqldb.jdbcDriver</param-value> </init-param> <init-param> <param-name>dbUrl</param-name> <param-value>jdbc:hsqldb:hsql://localhost:9002/bogus-uc-people</pa= ram-value> </init-param> <init-param> <param-name>dbUser</param-name> <param-value>sa</param-value> </init-param> <init-param> <param-name>dbPwd</param-name> <param-value></param-value> </init-param> <init-param> <param-name>SubjectID_AttributeType</param-name> <param-value>id</param-value> </init-param> <init-param> <param-name>Name_AttributeType</param-name> <param-value>name</param-value> </init-param> <init-param> <param-name>Description_AttributeType</param-name> <param-value>name</param-value> </init-param> <search> <searchType>searchSubject</searchType> <param> <param-name>sql</param-name> <param-value> select id, concat(firstname, concat(' ', lastname)) as name, concat(lastname, concat(', ', firstname)) as lfname, lastname, firstname, middlename, account.name as loginid, department, curriculum, appointment from individual left join account on (account.individualid =3D id) left join faculty on (faculty.individualid =3D id) left join staff on (staff.individualid =3D id) left join student on (student.individualid =3D id) where (id=3D'%TERM%') </param-value> </param> </search> <search> <searchType>searchSubjectByIdentifier</searchType> <param> <param-name>sql</param-name> <param-value> select id, concat(firstname, concat(' ', lastname)) as name, concat(lastname, concat(', ', firstname)) as lfname, lastname, firstname, middlename, account.name as loginid, department, curriculum, appointment from individual left join account on (account.individualid =3D id) left join faculty on (faculty.individualid =3D id) left join staff on (staff.individualid =3D id) left join student on (student.individualid =3D id) where (account.name=3D'%TERM%') </param-value> </param> </search> <search> <searchType>search</searchType> <param> <param-name>sql</param-name> <param-value> select id, concat(firstname, concat(' ', lastname)) as name, concat(lastname, concat(', ', firstname)) as lfname, lastname, firstname, middlename, account.name as loginid, department, curriculum, appointment from individual left join account on (account.individualid =3D id) left join faculty on (faculty.individualid =3D id) left join staff on (staff.individualid =3D id) left join student on (student.individualid =3D id) where (lower(firstname) like '%%TERM%%') or (lower(lastname) like '%%TERM%%') or (lower(department) like '%%TERM%%') or (lower(account.name) like '%%TERM%%') </param-value> </param> </search> </source> <!-- Example JNDI Person Resolver --> <source adapterClass=3D"edu.internet2.middleware.subject.provider.JNDISo= urceAdapter"> <id>kitn-person</id> <name>KITN People</name> <type>person</type> <init-param> <param-name>INITIAL_CONTEXT_FACTORY</param-name> <param-value>com.sun.jndi.ldap.LdapCtxFactory</param-value> </init-param> <init-param> <param-name>PROVIDER_URL</param-name> <param-value>ldap://localhost:389</param-value> </init-param> <init-param> <param-name>SECURITY_AUTHENTICATION</param-name> <param-value>simple</param-value> </init-param> <init-param> <param-name>SECURITY_PRINCIPAL</param-name> <param-value></param-value> </init-param> <init-param> <param-name>SECURITY_CREDENTIALS</param-name> <param-value></param-value> </init-param> <init-param> <param-name>SubjectID_AttributeType</param-name> <param-value>kitnEduPersonRegID</param-value> </init-param> <init-param> <param-name>Name_AttributeType</param-name> <param-value>cn</param-value> </init-param> <init-param> <param-name>Description_AttributeType</param-name> <param-value>description</param-value> </init-param> <search> <searchType>searchSubject</searchType> <param> <param-name>filter</param-name> <param-value> (& (kitnEduPersonRegId=3D%TERM%)(objectclass=3DkitnEduPerson)) </param-value> </param> <param> <param-name>scope</param-name> <param-value>SUBTREE_SCOPE</param-value> </param> <param> <param-name>base</param-name> <param-value>ou=3Dpeople,dc=3Dkitn,dc=3Dedu</param-value> </param> </search> <search> <searchType>searchSubjectByIdentifier</searchType> <param> <param-name>filter</param-name> <param-value> (& (uid=3D%TERM%)(objectclass=3DkitnEduPerson)) </param-value> </param> <param> <param-name>scope</param-name> <param-value>SUBTREE_SCOPE</param-value> </param> <param> <param-name>base</param-name> <param-value>ou=3Dpeople,dc=3Dkitn,dc=3Dedu</param-value> </param> </search> <search> <searchType>search</searchType> <param> <param-name>filter</param-name> <param-value> (&(|(uid=3D%TERM%)(cn=3D*%TERM%*)(kitnEduPersonRegId=3D%TERM%))(obj= ectclass=3DkitnEduPerson)) </param-value> </param> <param> <param-name>scope</param-name> <param-value>SUBTREE_SCOPE</param-value> </param> <param> <param-name>base</param-name> <param-value>ou=3Dpeople,dc=3Dkitn,dc=3Dedu</param-value> </param> </search> </source> </sources>