Authorization Open Service Interface Definitions authorization version 3.0.0
The Authorization OSID manages and queries authorizations.
Authorizations
An Authorization
is an OsidRelationship
that defines who can do
what to what. The grammar of an authorization incluides the subject or
the actor (who), the action or verb (do what), and the object or context
(to what). All three of these components must exist in an authorization
for it to have any explicit meaning. An Authorization
is a mapping
among these three components.
Agent:
the actor (eg: tom@coppeto.org)Function:
the action (eg: create purchase order)Qualifier:
the object or context within a Function (eg: on account 1967)
This tuple in essence defines a role. “Instructor” is not a role and is not suitable for making an authorization decision. “Instructs Physics 101”, both the function and qualifier, defines the complete role (within the context of a particular college) that can be used for an authorization decision.
The basic service of the Authorization OSID is to provide a means for
asking whether a given Agent
is authorized to perform a Function
with a Qualifier,
in other words, if such a mapping exists. The
Agent will generally be obtained from an Authentication service and the
Function
and Qualifier
generally known to the consuming
application (a server process needing to protect some resource).
- Example
Authentication auth = authNValidationSession.authenticate(creds);
AuthorizationSession session = authZManager.getAuthorizationSession(); boolean authorized = session.isAuthorized(auth.getAgentId(), functionId, qualifierId);
The rest of the Authorization OSID is concerned with managing authorizations.
Explicit/Implicit Authorizations
Authorizations can be explcit or implcit. Explicit authorizations are
managed while implcit authorizations are derived from Resources,
Function
and Qualifier
hierrachies. Examples of implcit
authorizations:
- The Authorization OSID can accept a
Resource
in lieu of anAgent
as the actor so a Person, Group or Organization may be used to specify an authorization. In this case, the explicit authorization is the one containing theResource
and an implicit authorization exists for eachAgent.
Qualifiers
only exist as Hierarchy Nodes since the Authorization OSID does not manage the objects used as qualifiers but may manage directly, or have access to, a Hierarchy service to obtain the identity and relationship among these objects. An explicit authorization for a givenQualifier
creates an implcit authorization for every child of thatQualifier.
The Authorization OSID manages Functions
directly through its owned
defined sessions and exposes actors via the Resource OSID.
Qualifiers
are only exposed through the Hierarchy service as the
Authorization service doesn’t have anything to say about the objects
represented by the Qualifiers
.
Vault Cataloging
Authorizations, Functions
and Qualifiers
may be organized into
one or many Vaults
. This serves to categorize authorizatiion data
for the purpose of browsing or auditing. Vaults
are hierarchical
where each node includes all the authorization data of its children. A
single root node will make available all known authorizations and is a
reasonable choice for a default Vault
for a non-federated aware
consumer. A federated authorization scheme is one in which Vaults
are available for selection.
Notifications
Certain consumers may wish to be notified of changes within the service.
Authorization supports notifications via
AuthorizatioNotificationSession,
FunctionNotificationSession
and VaultNotificationSession
.
- if (manager.supportsAuthorizationNotification()) {
- AuthorizationNotificationSession ans = manager.getAuthorizationNotificationSession(receiver); ans.registerForDeletedAuthorizations();
}
- AuthorizationReceiver receiver {
- newAuthorization(Authorization a) {print(“authorization created”);} deletedAuthorization(Authorization a) {print(“authorization removed”);}
}
Sub Packages
The Authorization OSID includes an Authorization Rules OSID for managing
the effectiveness of Authorizations
.
Service Managers¶
Authorization Profile¶
Bases:
dlkit.osid.managers.OsidProfile
The
AuthorizationProfile
describes the interoperability among authorization services.Tests for the availability of an authorization service which is the basic service for checking authorizations.
Returns: true
if authorization is supported,false
otherwiseReturn type: boolean
compliance: mandatory – This method must be implemented.
Tests if an authorization lookup service is supported.
An authorization lookup service defines methods to access authorizations.
Returns: true if authorization lookup is supported, false otherwise Return type: boolean
compliance: mandatory – This method must be implemented.
Tests if an authorization query service is supported.
Returns: true
if authorization query is supported,false
otherwiseReturn type: boolean
compliance: mandatory – This method must be implemented.
Tests if an authorization administrative service is supported.
Returns: true
if authorization admin is supported,false
otherwiseReturn type: boolean
compliance: mandatory – This method must be implemented.
Tests if a vault lookup service is supported.
A vault lookup service defines methods to access authorization vaults.
Returns: true
if function lookup is supported,false
otherwiseReturn type: boolean
compliance: mandatory – This method must be implemented.
Tests if a vault query service is supported.
Returns: true
if vault query is supported,false
otherwiseReturn type: boolean
compliance: mandatory – This method must be implemented.
Tests if a vault administrative service is supported.
Returns: true
if vault admin is supported,false
otherwiseReturn type: boolean
compliance: mandatory – This method must be implemented.
Gets the supported
Authorization
record types.Returns: a list containing the supported authorization record types Return type: osid.type.TypeList
compliance: mandatory – This method must be implemented.
Gets the supported
Authorization
search record types.Returns: a list containing the supported authorization search record types Return type: osid.type.TypeList
compliance: mandatory – This method must be implemented.
Gets the supported
Function
record types.Returns: a list containing the supported Function
record typesReturn type: osid.type.TypeList
compliance: mandatory – This method must be implemented.
Gets the supported
Function
search record types.Returns: a list containing the supported Function
search record typesReturn type: osid.type.TypeList
compliance: mandatory – This method must be implemented.
Gets the supported
Qualifier
record types.Returns: a list containing the supported Qualifier
record typesReturn type: osid.type.TypeList
compliance: mandatory – This method must be implemented.
Gets the supported
Qualifier
search record types.Returns: a list containing the supported Qualifier
search record typesReturn type: osid.type.TypeList
compliance: mandatory – This method must be implemented.
Gets the supported
Vault
record types.Returns: a list containing the supported Vault
record typesReturn type: osid.type.TypeList
compliance: mandatory – This method must be implemented.
Gets the supported vault search record types.
Returns: a list containing the supported Vault
search record typesReturn type: osid.type.TypeList
compliance: mandatory – This method must be implemented.
Gets the supported
AuthorizationCondition
record types.Returns: a list containing the supported AuthorizationCondition
record typesReturn type: osid.type.TypeList
compliance: mandatory – This method must be implemented.
Authorization Manager¶
Bases:
dlkit.osid.managers.OsidManager
,dlkit.osid.sessions.OsidSession
,dlkit.services.authorization.AuthorizationProfile
The authorization manager provides access to authorization sessions and provides interoperability tests for various aspects of this service.
The sessions included in this manager are:
AuthorizationSession:
a session to performs authorization checksAuthorizationLookupSession:
a session to look upAuthorizations
AuthorizationQuerySession:
a session to queryAuthorizations
AuthorizationSearchSession:
a session to searchAuthorizations
AuthorizationAdminSession:
a session to create, modify and deleteAuthorizations
AuthorizationNotificationSession: a
session to receive messages pertaining toAuthorization
changesAuthorizationVaultSession:
a session to look up authorization to vault mappingsAuthorizationVaultAssignmentSession:
a session to manage authorization to vault mappingsAuthorizationSmartVaultSession:
a session to manage smart authorization vaultsFunctionLookupSession:
a session to look upFunctions
FunctionQuerySession:
a session to queryFunctions
FunctionSearchSession:
a session to searchFunctions
FunctionAdminSession:
a session to create, modify and deleteFunctions
FunctionNotificationSession: a
session to receive messages pertaining toFunction
changesFunctionVaultSession:
a session for looking up function and vault mappingsFunctionVaultAssignmentSession:
a session for managing function and vault mappingsFunctionSmartVaultSession:
a session to manage dynamic function vaultsQualifierLookupSession:
a session to look upQualifiers
QualifierQuerySession:
a session to queryQualifiers
QualifierSearchSession:
a session to searchQualifiers
QualifierAdminSession:
a session to create, modify and deleteQualifiers
QualifierNotificationSession: a
session to receive messages pertaining toQualifier
changesQualifierHierarchySession:
a session for traversing qualifier hierarchiesQualifierHierarchyDesignSession:
a session for managing qualifier hierarchiesQualifierVaultSession:
a session for looking up qualifier and vault mappingsQualifierVaultAssignmentSession:
a session for managing qualifier and vault mappingsQualifierSmartVaultSession:
a session to manage dynamic qualifier vaultsVaultLookupSession:
a session to lookup vaultsVaultQuerySession:
a session to query VaultsVaultSearchSession
: a session to search vaultsVaultAdminSession
: a session to create, modify and delete vaultsVaultNotificationSession
: a session to receive messages pertaining toVault
changesVaultHierarchySession
: a session to traverse theVault
hierarchyVaultHierarchyDesignSession
: a session to manage theVault
hierarchy
Gets an
AuthorizationBatchManager
.Returns: an AuthorizationBatchManager
Return type: osid.authorization.batch.AuthorizationBatchManager
Raise: OperationFailed
– unable to complete requestRaise: Unimplemented
–supports_authorization_batch() is false
compliance: optional – This method must be implemented if ``supports_authorization_batch()`` is true.
Gets an
AuthorizationRulesManager
.Returns: an AuthorizationRulesManager
Return type: osid.authorization.rules.AuthorizationRulesManager
Raise: OperationFailed
– unable to complete requestRaise: Unimplemented
–supports_authorization_rules() is false
compliance: optional – This method must be implemented if ``supports_authorization_rules()`` is true.
Vault Lookup Methods¶
Tests if this user can perform
Vault
lookups.A return of true does not guarantee successful authorization. A return of false indicates that it is known all methods in this session will result in a
PermissionDenied
. This is intended as a hint to an application that may opt not to offer lookup operations to unauthorized users.
Returns: false
if lookup methods are not authorized,true
otherwiseReturn type: boolean
compliance: mandatory – This method must be implemented.
The returns from the lookup methods may omit or translate elements based on this session, such as authorization, and not result in an error.
This view is used when greater interoperability is desired at the expense of precision.
compliance: mandatory – This method is must be implemented.
A complete view of the
Vault
returns is desired.Methods will return what is requested or result in an error. This view is used when greater precision is desired at the expense of interoperability.
compliance: mandatory – This method is must be implemented.
Gets the
Vault
specified by itsId
.In plenary mode, the exact
Id
is found or aNotFound
results. Otherwise, the returnedVault
may have a differentId
than requested, such as the case where a duplicateId
was assigned to aVault
and retained for compatibility.
Parameters: vault_id ( osid.id.Id
) –Id
of theVault
Returns: the vault Return type: osid.authorization.Vault
Raise: NotFound
–vault_id
not foundRaise: NullArgument
–vault_id
isnull
Raise: OperationFailed
– unable to complete requestRaise: PermissionDenied
– authorization failurecompliance: mandatory – This method is must be implemented.
Gets a
VaultList
corresponding to the givenIdList
.In plenary mode, the returned list contains all of the vaults specified in the
Id
list, in the order of the list, including duplicates, or an error results if anId
in the supplied list is not found or inaccessible. Otherwise, inaccessibleVault
objects may be omitted from the list and may present the elements in any order including returning a unique set.
Parameters: vault_ids ( osid.id.IdList
) – the list ofIds
to retrieveReturns: the returned Vault
listReturn type: osid.authorization.VaultList
Raise: NotFound
– anId was
not foundRaise: NullArgument
–vault_ids
isnull
Raise: OperationFailed
– unable to complete requestRaise: PermissionDenied
– authorization failurecompliance: mandatory – This method must be implemented.
Gets a
VaultList
corresponding to the given vault genusType
which does not include vaults of types derived from the specifiedType
.In plenary mode, the returned list contains all known vaults or an error results. Otherwise, the returned list may contain only those vaults that are accessible through this session.
Parameters: vault_genus_type ( osid.type.Type
) – a vault genus typeReturns: the returned Vault
listReturn type: osid.authorization.VaultList
Raise: NullArgument
–vault_genus_type
isnull
Raise: OperationFailed
– unable to complete requestRaise: PermissionDenied
– authorization failurecompliance: mandatory – This method must be implemented.
Gets a
VaultList
corresponding to the given vault genusType
and include any additional vaults with genus types derived from the specifiedType
.In plenary mode, the returned list contains all known vaults or an error results. Otherwise, the returned list may contain only those vaults that are accessible through this session.
Parameters: vault_genus_type ( osid.type.Type
) – a vault genus typeReturns: the returned Vault
listReturn type: osid.authorization.VaultList
Raise: NullArgument
–vault_genus_type
isnull
Raise: OperationFailed
– unable to complete requestRaise: PermissionDenied
– authorization failurecompliance: mandatory – This method must be implemented.
Gets a
VaultList
containing the given vault recordType
.In plenary mode, the returned list contains all known vaults or an error results. Otherwise, the returned list may contain only those vaults that are accessible through this session.
Parameters: vault_record_type ( osid.type.Type
) – a vault record typeReturns: the returned Vault
listReturn type: osid.authorization.VaultList
Raise: NullArgument
–vault_record_type
isnull
Raise: OperationFailed
– unable to complete requestRaise: PermissionDenied
– authorization failurecompliance: mandatory – This method must be implemented.
Gets a
VaultList
from the given provider ````.In plenary mode, the returned list contains all known vaults or an error results. Otherwise, the returned list may contain only those vaults that are accessible through this session.
Parameters: resource_id ( osid.id.Id
) – a resourceId
Returns: the returned Vault
listReturn type: osid.authorization.VaultList
Raise: NullArgument
–resource_id
isnull
Raise: OperationFailed
– unable to complete requestRaise: PermissionDenied
– authorization failurecompliance: mandatory – This method must be implemented.
Gets all
Vaults
.In plenary mode, the returned list contains all known vaults or an error results. Otherwise, the returned list may contain only those vaults that are accessible through this session.
Returns: a VaultList
Return type: osid.authorization.VaultList
Raise: OperationFailed
– unable to complete requestRaise: PermissionDenied
– authorization failurecompliance: mandatory – This method must be implemented.
Vault Query Methods¶
Tests if this user can perform
Vault
searches.A return of true does not guarantee successful authorization. A return of false indicates that it is known all methods in this session will result in a
PermissionDenied
. This is intended as a hint to an application that may opt not to offer search operations to unauthorized users.
Returns: false
if search methods are not authorized,true
otherwiseReturn type: boolean
compliance: mandatory – This method must be implemented.
Gets a vault query.
Returns: a vault query Return type: osid.authorization.VaultQuery
compliance: mandatory – This method must be implemented.
Gets a list of
Vault
objects matching the given search.
Parameters: vault_query ( osid.authorization.VaultQuery
) – the vault queryReturns: the returned VaultList
Return type: osid.authorization.VaultList
Raise: NullArgument
–vault_query
isnull
Raise: OperationFailed
– unable to complete requestRaise: PermissionDenied
– authorization failureRaise: Unsupported
–vault_query
is not of this servicecompliance: mandatory – This method must be implemented.
Vault Admin Methods¶
Tests if this user can create
Vaults
.A return of true does not guarantee successful authorization. A return of false indicates that it is known creating a
Vault
will result in aPermissionDenied
. This is intended as a hint to an application that may not wish to offer create operations to unauthorized users.
Returns: false
ifVault
creation is not authorized,true
otherwiseReturn type: boolean
compliance: mandatory – This method must be implemented.
Tests if this user can create a single
Vault
using the desired record types.While
AuthorizationManager.getVaultRecordTypes()
can be used to examine which records are supported, this method tests which record(s) are required for creating a specificVault
. Providing an empty array tests if aVault
can be created with no records.
Parameters: vault_record_types ( osid.type.Type[]
) – array of vault record typesReturns: true
ifVault
creation using the specifiedTypes
is supported,false
otherwiseReturn type: boolean
Raise: NullArgument
–vault_record_types
isnull
compliance: mandatory – This method must be implemented.
Gets the vault form for creating new vaults.
A new form should be requested for each create transaction.
Parameters: vault_record_types ( osid.type.Type[]
) – array of vault record typesReturns: the vault form Return type: osid.authorization.VaultForm
Raise: NullArgument
–vault_record_types
isnull
Raise: OperationFailed
– unable to complete requestRaise: PermissionDenied
– authorization failureRaise: Unsupported
– unable to get form qith requested record typescompliance: mandatory – This method must be implemented.
Creates a new
Vault
.
Parameters: vault_form ( osid.authorization.VaultForm
) – the form for thisVault
Returns: the new Vault
Return type: osid.authorization.Vault
Raise: IllegalState
–vault_form
already used in a create transactionRaise: InvalidArgument
– one or more of the form elements is invalidRaise: NullArgument
–vault_form
isnull
Raise: OperationFailed
– unable to complete requestRaise: PermissionDenied
– authorization failureRaise: Unsupported
–vault_form
did not originate fromget_vault_form_for_create()
compliance: mandatory – This method must be implemented.
Tests if this user can update
Vaults
.A return of true does not guarantee successful authorization. A return of false indicates that it is known updating a
Vault
will result in aPermissionDenied
. This is intended as a hint to an application that may not wish to offer update operations to unauthorized users.
Returns: false
ifVault
modification is not authorized,true
otherwiseReturn type: boolean
compliance: mandatory – This method must be implemented.
Gets the vault form for updating an existing vault.
A new vault form should be requested for each update transaction.
Parameters: vault_id ( osid.id.Id
) – theId
of theVault
Returns: the vault form Return type: osid.authorization.VaultForm
Raise: NotFound
–vault_id
is not foundRaise: NullArgument
–vault_id
isnull
Raise: OperationFailed
– unable to complete requestRaise: PermissionDenied
– authorization failurecompliance: mandatory – This method must be implemented.
Updates an existing vault.
Parameters: vault_form ( osid.authorization.VaultForm
) – the form containing the elements to be updatedRaise: IllegalState
–vault_form
already used in an update transactionRaise: InvalidArgument
– the form contains an invalid valueRaise: NullArgument
–vault_form
isnull
Raise: OperationFailed
– unable to complete requestRaise: PermissionDenied
– authorization failureRaise: Unsupported
–vault_form
did not originate fromget_vault_form_for_update()
compliance: mandatory – This method must be implemented.
Tests if this user can delete vaults.
A return of true does not guarantee successful authorization. A return of false indicates that it is known deleting a
Vault
will result in aPermissionDenied
. This is intended as a hint to an application that may not wish to offer delete operations to unauthorized users.
Returns: false
ifVault
deletion is not authorized,true
otherwiseReturn type: boolean
compliance: mandatory – This method must be implemented.
Deletes a
Vault
.
Parameters: vault_id ( osid.id.Id
) – theId
of theVault
to removeRaise: NotFound
–vault_id
not foundRaise: NullArgument
–vault_id
isnull
Raise: OperationFailed
– unable to complete requestRaise: PermissionDenied
– authorization failurecompliance: mandatory – This method must be implemented.
Tests if this user can manage
Id
aliases forVaults
.A return of true does not guarantee successful authorization. A return of false indicates that it is known changing an alias will result in a
PermissionDenied
. This is intended as a hint to an application that may opt not to offer alias operations to an unauthorized user.
Returns: false
ifVault
aliasing is not authorized,true
otherwiseReturn type: boolean
compliance: mandatory – This method must be implemented.
Adds an
Id
to aVault
for the purpose of creating compatibility.The primary
Id
of theVault
is determined by the provider. The newId
performs as an alias to the primaryId
. If the alias is a pointer to another vault it is reassigned to the given vaultId
.
Parameters:
- vault_id (
osid.id.Id
) – theId
of aVault
- alias_id (
osid.id.Id
) – the aliasId
Raise:
AlreadyExists
–alias_id
is already assignedRaise:
NotFound
–vault_id
not foundRaise:
NullArgument
–vault_id
oralias_id
isnull
Raise:
OperationFailed
– unable to complete requestRaise:
PermissionDenied
– authorization failurecompliance: mandatory – This method must be implemented.