Page Operations
Browse SpaceAuthentication Service
| Name | AuthenticationService | |
|---|---|---|
| Version | Dev | Release Notes/History |
| References | Operations | Capabilities |
Authentication Service Description and Assumptions
Relationships
Following describes the relationship between a Principal, Person and an Agent.
|
- A Subject could represent a Person or an Agent (system or process or service within a system).
- A Person may have multiple identities each valid in different contexts, e.g. a person may be a staff member and a student. Each context would have different access levels. The same applies to agent as well (e.g. identity with public key, identity with username/password, etc.)
- Therefore, a Subject may have one or more identities, i.e. one or more principals.
- Each Subject could have one or more identity attributes.
Authentication process
The Authentication process is the process of verifying an identity claimed by or for a system entity. It consists of two steps :
- Identification step: Presenting an identifier to the security system.
- Verification step: Presenting or generating authentication information that corroborates the binding between the entity and the identifier.
Let's describe a typical authentication scenario using widely used security terms. Following are our assumptions.
Assumptions
- A system entity (e.g. a user with Berkeley CalNet ID) has/is already enrolled with at least one identity provider (e.g. CalNet).
- System entity could be human or non-human.
- An identity provider is expected to provide authentication services.
- How the enrollment or signup with the identity provider happens is out of scope for the Authentication Service. It could be part of registration or account set up process of CollectionSpace or elsewhere.
- A service provider (or relying party, e.g. a CollectionSpace service) relies on the identity provider to identify and verify the identity of the system entity
- A service provider could rely on one or more such identity provider for authentication services.
 | Notes |
References
Authentication Service Description and Assumptions
Authentication Service Structures
Principal Entity and Principal Set Entity - entity page with fields and examples.
[Authentication Stack Options] - help understand how the Authentication service might interact with other service layers
[KULSTA:PI Meeting Diagrams]
Operations
Setup
Dictionary Operations
findObjectTypes
fetchObjectStructure
fetchEnumeration
Search Operations
findSearchTypes
fetchSearchType
findSearchTypesByResult
findSearchTypesByCriteria
findSearchResultTypes
fetchSearchResultType
findSearchCriteriaTypes
fetchSearchCriteriaType
Domain Operations
findAuthenticationTypes
Read
Need to add operation for fetchCurrentUser
fetchPrincipal 
findPrincipalsByIdList
fetchPrincipalDisplayInfo
findPrincipalDisplayInfoByIdList
findPrincipalIdsByPerson
findPrincipalIdsBySystem
fetchPersonIdByPrincipal
fetchSystemIdByPrincipal Changed Service to System
fetchPrincipalTypeForPrincipal
Search
Maintenance
assignPrincipalToPerson
assignPrincipalToSystem Changed Service to System
removePrincipalFromPerson
removePrincipalFromSystem Changed Service to System
Setup
| Method | findObjectTypes | ||
|---|---|---|---|
| Description | Retrieves the list of object type identifiers known by this service. Example: cluInfo. | ||
| Parameters | None | None | No parameters |
| Return | objectTypeKeyList | list of object type identifiers | |
| Errors | OPERATION_FAILED | unable to complete request | |
| Capabilities | |||
| Use Cases | |||
| Comments/Feedback | |||
| Method | fetchObjectStructure | ||
|---|---|---|---|
| Description | Retrieves the basic dictionary information about a particular object structure. Including all variations based on a certain type and state. Example: Given that a CLU is of type "Course" and in the state of "Proposed," tell which fields are read only, mandatory, not applicable, have enumerations available, etc. | ||
| Parameters | objectTypeKey | objectTypeKey | identifier of the object type |
| Return | objectStructure | describes the fields for the input object type | |
| Errors | DOES_NOT_EXIST | specified objectTypeKey not found | |
| INVALID_PARAMETER | invalid objectTypeKey | ||
| MISSING_PARAMETER | missing objectTypeKey | ||
| OPERATION_FAILED | unable to complete request | ||
| Capabilities | |||
| Use Cases | |||
| Comments/Feedback | |||
| Method | fetchEnumeration | ||
|---|---|---|---|
| Description | Retrieves the list of enumeration values for a particular enumeration with a certain context for a particular date. The values returned should be those where the supplied date is between the effective and expiration dates. Certain enumerations may not support this functionality. | ||
| Parameters | enumerationKey | enumerationKey | identifier of the enumeration |
| enumContextKey | contextType | identifier of the enumeration context type | |
| string | contextValue | value of the enumeration context | |
| dateTime | contextDate | date and time to get the enumeration for | |
| Return | enumeratedValueList | list of enumerated codes and values | |
| Errors | DOES_NOT_EXIST | enumerationKey not found | |
| INVALID_PARAMETER | invalid enumerationKey, contextType, contextValue, contextDate | ||
| MISSING_PARAMETER | missing enumerationKey, contextType, contextValue, contextDate | ||
| OPERATION_FAILED | unable to complete request | ||
| Capabilities | |||
| Use Cases | |||
| Comments/Feedback | |||
| Method | findSearchTypes | ||
|---|---|---|---|
| Description | Retrieves the list of search types known by this service. | ||
| Parameters | None | None | No Parameters |
| Return | searchTypeInfoList | list of search type information | |
| Errors | OPERATION_FAILED | unable to complete request | |
| Capabilities | |||
| Use Cases | |||
| Comments/Feedback | |||
| Method | fetchSearchType | ||
|---|---|---|---|
| Description | Retrieves information about a particular search type. | ||
| Parameters | searchTypeKey | searchTypeKey | identifier of the search type |
| Return | searchTypeInfo | information on the search type | |
| Errors | DOES_NOT_EXIST | specified searchTypeKey not found | |
| INVALID_PARAMETER | invalid searchTypeKey | ||
| MISSING_PARAMETER | searchTypeKey not specified | ||
| OPERATION_FAILED | unable to complete request | ||
| Capabilities | |||
| Use Cases | |||
| Comments/Feedback | |||
| Method | findSearchTypesByResult | ||
|---|---|---|---|
| Description | Retrieves the list of search types which return results in the specified format. | ||
| Parameters | searchResultTypeKey | searchResultTypeKey | identifier of the search result type |
| Return | searchTypeInfoList | list of search type information | |
| Errors | DOES_NOT_EXIST | specified searchResultTypeKey not found | |
| INVALID_PARAMETER | invalid searchResultTypeKey | ||
| MISSING_PARAMETER | searchResultTypeKey not specified | ||
| OPERATION_FAILED | unable to complete request | ||
| Capabilities | |||
| Use Cases | |||
| Comments/Feedback | |||
| Method | findSearchTypesByCriteria | ||
|---|---|---|---|
| Description | Retrieves the list of search types which use criteria in the specified format. | ||
| Parameters | searchCriteriaTypeKey | searchCriteriaTypeKey | identifier of the search criteria |
| Return | searchTypeInfoList | list of search type information | |
| Errors | DOES_NOT_EXIST | specified searchCriteriaTypeKey not found | |
| INVALID_PARAMETER | invalid searchCriteriaTypeKey | ||
| MISSING_PARAMETER | searchCriteriaTypeKey not specified | ||
| OPERATION_FAILED | unable to complete request | ||
| Capabilities | |||
| Use Cases | |||
| Comments/Feedback | |||
| Method | findSearchResultTypes | ||
|---|---|---|---|
| Description | Retrieves the list of search result types known by this service. Search result types describe the return structure for a search. | ||
| Parameters | None | None | No Parameters |
| Return | searchResultTypeInfoList | list of search result type information | |
| Errors | OPERATION_FAILED | unable to complete request | |
| Capabilities | |||
| Use Cases | |||
| Comments/Feedback | |||
| Method | fetchSearchResultType | ||
|---|---|---|---|
| Description | Retrieves information about a particular search result type. Search result types describe the return structure for a search. | ||
| Parameters | searchResultTypeKey | searchResultTypeKey | identifier of the search result type |
| Return | searchResultTypeInfo | information on the search result type | |
| Errors | DOES_NOT_EXIST | specified searchResultTypeKey not found | |
| INVALID_PARAMETER | invalid searchResultTypeKey | ||
| MISSING_PARAMETER | searchResultTypeKey not specified | ||
| OPERATION_FAILED | unable to complete request | ||
| Capabilities | |||
| Use Cases | |||
| Comments/Feedback | |||
| Method | findSearchCriteriaTypes | ||
|---|---|---|---|
| Description | Retrieves the list of search criteria types known by this service. | ||
| Parameters | None | None | No parameters |
| Return | searchCriteriaTypeInfoList | list of search criteria type information | |
| Errors | OPERATION_FAILED | unable to complete request | |
| Capabilities | |||
| Use Cases | |||
| Comments/Feedback | |||
| Method | fetchSearchCriteriaType | ||
|---|---|---|---|
| Description | Retrieves information about a particular search criteria type. | ||
| Parameters | searchCriteriaTypeKey | searchCriteriaTypeKey | identifier of the search criteria type |
| Return | searchCriteriaTypeInfo | information on the search criteria type | |
| Errors | DOES_NOT_EXIST | specified searchCriteriaTypeKey not found | |
| INVALID_PARAMETER | invalid searchCriteriaTypeKey | ||
| MISSING_PARAMETER | searchCriteriaTypeKey not specified | ||
| OPERATION_FAILED | unable to complete request | ||
| Capabilities | |||
| Use Cases | |||
| Comments/Feedback | |||
| Method | findAuthenticationTypes | ||
|---|---|---|---|
| Description | Retrieve the list of authentication types known by this service | ||
| Parameters | None | None | No parameters |
| Return | authenticationTypeList | list of authentication types | |
| Errors | OPERATION_FAILED | unable to complete request | |
| Capabilities | |||
| Use Cases | |||
| Comments/Feedback | |||
Read
| Method | findPrincipalIdsByPerson | ||
|---|---|---|---|
| Description | Retrieves a list of Principals for a given Person | ||
| Parameters | personId | personId | person identifier |
| Return | principalIdList | list of principal ids for the specified person | |
| Errors | DISABLED_IDENTIFIER | personId found but has been retired | |
| DOES_NOT_EXIST | personId not found | ||
| INVALID_PARAMETER | invalid personId | ||
| MISSING_PARAMETER | missing personId | ||
| OPERATION_FAILED | unable to complete request | ||
| PERMISSION_DENIED | authorization failure | ||
| Capabilities | |||
| Use Cases | |||
| Comments/Feedback | |||
| Method | findPrincipalIdsBySystem | ||
|---|---|---|---|
| Description | Retrieves a list of Principals for a given System | ||
| Parameters | systemId | systemId | system identifier |
| Return | principalIdList | list of principal ids for the given system | |
| Errors | DISABLED_IDENTIFIER | systemId found but has been retired | |
| DOES_NOT_EXIST | systemId not found | ||
| INVALID_PARAMETER | invalid systemId | ||
| MISSING_PARAMETER | missing systemId | ||
| OPERATION_FAILED | unable to complete request | ||
| PERMISSION_DENIED | authorization failure | ||
| Capabilities | |||
| Use Cases | |||
| Comments/Feedback | |||
| Method | fetchPersonIdByPrincipal | ||
|---|---|---|---|
| Description | Retrieves a Person for a given Principal | ||
| Parameters | principalId | principalId | principal identifier |
| Return | personId | person identifier that matches the supplied criteria | |
| Errors | DISABLED_IDENTIFIER | principalId found but has been retired | |
| DOES_NOT_EXIST | principalId not found | ||
| INVALID_PARAMETER | invalid principalId | ||
| MISSING_PARAMETER | missing principalId | ||
| OPERATION_FAILED | unable to complete request | ||
| PERMISSION_DENIED | authorization failure | ||
| Capabilities | |||
| Use Cases | |||
| Comments/Feedback | |||
| Method | fetchSystemByPrincipal | ||
|---|---|---|---|
| Description | Retrieves a System for a given Principal | ||
| Parameters | principalId | principalId | principal identifier |
| Return | systemId | system identifier that matches the supplied criteria | |
| Errors | DISABLED_IDENTIFIER | systemId found but has been retired | |
| DOES_NOT_EXIST | systemId not found | ||
| INVALID_PARAMETER | invalid principalId | ||
| MISSING_PARAMETER | missing principalId | ||
| OPERATION_FAILED | unable to complete request | ||
| PERMISSION_DENIED | authorization failure | ||
| Capabilities | |||
| Use Cases | |||
| Comments/Feedback | |||
| Method | fetchPrincipalTypeForPrincipal | ||
|---|---|---|---|
| Description | Retrieves a Principal Type for a given Principal | ||
| Parameters | principalId | principalId | principal identifier |
| Return | principalType | principal type that matches the supplied criteria | |
| Errors | DISABLED_IDENTIFIER | principalId found but has been retired | |
| DOES_NOT_EXIST | principalId not found | ||
| INVALID_PARAMETER | invalid principalId | ||
| MISSING_PARAMETER | missing principalId | ||
| OPERATION_FAILED | unable to complete request | ||
| PERMISSION_DENIED | authorization failure | ||
| Capabilities | |||
| Use Cases | |||
| Comments/Feedback | |||
| Method | findPrincipalTypesByPrincipalIdList | ||
|---|---|---|---|
| Description | Retrieves a list of Principal Types for a given list of Principal Ids | ||
| Parameters | principalIdList | principalIdList | list of principal identifiers |
| Return | principalTypeList | List of principal types that match the supplied criteria | |
| Errors | DISABLED_IDENTIFIER | One or more principalIds found but have been retired | |
| DOES_NOT_EXIST | One or more principalIds not found | ||
| INVALID_PARAMETER | invalid principalIdList | ||
| MISSING_PARAMETER | missing principalId | ||
| OPERATION_FAILED | unable to complete request | ||
| PERMISSION_DENIED | authorization failure | ||
| Capabilities | |||
| Use Cases | |||
| Comments/Feedback | |||
Search
| Method | searchForResults | ||
|---|---|---|---|
| Description | Retrieves results in tabular form for the specified parameters. | ||
| Parameters | [searchTypeKey] | searchTypeKey | search identifier |
| [queryParamValueList] | queryParamValues | list of values for search parameters | |
| Return | [resultList] | list of results from the query | |
| Errors | DOES_NOT_EXIST | specified search type not found | |
| INVALID_PARAMETER | invalid searchTypeKey, queryParamValueList | ||
| MISSING_PARAMETER | searchTypeKey, queryParamValueList not specified | ||
| OPERATION_FAILED | unable to complete request | ||
| PERMISSION_DENIED | authorization failure | ||
| Capabilities | |||
| Use Cases | |||
| Comments/Feedback | |||
Maintenance
| Method | assignPrincipalToPerson | ||
|---|---|---|---|
| Description | Assigns a Principal to a Person | ||
| Parameters | principalId | principalId | principal identifier |
| personId | personId | person identifier | |
| Return | status | status of the operation | |
| Errors | ALREADY_EXISTS | association already exists | |
| DISABLED_IDENTIFIER | personId or principalId found but has been retired | ||
| DOES_NOT_EXIST | personId, principalId does not exist | ||
| INVALID_PARAMETER | invalid personId, principalId | ||
| MISSING_PARAMETER | missing personId, principalId | ||
| OPERATION_FAILED | unable to complete request | ||
| PERMISSION_DENIED | authorization failure | ||
| Capabilities | |||
| Use Cases | |||
| Comments/Feedback | |||
| Method | assignPrincipalToSystem | ||
|---|---|---|---|
| Description | Assigns a Principal to a System | ||
| Parameters | principalId | principalId | principal identifier |
| systemId | systemId | system identifier | |
| Return | status | status of the operation | |
| Errors | ALREADY_EXISTS | association already exists | |
| DISABLED_IDENTIFIER | principalId, systemId found but has been retired | ||
| DOES_NOT_EXIST | principalId, systemId does not exist | ||
| INVALID_PARAMETER | invalid principalId, systemId | ||
| MISSING_PARAMETER | missing principalId, systemId | ||
| OPERATION_FAILED | unable to complete request | ||
| PERMISSION_DENIED | authorization failure | ||
| Capabilities | |||
| Use Cases | |||
| Comments/Feedback | |||
| Method | removePrincipalFromPerson | ||
|---|---|---|---|
| Description | Remove a Principal from a Person | ||
| Parameters | principalId | principalId | principal identifier |
| personId | personId | person identifier | |
| Return | status | status of the operation | |
| Errors | DISABLED_IDENTIFIER | personId or principalId found but has been retired | |
| DOES_NOT_EXIST | personId, principalId, association does not exist | ||
| INVALID_PARAMETER | invalid personId, principalId | ||
| MISSING_PARAMETER | missing personId, principalId | ||
| OPERATION_FAILED | unable to complete request | ||
| PERMISSION_DENIED | authorization failure | ||
| Capabilities | |||
| Use Cases | |||
| Comments/Feedback | |||
| Method | removePrincipalFromSystem | ||
|---|---|---|---|
| Description | Remove a Principal from a System | ||
| Parameters | principalId | principalId | principal identifier |
| systemId | systemId | system identifier | |
| Return | status | status of the operation | |
| Errors | DISABLED_IDENTIFIER | principalId, systemId found but has been retired | |
| DOES_NOT_EXIST | principalId, systemId, association does not exist | ||
| INVALID_PARAMETER | invalid principalId, systemId | ||
| MISSING_PARAMETER | missing principalId, systemId | ||
| OPERATION_FAILED | unable to complete request | ||
| PERMISSION_DENIED | authorization failure | ||
| Capabilities | |||
| Use Cases | |||
| Comments/Feedback | |||