Embed Size (px)
Citation preview
IBM
Tivoli
Access
Manager
for
e-business
Authorization
C
API
Developer
Reference
Version
5.1
SC32-1355-00
���
IBM
Tivoli
Access
Manager
for
e-business
Authorization
C
API
Developer
Reference
Version
5.1
SC32-1355-00
���
Note
Before
using
this
information
and
the
product
it
supports,
read
the
information
in
Appendix
F,
“Notices,”
on
page
315.
First
Edition
(November
2003)
This
edition
replaces
SC32-1140-01.
©
Copyright
International
Business
Machines
Corporation
2000,2003.
All
rights
reserved.
US
Government
Users
Restricted
Rights
–
Use,
duplication
or
disclosure
restricted
by
GSA
ADP
Schedule
Contract
with
IBM
Corp.
Contents
Preface
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. ix
Who
should
read
this
book
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. ix
What
this
book
contains
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. ix
Publications
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. x
Release
information
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. xi
Base
information
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. xi
Web
security
information
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. xi
Developer
references
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. xii
Technical
supplements
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. xii
Related
publications
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. xiii
Accessing
publications
online
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. xvi
Accessibility
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. xvi
Contacting
software
support
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. xvi
Conventions
used
in
this
book
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. xvi
Typeface
conventions
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. xvi
Operating
system
differences
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. xvii
Chapter
1.
Authorization
API
overview
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 1
Introducing
the
authorization
API
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 2
The
Open
Group
Authorization
API
standard
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 2
The
Tivoli
Access
Manager
authorization
model
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 3
Locating
the
authorization
API
components
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 5
Building
applications
with
the
authorization
API
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 7
Tested
compilers
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 7
Demonstration
programs
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 8
Deploying
applications
with
the
authorization
API
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 9
Summarizing
authorization
API
tasks
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 9
Chapter
2.
Authorization
API
functions
and
data
types
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 11
API
functions
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 12
Attribute
lists
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 12
Credentials
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 12
Authorization
decisions
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 13
Initialization,
shutdown,
and
error
handling
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 13
API
extensions
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 14
Character
strings
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 14
Buffers
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 14
Protected
object
structures
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 15
Default
user
registry
information
structure
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 16
Unauthenticated
user
information
structure
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 17
Attribute
lists
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 18
Credential
handles
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 20
Status
codes
and
error
handling
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 21
Chapter
3.
Initializing
the
authorization
API
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 23
Specifying
UTF-8
or
local
codeset
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 24
Specifying
an
authorization
API
configuration
file
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 25
Specifying
cache
mode
settings
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 26
Specifying
cache
mode
type
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 26
Authorization
database
file
location
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 27
Local
cache
refresh
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 27
Local
cache
notification
listener
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 27
SSL
listener
ports
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 28
Local
domain
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 28
Configuring
SSL
from
the
API
client
to
Tivoli
Access
Manager
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 30
©
Copyright
IBM
Corp.
2000,2003
iii
Specifying
an
SSL
keyfile
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 30
Specifying
a
stash
file
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 30
Specifying
a
keyfile
label
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 30
SSL
session
timeout
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 31
SSL
password
expiration
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 31
Authentication
method
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 31
User
name
and
password
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 32
Tivoli
Access
Manager
configuration
file
location
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 32
Password
for
the
SSL
keyfile
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 32
Maximum
number
of
worker
threads
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 33
Automatic
refresh
of
SSL
certificate
and
keyfile
password
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 33
Connection
timeout
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 33
Specifying
communications
attributes
for
the
policy
server
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 35
Policy
server
hostname
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 35
Policy
server
port
number
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 35
Specifying
values
for
an
authorization
server
replica
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 36
Configuring
the
authorization
API
for
LDAP
access
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 37
LDAP
user
registry
support
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 37
LDAP
server
host
name
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 37
LDAP
server
port
number
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 37
LDAP
user
Distinguished
Name
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 37
LDAP
User
Password
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 38
SSL
communication
with
the
LDAP
server
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 38
SSL
keyfile
name
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 38
SSL
keyfile
distinguished
name
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 39
SSL
keyfile
password
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 39
Maximum
search
buffer
size
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 39
Caching
LDAP
data
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 39
LDAP
server
query
preference
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 39
Authentication
method
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 40
Specifying
LDAP
user
registry
replica
access
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 40
LDAP
client-side
timeout
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 40
LDAP
client-side
authentication
timeout
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 41
LDAP
client-side
search
timeout
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 41
URAF
registry
settings
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 42
Specify
the
URAF
configuration
file
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 42
Specify
the
server
identity
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 42
Specify
the
server
password
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 42
Enable
cache
mode
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 42
Specify
cache
size
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 42
Specify
cache
lifetime
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 43
Authorization
rules
initialization
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 44
Prolog
text
for
the
XMLADI
input
document
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 44
Prolog
text
for
the
XSL
rule
document
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 44
Resource
manager
ADI
prefix
list
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 45
Dynamic
ADI
retrieval
entitlement
service
list
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 46
XMLADI
attribute
definitions
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 46
Enabling
the
return
of
permission
information
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 47
Configuring
event
logging
and
legacy
auditing
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 49
Specifying
the
host
interface
on
which
to
listen
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 50
Starting
the
authorization
service
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 51
Chapter
4.
Using
the
authorization
API
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 53
Authenticating
an
API
application
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 54
Verifying
the
identity
of
a
user
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 55
Usage
tip
—
enforcing
user
lockout
policy
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 55
Obtaining
user
authorization
credentials
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 56
Step
1
—
Specifying
the
authorization
authority
and
authentication
mechanism
.
.
.
.
.
.
.
.
.
.
. 56
Step
2
—
Specifying
user
authentication
identity
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 56
Step
3
—
Specifying
additional
user
information
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 57
Step
4
—
Placing
user
information
into
an
API
buffer
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 57
iv
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
Step
5
—
Obtaining
authorization
credentials
for
the
user
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 57
Obtaining
an
authorization
decision
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 59
Step
1
—
Mapping
the
user
operation
to
a
Tivoli
Access
Manager
permission
.
.
.
.
.
.
.
.
.
.
.
. 59
Step
2
—
Mapping
the
requested
resource
to
a
protected
object
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 60
Step
3
—
Assigning
the
user
credentials
to
a
credentials
handle
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 60
Step
4
—
Building
an
attribute
list
for
additional
application
information
.
.
.
.
.
.
.
.
.
.
.
.
.
. 60
Step
5
—
Obtaining
an
authorization
decision
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 61
Cleaning
up
and
shutting
down
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 62
Releasing
allocated
memory
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 62
Shutting
down
the
authorization
API
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 62
Working
with
credentials
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 63
Converting
credentials
to
a
transportable
format
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 63
Converting
credentials
to
the
native
format
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 63
Creating
a
chain
of
credentials
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 63
Determining
the
number
of
credentials
in
a
credentials
chain
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 64
Obtaining
a
credential
from
a
chain
of
credentials
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 64
Modifying
the
contents
of
a
credential
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 64
Obtaining
an
attribute
list
from
a
credential
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 65
Setting
and
getting
string
attribute
values
for
a
credential
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 66
Comparing
two
credentials
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 67
Copying
a
credential
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 67
Chapter
5.
Backwards
compatibility
and
application
migration
.
.
.
.
.
.
.
.
.
.
.
. 69
Binary
backwards
compatibility
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 70
Deprecated
API
elements
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 70
Deprecated
attributes
for
Version
5.1
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 70
Operation
attributes
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 70
Permission
info
attribute
values
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 71
Initialization
attributes
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 71
Deprecated
API
for
comparing
credentials
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 71
Obtaining
the
user’s
authorization
identification
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 71
Authorization
API
initialization
attributes
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 72
DCE
authentication
APIs
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 72
User
registry
information
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 72
Deprecated
return
codes
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 72
Chapter
6.
Authorization
service
plug-ins
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 75
Service
plug-in
architecture
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 76
The
authorization
service
dispatcher
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 77
Authorization
service
plug-ins
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 77
Calling
applications
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 77
Supported
types
of
service
plug-ins
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 79
Implementing
a
service
plug-in
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 81
Initialization
and
configuration
of
service
plug-ins
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 82
Implementing
service
interfaces
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 86
Using
error
codes
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 88
Shut
down
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 92
Example
service
source
code
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 93
Supplied
implementations
for
service
plug-ins
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 96
Entitlement
services
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 97
Credentials
modification
service
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 101
Privilege
attribute
certificate
service
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 102
External
authorization
service
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 102
Chapter
7.
Entitlement
service
plug-ins
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 103
Understanding
entitlements
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 104
Entitlements
of
type
azn_string_t
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 104
Entitlements
of
type
azn_buffer_t
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 105
Initialization,
configuration,
and
shut
down
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 106
Obtaining
entitlements
for
a
specified
user
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 107
Contents
v
Authorizing
a
caller
to
a
specific
entitlement
service
plug-In
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 108
Using
authorization
API
interfaces
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 108
Entitlement
service
error
codes
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 109
Dynamic
ADI
retrieval
services
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 110
Credential
attributes
entitlement
service
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 112
Registry
attribute
entitlement
service
overview
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 113
Registry
attribute
entitlement
service
configuration
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 115
Migration
from
a
previous
release
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 118
Configuring
a
credential
attributes
entitlement
service
as
a
dynamic
ADI
retrieval
service
.
.
.
.
.
.
.
. 119
Chapter
8.
Administration
service
plug-ins
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 123
Understanding
administration
service
plug-ins
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 124
Configuring
administration
service
plug-ins
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 127
Creating
a
configuration
file
entry
for
an
administration
service
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 127
Configuring
an
administration
service
programmatically
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 128
Initializing
and
shutting
down
administration
service
plug-ins
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 129
Using
an
administration
service
plug-in
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 130
Error
codes
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 132
Errors
when
registering
the
administration
service
plug-in
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 132
Errors
when
registering
administration
definitions
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 132
Major
errors
from
administration
service
functions
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 133
Minor
errors
from
administration
service
functions
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 133
Error
codes
specific
to
an
authorization
services
plug-in
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 133
Deploying
an
administration
service
plug-in
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 135
Chapter
9.
External
authorization
service
plug-ins
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 137
Introducing
the
external
authorization
service
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 138
Understanding
the
external
authorization
service
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 139
External
authorization
service
architecture
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 139
Policy
triggers
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 140
Weightings
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 142
Configuring
an
external
authorization
service
plug-in
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 143
Using
a
configuration
file
entry
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 143
Configuring
an
external
authorization
service
programmatically
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 144
Initializing
and
shutting
down
external
authorization
service
plug-Ins
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 145
Obtaining
an
authorization
decision
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 146
Error
codes
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 147
Major
error
codes
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 147
Minor
error
codes
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 148
Appendix
A.
Authorization
API
reference
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 151
azn_attrlist_add_entry()
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 153
azn_attrlist_add_entry_buffer()
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 154
azn_attrlist_add_entry_pobj()
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 155
azn_attrlist_add_entry_ulong()
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 156
azn_attrlist_copy()
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 157
azn_attrlist_create()
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 158
azn_attrlist_delete()
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 159
azn_attrlist_delete_entry()
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 160
azn_attrlist_delete_entry_value()
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 161
azn_attrlist_get_entry_buffer_value()
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 162
azn_attrlist_get_entry_pobj_value()
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 164
azn_attrlist_get_entry_string_value()
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 165
azn_attrlist_get_entry_type()
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 167
azn_attrlist_get_entry_ulong_value()
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 169
azn_attrlist_get_names()
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 170
azn_attrlist_name_get_num()
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 171
azn_creds_combine()
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 172
azn_creds_copy()
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 174
azn_creds_create()
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 175
vi
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
azn_creds_delete()
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 176
azn_creds_equal()
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 177
azn_creds_for_subject()
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 178
azn_creds_get_attr_value_string()
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 180
azn_creds_get_attrlist_for_subject()
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 181
azn_creds_get_pac()
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 183
azn_creds_modify()
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 185
azn_creds_num_of_subjects()
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 188
azn_creds_set_attr_value_string()
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 190
azn_decision_access_allowed()
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 192
azn_decision_access_allowed_ext()
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 194
azn_entitlement_get_entitlements()
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 197
azn_error_get_string()
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 199
azn_error_major()
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 200
azn_error_minor()
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 201
azn_error_minor_get_string()
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 202
azn_id_get_creds()
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 203
azn_init_set_code_set()
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 206
azn_initialize()
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 207
azn_pac_get_creds()
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 210
azn_release_buffer()
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 212
azn_release_pobj()
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 213
azn_release_string()
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 214
azn_release_strings()
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 215
azn_shutdown()
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 216
azn_util_errcode()
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 217
azn_util_handle_is_valid()
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 218
azn_util_password_authenticate()
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 219
azn_util_password_change()
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 221
Appendix
B.
Authorization
service
plug-in
API
reference
.
.
.
.
.
.
.
.
.
.
.
.
.
. 223
azn_admin_get_object()
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 224
azn_admin_get_objectlist()
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 226
azn_admin_get_tasklist()
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 228
azn_admin_perform_task()
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 231
azn_svc_creds_get_pac()
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 234
azn_svc_creds_modify()
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 236
azn_svc_decision_access_allowed_ext()
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 239
azn_svc_entitlement_get_entitlements()
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 242
azn_svc_initialize()
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 244
azn_svc_pac_get_creds()
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 247
azn_svc_shutdown()
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 249
Appendix
C.
Attribute
names
reference
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 251
Initialization
attributes
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 252
Credential
attributes
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 261
Permission
information
attributes
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 263
Authorization
API
service
plug-in
attributes
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 268
Authorization
engine
attributes
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 271
Appendix
D.
Authorization
API
client
configuration
file
.
.
.
.
.
.
.
.
.
.
.
.
.
. 273
Guidelines
for
configuring
stanzas
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 274
General
guidelines
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 274
Default
values
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 274
Strings
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 274
Defined
strings
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 275
File
names
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 275
Integers
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 275
Boolean
values
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 276
How
to
change
configuration
settings
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 277
Contents
vii
[authentication-mechanisms]
stanza
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 278
[aznapi-configuration]
stanza
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 280
[aznapi-admin-services]
stanza
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 286
[aznapi-cred-modification-services]
stanza
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 287
[aznapi-entitlement-services]
stanza
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 288
[aznapi-external-authzn-services]
stanza
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 289
[aznapi-pac-services]
stanza
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 290
[ldap]
stanza
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 291
[manager]
stanza
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 297
[meta-info]
stanza
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 299
[ssl]
stanza
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 300
[uraf-registry]
stanza
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 305
[xmladi-attribute-definitions]
stanza
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 309
Appendix
E.
User
registry
differences
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 311
Appendix
F.
Notices
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 315
Trademarks
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 317
Glossary
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 319
Index
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 325
viii
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
Preface
Welcome
to
the
IBM
Tivoli
Access
Manager
for
e-business
Authorization
C
API
Developer
Reference.
The
Tivoli
Access
Manager
application
development
kit
(ADK)
is
an
application
development
kit
for
IBM
Tivoli
Access
Manager
that
enables
application
developers
to
add
Tivoli
Access
Manager
authorization
and
security
services
to
applications.
This
book
describes
the
C
implementation
of
the
Tivoli
Access
Manager
authorization
API.
See
IBM
Tivoli
Access
Manager
for
e-business
Authorization
Java
Classes
Developer
Reference
for
a
description
of
the
Java
classes
and
methods
associated
with
Tivoli
Access
Manager
authentication.
IBM®
Tivoli®
Access
Manager
(Tivoli
Access
Manager)
is
the
base
software
that
is
required
to
run
applications
in
the
IBM
Tivoli
Access
Manager
product
suite.
It
enables
the
integration
of
IBM
Tivoli
Access
Manager
applications
that
provide
a
wide
range
of
authorization
and
management
solutions.
Sold
as
an
integrated
solution,
these
products
provide
an
access
control
management
solution
that
centralizes
network
and
application
security
policy
for
e-business
applications.
Note:
IBM
Tivoli
Access
Manager
is
the
new
name
of
the
previously
released
software
entitled
Tivoli
SecureWay®
Policy
Director.
Also,
for
users
familiar
with
the
Tivoli
SecureWay
Policy
Director
software
and
documentation,
the
management
server
is
now
referred
to
as
the
policy
server.
Who
should
read
this
book
The
target
audience
for
this
developer
reference
includes:
v
Security
administrators
v
Network
system
administrators
v
IT
architects
v
Application
developers
Readers
should
be
familiar
with:
v
Internet
protocols,
including
HTTP,
TCP/IP,
file
transfer
protocol
(FTP),
and
telnet
v
Development
of
applications
in
a
C
language
environment
v
Security
management,
including
authentication
and
authorization
If
you
are
enabling
Secure
Sockets
Layer
(SSL)
communication,
you
also
should
be
familiar
with
SSL
protocol,
key
exchange
(public
and
private),
digital
signatures,
cryptographic
algorithms,
and
certificate
authorities.
What
this
book
contains
This
document
contains
the
following
chapters:
v
Chapter
1,
“Authorization
API
overview,”
on
page
1
©
Copyright
IBM
Corp.
2000,2003
ix
Describes
the
Tivoli
Access
Manager
implementation
of
the
Open
Group
standard
Authorization
C
API.
v
Chapter
2,
“Authorization
API
functions
and
data
types,”
on
page
11
Describes
the
functions
and
data
types
that
are
provided
in
the
authorization
API.
v
Chapter
3,
“Initializing
the
authorization
API,”
on
page
23
Describes
how
to
initialize
the
authorization
API,
using
either
configuration
file
entries
or
programmatic
structures.
v
Chapter
4,
“Using
the
authorization
API,”
on
page
53
Describes
how
to
perform
the
main
authorization
API
tasks,
such
as
verifying
user
identity,
obtaining
authorization
credentials,
and
obtaining
an
access
decision.
v
Chapter
5,
“Backwards
compatibility
and
application
migration,”
on
page
69
Describes
backwards
compatibility
support,
and
lists
deprecated
interfaces.
v
Chapter
6,
“Authorization
service
plug-ins,”
on
page
75
Describes
the
Authorization
Service
Plug-in
model,
provides
an
overview
of
how
to
implement
service
plug-ins,
and
describes
the
supplied
implementations.
v
Chapter
7,
“Entitlement
service
plug-ins,”
on
page
103
Describes
how
to
implement
and
configure
entitlements
service
plug-ins.
v
Chapter
8,
“Administration
service
plug-ins,”
on
page
123
Describes
how
to
implement
and
configure
administration
service
plug-ins.
v
Chapter
9,
“External
authorization
service
plug-ins,”
on
page
137
Describes
how
to
implement
and
configure
external
authorization
service
plug-ins.
v
Appendix
A,
“Authorization
API
reference,”
on
page
151
Provides
a
reference
page
for
each
authorization
API
function.
v
Appendix
B,
“Authorization
service
plug-in
API
reference,”
on
page
223
Provides
a
reference
page
for
each
service
plug-in
function.
v
Appendix
C,
“Attribute
names
reference,”
on
page
251
Provides
a
reference
to
the
attribute
names
specified
for
use
with
the
authorization
API.
v
Appendix
D,
“Authorization
API
client
configuration
file,”
on
page
273
Provides
a
reference
to
the
configuration
settings
specified
in
the
authorization
API
client
configuration
file.
v
Appendix
E,
“User
registry
differences,”
on
page
311
Provides
a
references
to
differences
between
user
registries.
Note:
The
Tivoli
SecureWay
Policy
Director
version
of
this
book
contained
information
on
the
Java
implementation
of
the
authorization
API.
The
Java
implementation
is
now
described
in
a
separate
book,
IBM
Tivoli
Access
Manager
for
e-business
Authorization
Java
Classes
Developer
Reference.
Publications
Review
the
descriptions
of
the
Tivoli
Access
Manager
library,
the
prerequisite
publications,
and
the
related
publications
to
determine
which
publications
you
might
find
helpful.
After
you
determine
the
publications
you
need,
refer
to
the
instructions
for
accessing
publications
online.
x
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
Additional
information
about
the
IBM
Tivoli
Access
Manager
for
e-business
product
itself
can
be
found
at:
http://www.ibm.com/software/tivoli/products/access-mgr-e-bus/
The
Tivoli
Access
Manager
library
is
organized
into
the
following
categories:
v
“Release
information”
v
“Base
information”
v
“Web
security
information”
v
“Developer
references”
on
page
xii
v
“Technical
supplements”
on
page
xii
Release
information
v
IBM
Tivoli
Access
Manager
for
e-business
Read
This
First
(GI11-4155-00)
Provides
information
for
installing
and
getting
started
using
Tivoli
Access
Manager.
v
IBM
Tivoli
Access
Manager
for
e-business
Release
Notes
(GI11-4156-00)
Provides
late-breaking
information,
such
as
software
limitations,
workarounds,
and
documentation
updates.
Base
information
v
IBM
Tivoli
Access
Manager
Base
Installation
Guide
(SC32-1362-00)
Explains
how
to
install
and
configure
the
Tivoli
Access
Manager
base
software,
including
the
Web
Portal
Manager
interface.
This
book
is
a
subset
of
IBM
Tivoli
Access
Manager
for
e-business
Web
Security
Installation
Guide
and
is
intended
for
use
with
other
Tivoli
Access
Manager
products,
such
as
IBM
Tivoli
Access
Manager
for
Business
Integration
and
IBM
Tivoli
Access
Manager
for
Operating
Systems.
v
IBM
Tivoli
Access
Manager
Base
Administration
Guide
(SC32-1360-00)
Describes
the
concepts
and
procedures
for
using
Tivoli
Access
Manager
services.
Provides
instructions
for
performing
tasks
from
the
Web
Portal
Manager
interface
and
by
using
the
pdadmin
command.
Web
security
information
v
IBM
Tivoli
Access
Manager
for
e-business
Web
Security
Installation
Guide
(SC32-1361-00)
Provides
installation,
configuration,
and
removal
instructions
for
the
Tivoli
Access
Manager
base
software
as
well
as
the
Web
Security
components.
This
book
is
a
superset
of
IBM
Tivoli
Access
Manager
Base
Installation
Guide.
v
IBM
Tivoli
Access
Manager
Upgrade
Guide
(SC32-1369-00)
Explains
how
to
upgrade
from
Tivoli
SecureWay
Policy
Director
Version
3.8
or
previous
versions
of
Tivoli
Access
Manager
to
Tivoli
Access
Manager
Version
5.1.
v
IBM
Tivoli
Access
Manager
for
e-business
WebSEAL
Administration
Guide
(SC32-1359-00)
Provides
background
material,
administrative
procedures,
and
technical
reference
information
for
using
WebSEAL
to
manage
the
resources
of
your
secure
Web
domain.
v
IBM
Tivoli
Access
Manager
for
e-business
IBM
WebSphere
Application
Server
Integration
Guide
(SC32-1368-00)
Preface
xi
Provides
installation,
removal,
and
administration
instructions
for
integrating
Tivoli
Access
Manager
with
IBM
WebSphere®
Application
Server.
v
IBM
Tivoli
Access
Manager
for
e-business
IBM
WebSphere
Edge
Server
Integration
Guide
(SC32-1367-00)
Provides
installation,
removal,
and
administration
instructions
for
integrating
Tivoli
Access
Manager
with
the
IBM
WebSphere
Edge
Server
application.
v
IBM
Tivoli
Access
Manager
for
e-business
Plug-in
for
Web
Servers
Integration
Guide
(SC32-1365-00)
Provides
installation
instructions,
administration
procedures,
and
technical
reference
information
for
securing
your
Web
domain
using
the
plug-in
for
Web
servers.
v
IBM
Tivoli
Access
Manager
for
e-business
BEA
WebLogic
Server
Integration
Guide
(SC32-1366-00)
Provides
installation,
removal,
and
administration
instructions
for
integrating
Tivoli
Access
Manager
with
BEA
WebLogic
Server.
v
IBM
Tivoli
Access
Manager
for
e-business
IBM
Tivoli
Identity
Manager
Provisioning
Fast
Start
Guide
(SC32-1364-00)
Provides
an
overview
of
the
tasks
related
to
integrating
Tivoli
Access
Manager
and
Tivoli
Identity
Manager
and
explains
how
to
use
and
install
the
Provisioning
Fast
Start
collection.
Developer
references
v
IBM
Tivoli
Access
Manager
for
e-business
Authorization
C
API
Developer
Reference
(SC32-1355-00)
Provides
reference
material
that
describes
how
to
use
the
Tivoli
Access
Manager
authorization
C
API
and
the
Tivoli
Access
Manager
service
plug-in
interface
to
add
Tivoli
Access
Manager
security
to
applications.
v
IBM
Tivoli
Access
Manager
for
e-business
Authorization
Java
Classes
Developer
Reference
(SC32-1350-00)
Provides
reference
information
for
using
the
Java™
language
implementation
of
the
authorization
API
to
enable
an
application
to
use
Tivoli
Access
Manager
security.
v
IBM
Tivoli
Access
Manager
for
e-business
Administration
C
API
Developer
Reference
(SC32-1357-00)
Provides
reference
information
about
using
the
administration
API
to
enable
an
application
to
perform
Tivoli
Access
Manager
administration
tasks.
This
document
describes
the
C
implementation
of
the
administration
API.
v
IBM
Tivoli
Access
Manager
for
e-business
Administration
Java
Classes
Developer
Reference
(SC32-1356-00)
Provides
reference
information
for
using
the
Java
language
implementation
of
the
administration
API
to
enable
an
application
to
perform
Tivoli
Access
Manager
administration
tasks.
v
IBM
Tivoli
Access
Manager
for
e-business
Web
Security
Developer
Reference
(SC32-1358-00)
Provides
administration
and
programming
information
for
the
cross-domain
authentication
service
(CDAS),
the
cross-domain
mapping
framework
(CDMF),
and
the
password
strength
module.
Technical
supplements
v
IBM
Tivoli
Access
Manager
for
e-business
Command
Reference
(SC32-1354-00)
xii
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
Provides
information
about
the
command
line
utilities
and
scripts
provided
with
Tivoli
Access
Manager.
v
IBM
Tivoli
Access
Manager
Error
Message
Reference
(SC32-1353-00)
Provides
explanations
and
recommended
actions
for
the
messages
produced
by
Tivoli
Access
Manager.
v
IBM
Tivoli
Access
Manager
for
e-business
Problem
Determination
Guide
(SC32-1352-00)
Provides
problem
determination
information
for
Tivoli
Access
Manager.
v
IBM
Tivoli
Access
Manager
for
e-business
Performance
Tuning
Guide
(SC32-1351-00)
Provides
performance
tuning
information
for
an
environment
consisting
of
Tivoli
Access
Manager
with
the
IBM
Tivoli
Directory
server
as
the
user
registry.
Related
publications
This
section
lists
publications
related
to
the
Tivoli
Access
Manager
library.
The
Tivoli
Software
Library
provides
a
variety
of
Tivoli
publications
such
as
white
papers,
datasheets,
demonstrations,
redbooks,
and
announcement
letters.
The
Tivoli
Software
Library
is
available
on
the
Web
at:
http://www.ibm.com/software/tivoli/library/
The
Tivoli
Software
Glossary
includes
definitions
for
many
of
the
technical
terms
related
to
Tivoli
software.
The
Tivoli
Software
Glossary
is
available,
in
English
only,
from
the
Glossary
link
on
the
left
side
of
the
Tivoli
Software
Library
Web
page
http://www.ibm.com/software/tivoli/library/
IBM
Global
Security
Kit
Tivoli
Access
Manager
provides
data
encryption
through
the
use
of
the
IBM
Global
Security
Kit
(GSKit)
Version
7.0.
GSKit
is
included
on
the
IBM
Tivoli
Access
Manager
Base
CD
for
your
particular
platform,
as
well
as
on
the
IBM
Tivoli
Access
Manager
Web
Security
CDs,
the
IBM
Tivoli
Access
Manager
Web
Administration
Interfaces
CDs,
and
the
IBM
Tivoli
Access
Manager
Directory
Server
CDs.
The
GSKit
package
provides
the
iKeyman
key
management
utility,
gsk7ikm,
which
is
used
to
create
key
databases,
public-private
key
pairs,
and
certificate
requests.
The
following
document
is
available
on
the
Tivoli
Information
Center
Web
site
in
the
same
section
as
the
IBM
Tivoli
Access
Manager
product
documentation:
v
IBM
Global
Security
Kit
Secure
Sockets
Layer
and
iKeyman
User’s
Guide
(SC32-1363-00)
Provides
information
for
network
or
system
security
administrators
who
plan
to
enable
SSL
communication
in
their
Tivoli
Access
Manager
environment.
IBM
Tivoli
Directory
Server
IBM
Tivoli
Directory
Server,
Version
5.2,
is
included
on
the
IBM
Tivoli
Access
Manager
Directory
Server
CD
for
the
desired
operating
system.
Note:
IBM
Tivoli
Directory
Server
is
the
new
name
for
the
previously
released
software
known
as:
v
IBM
Directory
Server
(Version
4.1
and
Version
5.1)
v
IBM
SecureWay
Directory
Server
(Version
3.2.2)
IBM
Directory
Server
Version
4.1,
IBM
Directory
Server
Version
5.1,
and
IBM
Tivoli
Directory
Server
Version
5.2
are
all
supported
by
IBM
Tivoli
Access
Manager
Version
5.1.
Preface
xiii
Additional
information
about
IBM
Tivoli
Directory
Server
can
be
found
at:
http://www.ibm.com/software/network/directory/library/
IBM
DB2
Universal
Database
IBM
DB2®
Universal
Database™
Enterprise
Server
Edition,
Version
8.1
is
provided
on
the
IBM
Tivoli
Access
Manager
Directory
Server
CD
and
is
installed
with
the
IBM
Tivoli
Directory
Server
software.
DB2
is
required
when
using
IBM
Tivoli
Directory
Server,
z/OS™,
or
OS/390®
LDAP
servers
as
the
user
registry
for
Tivoli
Access
Manager.
Additional
information
about
DB2
can
be
found
at:
http://www.ibm.com/software/data/db2/
IBM
WebSphere
Application
Server
IBM
WebSphere
Application
Server,
Advanced
Single
Server
Edition
5.0,
is
included
on
the
IBM
Tivoli
Access
Manager
Web
Administration
Interfaces
CD
for
the
desired
operating
system.
WebSphere
Application
Server
enables
the
support
of
both
the
Web
Portal
Manager
interface,
which
is
used
to
administer
Tivoli
Access
Manager,
and
the
Web
Administration
Tool,
which
is
used
to
administer
IBM
Tivoli
Directory
Server.
IBM
WebSphere
Application
Server
Fix
Pack
2
is
also
required
by
Tivoli
Access
Manager
and
is
provided
on
the
IBM
Tivoli
Access
Manager
WebSphere
Fix
Pack
CD.
Additional
information
about
IBM
WebSphere
Application
Server
can
be
found
at:
http://www.ibm.com/software/webservers/appserv/infocenter.html
IBM
Tivoli
Access
Manager
for
Business
Integration
IBM
Tivoli
Access
Manager
for
Business
Integration,
available
as
a
separately
orderable
product,
provides
a
security
solution
for
IBM
MQSeries®,
Version
5.2,
and
IBM
WebSphere®
MQ
for
Version
5.3
messages.
IBM
Tivoli
Access
Manager
for
Business
Integration
allows
WebSphere
MQSeries
applications
to
send
data
with
privacy
and
integrity
by
using
keys
associated
with
sending
and
receiving
applications.
Like
WebSEAL
and
IBM
Tivoli
Access
Manager
for
Operating
Systems,
IBM
Tivoli
Access
Manager
for
Business
Integration,
is
one
of
the
resource
managers
that
use
the
services
of
IBM
Tivoli
Access
Manager.
Additional
information
about
IBM
Tivoli
Access
Manager
for
Business
Integration
can
be
found
at:
http://www.ibm.com/software/tivoli/products/access-mgr-bus-integration/
The
following
documents
associated
with
IBM
Tivoli
Access
Manager
for
Business
Integration
Version
5.1
are
available
on
the
Tivoli
Information
Center
Web
site:
v
IBM
Tivoli
Access
Manager
for
Business
Integration
Administration
Guide
(SC23-4831-01)
v
IBM
Tivoli
Access
Manager
for
Business
Integration
Problem
Determination
Guide
(GC23-1328-00)
v
IBM
Tivoli
Access
Manager
for
Business
Integration
Release
Notes
(GI11-0957-01)
v
IBM
Tivoli
Access
Manager
for
Business
Integration
Read
This
First
(GI11-4202-00)
xiv
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
IBM
Tivoli
Access
Manager
for
WebSphere
Business
Integration
Brokers
IBM
Tivoli
Access
Manager
for
WebSphere
Business
Integration
Brokers,
available
as
part
of
IBM
Tivoli
Access
Manager
for
Business
Integration,
provides
a
security
solution
for
WebSphere
Business
Integration
Message
Broker,
Version
5.0
and
WebSphere
Business
Integration
Event
Broker,
Version
5.0.
IBM
Tivoli
Access
Manager
for
WebSphere
Business
Integration
Brokers
operates
in
conjunction
with
Tivoli
Access
Manager
to
secure
JMS
publish/subscribe
applications
by
providing
password
and
credentials-based
authentication,
centrally-defined
authorization,
and
auditing
services.
Additional
information
about
IBM
Tivoli
Access
Manager
for
WebSphere
Integration
Brokers
can
be
found
at:
http://www.ibm.com/software/tivoli/products/access-mgr-bus-integration/
The
following
documents
associated
with
IBM
Tivoli
Access
Manager
for
WebSphere
Integration
Brokers,
Version
5.1
are
available
on
the
Tivoli
Information
Center
Web
site:
v
IBM
Tivoli
Access
Manager
for
WebSphere
Business
Integration
Brokers
Administration
Guide
(SC32-1347-00)
v
IBM
Tivoli
Access
Manager
for
WebSphere
Business
Integration
Brokers
Release
Notes
(GI11-4154-00)
v
IBM
Tivoli
Access
Manager
for
Business
Integration
Read
This
First
(GI11-4202-00)
IBM
Tivoli
Access
Manager
for
Operating
Systems
IBM
Tivoli
Access
Manager
for
Operating
Systems,
available
as
a
separately
orderable
product,
provides
a
layer
of
authorization
policy
enforcement
on
UNIX
systems
in
addition
to
that
provided
by
the
native
operating
system.
IBM
Tivoli
Access
Manager
for
Operating
Systems,
like
WebSEAL
and
IBM
Tivoli
Access
Manager
for
Business
Integration,
is
one
of
the
resource
managers
that
use
the
services
of
IBM
Tivoli
Access
Manager.
Additional
information
about
IBM
Tivoli
Access
Manager
for
Operating
Systems
can
be
found
at:
http://www.ibm.com/software/tivoli/products/access-mgr-operating-sys/
The
following
documents
associated
with
IBM
Tivoli
Access
Manager
for
Operating
Systems
Version
5.1
are
available
on
the
Tivoli
Information
Center
Web
site:
v
IBM
Tivoli
Access
Manager
for
Operating
Systems
Installation
Guide
(SC23-4829-00)
v
IBM
Tivoli
Access
Manager
for
Operating
Systems
Administration
Guide
(SC23-4827-00)
v
IBM
Tivoli
Access
Manager
for
Operating
Systems
Problem
Determination
Guide
(SC23-4828-00)
v
IBM
Tivoli
Access
Manager
for
Operating
Systems
Release
Notes
(GI11-0951-00)
v
IBM
Tivoli
Access
Manager
for
Operating
Systems
Read
Me
First
(GI11-0949-00)
IBM
Tivoli
Identity
Manager
IBM
Tivoli
Identity
Manager
Version
4.5,
available
as
a
separately
orderable
product,
enables
you
to
centrally
manage
users
(such
as
user
IDs
and
passwords)
and
provisioning
(that
is
providing
or
revoking
access
to
applications,
resources,
or
operating
systems.)
Tivoli
Identity
Manager
can
be
integrated
with
Tivoli
Access
Preface
xv
Manager
through
the
use
of
the
Tivoli
Access
Manager
Agent.
Contact
your
IBM
account
representative
for
more
information
about
purchasing
the
Agent.
Additional
information
about
IBM
Tivoli
Identity
Manager
can
be
found
at:
http://www.ibm.com/software/tivoli/products/identity-mgr/
Accessing
publications
online
The
publications
for
this
product
are
available
online
in
Portable
Document
Format
(PDF)
or
Hypertext
Markup
Language
(HTML)
format,
or
both
in
the
Tivoli
software
library:
http://www.ibm.com/software/tivoli/library
To
locate
product
publications
in
the
library,
click
the
Product
manuals
link
on
the
left
side
of
the
library
page.
Then,
locate
and
click
the
name
of
the
product
on
the
Tivoli
software
information
center
page.
Product
publications
include
release
notes,
installation
guides,
user’s
guides,
administrator’s
guides,
and
developer’s
references.
Note:
To
ensure
proper
printing
of
publications,
select
the
Fit
to
page
check
box
in
the
Adobe
Acrobat
window
(which
is
available
when
you
click
File
→
Print).
Accessibility
Accessibility
features
help
a
user
who
has
a
physical
disability,
such
as
restricted
mobility
or
limited
vision,
to
use
software
products
successfully.
With
this
product,
you
can
use
assistive
technologies
to
hear
and
navigate
the
interface.
You
also
can
use
the
keyboard
instead
of
the
mouse
to
operate
all
features
of
the
graphical
user
interface.
Contacting
software
support
Before
contacting
IBM
Tivoli
Software
Support
with
a
problem,
refer
to
the
IBM
Tivoli
Software
Support
site
by
clicking
the
Tivoli
support
link
at
the
following
Web
site:
http://www.ibm.com/software/support/
If
you
need
additional
help,
contact
software
support
by
using
the
methods
described
in
the
IBM
Software
Support
Guide
at
the
following
Web
site:
http://techsupport.services.ibm.com/guides/handbook.html
The
guide
provides
the
following
information:
v
Registration
and
eligibility
requirements
for
receiving
support
v
Telephone
numbers,
depending
on
the
country
in
which
you
are
located
v
A
list
of
information
you
should
gather
before
contacting
customer
support
Conventions
used
in
this
book
This
reference
uses
several
conventions
for
special
terms
and
actions
and
for
operating
system-dependent
commands
and
paths.
Typeface
conventions
The
following
typeface
conventions
are
used
in
this
reference:
xvi
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
Bold
Lowercase
commands
or
mixed
case
commands
that
are
difficult
to
distinguish
from
surrounding
text,
keywords,
parameters,
options,
names
of
Java
classes,
and
objects
are
in
bold.
Italic
Variables,
titles
of
publications,
and
special
words
or
phrases
that
are
emphasized
are
in
italic.
Monospace
Code
examples,
command
lines,
screen
output,
file
and
directory
names
that
are
difficult
to
distinguish
from
surrounding
text,
system
messages,
text
that
the
user
must
type,
and
values
for
arguments
or
command
options
are
in
monospace.
Operating
system
differences
This
book
uses
the
UNIX
convention
for
specifying
environment
variables
and
for
directory
notation.
When
using
the
Windows
command
line,
replace
$variable
with
%variable%
for
environment
variables
and
replace
each
forward
slash
(/)
with
a
backslash
(\)
in
directory
paths.
If
you
are
using
the
bash
shell
on
a
Windows
system,
you
can
use
the
UNIX
conventions.
Preface
xvii
xviii
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
Chapter
1.
Authorization
API
overview
This
chapter
contains
the
following
topics:
v
“Introducing
the
authorization
API”
on
page
2
v
“Locating
the
authorization
API
components”
on
page
5
v
“Building
applications
with
the
authorization
API”
on
page
7
v
“Deploying
applications
with
the
authorization
API”
on
page
9
v
“Summarizing
authorization
API
tasks”
on
page
9
©
Copyright
IBM
Corp.
2000,2003
1
Introducing
the
authorization
API
Using
the
IBM
Tivoli
Access
Manager
(Tivoli
Access
Manager)
authorization
application
programming
interface
(API),
you
can
program
Tivoli
Access
Manager
applications
and
third-party
applications
to
query
the
Tivoli
Access
Manager
authorization
service
for
authorization
decisions.
The
Tivoli
Access
Manager
authorization
API
is
the
interface
between
the
server-based
resource
manager
and
the
authorization
service
and
provides
a
standard
model
for
coding
authorization
requests
and
decisions.
The
authorization
API
lets
you
make
standardized
calls
to
the
centrally
managed
authorization
service
from
any
legacy
or
newly
developed
application.
The
authorization
API
supports
two
implementation
modes:
v
Remote
cache
mode
In
remote
cache
mode,
you
use
the
authorization
API
to
call
the
Tivoli
Access
Manager
authorization
server,
which
performs
authorization
decisions
on
behalf
of
the
application.
The
authorization
server
maintains
its
own
cache
of
the
replica
authorization
policy
database.
v
Local
cache
mode
In
local
cache
mode,
you
use
the
authorization
API
to
download
a
local
replica
of
the
authorization
policy
database.
In
this
mode,
the
application
can
perform
all
authorization
decisions
locally.
The
authorization
API
shields
you
from
the
complexities
of
the
authorization
service
mechanism.
Issues
of
management,
storage,
caching,
replication,
credentials
format,
and
authentication
methods
are
all
hidden
behind
the
authorization
API.
The
authorization
API
works
independently
from
the
underlying
security
infrastructure,
the
credential
format,
and
the
evaluating
mechanism.
The
authorization
API
makes
it
possible
to
request
an
authorization
check
and
get
a
simple
“yes”
or
“no”
recommendation
in
return.
The
authorization
API
is
a
component
of
the
Tivoli
Access
Manager
application
development
kit
(ADK).
The
Open
Group
Authorization
API
standard
The
IBM
Tivoli
Access
Manager
authorization
API
implements
the
Open
Group
Authorization
API
(Generic
Application
Interface
for
Authorization
Frameworks)
standard.
This
interface
is
based
on
the
International
Organization
for
Standardization
(ISO)
10181-3
model
for
authorization.
In
this
model,
an
initiator
requests
access
to
a
target
resource.
The
initiator
submits
the
request
to
a
resource
manager,
which
incorporates
an
access
enforcement
function
(AEF).
The
AEF
submits
the
request,
along
with
information
about
the
initiator,
to
an
access
decision
function
(ADF).
The
ADF
returns
a
decision
to
the
AEF,
and
the
AEF
enforces
the
decision.
2
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
Tivoli
Access
Manager
implements
the
ADF
component
of
this
model
and
provides
the
authorization
API
as
an
interface
to
this
function.
In
the
figure
above,
a
browser
(initiator)
requests
access
to
a
file
or
other
resource
on
a
protected
system
(target).
The
browser
submits
the
request
to
a
Web
application
server
(the
resource
manager
incorporating
the
access
enforcement
function).
The
Web
application
server
uses
the
authorization
API
to
submit
the
request
to
the
Tivoli
Access
Manager
authorization
service
(the
access
decision
function).
The
Tivoli
Access
Manager
authorization
service
returns
an
access
decision,
through
the
authorization
API,
to
the
Web
application
server.
The
Web
application
server
processes
the
request
as
appropriate.
To
implement
this
model,
developers
of
AEF
applications
add
authorization
API
function
calls
to
their
application
code.
Note:
Developers
should
refer
to
the
Open
Group
Authorization
API
document
for
additional
information
on
the
standard
authorization
model.
The
Tivoli
Access
Manager
authorization
model
The
first
step
in
adding
authorization
to
an
application
is
to
define
the
security
policy
requirements
for
your
application.
Defining
a
security
policy
means
that
you
must
determine
the
business
requirements
that
apply
to
the
application’s
users,
operations,
and
data.
These
requirements
include:
Resource
Manager
AEF TargetInitiator
ADF
Submit
Access
Request
Present
Access
Request
Decision
RequestDecision
Figure
1.
The
ISO
10181-3
Authorization
Model
Browser ProtectedData
Access Manager Secure Domain
Initiator
Resource Manager
ADF
Target
Access ManagerAuthorization
Service
Authorization API
Web ApplicationServer
AEF
Figure
2.
The
IBM
Tivoli
Access
Manager
implementation
of
the
ISO
authorization
model
Chapter
1.
Authorization
API
overview
3
v
Objects
to
be
secured
v
Operations
permitted
on
each
object
v
Users
that
are
permitted
to
perform
the
operations
After
your
security
requirements
have
been
defined,
you
can
use
the
authorization
API
to
integrate
your
security
policy
with
the
Tivoli
Access
Manager
security
model.
Complete
the
following
steps
in
order
to
deploy
an
application
into
a
Tivoli
Access
Manager
secure
domain:
1.
Configure
the
Tivoli
Access
Manager
secure
domain
to
recognize
and
support
the
objects,
actions,
and
users
that
are
relevant
to
your
application.
v
For
an
introduction
to
the
Tivoli
Access
Manager
authorization
model,
see
the
IBM
Tivoli
Access
Manager
Base
Administration
Guide.
v
For
complete
information
on
access
control,
see
the
IBM
Tivoli
Access
Manager
Base
Administration
Guide.2.
Use
the
authorization
API
within
your
application
to
obtain
the
needed
authorization
decisions.
v
For
an
introduction
to
the
authorization
API,
including
information
on
remote
cache
mode
and
local
cache
mode,
see
the
IBM
Tivoli
Access
Manager
Base
Administration
Guide.3.
Develop
your
application
logic
to
enforce
the
security
policy.
4
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
Locating
the
authorization
API
components
The
authorization
API
is
included
in
an
optional
installation
package
(ADK)
in
the
Tivoli
Access
Manager
distribution.
The
authorization
API
files
are
installed
in
several
sub-directories
under
the
Tivoli
Access
Manager
installation
directory.
Directory
Contents
bin
On
Microsoft
Windows
systems,
the
library
to
include
at
run
time
is
pdauthzn.dll
include
C
header
files
lib
A
library
that
implements
the
API
functions.
The
name
of
the
library
is
platform
dependent:
Solaris
Operating
Environment
libpdauthzn.so
AIX
libpdauthzn.a
HP-UX
libpdauthzn.sl
Microsoft
Windows
pdauthzn.lib
example/authzn_demo/cpp
This
directory
contains
an
example
program
that
demonstrates
usage
of
the
authorization
API.
Source
files
and
a
MAKEFILE
are
provided.
For
installation
instructions
for
the
ADK,
see
the
IBM
Tivoli
Access
Manager
Base
Installation
Guide.
v
Header
Files
The
header
files
are
found
in
the
include
directory,
located
directly
under
the
Tivoli
Access
Manager
ADK
package
installation
directory.
File
Contents
ogauthzn.h
The
authorization
API
standard
functions
aznutils.h
Utility
functions
(extensions
to
the
authorization
API)
azn_svc_protos.h
Prototypes
for
generic
authorization
service
plug-in
functions.
Contains
prototypes
for
the
azn_service_initialize()
and
azn_service_shutdown()
calls.
This
can
optionally
be
included
by
a
plug-in
programmer
to
prototype
the
calls
defined
in
the
service.
azn_admin_svc_protos.h
Prototypes
for
plug-in
functions
for
the
authorization
administration
service.
azn_deprecated.h
Prototypes
and
declarations
for
the
functions,
variables
and
attributes
that
are
deprecated
in
this
version
of
Tivoli
Access
Manager.
Programmers
should
avoid
including
this
header
file
as
the
symbols
that
are
contained
there
will
not
be
supported
in
future
releases
of
the
product.
ivadminapi.h
Function
prototypes
for
the
Tivoli
Access
Manager
administration
API.
This
API
is
described
in
IBM
Tivoli
Access
Manager
for
e-business
Administration
C
API
Developer
Reference.
pdb*msg.h
Minor
error
codes.
v
Error
Codes
Chapter
1.
Authorization
API
overview
5
The
authorization
API
error
codes
are
defined
in
the
following
files,
located
in
the
include
directory:
File
Contents
ogauthzn.h
Major
error
codes
for
the
standard
authorization
API
functions.
aznutils.h
Major
error
codes
for
the
authorization
API
utility
functions.
pdb*msg.h
Minor
error
codes
for
utility
functions
and
the
Tivoli
Access
Manager
authorization
service
are
found
in
a
number
of
error
message
files,
such
as
pdbaclmsg.h
6
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
Building
applications
with
the
authorization
API
To
develop
applications
that
use
the
Tivoli
Access
Manager
authorization
API,
you
must
install
and
configure
a
IBM
Tivoli
Access
Manager
secure
domain.
If
you
do
not
have
a
Tivoli
Access
Manager
secure
domain
installed,
install
one
before
beginning
application
development.
The
minimum
installation
consists
of
a
single
system
with
the
following
Tivoli
Access
Manager
Base
components
installed:
v
Tivoli
Access
Manager
runtime
environment
v
Tivoli
Access
Manager
policy
server
v
Tivoli
Access
Manager
application
development
kit
When
the
Tivoli
Access
Manager
secure
domain
uses
an
LDAP
or
Lotus
Domino
server
user
registry,
the
application
development
system
must
have
an
LDAP
client
installed.
If
you
already
have
a
Tivoli
Access
Manager
secure
domain
installed,
and
want
to
add
a
development
system
to
the
domain,
the
minimum
Tivoli
Access
Manager
installation
consists
of
the
following
components:
v
Tivoli
Access
Manager
runtime
environment
v
Tivoli
Access
Manager
application
development
kit
Note:
For
Tivoli
Access
Manager
installation
instructions
refer
to
the
IBM
Tivoli
Access
Manager
Base
Installation
Guide.
In
order
to
compile
applications
that
use
the
authorization
API,
you
must
install
the
Tivoli
Access
Manager
ADK
on
the
build
machine.
When
compiling
your
application,
make
sure
you
add
the
include
directory
for
the
Tivoli
Access
Manager
ADK
to
the
compiler
command
line.
When
linking
your
application,
specify
the
directory
containing
the
authorization
shared
library
if
it
is
not
in
the
default
location.
Note:
The
Tivoli
Access
Manager
authorization
API
is
compiled
as
a
32-bit
application.
Tested
compilers
IBM
has
tested
the
use
of
the
IBM
Tivoli
Access
Manager
Application
Developer
Kit
(ADK)
component
with
the
compilers
listed
in
the
table
below.
Previous
versions
of
the
compilers
are
not
supported.
Compilers
on
other
supported
platforms,
such
as
IBM
AIX
5.1
or
HP-UX
11i,
have
not
been
tested.
Table
1.
Compilers
tested
with
Tivoli
Access
Manager.
Operating
system
platform
tested
Tested
compiler
IBM
AIX
4.3.3
x1C.3.6.7
Sun
Solaris
Operating
Environment
7
Forte
6.1
Hewlett-Packard
HP-UX
11.0
aCC
3.30a
Red
Hat
Linux
for
Intel
GNU
GCC
2.95.3
(see
note)
SuSe
Linux
Enterprise
Server
for
S/390
and
zSeries
GNU
GCC
2.95.3
(see
note)
Chapter
1.
Authorization
API
overview
7
Table
1.
Compilers
tested
with
Tivoli
Access
Manager.
(continued)
Microsoft
Windows
2000
Advanced
Server
Microsoft
Windows
NT
4.0
MSVC
6.0.5
Note:
The
GNU
GCC
compiler
listed
is
the
only
one
supported
on
Linux
systems.
The
GNU
GCC
compiler
is
not
supported
on
non-Linux
operating
systems.
Demonstration
programs
The
Tivoli
Access
Manager
authorization
API
is
provided
with
several
example
programs.
The
authzn_demo
directory
contains
examples
programs
that
demonstrate
use
of
the
authorization
API.
A
C
language
example
is
included.
The
C
example
contains
a
sample
Makefile.
See
the
sample
Makefile
for
build
instructions
specific
to
each
supported
operating
system
platform.
Refer
to
the
README
file,
located
in
the
same
directory,
for
information
regarding
the
use
of
this
example
program.
An
example
of
the
administration
service
plug-in
is
provided
in
the
admin_svc_demo
directory.
See
the
sample
Makefile
for
build
instructions.
An
example
of
an
external
authorization
service
plug-in
is
provided
in
the
eas_demo
directory.
See
the
sample
Makefile
for
build
instructions.
An
example
of
an
entitlement
service
plug-in
is
provided
in
the
ent_svc_demo
directory.
See
the
sample
Makefile
for
build
instructions.
Program
Description
authzn_demo
Authorization
API
demonstration
program
azn_admin_svc_demo
Administration
service
demonstration
program
azn_eas_demo
External
authorization
service
demonstration
program
azn_ent_svc_demo
Entitlement
service
demonstration
program
8
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
Deploying
applications
with
the
authorization
API
To
deploy
an
application
with
the
authorization
API,
verify
that
your
environment
contains
the
necessary
supporting
software.
You
can
test
your
environment
by
building
and
running
the
example
program
that
is
provided
with
the
authorization
API.
Applications
that
have
been
developed
with
the
Tivoli
Access
Manager
authorization
API
must
be
run
on
systems
that
are
configured
into
a
Tivoli
Access
Manager
secure
domain.
When
the
Tivoli
Access
Manager
secure
domain
uses
an
LDAP
user
registry,
the
application
deployment
system
must
have
an
LDAP
client
installed.
The
minimum
Tivoli
Access
Manager
installation
required
on
a
system
that
will
run
an
application
is
the
Tivoli
Access
Manager
runtime
environment
component.
For
deployment
examples,
see
the
demonstration
programs
described
in
“Demonstration
programs”
on
page
8.
Summarizing
authorization
API
tasks
The
primary
task
of
the
authorization
API
is
to
obtain
an
authorization
decision
from
the
Tivoli
Access
Manager
authorization
service.
Use
the
authorization
API
to
present
information
about
the
user,
operation,
and
requested
resource
to
the
Tivoli
Access
Manager
authorization
service,
and
receive
the
authorization
decision.
Your
application
is
responsible
for
enforcing
the
decision,
as
appropriate.
To
obtain
an
authorization
decision,
you
must
accomplish
certain
tasks
to
configure
the
authorization
API
client.
The
following
sections
in
this
document
provide
a
step-by-step
guide
to
completing
each
of
these
required
tasks:
v
Chapter
3,
“Initializing
the
authorization
API,”
on
page
23
v
“Authenticating
an
API
application”
on
page
54
v
“Verifying
the
identity
of
a
user”
on
page
55
v
“Obtaining
user
authorization
credentials”
on
page
56
v
“Obtaining
an
authorization
decision”
on
page
59
v
“Cleaning
up
and
shutting
down”
on
page
62
The
authorization
API
also
provides
functions
for
performing
optional
tasks
on
user
credentials.
The
following
section
describes
the
supported
optional
tasks:
v
“Working
with
credentials”
on
page
63
Chapter
1.
Authorization
API
overview
9
10
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
Chapter
2.
Authorization
API
functions
and
data
types
The
IBM
Tivoli
Access
Manager
(Tivoli
Access
Manager)
authorization
API
provides
a
set
of
functions
and
data
types.
This
section
lists
the
name
of
each
authorization
API
construct
and
the
task
it
accomplishes.
The
following
functions,
structured
data
types,
and
constants
are
defined
as
part
of
the
authorization
API:
v
“API
functions”
on
page
12
v
“Character
strings”
on
page
14
v
“Buffers”
on
page
14
v
“Protected
object
structures”
on
page
15
v
“Default
user
registry
information
structure”
on
page
16
v
“Attribute
lists”
on
page
18
v
“Credential
handles”
on
page
20
v
“Status
codes
and
error
handling”
on
page
21
©
Copyright
IBM
Corp.
2000,2003
11
API
functions
The
following
tables
list
the
authorization
API
functions
and
provide
both
a
link
to
the
reference
page
for
the
function
and
a
link
to
the
section
in
this
document
that
describes
each
function’s
task.
Note:
The
Tivoli
Access
Manager
authorization
API
functions
are
32-bit
only.
Attribute
lists
Function
Task
“azn_attrlist_add_entry()”
on
page
153
“azn_attrlist_add_entry_buffer()”
on
page
154
“azn_attrlist_add_entry_pobj()”
on
page
155
“azn_attrlist_add_entry_ulong()”
on
page
156
“azn_attrlist_create()”
on
page
158
“azn_attrlist_copy()”
on
page
157
“azn_attrlist_delete()”
on
page
159
“azn_attrlist_delete_entry()”
on
page
160
“azn_attrlist_delete_entry_value()”
on
page
161
“azn_attrlist_get_entry_buffer_value()”
on
page
162
“azn_attrlist_get_entry_type()”
on
page
167
“azn_attrlist_get_entry_ulong_value()”
on
page
169
“azn_attrlist_get_entry_pobj_value()”
on
page
164
“azn_attrlist_get_entry_string_value()”
on
page
165
“azn_attrlist_get_names()”
on
page
170
“azn_attrlist_name_get_num()”
on
page
171
“azn_release_buffer()”
on
page
212
“azn_release_pobj()”
on
page
213
“azn_release_string()”
on
page
214
“azn_release_strings()”
on
page
215
“azn_util_handle_is_valid()”
on
page
218
“Attribute
lists”
on
page
12
Credentials
Function
Task
“azn_creds_combine()”
on
page
172
“Creating
a
chain
of
credentials”
on
page
63
“azn_creds_copy()”
on
page
174
“Copying
a
credential”
on
page
67
“azn_creds_create()”
on
page
175
“Obtaining
user
authorization
credentials”
on
page
56
“azn_creds_delete()”
on
page
176
“Releasing
allocated
memory”
on
page
62
“azn_creds_equal()”
on
page
177
“Comparing
two
credentials”
on
page
67
“azn_creds_for_subject()”
on
page
178
“Obtaining
a
credential
from
a
chain
of
credentials”
on
page
64
“azn_creds_get_attrlist_for_subject()”
on
page
181
“Obtaining
an
attribute
list
from
a
credential”
on
page
65
“azn_creds_set_attr_value_string()”
on
page
190
“Setting
and
getting
string
attribute
values
for
a
credential”
on
page
66
“azn_creds_get_attr_value_string()”
on
page
180
“azn_creds_get_pac()”
on
page
183
“Converting
credentials
to
a
transportable
format”
on
page
63
12
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
Function
Task
“azn_creds_modify()”
on
page
185
“Modifying
the
contents
of
a
credential”
on
page
64
“azn_creds_num_of_subjects()”
on
page
188
“Determining
the
number
of
credentials
in
a
credentials
chain”
on
page
64
“azn_id_get_creds()”
on
page
203
“Obtaining
user
authorization
credentials”
on
page
56
“azn_pac_get_creds()”
on
page
210
“Converting
credentials
to
the
native
format”
on
page
63
“azn_util_handle_is_valid()”
on
page
218
“Credential
handles”
on
page
20
Authorization
decisions
Function
Task
“azn_decision_access_allowed()”
on
page
192
“azn_decision_access_allowed_ext()”
on
page
194
“Obtaining
an
authorization
decision”
on
page
59
Initialization,
shutdown,
and
error
handling
Function
Task
“azn_error_major()”
on
page
200
“Status
codes
and
error
handling”
on
page
21
“azn_error_minor()”
on
page
201
“azn_error_minor_get_string()”
on
page
202
“azn_error_get_string()”
on
page
199
“azn_initialize()”
on
page
207
Chapter
3,
“Initializing
the
authorization
API,”
on
page
23
“azn_release_buffer()”
on
page
212
“Releasing
allocated
memory”
on
page
62
“azn_release_pobj()”
on
page
213
“azn_release_string()”
on
page
214
“azn_release_strings()”
on
page
215
“azn_shutdown()”
on
page
216
“Shutting
down
the
authorization
API”
on
page
62
“azn_util_errcode()”
on
page
217
“Status
codes
and
error
handling”
on
page
21
“azn_init_set_code_set()”
on
page
206
Chapter
2.
Authorization
API
functions
and
data
types
13
API
extensions
Function
or
Data
Type
Task
“azn_util_errcode()”
on
page
217
“Status
codes
and
error
handling”
on
page
21
“azn_util_handle_is_valid()”
on
page
218
“Attribute
lists”
on
page
18
“Credential
handles”
on
page
20
“azn_util_password_authenticate()”
on
page
219
“Verifying
the
identity
of
a
user”
on
page
55
“azn_util_password_change()”
on
page
221
Character
strings
Many
authorization
API
functions
take
character
strings
as
arguments
or
return
character
strings
as
values.
Use
the
azn_string_t
data
type
to
pass
character
string
data
between
your
application
and
the
authorization
API:
typedef
char
*azn_string_t;
Use
azn_release_string()
and
azn_release_strings()
to
release
memory
that
has
been
allocated
to
strings
of
type
azn_string_t.
Buffers
Some
authorization
API
functions
take
byte
string
arguments
and
return
byte
strings
as
values.
Use
the
data
type
azn_buffer_t
to
pass
byte
string
data
between
your
application
and
the
authorization
API.
The
azn_buffer_t
data
type
is
a
pointer
to
a
buffer
descriptor
consisting
of
a
length
field
and
a
value
field.
The
length
field
contains
the
total
number
of
bytes
in
the
data.
The
value
field
contains
a
pointer
to
the
data.
typedef
struct
azn_buffer_desc_struct
{
size_t
length;
unsigned
char
*value;
}
azn_buffer_desc,
*azn_buffer_t;
You
must
allocate
and
release
the
storage
necessary
for
all
azn_buffer_desc
objects.
Objects
of
type
azn_buffer_t
appear
as
output
parameters
to
the
azn_attrlist_get_entry_buffer_value()
and
azn_creds_get_pac()
calls.
For
these
functions,
storage
for
the
buffer
array
referred
to
by
the
value
member
of
an
azn_buffer_desc
object
is
allocated
by
the
authorization
API.
Use
azn_release_buffer()
to
release
storage
allocated
for
use
by
azn_buffer_desc
objects.
Parameters
of
type
azn_buffer_t
can
be
assigned
and
compared
with
the
following
constant
values:
Name
Value
Definition
AZN_C_EMPTY_BUFFER
NULL
Empty
data
value-buffer.
AZN_C_NO_BUFFER
NULL
No
value-buffer
is
supplied
or
returned.
14
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
Protected
object
structures
This
data
structure
is
available
for
applications
that
want
to
track
information
about
protected
objects.
typedef
struct
azn_pobj_desc_struct
(
azn_string_t
name;
unsigned
int
type;
azn_string_t
description;
azn_boolean_t
is_policy_attachable;
)
azn_pobj_desc,
*azn_pobj_t
The
variables
in
the
structure
above
contain
the
following
information:
Variable
Description
name
A
string
containing
the
protected
object
path.
type
The
protected
object
type,
expressed
as
an
unsigned
int.
This
can
be
defined
by
the
application
developer.
description
A
string
description
of
the
protected
object.
is_policy_attachable
A
boolean
value
that
indicates
whether
authorization
policy
can
be
attached
to
this
object.
Chapter
2.
Authorization
API
functions
and
data
types
15
Default
user
registry
information
structure
The
authorization
API
uses
this
structure
to
pass
information
for
building
Tivoli
Access
Manager
credentials
to
the
azn_id_get_creds()
call.
When
this
structure
is
used
in
conjunction
with
a
NULL
mechanism
ID
in
a
function
call
to
azn_id_get_creds(),
the
client
credential
is
built
from
information
stored
in
the
default
user
registry.
It
will
use
the
registry
option
that
was
selected
when
the
Tivoli
Access
Manager
secure
domain
was
installed.
The
client
does
not
need
to
know
the
registry
type.
This
structure
replaces
the
deprecated
structures
azn_authdce_t,
azn_authldap_t,
and
azn_authuraf_t.
typedef
struct
{
azn_string_t
principal;
azn_string_t
auth_method;
unsigned
int
ipaddr;
azn_string_t
qop;
azn_string_t
user_info;
azn_string_t
browser_info;
azn_string_t
authmech_info;
void
*reserved[9];
}
azn_authdefault_t;
Field
Description
principal
The
client’s
principal
name
in
the
registry.
This
value
is
mandatory.
Example:
sec_master
auth_method
The
user
registry
used
to
authenticate
this
user
credential.
This
string
is
optional.
This
field
is
deprecated
and
should
be
set
to
NULL.
ipaddr
A
network
order
unsigned
long
IP
address.
For
example:
0x56780012
This
value
is
mandatory
for
IP
authorization.
Otherwise,
it
is
optional.
qop
Quality
of
protection
required
for
requests
made
by
this
user.
Supplied
for
use
by
applications
to
keep
track
of
the
user’s
current
level
of
protection.
This
value
is
optional.
Note:
This
entry
is
not
used
by
the
authorization
engine
for
the
purpose
of
returning
the
Quality
of
Protection
required
for
access
to
an
object.
Examples:
none
integrity
privacy
user_info
Additional
user
information
that
may
be
required
for
auditing.
Supplied
for
use
by
the
application
to
keep
track
of
any
additional
user
information
it
may
need.
This
value
is
optional.
browser_info
The
browser
employed
by
the
user.
Supplied
for
use
by
web
applications.
This
value
is
optional.
16
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
Field
Description
authnmech_info
Additional
authentication
mechanism
information.
Supplied
for
use
by
the
application
to
keep
track
of
any
additional
information
on
the
method
of
authentication
used
for
the
user.
Example:
X.509
certificate
This
value
is
optional.
reserved
Fields
reserved
for
future
use.
Unauthenticated
user
information
structure
This
data
structure
contains
information
for
use
in
building
an
unauthenticated
authorization
credential
for
a
user
within
the
Tivoli
Access
Manager
secure
domain.
This
data
structure
is
used
to
pass
information
about
an
unauthenticated
user
into
the
azn_id_get_creds()
interface.
The
content
of
each
element
of
this
structure
is
determined
by
the
application,
based
on
application
requirements.
typedef
struct
{
unsigned
int
ipaddr;
azn_string_t
qop;
azn_string_t
user_info;
azn_string_t
browser_info;
}
azn_unauth_t;
Field
Description
ipaddr
IP
address
of
the
requesting
user
in
network
byte
order.
qop
Quality
of
protection
required
for
requests
made
by
this
user.
user_info
Additional
user
information
that
may
be
required
for
auditing.
browser_info
The
browser
employed
by
the
user.
This
field
is
optional.
Chapter
2.
Authorization
API
functions
and
data
types
17
Attribute
lists
Several
authorization
API
functions
take
attribute
list
handles
as
input
parameters
or
return
attribute
list
handles
as
output
parameters.
Use
the
azn_attrlist_h_t
data
type
to
pass
attribute
list
handles
between
the
authorization
API
and
the
calling
application.
Variables
of
type
azn_attrlist_h_t
are
opaque
handles
to
lists
of
name
and
value
pairs.
Use
authorization
API
functions
to
add
or
retrieve
name
and
value
pairs
from
attribute
lists.
CAUTION:
Always
initialize
attribute
list
handles
to
AZN_C_INVALID_HANDLE
when
declaring
them
on
the
stack.
If
an
application
attempts
to
access
an
uninitialized
attribute
list
handle,
the
access
request
may
result
in
memory
corruption
or
undefined
behavior.
Many
authorization
API
functions
use
attribute
lists
to
store
and
retrieve
values.
Attribute
lists
are
lists
of
name
and
value
pairs.
The
values
can
be
stored
as
either
strings
or
buffers.
A
name
can
have
more
than
one
value.
The
values
under
each
attribute
name
are
stored
in
the
order
in
which
they
were
inserted
into
the
list.
Each
value
entry
can
be
retrieved
using
the
azn_attrlist_get_entry_*()
functions
with
an
index
number
starting
at
0
for
the
first
value
in
the
list.
There
is
no
checking
performed
upon
values
in
the
list
so
duplicate
values
are
permitted.
The
authorization
API
defines
some
names.
You
can
also
define
additional
names
as
needed
by
your
application.
The
authorization
API
provides
functions
to
create
attribute
lists,
set
or
get
list
entries,
and
delete
attribute
lists.
The
following
table
summarizes
the
functions
that
operate
on
attribute
lists:
Task
Description
Create
an
attribute
list
Use
azn_attrlist_create()
to
complete
the
following
tasks:
v
Allocate
a
new,
empty
attribute
list.
v
Associate
a
handle
with
the
attribute
list.
v
Return
the
handle.
Set
an
entry
in
an
attribute
list
Use
azn_attrlist_add_entry()
to
add
a
string
name-value
pair
of
type
azn_string_t.
Use
azn_attrlist_add_entry_buffer()
to
add
a
buffer
name-value
pair
of
type
azn_buffer_t.
Use
azn_attrlist_add_entry_ulong()
to
add
a
name-value
pair
of
type
azn_ulong_t.
Use
azn_attrlist_add_entry_pobj()
to
add
a
name-value
pair
of
type
azn_pobj_t.
Delete
an
entry
from
an
attribute
list.
Use
azn_attrlist_delete_entry()
to
delete
all
the
values
that
are
assigned
to
an
attribute
in
an
attribute
list.
Delete
a
value
from
an
entry
in
an
attribute
list.
Use
azn_attrlist_delete_entry_value()
to
delete
a
specified
values
from
the
array
of
values
that
are
assigned
to
an
attribute
in
an
attribute
list.
18
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
Task
Description
Get
the
type
of
a
specified
value
for
a
specified
entry
in
the
attribute
list
Use
azn_attrlist_get_entry_type()
to
get
the
type
for
the
specified
value
for
the
specified
entry
in
the
attribute
list.
Get
attribute
names
from
an
attribute
list
Use
azn_attrlist_get_names()
to
get
all
the
names
in
an
attribute
list.
The
names
are
returned
in
a
NULL-terminated
array
of
strings
of
type
azn_string_t.
Get
the
number
of
values
for
a
specified
attribute
name
Use
azn_attrlist_name_get_num()
to
get
the
number,
as
an
integer,
of
the
value
attributes
for
a
specified
name
in
the
attribute
list.
Copy
an
attribute
list.
Use
azn_attrlist_copy()
to
make
a
copy
of
an
attribute
list.
Get
a
value
Use
azn_attrlist_get_entry_string_value()
to
get
the
value
attribute
of
a
string
of
type
azn_string_t
for
a
specified
name
in
an
attribute
list.
Use
azn_attrlist_get_entry_buffer_value()
to
get
the
value
attribute
of
a
buffer
of
type
azn_buffer_t
for
a
specified
name
in
an
attribute
list.
Use
azn_attrlist_get_entry_ulong_value()
to
get
the
value
attribute
of
type
azn_ulong_t.
Use
azn_attrlist_get_entry_pobj_value()
to
get
the
value
attribute
of
type
azn_pobj_t.
For
each
of
the
functions
described
above,
the
specified
attribute
list
entry
can
have
multiple
values.
For
a
multi-valued
attribute,
specify
an
index
to
get
that
instance
of
the
value.
For
a
single-valued
attribute,
the
index
should
be
set
to
0.
Delete
an
attribute
list
Use
azn_attrlist_delete()
to
delete
the
attribute
list
associated
with
a
specified
attribute
list
handle.
Determine
if
the
attribute
list
handle
is
valid
Use
azn_util_handle_is_valid()
to
determine
if
an
attribute
list
handle
is
associated
with
valid
data.
Chapter
2.
Authorization
API
functions
and
data
types
19
Credential
handles
A
credential
handle
refers
to
a
credentials
chain
consisting
of
the
credentials
of
the
initiator
and
a
series
of
(zero
or
more)
intermediaries
through
which
the
initiator’s
request
has
passed.
By
default,
the
credentials
generated
by
the
azn_id_get_creds()
interface
and
Tivoli
Access
Manager
components
contain
only
a
single
Tivoli
Access
Manager
credential.
The
intermediary
credentials
are
not
referenced
by
Tivoli
Access
Manager
when
making
an
authorization
decision.
Only
the
primary
credential,
referred
to
as
the
“initiator”
is
used
in
authorization
decisions.
Chains
can
be
used
for
customer
API
applications
but
an
External
authorization
service
would
need
to
be
developed
to
authorize
the
remaining
credentials
in
a
chain.
Several
authorization
API
functions
take
credentials
handles
as
input
parameters
or
return
pointers
to
credential
handles
as
output
parameters.
Use
the
azn_creds_h_t
data
type
to
pass
credential
handles
between
the
authorization
API
and
the
calling
application.
Variables
of
type
azn_creds_h_t
are
opaque
handles
to
credential
structures
that
are
internal
to
the
Tivoli
Access
Manager
security
framework.
CAUTION:
Always
initialize
credential
handles
to
AZN_C_INVALID_HANDLE
when
declaring
them
on
the
stack.
If
an
application
attempts
to
access
an
uninitialized
credential
handle,
the
access
request
may
result
in
memory
corruption
or
undefined
behavior.
Use
the
function
azn_creds_create()
to
complete
the
following
tasks:
v
Allocate
a
new,
empty
credential
structure.
v
Associate
a
handle
with
the
credential
structure.
v
Return
a
pointer
to
the
handle.
Call
the
function
azn_creds_delete()
on
the
handle
to
release
the
memory
allocated
for
the
credential
structure.
To
determine
if
a
credentials
handle
is
valid,
use
the
authorization
API
utility
function
azn_util_handle_is_valid().
For
more
information
on
functions
that
use
credentials
handles
to
access
credential
information,
see
“Working
with
credentials”
on
page
63.
20
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
Status
codes
and
error
handling
Authorization
API
functions
return
a
status
code
of
type
azn_status_t.
The
values
in
azn_status_t
are
integers.
The
return
value
for
successful
completion
of
a
function
is
AZN_S_COMPLETE,
which
is
defined
to
be
0.
The
returned
status
code
includes
both
major
and
minor
error
codes.
A
major
error
code
of
AZN_S_FAILURE
indicates
that
a
minor
error
code
contains
the
error
status.
Use
azn_error_major()
to
extract
major
error
codes
from
the
returned
status.
Major
error
codes
are
defined
according
to
The
Open
Group
authorization
API
Standard.
Use
azn_error_minor()
to
extract
minor
error
codes
from
the
returned
status.
The
minor
codes
contain
error
messages
from
the
utility
function
extensions
to
the
API,
and
contain
error
messages
from
the
Tivoli
Access
Manager
authorization
server.
Use
azn_error_minor_get_string()
to
obtain
string
values
for
the
minor
error
codes
returned
by
azn_error_minor().
Use
azn_error_get_string()
to
return
the
Tivoli
Access
Manager
serviceability
message
string
from
a
authorization
API
status
structure
of
type
azn_status_t.
This
function
will
automatically
select
the
major
or
minor
code
and
map
the
error
value
to
an
error
message
string.
Use
azn_util_errcode()
to
build
an
azn_status_t
error
code
from
a
major
and
minor
status.
Use
this
to
return
standardized
error
codes
to
authorization
API
applications
when
developing
authorization
service
plug-ins.
See
the
following
files
for
a
complete
list
of
error
codes:
File
Contents
ogauthzn.h
Major
error
codes
for
the
standard
authorization
API
functions.
aznutils.h
Major
error
codes
for
the
authorization
API
utility
functions.
pdb*msg.h
Minor
error
codes
for
utility
functions
and
the
Tivoli
Access
Manager
authorization
service
are
found
in
a
number
of
files.
The
filenames
for
these
files
all
share
the
prefix
pdb
and
the
suffix
msg.h
Chapter
2.
Authorization
API
functions
and
data
types
21
22
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
Chapter
3.
Initializing
the
authorization
API
To
use
the
IBM
Tivoli
Access
Manager
(Tivoli
Access
Manager)
authorization
API,
an
application
must
initialize
the
API.
Initialization
consists
of
specifying
initialization
data
and
calling
an
initialization
function.
There
are
two
ways
to
specify
the
initialization
data:
v
Specify
input
arguments
to
azn_initialize()
v
Specify
entries
in
the
authorization
API
configuration
file
The
authorization
API
initialization
function
azn_initialize()
takes
as
an
input
parameter
an
attribute
list
named
init_data.
To
specify
initialization
data,
you
must
add
the
necessary
attributes
to
init_data.
Each
input
argument
to
azn_initialize()
has
a
corresponding
entry
in
the
authorization
API
configuration
file.
Input
arguments
take
precedence
over
configuration
file
entries.
You
can
define
entries
in
the
configuration
file,
and
then
use
input
parameters
to
azn_initialize()
to
override
them
as
needed
when
each
authorization
API
application
initializes.
In
order
to
use
a
configuration
file,
specify
the
configuration
file
location
as
an
input
parameter
to
azn_initialize().
Complete
the
instructions
in
the
following
sections:
v
“Specifying
UTF-8
or
local
codeset”
on
page
24
v
“Specifying
an
authorization
API
configuration
file”
on
page
25
v
“Specifying
cache
mode
settings”
on
page
26
v
“Configuring
SSL
from
the
API
client
to
Tivoli
Access
Manager”
on
page
30
v
“Specifying
communications
attributes
for
the
policy
server”
on
page
35
v
“Specifying
values
for
an
authorization
server
replica”
on
page
36
v
“Configuring
the
authorization
API
for
LDAP
access”
on
page
37
v
“URAF
registry
settings”
on
page
42
v
“Authorization
rules
initialization”
on
page
44
v
“Enabling
the
return
of
permission
information”
on
page
47
v
“Configuring
event
logging
and
legacy
auditing”
on
page
49
v
“Specifying
the
host
interface
on
which
to
listen”
on
page
50
v
“Starting
the
authorization
service”
on
page
51
©
Copyright
IBM
Corp.
2000,2003
23
Specifying
UTF-8
or
local
codeset
Tivoli
Access
Manager
Version
5.1
uses
UTF-8
strings
for
all
of
its
internal
processing
of
data.
When
applications
send
data
in
the
forms
of
strings
in
the
local
codeset,
the
data
must
be
converted
to
UTF-8.
Tivoli
Access
Manager
assumes
by
default
that
clients
run
using
the
local
codeset.
To
override,
this
assumption,
you
can
call
the
azn_init_set_code_set()
function.
This
function
tells
the
codeset
in
which
the
client
is
running.
The
only
valid
alternative
to
local
is
UTF-8.
To
perform
the
appropriate
conversions
to
and
from
the
calling
application’s
codeset,
the
authorization
API
runtime
needs
to
be
configured
(initialized)
with
the
caller’s
codeset.
When
the
codeset
is
not
explicitly
specified,
the
runtime
assumes
that
the
caller
is
using
a
local
codeset.
When
the
calling
application
wants
to
use
UTF-8
codeset,
the
function
azn_init_set_code_set()
must
be
called.
This
function
takes
one
input
parameter,
codeset.
The
following
table
lists
the
valid
values
for
this
parameter:
Attribute
name
Description
azn_code_set_utf8
Use
UTF-8
codeset
azn_code_set_local
Use
local
codeset
Authorization
service
plug-ins
automatically
inherit
the
codeset
of
the
application
because
they
are
loaded
into
the
address
space
of
the
authorization
client
application.
The
service
plug-ins
cannot
run
in
a
different
codeset
to
the
application
that
is
loading
them.
Authorization
services
can
determine
the
codeset
of
the
calling
application
from
the
value
of
the
azn_svc_init_code_set
initialization
attribute.
This
attribute
is
passed
to
the
service
plug-in
by
the
service
dispatcher
at
initialization
time.
The
service
plug-in
receives
this
attribute
in
the
svcInit
attribute
list
passed
to
its
azn_svc_initialize()
interface.
Backward
compatibility
The
authorization
API
runs
by
default
expecting
data
to
be
delivered
in
local
codeset.
This
enables
backwards
compatibility
with
applications
written
to
operate
with
previous
versions
of
Tivoli
Access
Manager.
To
retain
backwards
compatibility,
do
not
call
azn_init_set_code_set().
Authorization
services
from
versions
of
Tivoli
Access
Manager
prior
to
Version
5.1
are
not
UTF-8
codeset
aware
and
operate
exclusively
in
the
ASCII
codeset.
These
service
plug-ins
can
be
used
with
AM
5.1
authorization
applications
that
use
the
ASCII
codeset.
However,
these
plug-ins
must
be
made
UTF-8
aware
before
they
can
be
used
with
applications
that
run
on
the
Access
Manager
5.1
authorization
runtime
and
use
either
the
UTF-8
codeset
or
a
local
codeset
other
than
ASCII.
Note
that
the
IBM
Tivoli
Access
Manager
for
e-business
Version
5.1
WebSEAL
application
uses
the
UTF-8
codeset.
24
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
Specifying
an
authorization
API
configuration
file
You
can
specify
a
configuration
file
that
contains
initialization
values.
The
configuration
file
is
a
text
file
consisting
of
stanzas.
Each
stanza
contains
a
series
of
name
=
value
pairs.
Each
of
the
pairs
corresponds
to
an
input
parameter
that
can
get
passed
to
azn_initialize().
If
no
configuration
file
is
specified,
azn_initialize()
obtains
initialization
parameters
only
from
the
attribute
list
contained
in
the
init_data
input
parameter.
There
is
no
configuration
file
specified
by
default.
Specify
a
configuration
file
by
using
the
azn_init_cfg_file
attribute.
To
specify
the
location
of
a
configuration
file:
1.
Call
azn_attrlist_create()
to
create
a
new
attribute
list
called
init_data.
This
function
returns
a
pointer
to
an
attribute
list
handle.
2.
Use
azn_attrlist_add_entry()
to
add
the
attribute
azn_init_cfg_file
and
assign
it
a
value,
as
described
in
the
table
below.
azn_init_cfg_file
Value
Description
filename
A
configuration
file
containing
initialization
values
for
the
Tivoli
Access
Manager
authorization
API.
There
is
no
default
value.
The
sample
configuration
file
distributed
with
the
Authorization
demonstration
program
is
named
aznapi.conf.
Chapter
3.
Initializing
the
authorization
API
25
Specifying
cache
mode
settings
The
cache
mode
determines
if
the
authorization
API
talks
to
a
Tivoli
Access
Manager
authorization
service
running
in
the
same
process
space
(local
cache
mode)
or
in
a
different
process
space
(remote
cache
mode)
in
the
secure
domain.
Local
cache
mode
can
increase
application
performance
because
authorization
checks
can
be
performed
on
the
same
system
as
the
application.
Local
cache
mode,
however,
requires
additional
configuration
and
maintenance
of
a
replicated
authorization
database.
v
When
using
remote
mode,
the
caller
of
the
authorization
API
must
be
a
member
of
the
remote-acl-users
group.
v
When
using
local
mode,
the
caller
of
the
authorization
API
must
be
a
member
of
the
ivacld-servers
group.
Note:
For
more
information
on
remote
cache
mode
or
local
cache
mode,
see
the
IBM
Tivoli
Access
Manager
Base
Administration
Guide.
The
svrsslcfg
utility
creates
a
user
identity
for
the
caller
and
automatically
adds
it
to
the
appropriate
group.
The
svrsslcfg
utility
determines
which
group
membership
is
required,
based
on
whether
you
specified
local
or
remote
to
the
-s
parameter.
For
more
information,
see
the
IBM
Tivoli
Access
Manager
for
e-business
Command
Reference.
Specifying
cache
mode
type
You
can
specify
the
cache
mode
by
using
either
an
attribute
list
entry
or
a
configuration
file
entry.
v
Attribute
List
Entry:
azn_init_mode
v
Configuration
File
Entry:
mode
v
Configuration
File
Stanza:
[aznapi-configuration]
v
Modified
by
svrsslcfg?
Yes.
Must
be
specified.
Use
the
option
-s
[
local
|
remote
].
The
following
table
displays
the
valid
values
for
cache
modes.
Values
Description
local
The
Tivoli
Access
Manager
authorization
service
runs
in
the
same
server
process
as
the
application
using
the
authorization
API.
remote
The
Tivoli
Access
Manager
authorization
service
runs
as
a
different
server
process
from
the
application
using
the
authorization
API.
When
you
specify
local
cache
mode,
you
must
decide
how
the
local
copy
of
the
authorization
database
will
be
updated.
Choose
one
of
the
following
methods
to
implement
updating:
v
Set
the
authorization
API
to
poll
the
master
authorization
service
database.
v
Register
the
local
(replicated)
database
with
the
master
database,
and
enable
a
listener
process
on
the
local
database’s
system.
This
process
listens
for
update
notifications.
v
Configure
the
authorization
API
to
both
poll
and
listen.
26
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
v
Configure
the
authorization
API
to
neither
poll
nor
listen.
This
could
be
useful,
for
example,
when
the
local
system
is
not
connected
to
a
network.
You
can
use
this
configuration
to
only
receive
updates
when
the
pdadmin
server
replicate
command
is
issued.
Note
that
in
order
for
the
pdadmin
server
replicate
command
to
function
correctly,
a
valid
non-zero
listening
port
(azn_ssl_listening_port)
must
be
set.
Authorization
database
file
location
You
can
specify
the
location
of
the
database
file
used
by
the
authorization
service
by
either
using
attribute
list
entries
or
by
using
configuration
file
entries.
v
Attribute
List
entry:
azn_init_db_file
v
Configuration
File
Entry:
db-file
v
Configuration
File
Stanza:
[aznapi-configuration]
v
Modified
by
svrsslcfg?
No.
Authorization
Database
File
Location
Value
Description
filename
Path
name
to
the
persistent
authorization
policy
database
replica.
Local
cache
refresh
You
can
specify
the
interval
for
the
local
cache
refresh
by
either
using
attribute
list
entries
or
by
using
configuration
file
entries.
v
Attribute
List
entry:
azn_init_cache_refresh_interval
v
Configuration
File
entry:
cache-refresh-interval
v
Configuration
File
Stanza:
[aznapi-configuration]
v
Modified
by
svrsslcfg?
No.
The
following
table
shows
that
you
can
disable
or
enable
the
cache
refresh.
When
you
enable
the
cache
refresh,
you
can
specify
the
cache
refresh
interval
in
number
of
seconds.
Values
Description
disable
Refreshing
of
the
local
authorization
policy
database
disabled.
default
disabled
number
of
seconds
Number
of
seconds
between
refreshes
of
the
local
authorization
policy
database.
Set
appropriate
values
to
ensure
that
the
replicated
database
is
updated
in
a
timely
manner
to
reflect
changes
made
to
the
master
database.
Local
cache
notification
listener
You
can
configure
the
notification
listener
by
either
using
attribute
list
entries
or
by
using
configuration
file
entries.
v
Attribute
List
entry:
azn_init_listen_flags
v
Configuration
File
entry:
listen-flags
v
Configuration
File
Stanza:
[aznapi-configuration]
v
Modified
by
svrsslcfg?:
Yes.
Use
the
option
-l
[
yes
|
no
].
If
not
specified
the
default
is
disable.
Chapter
3.
Initializing
the
authorization
API
27
Value
Description
disable
Disable
the
notification
listener.
This
is
the
default.
enable
Enable
the
notification
listener.
SSL
listener
ports
This
port
is
also
used
to
listen
for
administration
requests
from
the
policy
server.
It
is
mandatory
to
specify
this
port
when
running
svrsslcfg.
Note:
If
you
disabled
the
notification
listener,
skip
this
section.
You
can
specify
the
notification
listener
port
by
using
a
configuration
file
entry.
v
Attribute
List
entry:
azn_init_ssl_listening_port
v
Configuration
File
entry:
ssl-listening-port
v
Configuration
File
stanza:
[ssl]
v
Modified
by
svrsslcfg?:
Yes.
Use
the
option
-r
[
<port-number>
].
This
must
be
specified.
Value
Description
port
number
Use
this
value
to
specify
the
TCP
port
on
which
the
application
will
listen
for
notifications
from
the
master
database
that
is
has
changed.
All
communications
on
this
port
are
SSL
encrypted.
The
value
should
be
non-zero
and
not
used
by
any
other
service
on
the
computer.
Local
domain
This
attribute
specifies
the
operational
domain
of
the
authorization
client
in
a
multiple-domain
Tivoli
Access
Manager
deployment.
The
domain
name
is
used
in
communications
with
the
user
registry
and
the
Tivoli
Access
Manager
policy
server.
An
authorization
client
can
be
configured
into
only
one
Tivoli
Access
Manager
domain.
This
attribute,
and
the
corresponding
configuration
file
entry,
can
be
empty
(unspecified).
In
this
case,
the
domain
defaults
to
the
Management
domain.
Thus,
in
a
single-domain
environment
this
attribute
can
be
left
unspecified.
In
a
multiple-domain
environment,
ensure
that
this
attribute
matches
the
Tivoli
Access
Manager
secure
domain
that
was
specified
when
the
authorization
server
was
configured.
If
the
domain
name
is
specified
in
both
the
azn_init_ssl_local_domain
initialization
attribute
and
in
the
ssl-local-domain
configuration
file
entry,
an
error
is
returned,
to
indicate
a
conflict
in
the
domain
configuration.
Note:
Unlike
other
authorization
API
initialization
parameters,
the
configuration
file
entry
cannot
be
overridden
by
the
initialization
attribute.
v
Attribute
List
entry:
azn_init_ssl_local_domain
v
Configuration
File
entry:
ssl-local-domain
v
Configuration
File
stanza:
[ssl]
v
Modified
by
svrsslcfg?:
Yes.
Table
2.
Local
domain
value
Value
Description
28
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
Table
2.
Local
domain
value
(continued)
domain_name
The
domain
in
which
the
authorization
server
runs.
If
this
value
is
not
specified
in
the
configuration
file
or
as
an
initialization
parameter,
operations
that
rely
on
it
will
fail.
This
value
must
match
the
name
of
the
Tivoli
Access
Manager
secure
domain
that
was
specified
when
the
authorization
server
was
configured.
Chapter
3.
Initializing
the
authorization
API
29
Configuring
SSL
from
the
API
client
to
Tivoli
Access
Manager
You
can
specify
a
number
of
attributes
or
configuration
file
entries
that
describe
the
SSL
communications
configuration
between
the
authorization
API
Client,
running
in
remote
mode,
and
the
Tivoli
Access
Manager
authorization
server
and
Tivoli
Access
Manager
policy
server.
Specifying
an
SSL
keyfile
v
Attribute
List
Entry:
azn_init_ssl_keyfile
v
Configuration
File
Entry:
ssl-keyfile
v
Configuration
File
Stanza:
[ssl]
v
Modified
by
svrsslcfg?:
Yes.
Must
be
specified.
This
uses
the
svrsslcfg
options
-d
[kdb-directory]
and
the
root
from
-n
[server-name]
to
create
an
entry
value:
<kdb-directory>/<server-name>.kdb.
Value
Description
<keyfile-path>
This
is
the
keyfile
used
to
communicate
with
the
Tivoli
Access
Manager
policy
server
and
the
Tivoli
Access
Manager
authorization
server.
It
is
created
by
the
svrsslcfg
utility.
This
can
be
any
relative
or
fully
qualified
filename.
Specifying
a
stash
file
v
Attribute
List
Entry:
azn_init_ssl_stashfile
v
Configuration
File
Entry:
ssl-keyfile-stash
v
Configuration
File
Stanza:
[ssl]
v
Modified
by
svrsslcfg?:
Yes.
Must
be
specified.
This
uses
the
svrsslcfg
options
-d
[kdb-directory]
and
the
root
from
-n
[server-name]
to
create
an
entry
value:
<kdb-directory>/<server-name>.sth.
Value
Description
<keyfile-path>
This
the
stash
file
for
the
keyfile.
It
is
created
by
the
svrsslcfg
utility.
It
is
used
as
an
obfuscated
password
to
the
keyfile.
This
file
should
be
appropriately
secured.
This
can
be
any
relative
or
fully
qualified
filename.
Specifying
a
keyfile
label
v
Attribute
List
Entry:
azn_init_ssl_keyfile_label
v
Configuration
File
Entry:
ssl-keyfile-label
v
Configuration
File
Stanza:
{ssl}
v
Modified
by
svrsslcfg?:
No.
Value
Description
Any
string
The
label
of
the
certificate
to
use
within
the
keyfile.
In
normal
operation
this
is
not
used.
However
it
is
useful
if
the
keyfiles
are
constructed
outside
of
the
svrsslcfg
utility
and
contain
multiple
certificates.
30
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
SSL
session
timeout
v
Attribute
List
Entry:
azn_init_ssl_timeout
v
Configuration
File
Entry:
ssl-v3-timeout
v
Configuration
File
Stanza:
[ssl]
v
Modified
by
svrsslcfg?:
Yes.
Use
the
option
-t
[ssl-timeout].
If
not
specified,
the
default
is
7200
seconds.
Value
Description
Any
non-negative
integer.
Default
value
is
7200
seconds
This
is
the
amount
of
time
before
an
SSL
session
will
expire.
The
Tivoli
Access
Manager
authorization
API
client
automatically
create
a
new
SSL
session
with
new
keys
when
a
session
expires.
This
value
only
applies
to
the
listening
aspect
of
the
authorization
API’s
(when
the
Tivoli
Access
Manager
policy
server
is
calling
the
application).
When
the
application
is
calling
the
Tivoli
Access
Manager
policy
server
or
the
Tivoli
Access
Manager
authorization
server,
the
session
timeout
value
is
dictated
by
the
most
restrictive
of
the
values
for
that
client
and
server.
SSL
password
expiration
v
Attribute
List
Entry:
azn_init_ssl_pwd_life
v
Configuration
File
Entry:
ssl-pwd-life
v
Configuration
File
Stanza:
[ssl]
v
Modified
by
svrsslcfg?:
Yes.
Use
the
option
-e
[<password-life>].
If
not
specified,
the
default
is
183
days.
Value
Description
Any
non-negative
integer.
Default
value
is
183
days.
This
is
the
amount
of
time
before
the
password
or
stash
file
to
the
keyfile
will
expire.
The
Tivoli
Access
Manager
authorization
API
client
automatically
refreshes
the
password
or
stash
file
before
this
expiry
time,
if
automatic
refresh
is
enabled.
Authentication
method
v
Attribute
List
Entry:
azn_init_ssl_authn_type
v
Configuration
File
Entry:
ssl-authn-type
v
Configuration
File
Stanza:
[ssl]
v
Modified
by
svrsslcfg?:
Yes.
This
is
always
set
by
svrsslcfg
to
certificate.
Chapter
3.
Initializing
the
authorization
API
31
Value
Description
The
type
of
authentication.
Possible
values
are:
v
certificate
v
password
v
none
The
default
value
is
none.
The
method
that
the
Tivoli
Access
Manager
policy
server
will
use
to
authenticate
the
authorization
API
client.
The
svrsslcfg
utility
automatically
sets
this
to
certificate.
If
the
value
is
certificate
the
Tivoli
Access
Manager
policy
server
will
map
the
certificate
provided
by
the
authorization
API
client
into
an
identity
and
authenticate
against
it.
Note
that
even
if
password
or
none
are
specified,
the
client
will
still
use
SSL
to
communicate
with
the
server,
and
as
such
will
still
require
a
keyring
database
file
that
has
the
Tivoli
Access
Manager
Certificate
Authority
(CA)
certificate
as
a
signer
certificate
or
trusted
certificate.
There
are
currently
no
operations
that
can
be
performed
by
the
API
successfully
with
an
authentication
type
of
none.
User
name
and
password
v
Attribute
List
Entry:
azn_init_ssl_authn_user
v
Attribute
List
Entry:
azn_init_ssl_authn_pwd
v
Configuration
File
Entry:
ssl-authn-user
v
Configuration
File
Entry:
ssl-authn-password
v
Configuration
File
Stanza:
[ssl]
v
Modified
by
svrsslcfg?:
No.
Value
Description
Any
string.
The
user
name
and
password
that
are
used
if
the
authentication
type
is
password.
It
may
be
unwise
to
store
these
in
the
configuration
file,
however
they
can
be
useful
for
testing
communications.
Tivoli
Access
Manager
configuration
file
location
v
Attribute
List
Entry:
azn_init_ssl_mgr_config
v
Configuration
File
Entry:
ssl-mgr-config
v
Configuration
File
Stanza:
[ssl]
Value
Description
The
relative
or
fully
qualified
path
name
to
the
pd.conf
file.
This
entry
is
used
to
point
to
the
configuration
file
that
was
created
as
part
of
configuring
the
Tivoli
Access
Manager
runtime
environment
(pd.conf).
If
it
is
specified,
the
values
for
master-host,
master-port,
and
master-dn
will
come
from
the
manager
stanza
of
pd.conf
and
override
any
values
specified
in
the
authorization
API
client’s
configuration
file.
Furthermore,
if
entries
or
values
are
not
found
in
pd.conf
for
any
of
these
entries,
empty
values
will
be
used.
The
pd.conf
usually
lives
in
the
Tivoli
Access
Manager
installation
directory,
under
./lib/pd.conf
Password
for
the
SSL
keyfile
v
Attribute
List
Entry:
azn_init_ssl_keyfile_pwd
v
Configuration
File
Entry:
ssl-keyfile-pwd
32
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
v
Configuration
File
Stanza:
[ssl]
v
Modified
by
svrsslcfg?:
No.
Value
Description
<password
string>
Password
used
to
protect
keys
in
the
keyfile.
When
both
ssl-keyfile-pwd
and
ssl-keyfile-stash
are
specified,
the
value
in
ssl-keyfile-pwd
is
used.
Maximum
number
of
worker
threads
v
Attribute
List
Entry:
azn_init_ssl_max_worker_threads
v
Configuration
File
Entry:
ssl-maximum-worker-threads
v
Configuration
File
Stanza:
[ssl]
v
Modified
by
svrsslcfg?:
No.
Value
Description
maximum
number
of
worker
threads
Maximum
number
of
worker
threads
that
are
created
by
the
server
to
handle
incoming
requests.
The
value
is
an
integer.
The
minimum
number
is
1.
The
maximum
number
is
determined
by
the
amount
of
system
resources
available.
The
default
number
is
50.
Automatic
refresh
of
SSL
certificate
and
keyfile
password
v
Attribute
List
Entry:
azn_init_ssl_auto_refresh
v
Configuration
File
Entry:
ssl-auto-refresh
v
Configuration
File
Stanza:
[ssl]
v
Modified
by
svrsslcfg?:
Yes.
Use
the
option
-a
[
yes
|
no
].
If
not
specified
the
default
is
yes.
Value
Description
yes
or
no
Enables
or
disables
automatic
refresh
of
the
SSL
certificate
and
key
database
file
password.
When
enabled,
the
certificate
is
renewed
when
it
is
close
to
expiration.
This
means
that
the
same
public
key
gets
a
renewed
signature
from
the
certificate
authority,
which
results
in
an
extended
lifetime
for
the
certificate.
A
value
of
yes
enables
automatic
refresh.
A
value
of
no
disables
automatic
refresh.
Connection
timeout
v
Attribute
List
Entry:
azn_init_ssl_io_inactivity_timeout
v
Configuration
File
Entry:
ssl-io-inactivity-timeout
v
Configuration
File
Stanza:
[ssl]
v
Modified
by
svrsslcfg?:
No.
Chapter
3.
Initializing
the
authorization
API
33
Value
Description
<number
of
seconds>
Inactivity
timeout
for
the
input/output
connection,
expressed
in
seconds.
The
value
is
an
integer.
The
minimum
value
is
0.
When
the
value
is
0,
no
timeout
is
enforced.
The
default
value
is
0
seconds.
The
recommended
value
is
90
seconds.
Note
that
this
value
is
set
in
the
supplied
aznapi.conf
file.
34
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
Specifying
communications
attributes
for
the
policy
server
Use
the
attributes
described
in
this
section
to
specify
the
location
and
port
number
of
the
Tivoli
Access
Manager
policy
server.
Authorization
API
clients
use
this
information
to
communicate
with
the
policy
server.
Policy
server
hostname
v
Attribute
List
Entry:
azn_init_master_host
v
Configuration
File
Entry:
master-host
v
Configuration
File
Stanza:
[manager]
v
Modified
by
svrsslcfg?:
Yes.
The
value
is
taken
from
the
pd.conf
file.
The
pd.conf
file
is
created
when
the
Tivoli
Access
Manager
runtime
component
is
configured
on
the
machine.
Value
Description
<policy
server
hostname>
Specifies
the
hostname
of
the
Tivoli
Access
Manager
policy
server.
This
entry
and
stanza
can
be
in
either
the
authorization
API
client’s
configuration
file
or
the
file
pointed
to
by
the
azn_init_ssl_mgr_config
attribute
(if
specified).
If
the
azn_init_ssl_mgr_config
attribute
is
specified,
its
value
overrides
that
in
aznAPI.conf.
Policy
server
port
number
v
Attribute
List
Entry:
azn_init_master_port
v
Configuration
File
Entry:
master-port
v
Configuration
File
Stanza:
[manager]
v
Modified
by
svrsslcfg?:
Yes.
The
value
is
taken
from
the
pd.conf
file.
The
pd.conf
file
is
created
when
the
Tivoli
Access
Manager
runtime
component
is
configured
on
the
machine.
Value
Description
<port
number>
This
entry
and
stanza
can
be
in
either
the
authorization
API
client’s
configuration
file
or
the
file
pointed
to
by
the
azn_init_ssl_mgr_config
attribute
(if
specified).
If
the
azn_init_ssl_mgr_config
attribute
is
specified,
its
value
overrides
that
in
the
authorization
API
client’s
configuration
file.
Chapter
3.
Initializing
the
authorization
API
35
Specifying
values
for
an
authorization
server
replica
You
can
specify
a
series
of
values
that
describe
the
location
and
communication
values
for
an
authorization
server
replica.
All
values
are
assigned
to
one
configuration
file
entry.
Each
configuration
file
entry
describes
one
Tivoli
Access
Manager
authorization
server.
You
can
add
one
or
more
entries
for
each
authorization
server
to
the
configuration
file.
The
replicas
are
of
the
format:
<replica
hostname>:<port>:<preference>:<replica
cert
dn>
For
example:
“rweber.bball.com:7137:5:cn=ivacld/rweber,o=Access
Manager,C=US”
Note
that
the
separator
for
the
fields
is
a
colon
(“:”)
and
not
a
comma
(“,”)
like
the
LDAP
replicas
use.
v
Attribute
List
Entry:
azn_init_replica
v
Configuration
File
Entry:
replica
v
Configuration
File
Stanza:
[manager]
v
Modified
by
svrsslcfg:
Can
be.
Replicas
can
be
added
to
the
configuration
file
by
using
the
svrsslcfg
-add_replica
option.
Value
Description
<replica
hostname>
The
fully
qualified
domain
name
of
the
server.
<port>
The
port
on
the
server.
<preference>
A
ranking
for
attempting
contact.
Valid
values
are
from
1
to
10.
The
lowest
preference
is
1,
the
highest
preference
is
10.
<replica
certificate
distinguished
name>
The
LDAP
distinguished
name
for
the
authorization
server.
36
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
Configuring
the
authorization
API
for
LDAP
access
When
your
application
runs
in
a
Tivoli
Access
Manager
secure
domain
that
uses
an
LDAP
user
registry,
you
must
provide
the
LDAP
configuration
settings
to
the
authorization
API.
The
required
LDAP
configuration
settings
match
the
settings
that
were
entered
when
Tivoli
Access
Manager
was
installed
on
the
local
system.
LDAP
user
registry
support
v
Attribute
List
Entry:
None.
v
Configuration
File
Entry:
enable
v
Configuration
File
Stanza:
[ldap]
v
Modified
by
svrsslcfg?
Yes.
The
value
is
taken
from
the
pd.conf
file.
The
pd.conf
file
is
created
when
the
Tivoli
Access
Manager
runtime
component
is
configured
on
the
machine.
Value
Description
yes
Enable
LDAP
user
registry
support.
This
is
the
default
value.
This
entry
is
not
used
when
building
an
attribute
list.
LDAP
access
is
automatically
enabled
when
the
attribute
azn_init_ldap_port
is
not
null.
When
azn_init_ldap_port
is
null,
LDAP
access
is
automatically
disabled.
LDAP
server
host
name
v
Attribute
List
Entry:
azn_init_ldap_host
v
Configuration
File
Entry:
host
v
Configuration
File
Stanza:
[ldap]
v
Modified
by
svrsslcfg?
Yes.
The
value
is
taken
from
the
pd.conf
file.
The
pd.conf
file
is
created
when
the
Tivoli
Access
Manager
runtime
component
is
configured
on
the
machine.
Value
Description
host
name
Host
name
of
LDAP
server.
LDAP
server
port
number
v
Attribute
List
Entry:
azn_init_ldap_port
v
Configuration
File
Entry:
port
v
Configuration
File
Stanza:
[ldap]
v
Modified
by
svrsslcfg?
Yes.
The
value
is
taken
from
the
pd.conf
file.
The
pd.conf
file
is
created
when
the
Tivoli
Access
Manager
runtime
component
is
configured
on
the
machine.
Value
Description
port
number
Port
number
for
communicating
with
the
LDAP
server.
LDAP
user
Distinguished
Name
v
Attribute
List
Entry:
azn_init_ldap_bind_dn
v
Configuration
File
Entry:
bind-dn
Chapter
3.
Initializing
the
authorization
API
37
v
Configuration
File
Stanza:
[ldap]
v
Modified
by
svrsslcfg?
Yes.
The
value
is
created
based
on
the
server
name
that
was
specified
with
the
-n
server_name
flag
and
the
local
host
of
the
machine.
Value
Description
LDAP
DN
Distinguished
Name
of
the
LDAP
user.
Created
by
the
svrsslcfg
utility.
LDAP
User
Password
v
Attribute
List
Entry:
azn_init_ldap_bind_pwd
v
Configuration
File
Entry:
bind-pwd
v
Configuration
File
Stanza:
[ldap]
v
Modified
by
svrsslcfg?
Yes.
The
value
is
created
based
on
the
password
that
was
specified
with
the
-S
password
flag.
Value
Description
password
Password
for
the
LDAP
user.
Created
by
the
svrsslcfg
utility.
SSL
communication
with
the
LDAP
server
If
the
communication
between
the
Tivoli
Access
Manager
Authorization
server
and
the
LDAP
server
is
over
Secure
Sockets
Layer
(SSL),
you
must
specify
the
communication
settings.
Note
that
the
Tivoli
Access
Manager
authorization
API
client
must
use
two
key
files:
one
for
communicating
with
the
LDAP
server
and
one
for
communicating
with
the
Tivoli
Access
Manager
servers.
v
Attribute
List
Entry:
None.
v
Configuration
File
Entry:
ssl-enabled
v
Configuration
File
Stanza:
[ldap]
Value
Description
yes
Enables
SSL
communication
with
the
LDAP
server.
This
entry
is
not
used
when
building
attribute
lists.
If
azn_init_ldap_ssl_keyfile
is
not
null,
then
SSL
is
automatically
configured.
When
azn_init_ldap_ssl_keyfile
is
null,
SSL
is
not
automatically
configured
SSL
keyfile
name
v
Attribute
List
Entry:
azn_init_ldap_ssl_keyfile
v
Configuration
File
Entry:
ssl-keyfile
v
Configuration
File
Stanza:
[ldap]
Value
Description
<filename>
Name
of
the
SSL
key
file.
38
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
SSL
keyfile
distinguished
name
v
Attribute
List
Entry:
azn_init_ldap_ssl_keyfile_dn
v
Configuration
File
Entry:
ssl-keyfile-dn
v
Configuration
File
Stanza:
[ldap]
Value
Description
KeyLabel
Key
label
to
identify
the
client
certificate
that
is
presented
to
the
LDAP
server.
SSL
keyfile
password
v
Attribute
List
Entry:
azn_init_ldap_ssl_keyfile_pwd
v
Configuration
File
Entry:
ssl-keyfile-pwd
v
Configuration
File
Stanza:
[ldap]
Value
Description
password
Password
to
access
the
SSL
key
file.
When
the
keyfile
is
specified
but
the
password
is
not
specified
or
is
set
to
NULL,
this
indicates
that
there
is
no
password
required
for
access
to
the
SSL
key
file.
When
the
keyfile
is
specified,
and
the
password
is
a
non-NULL
string,
the
password
is
used
by
the
LDAP
client
to
access
the
SSL
key
file.
Maximum
search
buffer
size
v
Attribute
List
Entry:
azn_init_ldap_max_search_size
v
Configuration
File
Entry:
max-search-size
v
Configuration
File
Stanza:
[ldap]
Value
Description
<search-size>
Optional.
Limit
for
the
maximum
search
buffer
size
returned
from
the
LDAP
server
in
entries.
Note
that
this
value
can
also
be
limited
by
the
LDAP
server
itself.
Caching
LDAP
data
v
Attribute
List
Entry:
azn_init_ldap_cache
v
Configuration
File
Entry:
cache-enabled
v
Configuration
File
Stanza:
[ldap]
Value
Description
true
Optional.
Enable
LDAP
client-side
caching
of
user,
group
and
LDAP
policy
data
to
improve
performance
for
similar
LDAP
queries.
false
Optional.
Disable
LDAP
client-side
caching.
This
is
the
default
value.
LDAP
server
query
preference
v
Attribute
List
Entry:
azn_init_prefer_rw_svr
v
Configuration
File
Entry:
prefer-readwrite-server
Chapter
3.
Initializing
the
authorization
API
39
v
Configuration
File
Stanza:
[ldap]
Value
Description
true
Optional.
The
client
attempts
to
query
the
read/write
LDAP
server
(see
ldap-replica
configuration
option)
before
querying
any
read-only
servers
that
are
configured
in
the
domain.
false
Optional.
Do
not
query
read/write
LDAP
server
first
Authentication
method
v
Attribute
List
Entry:
azn_init_ldap_using_compare
v
Configuration
File
Entry:
auth-using-compare
v
Configuration
File
Stanza:
[ldap]
Value
Description
true
Optional.
Choose
whether
ldap_compare()
is
used
instead
of
ldap_bind()
to
authenticate
LDAP
users.
This
option
changes
the
method
used
by
the
Tivoli
Access
Manager
authorization
API
call
and
azn_util_password_authenticate().
false
Optional.
Use
ldap_bind().
Specifying
LDAP
user
registry
replica
access
Use
can
adds
an
attribute
or
configuration
file
entry
that
defines
the
LDAP
user
registry
replicas
in
the
domain.
v
Attribute
List
Entry:
azn_init_ldap_replica
v
Configuration
File
Entry:
replica
v
Configuration
File
Stanza:
[ldap]
Assign
multiple
values
to
replica
by
entering
a
list
consisting
of
entries
that
are
separated
by
commas.
For
example:
ldap-replica
=
barney,391,readwrite,2
ldap-replica
=
fred,391,readonly,3
Value
Description
ldap-server
The
network
name
of
the
LDAP
server.
port
The
port
on
the
LDAP
server.
type
Either
readonly
or
readwrite
pref
A
preference
or
priority
level
to
assign
to
accessing
this
replica.
The
minimum
value
is
1.
The
maximum
value
is
10.
A
higher
number
denotes
a
higher
preference.
LDAP
client-side
timeout
v
Attribute
List
Entry:
azn_init_ldap_timeout
v
Configuration
File
Entry:
timeout
v
Configuration
File
Stanza:
[ldap]
Value
Description
40
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
number_of_seconds
Client-side
timeout
setting
for
communication
to
LDAP
servers.
This
setting
applies
to
both
authentication
and
search
timeouts.
This
setting
can
be
overridden
by
azn_init_ldap_authn_timeout
and
azn_init_ldap_search_timeout.
By
default,
or
with
a
value
of
0,
LDAP
requests
do
not
timeout.
LDAP
client-side
authentication
timeout
v
Attribute
List
Entry:
azn_init_ldap_authn_timeout
v
Configuration
File
Entry:
authn-timeout
v
Configuration
File
Stanza:
[ldap]
Value
Description
number_of_seconds
Client-side
timeout
setting
for
authentication
requests
to
LDAP
servers.
By
default,
or
with
a
value
of
0,
authentication
requests
do
not
timeout.
LDAP
client-side
search
timeout
v
Attribute
List
Entry:
azn_init_ldap_search_timeout
v
Configuration
File
Entry:
search-timeout
v
Configuration
File
Stanza:
[ldap]
Value
Description
number_of_seconds
Client-side
timeout
setting
for
search
requests
to
LDAP
servers.
By
default,
or
with
a
value
of
0,
search
requests
do
not
timeout.
Chapter
3.
Initializing
the
authorization
API
41
URAF
registry
settings
Configure
the
settings
in
this
section
when
using
the
Tivoli
Access
Manager
User
Registry
Adapter
Framework
(URAF)
to
specify
Active
Directory
or
Lotus
Domino
configurations.
Specify
the
URAF
configuration
file
v
Attribute
List
Entry:
azn_init_uraf_cfg_file
v
Configuration
File
Entry:
uraf-registry-config
v
Configuration
File
Stanza:
[uraf-registry]
Value
Description
fully_qualified_pathname
URAF
configuration
file.
Specify
the
server
identity
v
Attribute
List
Entry:
azn_init_uraf_bind_id
v
Configuration
File
Entry:
bind-id
v
Configuration
File
Stanza:
[uraf-registry]
Value
Description
identity
Identity
to
use
when
binding
to
the
URAF
server.
Specify
the
server
password
v
Attribute
List
Entry:
azn_init_uraf_bind_pwd
v
Configuration
File
Entry:
bind-pwd
v
Configuration
File
Stanza:
[uraf-registry]
Value
Description
password_string
The
password
for
the
server
specified
in
either
azn_init_uraf_bind_id
or
in
the
configuration
file
entry
bind-id.
Enable
cache
mode
v
Attribute
List
Entry:
azn_init_uraf_cache_mode
v
Configuration
File
Entry:
cache-mode
v
Configuration
File
Stanza:
[uraf-registry]
Table
3.
Cache
mode
values
Value
Description
enable
Enable
cache
mode.
disable
Disable
cache
mode.
This
is
the
default
value.
Specify
cache
size
v
Attribute
List
Entry:
azn_init_uraf_cache_size
v
Configuration
File
Entry:
cache-size
42
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
v
Configuration
File
Stanza:
[uraf-registry]
Table
4.
Cache
size
values
Value
Description
integer
value
The
default
cache
size
is
251.
Specify
cache
lifetime
v
Attribute
List
Entry:
azn_init_uraf_cache_lifetime
v
Configuration
File
Entry:
cache-lifetime
v
Configuration
File
Stanza:
[uraf-registry]
Table
5.
Cache
lifetime
value
Value
Description
integer
value
The
default
cache
lifetime
is
86400.
Chapter
3.
Initializing
the
authorization
API
43
Authorization
rules
initialization
The
authorization
API
can
be
initialized
with
several
settings
that
control
the
behavior
of
authorization
rules
processing
and
inform
the
API
of
the
presence
of
one
or
more
sources
for
gathering
access
decision
information
(ADI)
needed
for
rule
evaluation.
The
ADI
can
come
from
the
resource
manager
application
and
from
dynamic
ADI
retrieval
entitlement
services.
Application
developers
should
understand
the
ADI
XML
document
model
and
services
before
modifying
the
settings
in
this
section.
The
authorization
rules
model
is
described
in
IBM
Tivoli
Access
Manager
Base
Administration
Guide.
The
dynamic
ADI
retrieval
entitlement
service
is
described
in
“Dynamic
ADI
retrieval
services”
on
page
110.
Prolog
text
for
the
XMLADI
input
document
v
Attribute
List
Entry:
azn_init_input_adi_xml_prolog
v
Configuration
File
Entry:
input-adi-xml-prolog
v
Configuration
File
Stanza:
[aznapi-configuration]
This
text
is
prepended
to
the
XML
input
document
that
is
created
from
the
rule
access
decision
information
(ADI).
The
rule
ADI
is
passed
to
the
authorization
API
in
the
application
context
and
credential
attributes.
This
configurable
parameter
allows
the
administrator
to
customize
the
XML
prolog
statement
that
is
prepended
to
the
XMLADI
input
document.
The
XMLADI
input
document
contains
the
XML
encoded
ADI
for
use
during
the
rule
evaluation.
If
this
prolog
is
changed
then
it
is
strongly
suggested
that
the
existing
attribute
values
are
maintained
in
the
new
prolog.
The
default
text
is:
<?xml
version="1.0"
encoding="UTF-8"?>
Attention:
Be
sure
to
understand
the
authorization
rules
model
before
changing
this
setting.
See
the
description
in
IBM
Tivoli
Access
Manager
Base
Administration
Guide.
Prolog
text
for
the
XSL
rule
document
v
Attribute
List
Entry:
azn_init_xsl_stylesheet_prolog
v
Configuration
File
Entry:
xsl-stylesheet-prolog
v
Configuration
File
Stanza:
[aznapi-configuration]
This
configurable
parameter
allows
the
administrator
to
customize
the
XSL
prolog
statement
that
is
prepended
to
the
XSL
stylesheet
that
is
created
from
the
XSL
language
rule
text.
This
allows
the
administrator
to
control
aspects
of
the
XSL
processor
initialization.
The
most
common
use
for
this
configurable
parameter
is
to
add
XML
namespace
definitions
for
a
customers
namespaces.
For
more
information
on
XML
namespaces
and
how
to
configure
and
use
them,
see
IBM
Tivoli
Access
Manager
Base
Administration
Guide.
Attention:
Modifying
this
value
for
reasons
other
than
to
add
XML
namespace
definitions
is
not
recommended.
Modifications
can
affect
the
results
returned
by
the
processor
and
make
them
unrecognizable
by
the
rules
policy
evaluator.
Be
sure
to
understand
the
authorization
rules
model
before
changing
this
setting.
The
default
and
recommended
setting
for
this
prolog
is:
44
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
<!—
Required
for
XSLT
language
—>
<?xml
version="1.0"
encoding=’UTF-8’?>
<xsl:stylesheet
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
version="1.0">
<!—
Required
to
constrain
output
of
rule
evaluation
—>
<xsl:output
method="text"
omit-xml-declaration="yes"
encoding=’UTF-8’
indent="no"
/>
<!—
Need
this
to
ensure
default
text
node
printing
is
off
—>
<xsl:template
match="text()"></xsl:template>
Resource
manager
ADI
prefix
list
v
Attribute
List
Entry:
azn_init_resource_mgr_provided_adi
v
Configuration
File
Entry:
resource-mgr-provided-adi
v
Configuration
File
Stanza:
[aznapi-configuration]
Authorization
API
clients
use
this
configuration
entry
to
notify
the
authorization
engine
that
the
client
is
a
source
for
application-specific
access
decision
information
(ADI)
needed
for
rule
evaluations.
The
entries
are
strings.
The
strings
are
prefixes
that
identify
ADI
that
will
be
supplied
by
the
resource
manager.
A
resource
manager
can
be
any
authorization
API
client,
including,
for
example,
Tivoli
Access
Manager
WebSEAL.
Note:
For
more
information
on
the
types
of
ADI
that
are
specific
to
Web
servers,
and
how
WebSEAL
can
provide
that
ADI
to
the
authorization
rule
evaluation
process,
see
IBM
Tivoli
Access
Manager
for
e-business
WebSEAL
Administration
Guide.
For
example,
a
resource
manager
that
manages
and
protects
a
printer
queue
may
define
a
prefix
of
printmgr_
which
notifies
the
authorization
API
client
that
the
resource
manager
will
supply
the
values
for
any
ADI
it
needs
for
any
container
whose
name
has
a
prefix
of
printmgr_.
For
example,
printmgr_print_status
and
printmgr_user_print_quota
are
examples
of
two
items
of
ADI
that
the
authorization
engine
will
request
of
the
printer
resource
manager.
The
authorization
engine
will
request
this
ADI
from
the
resource
manager
when
the
ADI
is
not
available
in
the
credential
or
application
context
that
is
passed
in
with
the
access
decision
call.
The
authorization
engine
will
fail
the
access
decision
and
will
also
request
that
the
resource
manager
retry
the
request
after
the
required
data
has
been
added
to
the
application
context
that
will
be
passed
in
with
the
next
request.
Additional
prefixes
are
specified
with
additional
entries.
For
example,
if
the
printer
resource
manager
can
also
provide
information
on
the
user
requesting
the
submission
then
the
configuration
file
entries
would
be:
resource-mgr-provided-adi
=
printmgr_
resource-mgr-provided-adi
=
printuser_
By
default
there
are
no
resource
manager
prefixes
configured.
For
more
information,
refer
to
the
section
on
providing
ADI
on
demand
from
the
resource
manager,
in
the
authorization
rule
management
chapter
in
the
IBM
Tivoli
Access
Manager
Base
Administration
Guide.
This
section
provides
more
detail
on
how
to
enable
this
feature
and
provides
more
examples
of
prefixes.
Chapter
3.
Initializing
the
authorization
API
45
Dynamic
ADI
retrieval
entitlement
service
list
v
Attribute
List
Entry:
azn_init_dynamic_adi_entitlements_service
v
Configuration
File
Entry:
dynamic-adi-entitlement-services
v
Configuration
File
Stanza:
[aznapi-configuration]
This
configurable
parameter
allows
the
administrator
to
specify
the
set
of
dynamic
ADI
retrieval
entitlement
services
that
the
authorization
engine
will
query
for
any
ADI
that
it
finds
it
still
needs
after
searching
the
client
credential,
the
application
context,
and
the
authorization
engine
context.
The
value
of
each
entry
is
a
string
containing
a
dynamic
ADI
retrieval
entitlement
service
ID.
Each
entitlement
service
specified
will
be
queried
by
the
rules
engine
if
missing
ADI
is
detected
during
an
authorization
rule
evaluation.
Entitlement
services
listed
here
must
adhere
to
the
input
and
output
specifications
for
a
dynamic
ADI
retrieval
service.
The
entitlement
services
in
the
list
are
in
the
order
defined
by
the
order
of
the
entries
in
the
configuration
file
or
initialization
attribute
list.
By
default
there
are
no
dynamic
ADI
retrieval
services
configured
in
this
manner.
For
more
information
on
the
dynamic
ADI
retrieval
service,
see
“Dynamic
ADI
retrieval
services”
on
page
110.
XMLADI
attribute
definitions
v
Attribute
List
Entry:
azn_init_xmladi_attribute_definitions
v
Configuration
File
Entry:
attribute_name
=
attribute_value
v
Configuration
File
Stanza:
[xmladi-attribute-definitions]
The
attribute
definitions
are
inserted
into
the
XMLADI
element
start
tag
to
enable
attributes
to
be
defined
for
the
entire
XMLADI
document
and
all
ADI
defined
therein.
The
programmatic
initialization
attribute
can
contain
multiple
attribute
values,
one
for
each
attribute
definition
to
be
added
to
the
XMLADI
element
start
tag.
The
attribute
definitions
are
in
the
format:
attribute_name
=
attribute_value
For
example:
[xmladi-attribute-definitions]
xmlns:myNS
=
"http://myURI.mycompany.com"
appID
=
’"Jupiter"
-
Account
Management
Web
\
Portal
Server
#1.’
The
XMLADI
element
start
tag
built
from
these
definitions
is:
<XMLADI
xmlns:myNS="http://myURI.mycompany.com"
\
appID=’"Jupiter"
-
Account
Management
Web
Portal
\
Server
#1.’>
For
more
information
on
XML
namespaces
and
how
to
configure
and
use
them,
see
IBM
Tivoli
Access
Manager
Base
Administration
Guide.
46
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
Enabling
the
return
of
permission
information
You
can
specify
information
to
be
returned
by
the
azn_decision_access_allowed_ext()
function
call.
This
call
returns
a
pointer
to
an
attribute
list
(azn_attrlist_h_t)
named
permission_info.
This
attribute
list
contains
more
detailed
information
on
the
result
or
reasoning
behind
the
access
decision
that
was
made.
It
may
also
be
used
to
return
additional
information
that
is
applicable
to
the
authorization
decision.
For
example,
this
could
include
the
quality
of
protection
(QOP)
that
is
required
for
communication
between
client
and
server
entities.
To
enable
the
return
of
permission
information
you
must
supply
values
for
one
of
the
following:
v
Attribute
List
Entry:
azn_init_set_perminfo_attrs
v
Configuration
File
Entry:
permission-info-returned
v
Configuration
File
Stanza:
[aznapi-configuration]
You
can
specify
the
information
returned
in
the
permission_info
attribute
list
by
adding
values
to
the
azn_init_set_perminfo_attrs
attribute
during
initialization
of
the
authorization
API.
The
azn_init_set_perminfo_attrs
attribute
is
set
in
the
init_data
attribute
list.
The
init_data
attribute
list
is
passed
as
an
input
parameter
to
the
authorization
API
initialization
function,
azn_initialize().
You
can
add
multiple
attribute
values
to
azn_init_set_perminfo_attrs.
The
permission-info-returned
configuration
entry
takes
the
same
set
of
permission
information
values
as
the
initialization
attribute
does.
To
specify
multiple
values,
each
value
must
separated
from
the
next
with
a
space.
For
example:
permission-info-returned
=
azn_perminfo_wm_ulong
azn_perminfo_qop_ulong
The
defined
values
for
use
with
azn_init_set_perminfo_attrs
or
permission-info-returned
are
listed
below:
azn_acl_ext_attr_loc
azn_dynadi_target_url
azn_perminfo_all_attrs
azn_perminfo_auditlevel_ulong
azn_perminfo_dynadi_redirect_url
azn_perminfo_fail_reason
azn_perminfo_qop
azn_perminfo_qop_ulong
azn_perminfo_reason_rule_failed
azn_perminfo_rules_adi_request
azn_perminfo_stepup_level
azn_perminfo_warningmode_ulong
azn_perminfo_warningmodepermitted_ulong
azn_pop_ext_attr_loc
azn_rule_ext_attr_loc
For
a
description
of
each
of
the
above
values,
see
“Permission
information
attributes”
on
page
263.
When
using
a
remote
mode
C
authorization
client
or
the
Java
authorization
client
(PDPermission
class),
the
authorization
server,
not
the
client,
must
be
configured
to
return
permission
information.
This
is
because
only
the
authorization
server
has
the
information.
The
authorization
server
can
only
be
configured
using
the
permission-info-returned
configuration
file
entry.
The
default
configuration
file
Chapter
3.
Initializing
the
authorization
API
47
for
the
authorization
server
is
ivacld.conf.
This
configuration
file
has
the
permission-info-returned
parameter
commented
out
(disabled)
by
default:
#
#permission-info-returned
=
azn_perminfo_qop
azn_perminfo_qop_ulong
#
Uncomment
the
line
in
order
to
enable
the
return
of
permission
info
from
the
authorization
server.
48
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
Configuring
event
logging
and
legacy
auditing
Tivoli
Access
Manager
provides
an
event
logging
facility.
This
is
used
for
both
the
capture
and
logging
of
system
events.
This
capture
and
logging
process
provides
event
tracking
needed
for
auditing
purposes.
The
authorization
API
clients
can
specify
settings
for
this
facility
either
by
using
a
single
configuration
file
setting
(with
multiple
values)
or
by
specifying
multiple
values
for
a
single
initialization
data
attribute.
To
enable
the
event
logging
you
must
supply
values
for
one
of
the
following:
v
Attribute
List
Entry:
azn_init_logcfg
Note:
The
attribute
azn_init_logcfg
is
not
defined
in
ogauthzn.h.
Thus,
you
should
use
the
literal
string
azn_init_logcfg
instead
of
a
reference
to
an
exported
string
variable.
v
Configuration
File
Entry:
logcfg
v
Configuration
File
Stanza:
[aznapi-configuration]
The
event
logging
facility
can
be
configured
to
capture
a
variety
of
events,
and
can
be
configured
to
specify
one
or
more
output
destinations.
For
example,
the
syntax
for
specifying
logcfg
output
to
a
file
is:
logcfg
=category:file
path=file_pathname,
flush_interval=seconds,\
rollover_size=number,log_id=logid,queue_size=number,hi_water=number,\
buffer_size=number,mode={text|binary}
For
information
on
how
to
specify
values
for
logcfg,
see
the
description
of
event
logging
in
the
IBM
Tivoli
Access
Manager
Base
Administration
Guide.
Legacy
auditing
Tivoli
Access
Manager
also
supports
a
legacy
auditing
facility.
This
facility
is
a
subset
of
the
event
logging
facility.
Typically,
it
is
not
used
for
new
applications.
When
needed
for
backwards
compatibility,
the
authorization
API
can
be
configured
to
support
legacy
auditing.
The
following
table
shows
the
authorization
API
legacy
initialization
data
attributes
that
correspond
to
configuration
file
entries
for
legacy
auditing.
Table
6.
Legacy
attributes
and
configuration
file
entries
Legacy
initialization
data
attribute
Legacy
configuration
file
entry
azn_init_auditcfg
auditcfg
azn_init_auditfile
auditlog
azn_init_audit_attribute
audit-attribute
azn_init_log_size
logsize
azn_init_log_flush_interval
logflush
azn_init_logging_client_id
(none)
For
more
information
on
configuring
legacy
auditing,
see
the
IBM
Tivoli
Access
Manager
Base
Administration
Guide.
Chapter
3.
Initializing
the
authorization
API
49
Specifying
the
host
interface
on
which
to
listen
Machines
that
have
more
than
one
network
interface
card
installed
and
configured
can
have
more
than
one
hostname.
When
more
than
one
network
interface
card
is
configured,
use
this
authorization
API
initialization
attribute
to
specify
the
hostname
on
which
the
authorization
API
application
listens.
When
this
attribute
is
not
specified,
the
default
hostname
is
used.
v
Attribute
List
Entry:
azn_app_host
v
Configuration
File
Entry:
azn-app-host
v
Configuration
File
Stanza:
[aznapi-configuration]
Value
Description
<hostname>
The
hostname
on
which
the
application
is
running.
This
value
can
be
used
to
specify
a
hostname
on
machines
that
support
multiple
hostnames
(by
using
multiple
network
interface
cards).
When
this
is
not
specified,
the
default
hostname
is
used.
Note:
This
cannot
be
an
IP
address.
50
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
Starting
the
authorization
service
Complete
the
following
steps:
1.
Ensure
that
the
attribute
list
init_data
has
been
created
and
filled
in,
as
described
in
the
preceding
sections.
2.
Call
azn_initialize()
to
bind
to
and
initialize
the
authorization
service.
For
example:
/*
Start
the
service
*/
status
=
azn_initialize(init_data,
&init_info);
if
(status
!=
AZN_S_COMPLETE)
return(status);
In
the
example
code
above,
azn_initialize()
returns
the
attribute
list
init_info.
This
attribute
list
is
appended
with
any
initialization
information
attributes
that
apply.
This
includes
the
AZN_C_VERSION
attribute,
which
contains
the
version
number
of
the
API
implementation.
Note:
To
re-initialize
the
API,
use
azn_shutdown()
and
then
call
azn_initialize().
When
using
this
function
on
Windows
NT,
do
not
call
it
from
dllMain().
For
more
information,
see
the
reference
page
for
“azn_initialize()”
on
page
207.
Chapter
3.
Initializing
the
authorization
API
51
52
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
Chapter
4.
Using
the
authorization
API
This
chapter
contains
the
following
topics:
v
“Authenticating
an
API
application”
on
page
54
v
“Verifying
the
identity
of
a
user”
on
page
55
v
“Obtaining
user
authorization
credentials”
on
page
56
v
“Obtaining
an
authorization
decision”
on
page
59
v
“Cleaning
up
and
shutting
down”
on
page
62
v
“Working
with
credentials”
on
page
63
©
Copyright
IBM
Corp.
2000,2003
53
Authenticating
an
API
application
The
API
application
must
establish
its
own
authenticated
identity
within
the
IBM
Tivoli
Access
Manager
(Tivoli
Access
Manager)
secure
domain,
in
order
to
request
authorization
decisions
from
the
Tivoli
Access
Manager
authorization
service.
Before
you
run
the
authorization
API
application
for
the
first
time,
you
must
create
a
unique
identity
for
the
application
in
the
Tivoli
Access
Manager
secure
domain.
In
order
for
the
authenticated
identity
to
perform
API
checks,
the
application
must
be
a
member
of
at
least
one
of
the
following
groups:
v
ivacld-servers
This
group
membership
is
needed
for
applications
using
local
cache
mode.
v
remote-acl-users
This
group
membership
is
needed
for
applications
using
remote
cache
mode.
When
the
application
wants
to
contact
one
of
the
secure
domain
services,
it
must
first
log
in
to
the
secure
domain.
Use
the
svrsslcfg
utility
to
accomplish
the
above
tasks.
Run
this
utility
before
initializing
the
authorization
API.
The
svrsslcfg
utility
creates
a
user
identity
for
the
application,
and
configures
the
SSL
communication
between
the
application
and
the
Tivoli
Access
Manager
policy
server.
The
svrsslcfg
utility
performs
the
following
tasks:
v
Creates
a
user
identity
for
the
application
by
combining
the
server
name
with
the
local
TCP/IP
host
name.
v
Creates
an
SSL
key
file
for
that
user:
For
example,
demo_user.kdb
and
demo_user.sth.
v
Adds
the
user
ivacld-servers
group
for
a
server
type
of
local,
or
to
the
remote-acl-users
group
for
a
server
type
of
remote.
For
more
information,
including
the
svrsslcfg
syntax,
see
the
IBM
Tivoli
Access
Manager
for
e-business
Command
Reference.
54
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
Verifying
the
identity
of
a
user
The
application
must
verify
the
identity
of
the
user
who
has
submitted
a
request.
The
identity
can
be
expressed
as
one
of
the
following
types
of
users:
v
Authenticated
In
this
case,
the
user’s
identity
in
the
secure
domain
is
registered
in
the
LDAP
User
registry.
The
user
is
authenticated,
and
information
about
the
user
can
be
obtained.
This
information
includes,
for
example,
the
LDAP
Distinguished
Name.
v
Unauthenticated
In
this
case,
the
user’s
identity
in
the
secure
domain
is
not
specifically
registered
in
the
LDAP
user
registry.
The
user
is
defined
to
be
unauthenticated,
and
further
information
about
the
user’s
identity
is
irrelevant
to
the
authorization
process.
Applications
can
obtain
user
identities
through
a
variety
of
methods.
These
can
include
the
use
of
a
Credentials
Acquisition
Server,
or
a
call
to
an
application-specific
method
for
querying
user
registries
and
establishing
a
security
(login)
context.
Optionally,
applications
can
use
the
Tivoli
Access
Manager
authorization
API
utility
function
azn_util_password_authenticate()
to
obtain
user
identity
information
from
the
secure
domain.
The
function
azn_util_password_authenticate()
requires
the
user
name
and
password
as
input
parameters.
Typically,
an
application
receives
a
user
name
and
password
from
the
user
who
initiated
the
access
request.
The
function
performs
a
login
using
the
supplied
user
name
and
password.
If
the
login
is
successful,
the
function
returns
the
following
information:
v
The
string
mechanism_id,
which
specifies
the
authentication
mechanism
(LDAP)
that
was
used.
v
A
pointer
to
the
buffer
authinfo.
This
buffer
contains
user
identity
information.
Note:
The
function
azn_util_password_authenticate()
does
not
obtain
a
security
(login)
context
for
the
user.
For
more
information,
see
the
reference
page
for
“azn_util_password_authenticate()”
on
page
219.
After
the
application
has
obtained
identity
information
for
the
user,
you
can
use
the
authorization
API
to
obtain
authorization
credentials
for
the
user.
Usage
tip
—
enforcing
user
lockout
policy
Authorization
API
clients
that
authenticate
users
sometimes
need
to
enforce
user
access
policy.
For
example,
a
local
mode
application
might
need
to
disable
(lockout)
a
user
account
after
a
specified
number
of
incorrect
login
attempts.
The
declaration
of
this
policy
can
be
placed
either
in
a
configuration
file
or
programmed
into
the
application
logic.
The
enforcement
of
some
policies,
such
as
disablement
of
a
user
account,
require
that
attributes
of
the
user
account
be
modified
within
the
user
registry.
In
order
to
modify
a
user
registry
entry,
the
application
must
have
modify
permissions
on
the
user
registry.
To
provide
these
permissions,
place
an
ACL
on
the
appropriate
objects
within
the
user
registry
to
enable
the
application
identity
(for
example,
an
LDAP
bind-id)
to
modify
those
objects.
Chapter
4.
Using
the
authorization
API
55
Obtaining
user
authorization
credentials
In
order
to
submit
an
authorization
request
to
the
Tivoli
Access
Manager
authorization
service,
an
application
must
obtain
authorization
credentials
for
the
user
making
the
request.
The
authorization
credentials
contain
user
identity
information
that
is
needed
to
make
authorization
decisions,
such
as
group
memberships
and
a
list
of
actions
or
rights
that
the
user
can
exercise.
To
obtain
credentials
for
a
user
who
has
submitted
an
access
request,
an
application
must
obtain
user
identity
information
from
the
user
registry
that
is
used
by
the
Tivoli
Access
Manager
secure
domain.
The
authorization
API
function
azn_id_get_creds()
takes
user
identity
information
as
input
parameters
and
returns
user
authorization
credentials.
The
credentials
can
then
be
submitted
to
the
authorization
service
for
an
authorization
decision.
Note:
Identity
information
can
also
be
obtained
from
a
privilege
attribute
certificate
(PAC).
See“Converting
credentials
to
the
native
format”
on
page
63.
To
obtain
a
credential,
complete
the
instructions
in
each
of
the
following
sections:
v
“Step
1
—
Specifying
the
authorization
authority
and
authentication
mechanism”
v
“Step
2
—
Specifying
user
authentication
identity”
v
“Step
3
—
Specifying
additional
user
information”
on
page
57
v
“Step
4
—
Placing
user
information
into
an
API
buffer”
on
page
57
v
“Step
5
—
Obtaining
authorization
credentials
for
the
user”
on
page
57
Step
1
—
Specifying
the
authorization
authority
and
authentication
mechanism
The
authorization
authority
is
the
name
of
the
secure
domain
into
which
the
authorization
API
client
will
be
configured.
Assign
the
appropriate
value
for
the
authorization
authority
to
a
string
of
type
azn_string_t.
This
string
is
passed
as
the
parameter
authzn_authority
to
azn_id_get_creds().
When
authzn_authority
is
NULL,
the
local
domain
specified
in
the
client’s
configuration
file
is
used.
If
it
is
specified,
then
the
authzn_authority
parameter
must
match
the
name
of
the
secure
domain
into
which
the
client
will
be
configured,
whether
this
is
the
default
Management
domain,
or
a
sub-domain
in
a
multiple
domain
environment.
For
more
information,
see
the
azn_id_get_creds()
reference
page.
The
authentication
mechanism
is
specified
in
the
mechanism_id
input
parameter.
Set
mechanism_id
to
NULL
to
specify
Tivoli
Access
Manager
authorization.
Step
2
—
Specifying
user
authentication
identity
For
each
user
to
be
authenticated,
information
is
loaded
into
the
data
structure
azn_authdefault_t.
If
the
user
is
authenticated,
you
must
load
the
user’s
identity
into
the
principal
string
(of
type
azn_string_t)
in
the
azn_authdefault_t
data
structure.
56
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
If
the
user
is
unauthenticated,
information
is
loaded
into
the
data
structure
azn_unauth_t.
You
do
not
have
to
load
an
identity
into
azn_unauth_t.
Step
3
—
Specifying
additional
user
information
When
the
application
authenticates
the
user,
the
application
can
optionally
obtain
additional
information
about
the
user.
This
additional
information
is
for
use
by
the
application
as
needed.
The
Tivoli
Access
Manager
authorization
service
does
not
use
this
information.
The
application
can
store
the
additional
user
information
in
the
data
structures
that
the
authorization
API
provides
for
each
type
of
authenticated
identity.
The
data
structures
are:
azn_authdefault_t,
and
azn_unauth_t.
The
elements
in
each
data
structure
are
character
strings,
with
the
exception
of
ipaddr,
which
is
an
integer.
Element
Description
authnmech_info
Additional
authentication
information.
This
value
can
be
any
string
that
is
useful
to
the
application.
Not
available
in
azn_unauth_t.
user_info
Additional
user
information
for
auditing
purposes.
This
string
can
contain
any
information
that
is
useful
to
the
application.
browser_info
Information
about
the
type
of
browser
through
which
the
user
has
submitted
the
request,
if
applicable.
This
string
can
contain
any
information
that
is
useful
to
the
application.
ipaddr
The
IP
address
of
the
user.
This
is
optional
information
for
use
by
the
application.
qop
The
quality
of
protection
required
for
requests
made
by
this
user.
Step
4
—
Placing
user
information
into
an
API
buffer
Place
the
data
structure
you
filled
out
in
“Step
2
—
Specifying
user
authentication
identity”
on
page
56
and
“Step
3
—
Specifying
additional
user
information”
into
an
authorization
API
buffer.
Complete
the
following
steps:
1.
Declare
a
buffer
of
type
azn_buffer_t:
typedef
struct
azn_buffer_desc_struct
{
size_t
length;
unsigned
char
*value;
}
azn_buffer_desc,
*azn_buffer_t;
2.
Determine
the
length
of
your
data
structure
and
assign
that
value
to
length.
3.
Set
the
pointer
value
to
point
to
the
address
of
your
data
structure.
This
buffer
is
passed
as
the
parameter
mechanism_info
to
azn_id_get_creds().
Step
5
—
Obtaining
authorization
credentials
for
the
user
To
obtain
authorization
credentials,
call
azn_id_get_creds()
with
the
following
input
parameters:
Chapter
4.
Using
the
authorization
API
57
Parameter
Description
authzn_authority
The
authorization
authority,
as
described
in
“Step
1
—
Specifying
the
authorization
authority
and
authentication
mechanism”
on
page
56.
mechanism_id
The
authentication
mechanism.
mechanism_info
User
information,
as
described
in
the
preceding
sections:
v
“Step
2
—
Specifying
user
authentication
identity”
on
page
56
v
“Step
3
—
Specifying
additional
user
information”
on
page
57
v
“Step
4
—
Placing
user
information
into
an
API
buffer”
on
page
57
The
azn_id_get_creds()
function
returns
a
handle
to
the
authorization
credentials
for
the
user.
The
authorization
credentials
are
contained
in
an
azn_creds_h_t
structure.
For
example,
the
following
sample
code
demonstrates
the
assigning
of
identity
information
for
a
user
authenticated
in
an
LDAP
user
registry,
and
calls
azn_id_get_creds()
to
obtain
authorization
credentials:
azn_authdefault_t
user_info;
azn_buffer_desc
buf
=
{
0,
0
};
azn_creds_h_t
creds
=
AZN_C_INVALID_HANDLE;
azn_creds_create(&creds);
/*
Specify
LDAP
user
name
*/
user_info.principal
=
“testuser”;
/*
Set
LDAP
user
information.
Note:
these
values
are
just
placeholders
*/
user_info.auth_method
=
“ldap_auth_method”;
user_info.authnmech_info
=
“ldap_authnmech_info”;
user_info.user_info
=
“ldap_user_info”;
user_info.browser_info
=
“ldap_browser_info”;
user_info.ipaddr
=
0x0a000002;
/*
Set
a
buffer
to
point
to
the
user
information
*/
buf.length
=
sizeof(user_info);
buf.value
=
(unsigned
char
*)&user_info;
/*
Obtain
an
authorization
credential.
*/
/*
Specify
the
authority
as
NULL
*/
/*
Specify
the
authentication
registry
(mech)
as
NULL
*/
status
=
azn_id_get_creds(NULL,
NULL,
&buf,
&creds);
if
(status
!=
AZN_S_COMPLETE)
{
fprintf(stderr,
“Could
not
get
creds.\n”);
continue;
}
For
more
information,
see
the
reference
page
for
“azn_id_get_creds()”
on
page
203.
Refer
also
to
the
authorization
API
demonstration
program.
The
application
is
now
ready
to
submit
the
authorization
request.
See
“Obtaining
an
authorization
decision”
on
page
59.
58
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
Obtaining
an
authorization
decision
After
the
application
has
obtained
authorization
credentials
for
the
user,
the
application
passes
the
requested
operation
and
the
requested
resource
to
the
authorization
API
function
azn_decision_access_allowed().
This
function
returns
the
authorization
decision.
To
obtain
an
authorization
decision,
complete
the
instructions
in
each
of
the
following
sections:
v
“Step
1
—
Mapping
the
user
operation
to
a
Tivoli
Access
Manager
permission”
v
“Step
2
—
Mapping
the
requested
resource
to
a
protected
object”
on
page
60
v
“Step
3
—
Assigning
the
user
credentials
to
a
credentials
handle”
on
page
60
v
“Step
4
—
Building
an
attribute
list
for
additional
application
information”
on
page
60
v
“Step
5
—
Obtaining
an
authorization
decision”
on
page
61
Step
1
—
Mapping
the
user
operation
to
a
Tivoli
Access
Manager
permission
The
operation
requested
by
the
user
must
correspond
to
one
of
the
operations
for
which
a
Tivoli
Access
Manager
permission
has
been
defined.
The
operation
is
a
standard
action
supported
in
all
Tivoli
Access
Manager
secure
domains.
Examples
operations
are
azn_operation_read
and
azn_operation_traverse.
Operations
can
be
concatenated
together
to
form
an
operations
string.
Operations
are
defined
in
ogauthzn.h:
azn_operation_attach
azn_operation_bypasspop
azn_operation_bypassrule
azn_operation_browse
azn_operation_control
azn_operation_traverse
azn_operation_delegation
azn_operation_view
azn_operation_modify
azn_operation_delete
azn_operation_server_admin
azn_operation_read
azn_operation_execute
azn_operation_list_directory
azn_operation_connect
azn_operation_forward
azn_operation_password
azn_operation_create
azn_operation_add
azn_operation_trace
Alternatively,
you
can
assign
a
simple
string
to
the
operation
input
parameter.
For
example,
the
string
value
Tr
conveys
the
same
information
as
concatenating
azn_operation_traverse
and
azn_operation_read
.
Alternatively,
the
operation
can
be
a
custom
operation.
v
Assign
the
operation
to
a
string
named
operation.
v
Pass
this
string
as
an
input
parameter
to
azn_decision_access_allowed()
or
azn_decision_access_allowed_ext().
Chapter
4.
Using
the
authorization
API
59
Step
2
—
Mapping
the
requested
resource
to
a
protected
object
The
requested
resource
to
query
for
must
correspond
to
a
resource
that
has
been
defined
as
a
protected
object
in
the
secure
domain’s
protected
object
namespace.
The
resource
can
be
a
standard
WebSEAL
protected
resource,
such
as
a
file
in
the
Web
space.
Alternatively,
the
resource
can
be
a
custom
protected
object.
Complete
the
following
steps:
v
Assign
the
protected
object
to
the
string
protected_resource.
v
Pass
this
string
as
an
input
parameter
to
azn_decision_access_allowed().
Step
3
—
Assigning
the
user
credentials
to
a
credentials
handle
The
authorization
credentials
for
a
user
obtained
in
“Obtaining
user
authorization
credentials”
on
page
56
can
be
accessed
through
the
handle
returned
by
azn_id_get_creds().
These
credentials
contain
the
user’s
identity
information
and
include
information
such
as
the
user’s
group
membership
and
permitted
operations.
Complete
the
following
step:
v
Pass
the
handle
returned
by
azn_id_get_creds()
as
an
input
parameter
to
azn_decision_access_allowed().
Note:
Authorization
credentials
can
also
be
obtained
from
the
function
azn_pac_get_creds().
For
more
information,
see
“Converting
credentials
to
the
native
format”
on
page
63.
Step
4
—
Building
an
attribute
list
for
additional
application
information
The
Tivoli
Access
Manager
authorization
API
provides
the
extended
function
azn_decision_access_allowed_ext()
for
obtaining
an
access
decision.
This
function
extends
azn_decision_access_allowed()
by
providing
an
additional
input
parameter
and
an
additional
output
parameter.
These
parameters
can
be
used
to
supply
additional
information
as
needed
by
the
application.
The
Tivoli
Access
Manager
authorization
service
does
not
use
these
parameters
when
making
the
access
control
decision.
However,
you
can
write
external
authorization
servers
to
use
this
information.
The
parameters
consist
of
an
attribute
list.
You
can
build
an
attribute
list
of
any
length
to
hold
information
specific
to
the
application.
To
add
additional
application-specific
context,
complete
the
following
steps:
1.
Use
azn_attrlist_create()
to
create
a
new,
empty
attribute
list.
2.
Use
azn_attrlist_add_entry()
or
azn_attrlist_add_entry_buffer()
to
add
attributes.
3.
When
all
attributes
have
been
added,
assign
the
input
parameter
app_context
to
point
to
the
attribute
list.
60
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
For
more
information,
see
the
reference
page
for
“azn_decision_access_allowed_ext()”
on
page
194.
Step
5
—
Obtaining
an
authorization
decision
To
obtain
an
authorization
decision,
call
one
of
the
following
functions:
v
azn_decision_access_allowed()
v
azn_decision_access_allowed_ext()
If
the
API
is
operating
in
remote
cache
mode,
the
authorization
request
will
be
forwarded
to
the
Tivoli
Access
Manager
authorization
server.
The
authorization
server
makes
the
decision
and
returns
the
result.
If
the
API
is
operating
in
local
cache
mode,
the
API
uses
the
local
authorization
policy
database
replica
to
make
the
authorization
decision.
The
result
of
the
access
request
is
returned
in
the
following
output
parameter:
Type
Parameter
Description
int
permission
The
result
of
the
access
request.
Consists
of
one
of
the
following
constants:
AZN_C_PERMITTED
AZN_C_NOT_PERMITTED
The
extended
function
azn_decision_access_allowed_ext()
also
returns
the
following
information:
Type
Parameter
Description
azn_attrlist_h_t
*permission_info
Application-specific
context
information
contained
in
attribute
list.
For
more
information,
see
the
reference
pages
for
the
following
functions:
v
“azn_decision_access_allowed()”
on
page
192
v
“azn_decision_access_allowed_ext()”
on
page
194
Chapter
4.
Using
the
authorization
API
61
Cleaning
up
and
shutting
down
The
authorization
API
provides
functions
to
perform
the
following
clean
up
and
shut
down
functions:
v
“Releasing
allocated
memory”
v
“Shutting
down
the
authorization
API”
Releasing
allocated
memory
The
authorization
API
provides
the
following
functions
to
perform
the
releasing
of
memory
functions:
v
azn_attrlist_delete()
Use
this
function
to
release
memory
that
is
allocated
for
attribute
lists.
v
azn_attrlist_delete_entry()
Use
this
function
to
delete
an
entry
from
an
attribute
list.
v
azn_creds_delete()
Use
this
function
to
release
memory
that
is
allocated
for
the
azn_creds_h_t
structure
that
is
returned
by
a
call
to
azn_creds_create().
v
azn_release_buffer()
Use
this
function
to
release
memory
that
is
allocated
for
buffers
of
type
azn_buffer_t.
Buffers
of
this
type
are
used
by
some
attribute
list
functions,
and
also
by
some
of
the
credentials
handling
functions.
v
azn_release_pboj()
Use
this
function
to
release
memory
that
is
allocated
for
the
azn_pobj_t
structure
that
is
returned
by
a
call
to
azn_attrlist_entry_get_pobj_value().
v
azn_release_string()
Use
this
function
to
release
memory
allocated
for
any
strings
of
type
azn_string_t.
Many
authorization
API
functions
use
this
data
type
to
store
values
in
strings.
v
azn_release_strings()
Use
this
function
to
release
memory
allocated
for
an
array
of
strings
of
type
azn_string_t.
Shutting
down
the
authorization
API
When
an
application
has
obtained
an
authorization
decision
and
when
it
does
not
need
further
authorization
decisions,
use
azn_shutdown()
to
disconnect
from
and
shut
down
the
authorization
API.
62
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
Working
with
credentials
In
addition
to
the
credentials
handling
tasks
described
earlier
in
this
chapter,
the
authorization
API
provides
functions
to
accomplish
the
following
optional
tasks:
v
“Converting
credentials
to
a
transportable
format”
v
“Converting
credentials
to
the
native
format”
v
“Creating
a
chain
of
credentials”
v
“Determining
the
number
of
credentials
in
a
credentials
chain”
on
page
64
v
“Obtaining
a
credential
from
a
chain
of
credentials”
on
page
64
v
“Modifying
the
contents
of
a
credential”
on
page
64
v
“Obtaining
an
attribute
list
from
a
credential”
on
page
65
v
“Setting
and
getting
string
attribute
values
for
a
credential”
on
page
66
v
“Comparing
two
credentials”
on
page
67
v
“Copying
a
credential”
on
page
67
Converting
credentials
to
a
transportable
format
Use
the
function
azn_creds_get_pac()
to
place
user
credentials
into
a
format
that
can
be
transported
across
a
network
to
another
application.
Use
this
function
when
you
need
to
delegate
the
authorization
decision
to
an
application
on
another
system.
Complete
the
following
steps:
1.
Set
the
input
string
pac_svc_id
to
NULL.
2.
Set
the
input
credentials
handle
creds
to
the
credentials
handle
returned
by
a
previous
call
to
azn_id_get_creds()
or
azn_pac_get_creds().
3.
Call
azn_creds_get_pac().
The
privilege
attribute
certificate
(PAC)
is
returned
in
an
output
buffer
named
pac.
This
buffer
can
be
transported
to
another
system,
where
the
function
azn_pac_get_creds()
can
be
used
to
return
the
credentials
to
a
native
format.
Converting
credentials
to
the
native
format
Use
the
function
azn_pac_get_creds()
when
an
application
receives
credentials
from
another
system
on
the
network.
Typically,
these
credentials
are
placed
into
a
buffer
by
azn_creds_get_pac().
Complete
the
following
steps:
1.
Set
the
input
string
pac_svc_id
to
NULL.
2.
Set
the
input
buffer
pac
to
the
buffer
returned
by
a
previous
call
to
azn_creds_get_pac().
3.
Call
azn_pac_get_creds().
This
function
returns
a
handle
to
a
credentials
structure
of
type
azn_creds_h_t,
for
access
by
other
authorization
API
functions.
Creating
a
chain
of
credentials
Use
the
function
azn_creds_combine
to
combine,
or
chain,
two
credentials
together.
Use
this,
for
example,
when
the
credentials
for
a
server
application
must
be
combined
with
user
credentials
in
order
to
delegate
the
authorization
decision
to
another
application.
Chapter
4.
Using
the
authorization
API
63
Complete
the
following
steps:
1.
Assign
the
credentials
handle
creds_to_prepend
to
point
to
the
credentials
of
the
initiator
of
the
request.
2.
Assign
the
credentials
handle
creds_to_add
to
point
to
the
credentials
to
be
added.
3.
Call
azn_creds_create()
to
create
a
new,
empty
credentials
structure.
4.
Call
azn_creds_combine().
The
combined
credentials
are
placed
in
a
credentials
structure
that
can
be
referenced
by
the
credentials
handle
combined_creds.
Determining
the
number
of
credentials
in
a
credentials
chain
Use
the
function
azn_creds_num_of_subjects()
to
determine
the
number
of
credentials
that
are
contained
in
a
credentials
chain.
Credentials
chains
are
created
by
the
azn_creds_combine()
function.
This
functions
takes
as
an
input
parameter
the
credentials
handle
of
the
credentials
chain,
and
returns
an
integer
containing
the
number
of
credentials.
Obtaining
a
credential
from
a
chain
of
credentials
Use
the
function
azn_creds_for_subject()
to
extract
individual
credentials
from
a
credentials
chain.
Credentials
chains
are
created
by
the
azn_creds_combine()
function.
Complete
the
following
steps:
1.
Assign
the
credentials
handle
creds
to
point
to
the
credentials
chain.
2.
Assign
the
integer
subject_index
the
index
of
the
needed
credential
within
the
credentials
chain.
The
credentials
of
the
user
who
made
the
request
are
always
stored
at
index
0.
To
retrieve
the
credentials
for
the
initiator
(user),
you
can
pass
the
constant
AZN_C_INITIATOR_INDEX
as
the
value
for
subject_index.
Use
azn_creds_num_of_subjects(),
if
necessary,
to
determine
the
number
of
credentials
in
the
chain.
3.
Call
azn_creds_for_subject().
This
function
returns
the
requested
credentials
in
the
credentials
structure
new_creds.
Modifying
the
contents
of
a
credential
Use
the
function
azn_creds_modify()
and
the
default
credential
modification
service
to
modify
a
credential
by
placing
additional
information,
contained
in
an
attribute
list,
into
the
credentials
structure.
Use
this
function
when
you
need
to
add,
delete,
or
modify
application-specific
information
in
a
user’s
credentials.
The
effect
of
this
call
is
to
replace
the
existing
credential
attribute
list
with
the
new
attribute
list
supplied.
Complete
the
following
steps:
1.
Use
the
attribute
list
functions
to
create
an
attribute
list
containing
the
information
to
be
added.
(Alternatively,
you
can
use
azn_creds_get_attrlist_for_subject()
to
obtain
a
handle
to
an
existing
attribute
list.)
Assign
the
attribute
list
handle
mod_info
to
the
new
attribute
list.
64
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
For
more
information
on
attribute
lists,
see
the
section
“Attribute
lists”
on
page
18.
2.
Set
the
credential
modification
service
mod_svc_id
to
NULL.
This
invokes
the
default
credential
modification
service,
which
replaces
the
existing
attribute
list
in
the
credential
with
the
new
attribute
list
passed
as
mod_info.
3.
Assign
the
credentials
handle
creds
to
point
to
the
credentials
to
be
modified.
4.
Call
azn_creds_modify(),
passing
the
credential
to
be
modified
in
the
creds
parameter
and
the
attribute
list
that
will
replace
the
credential’s
existing
attribute
list
in
the
mod_info
parameter.
The
modified
credentials
are
placed
in
the
credentials
structure
new_creds.
Note
that
the
following
attributes
are
considered
read-only
and
must
not
be
modified
by
azn_creds_modify():
v
azn_cred_principal_uuid
v
azn_cred_principal_name
v
azn_cred_principal_domain
v
azn_cred_version
v
azn_cred_mech_id
v
azn_cred_group_uuids
v
azn_cred_group_names
v
azn_cred_authzn_id
v
azn_cred_ldap_dn
Obtaining
an
attribute
list
from
a
credential
Use
the
function
azn_creds_get_attrlist_for_subject()
to
obtain
information,
in
the
form
of
an
attribute
list,
from
a
credential.
You
can
use
this
function
to
obtain
the
attribute
list
for
a
credential
that
is
part
of
a
credentials
chain
as
well.
Entire
attribute
lists
can
be
added
or
modified
within
the
credential
structures
by
using
the
azn_creds_modify()
function.
Single
string
attributes
can
be
set
and
retrieved
by
using
the
azn_creds_set_attr_value_string()
and
azn_creds_get_attr_value_string()
functions,
respectively.
The
authorization
API
defines
a
number
of
attributes
that
can
be
returned
in
the
attribute
list.
Some
of
the
attributes
might
not
be
present
in
an
attribute
list
according
to
the
type
of
authenticated
user
and
the
information
that
was
used
when
the
credential
was
built.
The
defined
attributes
are:
"AUTHENTICATION_LEVEL"
azn_cred_auth_method
azn_cred_authnmech_info
azn_cred_authzn_id
azn_cred_browser_info
azn_cred_group_registry_ids
azn_cred_group_uuids
azn_cred_groups
azn_cred_ip_address
azn_cred_mech_id
azn_cred_principal_domain
azn_cred_principal_name
azn_cred_principal_uuid
azn_cred_qop_info
azn_cred_registry_id
azn_cred_user_info
azn_cred_version
Chapter
4.
Using
the
authorization
API
65
For
a
description
of
each
of
the
defined
attributes,
see
“Credential
attributes”
on
page
261.
Complete
the
following
steps:
1.
Assign
the
credentials
handle
creds
to
point
to
the
credentials
chain.
2.
Assign
the
integer
subject_index
to
the
index
of
the
credential
within
the
credentials
chain.
If
the
credential
is
not
part
of
a
chain,
set
subject_index
to
0.
The
credentials
of
the
user
who
made
the
request
are
always
stored
at
index
0.
To
retrieve
the
credentials
for
the
initiator
(user),
you
can
pass
the
constant
AZN_C_INITIATOR_INDEX
as
the
value
for
subject_index.
Use
azn_creds_num_of_subjects(),
if
necessary,
to
determine
the
number
of
credentials
in
the
chain.
3.
Call
azn_attrlist_create()
to
create
a
new,
empty
attribute
list.
4.
Call
azn_creds_get_attrlist_for_subject().
The
function
returns
a
pointer
to
a
handle
to
the
attribute
list
containing
the
credential’s
attribute
information.
The
handle
is
named
creds_attrlist.
Setting
and
getting
string
attribute
values
for
a
credential
The
azn_creds_get_attr_value_string()
and
azn_creds_set_attr_value_string()
functions
are
provided
for
manipulating
a
single
string
attribute
within
a
credential.
Use
the
function
azn_creds_get_attr_value_string()
to
obtain
the
string
value
of
a
specified
attribute
in
a
credential.
This
function
accesses
the
attribute
list
for
a
specified
credential,
and
returns
the
string
value
of
the
specified
attribute.
Use
the
function
azn_creds_set_attr_value_string()
to
set
the
value
of
a
specified
attribute
in
the
user
credential.
This
function
edits
the
attribute
list
of
the
specified
credential
and
sets
the
attribute
to
the
specified
string
value.
Note
that
the
following
attributes
are
considered
read-only
and
must
not
be
modified
by
azn_creds_set_attr_value_string():
v
azn_cred_principal_uuid
v
azn_cred_principal_name
v
azn_cred_principal_domain
v
azn_cred_version
v
azn_cred_mech_id
v
azn_cred_group_uuids
v
azn_cred_group_names
v
azn_cred_authzn_id
v
azn_cred_ldap_dn
Note:
To
work
with
attribute
values
other
than
strings,
or
to
work
with
more
than
one
attribute
within
the
credential
at
a
time,
you
should
use
the
azn_creds_get_attrlist_for_subject()
and
azn_creds_modify()
functions
instead.
See
“Modifying
the
contents
of
a
credential”
on
page
64.
66
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
For
more
information,
see
the
reference
pages
for
“azn_creds_set_attr_value_string()”
on
page
190
and
“azn_creds_get_attr_value_string()”
on
page
180.
Comparing
two
credentials
Use
the
function
azn_creds_equal()
to
compare
the
contents
of
two
credentials.
1.
Identify
the
credentials
handles
(azn_creds_h_t)
for
each
credential
to
be
compared.
2.
Pass
the
credentials
handles
as
input
parameters
to
azn_creds_equal().
The
function
azn_creds_eqaul()
returns
a
boolean
value
of
type
azn_boolean_t.
The
value
is
true
if
the
credentials
are
identical
or
false
if
the
credentials
differ.
Copying
a
credential
Use
the
azn_creds_copy()
function
to
copy
the
contents
of
one
credentials
to
another,
new
credentials.
The
azn_creds_copy()
function
does
not
actually
make
another
copy
of
the
credentials,
it
merely
creates
a
new
handle
to
the
credentials.
Tivoli
Access
Manager
releases
the
storage
associated
with
the
credentials
after
the
last
handle
to
the
credentials
is
released.
1.
Identify
the
credentials
handles
(azn_creds_h_t)
for
the
credential
to
be
copied.
2.
Pass
the
credentials
handle
as
the
input
parameter
to
azn_creds_copy().
The
azn_creds_copy()
function
returns
a
new
credentials
handle
to
the
credential.
When
the
application
is
finished
using
the
new
credential,
use
azn_creds_delete()
to
release
the
handle.
The
storage
for
the
credentials
is
released
after
all
handles
have
been
released.
Note:
To
add
a
credential
to
an
existing
credential,
use
the
azn_creds_combine()
function.
Chapter
4.
Using
the
authorization
API
67
68
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
Chapter
5.
Backwards
compatibility
and
application
migration
IBM
Tivoli
Access
Manager
(Tivoli
Access
Manager)
Base
Version
5.1
is
binary
backwards
compatible
to
existing
Tivoli
Access
Manager
Versions
4.1
and
Version
3.9.
Existing
authorization
API
clients
that
are
being
migrated
to
use
the
Tivoli
Access
Manager
Base
Version
5.1
ADK
must
run
the
svrsslcfg
utility
again.
You
should
use
the
sample
configuration
file
aznAPI.conf,
which
is
provided
with
the
authorization
API
demonstration
program,
as
the
base
to
create
the
authorization
API
configuration
file.
When
the
svrsslcfg
configuration
is
complete
you
can
merge
the
configuration
file
entries
into
the
new
aznAPI.conf
file
as
required.
Where
possible
you
may
need
to
translate
entries
from
the
configuration
file
entries
of
an
older
client
version
to
the
new
configuration
file
format.
You
might
receive
errors
for
some
interfaces
when
compiling
existing
authorization
API
clients
with
the
Tivoli
Access
Manager
Version
5.1
ADK.
This
is
because
some
of
the
authorization
API
interfaces
from
Version
3.9
and
Version
4.1
have
been
deprecated
for
Version
5.1.
The
deprecated
interfaces
are
located
in
the
azn_deprecated.h
header
file.
You
can
look
in
theazn_deprecated.h
file
to
determine
the
new
interface
that
replaces
each
deprecated
interface.
You
can
also
review
the
section
“Deprecated
API
elements”
on
page
70.
In
the
short
term,
you
can
compile
with
the
azn_deprecated.h
header
file
to
continue
to
use
the
deprecated
Version
3.9
and
Version
4.1
interfaces.
However,
you
should
switch
as
soon
as
possible
to
the
new
interfaces,
to
avoid
further
problems.
This
chapter
contains
the
following
sections:
v
“Binary
backwards
compatibility”
on
page
70
v
“Deprecated
API
elements”
on
page
70
©
Copyright
IBM
Corp.
2000,2003
69
Binary
backwards
compatibility
The
Tivoli
Access
Manager
Version
5.1
runtime
environment
supports
applications
compiled
against
the
following
Tivoli
Access
Manager
application
development
kits
(ADKs):
v
Tivoli
Access
Manager
Version
4.1
v
Tivoli
Access
Manager
Version
3.9
Deprecated
API
elements
This
section
describes
elements
of
the
authorization
API
that
have
been
deprecated.
The
deprecated
elements
are
supported
for
backwards
compatibility
in
Tivoli
Access
Manager
Version
5.1.
Application
developers
should
not
use
any
deprecated
elements
in
new
applications
Deprecated
attributes
for
Version
5.1
Deprecated
attribute
Replacement
attribute
azn_cred_group_names
azn_cred_groups
azn_cred_ldap_dn
azn_cred_group_registry_ids
azn_pac_svc_dce_epac
none
azn_perminfo_qop_uint
azn_perminfo_qop_ulong
azn_perminfo_qop_uint_none
azn_perminfo_qop_value_none
azn_perminfo_qop_uint_integrity
azn_perminfo_qop_value_integrity
azn_perminfo_qop_uint_privacy
azn_perminfo_qop_value_privacy
azn_perminfo_al_ulong
azn_perminfo_auditlevel_ulong
azn_perminfo_wm_ulong
azn_perminfo_warningmode_ulong
azn_perminfo_wm_permitted_ulong
azn_perminfo_warmingmodepermitted_ulong
unsigned
int
azn_perminfo_al_none
azn_perminfo_auditlevel_none
unsigned
int
azn_perminfo_al_permit
azn_perminfo_auditlevel_permit
unsigned
int
azn_perminfo_al_deny
azn_perminfo_auditlevel_deny
unsigned
int
azn_perminfo_al_error
azn_perminfo_auditlevel_error
unsigned
int
azn_perminfo_al_admin
azn_perminfo_auditlevel_admin
unsigned
int
azn_perminfo_al_all
azn_perminfo_auditlevel_all
IV_DCE
none
IV_LDAP
none
IV_URAF
none
IV_UNAUTH
none
Operation
attributes
Deprecated
Replacement
azn_operation_bypasstod
azn_operation_bypasspop
70
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
Permission
info
attribute
values
The
following
values
for
the
azn_init_set_perminfo_attrs
attribute
have
been
deprecated:
v
azn_perminfo_wm
Replaced
by
azn_perminfo_wm_ulong.
v
azn_perminfo_wm_permitted
Replaced
by
azn_perminfo_wm_permitted_ulong
v
azn_perminfo_al
Replaced
by
azn_perminfo_al_ulong
The
above
attributes
are
passed
as
input
parameters
to
azn_initialize().
Each
of
the
deprecated
attributes
has
a
corresponding
attribute
that
is
returned
by
the
permission_info
output
parameter
of
the
azn_decision_access_allowed_ext()
function
call.
The
corresponding
attributes
have
been
deprecated
also.
The
deprecated
attributes
do
not
work
when
the
remote
authorization
API
client
and
the
Authorization
server
are
on
operating
system
platforms
that
implement
different
Endian
ordering.
Remote
authorization
API
clients
no
longer
receive
the
azn_perminfo_qop
and
azn_perminfo_qop_int
attributes
by
default.
To
enable
this
support,
you
must
specify
these
attributes
in
the
authorization
server’s
configuration
file
ivacld.conf.
To
specify
these
attributes,
uncomment
the
following
line
in
the
configuration
file:
#permission-info-returned
=
azn_perminfo_qop
azn_perminfo_qop_ulong
Initialization
attributes
The
following
initialization
attribute
has
been
deprecated:
v
Attribute
List
Entry:
azn_init_master_dn
v
Configuration
File
Entry:
master-dn
The
configuration
file
entry
was
located
in
the[manager]
stanza.
When
specifying
communication
attributes
for
the
policy
server,
it
is
no
longer
necessary
to
supply
the
policy
server
distinguished
name.
Deprecated
API
for
comparing
credentials
The
API
for
comparing
credentials
have
been
deprecated.
v
azn_creds_compare()
The
azn_creds_compare()
API
has
been
replaced
by
azn_creds_equal().
You
should
use
azn_creds_equal()
because
it
returns
an
azn_status_t
return
code,
which
can
be
used
to
handle
API
execution
failures.
Obtaining
the
user’s
authorization
identification
The
new
attribute
azn_cred_authzn_id
replaces
the
following
attributes:
v
azn_cred_dce_name
v
azn_cred_uraf_name
The
attribute
azn_cred_ldap_dn
remains
a
valid
attribute
specific
to
LDAP
but
does
not
now
perform
the
same
function
as
azn_cred_authzn_id.
The
Chapter
5.
Backwards
compatibility
and
application
migration
71
azn_cred_ldap_dn
attribute
is
now,
for
LDAP
credentials
only,
defined
to
be
the
LDAP
Distinguished
Name
(DN)
of
the
principal
Authorization
API
initialization
attributes
The
following
attributes
have
been
deprecated.
These
attributes
formerly
were
passed
as
parameters
to
azn_initialize().
v
azn_init_namespace_location
v
azn_init_tcp_port
v
azn_init_udp_port
v
azn_init_qop
v
azn_init_remote_ns_loc
v
azn_init_max_handle_groups
The
following
configuration
file
entries
have
been
deprecated.
These
configuration
file
entries
correspond
to
each
of
the
attributes
in
the
list
above.
v
namespace-location
v
tcp-port
v
udp-port
v
remote-qop
v
remote-ns-loc
v
max-handle-groups
DCE
authentication
APIs
The
following
DCE
authentication
APIs
have
been
deprecated:
v
azn_util_server_authenticate()
v
azn_util_client_authenticate()
When
called,
these
functions
now
return
the
error
code
AZN_S_UNIMPLEMENTED_FUNCTION.
Applications
are
now
authenticated
as
part
of
azn_initialize().
User
registry
information
The
new
data
structure
azn_authdefault_t
contains
credential
and
other
information
used
within
the
Tivoli
Access
Manager
secure
domain.
This
data
structure
replaces
the
following
deprecated
data
structures:
v
azn_authdce_t
v
azn_authldap_t
v
azn_authuraf_t
Deprecated
return
codes
The
following
minor
error
codes
have
been
deprecated:
v
AZN_ENT_PDPOBJ_INVALID_SVCINFO_HDL
v
AZN_ENT_PDPOBJ_INVALID_ARG_COUNT
v
AZN_ENT_PDPOBJ_ARG_ARRAY
v
AZN_ENT_PDPOBJ_OUT_OF_MEMORY
v
AZN_ENT_PDPOBJ_INVALID_ARGUMENT
v
AZN_PAC_EPAC_INVALID_SVCINFO_HDL
72
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
v
AZN_PAC_EPAC_INVALID_ARG_COUNT
v
AZN_PAC_EPAC_ARG_ARRAY
v
AZN_PAC_EPAC_OUT_OF_MEMORY
v
AZN_PAC_EPAC_INVALID_ARGUMENT
The
following
return
codes
have
been
replaced
by
major
error
codes
defined
in
ogauthzn.h.
v
AZN_S_SVC_ENT_INVALID_SVCINFO_HDL
v
AZN_S_SVC_ENT_INVALID_ARG_COUNT
v
AZN_S_SVC_ENT_ARG_ARRAY
v
AZN_S_SVC_ENT_OUT_OF_MEMORY
v
AZN_S_SVC_ENT_INVALID_ARGUMENT
v
AZN_S_SVC_PAC_INVALID_SVCINFO_HDL
v
AZN_S_SVC_PAC_INVALID_ARG_COUNT
v
AZN_S_SVC_PAC_ARG_ARRAY
v
AZN_S_SVC_PAC_OUT_OF_MEMORY
v
AZN_S_SVC_PAC_INVALID_ARGUMENT
Chapter
5.
Backwards
compatibility
and
application
migration
73
74
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
Chapter
6.
Authorization
service
plug-ins
The
IBM
Tivoli
Access
Manager
(Tivoli
Access
Manager)
authorization
API
supports
a
service
plug-in
model.
This
model
enables
developers
to
write
plug-in
modules
that
extend
the
capabilities
of
the
Tivoli
Access
Manager
authorization
service.
Developers
of
third
party
applications
can
use
authorization
API
functions
that
access
the
service
plug-in
interface
to
perform
authorization
operations
that
are
specific
to
the
Tivoli
Access
Manager
secure
domain.
This
chapter
contains
the
following
sections:
v
“Service
plug-in
architecture”
on
page
76
v
“Implementing
a
service
plug-in”
on
page
81
v
“Supplied
implementations
for
service
plug-ins”
on
page
96
©
Copyright
IBM
Corp.
2000,2003
75
Service
plug-in
architecture
The
Authorization
service
plug-in
Architecture
features
the
following
objects:
v
Authorization
service
plug-in
dispatcher
v
Service
plug-in
modules
v
Calling
applications
When
an
external
application
needs
authorization
information,
it
sends
a
request
to
the
service
dispatcher.
The
service
dispatcher
vectors
the
request
to
the
appropriate
service
plug-in.
The
architecture
for
each
type
of
service
plug-in
may
expand
the
architecture
model
illustrated
above.
For
example,
the
administration
service
presents
some
extensions,
as
shown
in
Figure
4
on
page
125.
Access ManagerPolicy Server
Access Manager Administration API
pdadmin
AccessManager
Web PortalManager
UserApplication
or GUI
CredentialsModification
ServicePlug-in
databasedatabase
PrivilegeAttribute
CertificateServicePlug-in
EntitlementsServicePlug-in
ExternalAuthorization
ServicePlug-in
AdministrationServicePlug-in
User Application
Authorization API Client
Service Dispatcher
Authorization APIAdministration
Service APIInterface
AuthorizationEngine
Figure
3.
Authorization
service
plug-in
Architecture
76
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
The
authorization
service
dispatcher
The
authorization
service
dispatcher
is
a
service
of
the
authorization
API
library.
The
dispatcher
is
the
management
layer
between
authorization
API
interfaces
and
the
service
plug-in
modules.
The
dispatcher
manages
the
location,
configuration
and
loading
of
available
service
plug-ins.
The
service
dispatcher
performs
the
following
tasks:
v
Initializes
each
configured
service
plug-in.
v
Directs
authorization
API
interface
calls
to
the
specified
service
plug-in.
v
Receives
returned
information
from
the
service
plug-in
and
returns
it
to
the
calling
application.
v
Shuts
down
each
configured
service
plug-in
when
the
authorization
API
is
shut
down.
Authorization
service
plug-ins
Authorization
service
plug-ins
are
shared
libraries
written
by
application
developers.
Developers
create
these
libraries
to
implement
a
domain-specific
task
for
the
domain-specific
application.
The
types
of
data
passed
between
the
service
plug-in
and
the
application
are
also
domain-specific.
This
means
that
the
only
restrictions
on
the
data
types
are
the
parameter
definitions
in
the
authorization
API
service
functions.
The
data
can
be
in
a
format
that
is
unknown
to
the
Tivoli
Access
Manager
authorization
server.
The
data
is
passed
unchanged
through
the
authorization
service
dispatcher
to
the
authorization
service
plug-ins.
Authorization
service
plug-ins
are
identified
by
a
unique
identification
number
(ID).
The
service
dispatcher
uses
the
unique
ID
number
to
load
the
service
plug-in.
The
service
dispatcher
can
optionally
pass
initialization
parameters
to
the
service
plug-in.
The
service
plug-in
can
optionally
return
service
information,
such
as
the
plug-in
version
number,
to
the
service
dispatcher.
Calling
applications
Applications
may
choose
to
use
information
received
from
service
plug-ins
to
make
authorization
decisions
without
requiring
access
to
databases
maintained
by
the
Tivoli
Access
Manager
authorization
server.
In
general,
the
service
plug-in
framework
operates
independently
from
the
authorization
functionality.
The
exception
to
this
is
External
Authorization
Services
which
can
only
be
invoked
in
the
course
of
making
an
access
decision
from
an
azn_decision_*
interface.
The
application
invokes
an
authorization
API
function
that
is
specific
to
the
type
of
service.
For
example,
to
obtain
entitlements
information,
the
calling
application
calls
azn_entitlement_get_entitlements().
The
API
call
is
processed
by
the
service
dispatcher
and
forwarded
to
the
appropriate
service
plug-in.
The
service
performs
basic
error
checking
on
the
passed
parameters,
to
ensure
that
all
handles
are
valid.
Handles
can
be
either
input
parameters
or
output
parameters.
An
input
parameter
is
valid
when
the
handle
was
either:
v
Created
by
a
call
to
azn_creds_create()
v
Created
by
a
call
to
azn_attrlist_create()
v
Returned
as
output
from
an
authorization
API
function
Chapter
6.
Authorization
service
plug-ins
77
If
the
handle
is
an
output
parameter,
then
its
valid
values
also
include
an
initialization
to
AZN_C_INVALID_HANDLE.
The
following
table
lists
the
handles
that
must
be
valid:
Service
API
Function
Invoked
By
the
Calling
Application
Handle
Entitlements
azn_svc_entitlement_get_entitlements()
entitlements
Output
parameter.
Credentials
Modification
azn_svc_creds_modify()
creds
Input
parameter.
new_creds
Output
parameter.
Privilege
Attribute
Certificate
azn_svc_pac_get_creds()
new_creds
Output
parameter.
azn_svc_creds_get_pac()
pac
Output
parameter.
Administration
ivadmin_protobj_get2()
ivadmin_protobj_list3()
ivadmin_server_gettasklist()
ivadmin_server_performtask()
creds
indata
outdata
The
creds
and
indata
parameters
are
input
parameters.
The
outdata
parameter
is
an
output
parameter.
External
authorization
azn_svc_decision_access_allowed_ext()
creds
app_context
permission_info
The
creds
and
app_context
parameters
are
input
parameters.
The
permission_info
parameter
is
an
output
parameter.
Applications
are
responsible
for
initializing
and
shutting
down
the
authorization
API.
To
do
this,
applications
call
the
authorization
API
functions
azn_initialize()
and
azn_shutdown().
These
functions
call
the
appropriate
functions
for
initializing
and
shutting
down
the
service
plug-ins.
For
some
services,
Tivoli
Access
Manager
provides
a
default
service.
For
all
other
services,
the
application
must
specify
a
service
ID
as
a
parameter
to
the
appropriate
API
service
function
interface.
For
example,
custom
entitlement
services
can
be
invoked
from
an
application
by
calling
the
azn_entitlement_get_entitlements()
API
interface
with
the
service
ID
of
the
required
entitlement
service.
Authorization
service
plug-ins
automatically
inherit
the
codeset
of
the
application
because
they
are
loaded
into
the
address
space
of
the
authorization
client
78
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
application.
The
service
plug-ins
cannot
run
in
a
different
codeset
to
the
application
that
is
loading
them.
Authorization
services
can
determine
the
codeset
of
the
calling
application
from
the
value
of
the
azn_svc_init_code_set
initialization
attribute.
This
attribute
is
passed
to
the
service
plug-in
by
the
service
dispatcher
at
initialization
time.
The
service
plug-in
receives
this
attribute
in
the
svcInit
attribute
list
passed
to
its
azn_svc_initialize()
interface.
Supported
types
of
service
plug-ins
The
authorization
service
supports
these
types
of
service
plug-ins:
v
Entitlement
service
v
Credentials
modification
service
v
Privilege
attribute
certificate
(PAC)
service
v
Administration
service
v
External
authorization
service
The
authorization
API
provides
common
initialization
and
shutdown
interface
calls
for
use
by
the
service
plug-ins.
The
authorization
API
also
provides
additional
interfaces
that
are
specific
to
each
of
the
service
plug-ins.
Entitlement
services
An
entitlement
service
plug-in
enables
domain-specific
authorization
API
applications
to
retrieve
the
entitlements
for
a
user
from
a
domain-specific
policy
repository.
The
application
can
use
this
entitlements
information
as
needed.
For
example:
v
An
application
can
allow
or
deny
a
user
request
for
access
to
a
protected
action
or
protected
resource,
based
on
the
user’s
entitlements.
v
A
graphical
user
interface
application
can
use
entitlements
information
to
construct
a
graphical
view
of
the
Tivoli
Access
Manager
secure
domain
that
contains
only
those
protected
objects
that
the
user
is
authorized
to
view.
Tivoli
Access
Manager
5.1
also
supports
two
sub-classes
of
entitlement
service
known
as
the
dynamic
ADI
retrieval
service
and
the
credential
attribute
service.
For
more
information
on
dynamic
ADI
retrieval
services,
see
“Dynamic
ADI
retrieval
services”
on
page
110.
For
information
on
the
credential
attribute
entitlement
service,
see
“Credential
attributes
entitlement
service”
on
page
112
Credentials
modification
service
A
credentials
modification
service
plug-in
enables
domain-specific
authorization
API
applications
to
perform
modifications
on
a
Tivoli
Access
Manager
credential.
The
credentials
modification
service
can
then
return
this
modified
credential
for
use
by
the
calling
application.
Applications
can
use
this
service
to
add
additional
information
to
a
user’s
credential.
For
example,
this
additional
information
could
include
the
user’s
credit
card
number
and
the
user’s
credit
limit.
Privilege
attribute
certificate
service
A
privilege
attribute
certificate
(PAC)
service
plug-in
gives
domain-specific
authorization
API
applications
the
ability
to
move
Tivoli
Access
Manager
credentials
back
and
forth
between
the
native
Tivoli
Access
Manager
credentials
format
and
an
alternate
format
called
privilege
attribute
certificates
(PAC).
Applications
can
convert
user
credentials
to
PACs
for
use
within
other
authorization
domains.
Applications
can
then
pass
the
PACs
to
a
server
in
another
authorization
domain
and
perform
an
operation.
For
example,
the
default
PAC
service
supplied
with
the
authorization
API
converts
a
Tivoli
Access
Manager
Chapter
6.
Authorization
service
plug-ins
79
credential
into
a
proprietary
flattened
text
format
for
transmission
over
text-based
transmission
mediums
like
HTML.
Customers
may
also
write
a
PAC
service
implementation
to
transform
the
attributes
in
Tivoli
Access
Manager
credentials
into
a
SAML
assertion,
an
attribute
certificate,
or
some
other
standardized
PAC
format
used
by
other
elements
of
the
business
model.
Administration
service
An
administration
service
plug-in
enables
applications
to
perform
application-specific
administration
tasks
on
protected
object
resources
that
are
secured
in
the
Tivoli
Access
Manager
secure
domain.
The
administration
service
provides
functions
that
enable
a
plug-in
to
obtain
the
contents
of
a
defined
portion
of
the
protected
object
hierarchy.
Additional
functions
enable
a
plug-in
to
define
application-specific
administration
tasks,
and
to
return
commands
that
perform
those
tasks.
The
administration
service
plug-in
is
accessed
by
a
calling
application
that
sends
Tivoli
Access
Manager
administration
API
calls.
The
calling
application
can
be
either
a
administrative
utility
such
as
the
Tivoli
Access
Manager
pdadmin
command
or
the
Tivoli
Access
Manager
Web
Portal
Manager,
or
can
be
a
custom-built
application.
The
administration
service
maps
the
administration
API
calls
to
the
corresponding
administration
service
API
calls,
and
carries
out
the
requested
action.
External
authorization
service
An
external
authorization
service
plug-in
is
an
optional
extension
of
the
Tivoli
Access
Manager
authorization
service
that
allows
you
to
impose
additional
authorization
controls
and
conditions.
You
can
use
an
external
authorization
service
plug-in
to
force
authorization
decisions
to
be
made
based
on
application-specific
criteria
that
are
not
known
to
the
Tivoli
Access
Manager
authorization
service.
80
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
Implementing
a
service
plug-in
This
section
describes
how
to
implement
a
service
plug-in.
The
service
plug-in
architecture
supports
standard
methods
for
initialization,
configuration,
error
handling
and
shutdown.
Each
service
plug-in
requires
implementation
of
interfaces
that
are
specific
to
the
service
type.
This
section
contains
the
following
topics:
v
“Initialization
and
configuration
of
service
plug-ins”
on
page
82
v
“Implementing
service
interfaces”
on
page
86
v
“Using
error
codes”
on
page
88
v
“Shut
down”
on
page
92
v
“Example
service
source
code”
on
page
93
Chapter
6.
Authorization
service
plug-ins
81
Initialization
and
configuration
of
service
plug-ins
Applications
initialize
the
authorization
API
by
calling
azn_initialize().
This
function
checks
the
services
stanzas
in
either
the
specified
authorization
configuration
file
or
in
data
contained
in
the
init_data
attribute
list
parameter.
When
a
service
is
defined,
azn_initialize()
loads
the
service
plug-in
and
calls
the
azn_svc_initialize()
interface
of
the
plug-in.
The
azn_svc_initialize()
interface
contains
parameters
named
argc
and
argv.
When
the
azn_svc_initialize()
interface
is
called
by
the
authorization
API
runtime,
these
parameters
contain
arguments
to
the
service
plug-in
specified
in
the
service
definition
within
the
configuration
file.
The
service
definition
defines
all
text
after
the
character
&
to
be
initialization
parameters.
Unlike
the
C
language
argv,
the
argv[0]
array
entry
is
the
first
parameter,
and
not
the
name
of
the
service
plug-in.
The
azn_svc_initialize()
interface
must
also
take
the
svc_init
input
parameter,
which
specifies
an
attribute
list.
The
service
dispatcher
may
use
the
attribute
list
to
pass
additional
information
to
the
service
plug-in.
Note:
Currently,
there
are
no
initialization
attributes
defined
for
the
svc_init
parameter.
The
service
plug-in
can,
but
is
not
required
to,
return
information
to
the
service
dispatcher
through
the
optional
output
parameter
svc_info.
This
parameter
specifies
an
attribute
list
that
can
be
used
to
return
information,
such
as
the
version
number,
that
is
specific
to
the
service
plug-in.
For
more
information,
see
the
reference
page
for
“azn_svc_initialize()”
on
page
244.
Constructing
a
service
definition
You
can
deploy
an
authorization
service
plug-in
by
registering
it
with
the
authorization
service.
To
register
a
service
plug-in,
construct
a
service
definition.
The
service
definition
can
be
entered
into
a
configuration
file,
or
passed
in
programmatically
to
azn_svc_initialize().
To
construct
a
service
definition,
you
must
define
several
elements
and
then
combine
them
into
a
service
definition.
To
do
this,
complete
the
following
tasks:
1.
Specifying
a
service
ID
The
service
ID
is
a
unique
string
that
identifies
the
service
to
the
calling
application.
The
service
ID
can
be
any
string
that
is
accepted
as
a
valid
key
name
by
the
stanza
file
parsing
code.
The
service
ID
is
case
insensitive.
2.
Specifying
the
location
of
the
plug-in
library
The
plug-in
location
is
the
fully
qualified
path
name
for
the
shared
library
or
DLL
module
that
contains
the
plug-in
for
the
given
service
ID.
The
fully
qualified
path
name
is
case
sensitive.
If
the
library
or
DLL
is
located
in
a
directory
that
is
normally
searched
for
system
libraries
or
DLLs,
you
can
just
use
the
library
name.
Examples
of
this
type
of
location
are
/usr/lib
on
UNIX
systems
and
%PATH%
on
Windows
NT
systems.
You
can
specify
a
“short
form”
library
name
if
you
want
the
library
name
to
be
platform
independent.
This
enables
the
library
to
be
loaded
on
any
supported
Tivoli
Access
Manager
platform.
The
authorization
API
will
prepend
and
append
the
library
with
known
library
prefixes
and
suffixes,
and
search
for
each
possibility
in
turn.
82
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
For
example,
the
authorization
API
will
search
for
a
library
with
the
short
form
name
of
azn_ent_user
by
looking
for
each
of
the
following
files:
Platform
Library
File
Name
Windows
NT
azn_ent_user.dll
AIX
libazn_ent_user.so,
libazn_ent_user.a
Solaris
libazn_ent_user.so
HP/UX
libazn_ent_user.sl
3.
Specifying
plug-in
parameters
The
entry
of
additional
parameters
is
optional.
The
azn_svc_initialize()
function
can
pass
these
parameters
to
the
service
plug-in
as
initialization
information
in
the
form
of
arguments.
To
add
optional
initialization
parameters
to
the
service
definition,
insert
the
&
character
and
then
specify
the
arguments.
4.
Building
a
service
definition
Each
service
plug-in
entry
uses
the
following
syntax:
<service-id>
=
<plug-in
location>
[
&
<plug-in
parameters>
]
Parameters
specified
after
the
ampersand
(&)
are
passed
to
the
service
plug-in’s
shared
library.
The
shared
library
takes
the
remainder
of
the
string
following
the
ampersand
&,
breaks
the
string
up
into
white
space
separated
tokens,
and
passes
the
tokens
directly
to
the
administration
service’s
initialization
interface,
azn_svc_initialize(),
in
the
argv
array
parameter.
The
number
of
strings
in
the
argv
array
is
indicated
by
the
argc
function
parameter.
Parameters
specified
before
the
&
are
processed
by
the
authorization
API.
For
example,
the
external
authorization
service
can
have
an
optional
weight
parameter,
and
the
administration
service
can
optionally
take
the
name
of
a
protected
object
hierarchy
name.
The
following
line
is
an
example
entry
for
an
entitlement
service
plug-in:
entsvc
=
/lib/libentsvc.so
&
-server
barney
In
the
above
example:
v
The
service
ID
is
entsvc.
v
The
plug-in
location
is
/lib/libentsvc.so
v
The
optional
arguments
are
-server
barney.
In
this
example,
the
optional
arguments
tell
the
service
plug-in
the
name
of
the
server
where
the
plug-in
executes.
After
constructing
your
service
definition,
choose
one
of
the
following
methods
for
registering
your
service
definition:
v
“Configuring
a
service
by
using
a
configuration
file”
on
page
83
v
“Configuring
a
service
programmatically”
on
page
84
Configuring
a
service
by
using
a
configuration
file
The
Tivoli
Access
Manager
authorization
service
recognizes
and
registers
service
plug-ins
by
reading
entries
in
the
authorization
API
client
configuration
file.
Chapter
6.
Authorization
service
plug-ins
83
When
the
application
initializes
the
authorization
API,
the
authorization
server
parses
the
configuration
file.
The
dispatcher
resolves
the
location
of
each
service
plug-in,
and
loads
each
service
plug-in.
The
azn_svc_initialize()
function
returns
an
error
if
a
service
plug-in
is
not
configured
correctly
or
if
the
service
plug-in
module
cannot
be
located.
Each
type
of
service
has
a
separate
section
within
the
configuration
file.
The
default
configuration
file
contains
the
following
entries:
Entry
Service
Type
[aznapi-entitlement-services]
entitlement
service
plug-ins
[aznapi-pac-services]
Privilege
attribute
certificate
service
plug-ins
[aznapi-cred-modification-services]
Credentials
modification
service
plug-ins
[aznapi-admin-services]
Administration
service
plug-ins
[aznapi-extern-authzn-services]
External
Authorization
service
plug-ins
Configuring
a
service
programmatically
You
can
use
the
init_data
input
parameter
to
pass
a
service
definition
to
azn_initialize().
Service
definitions
that
are
defined
programmatically
do
not
have
to
be
defined
in
the
configuration
file.
To
use
init_data,
build
an
attribute
list
that
contains
the
service
definition
entries.
The
file
ogauthzn.h
defines
the
following
strings
to
use
for
the
attribute
list
names
for
each
type
of
service.
/*
Entitlement
service
definition
attribute
*/
AZN_DECLSPEC
azn_string_t
azn_init_ent_svc;
/*
PAC
service
definition
attribute
*/
AZN_DECLSPEC
azn_string_t
azn_init_pac_svc;
/*
Credential
modification
service
definition
attribute
*/
AZN_DECLSPEC
azn_string_t
azn_init_cred_mod_svc;
/*
Administration
service
definition
attribute
*/
AZN_EXTSPEC
azn_string_t
azn_init_admin_svc;
/*
External
authorization
service
definition
attribute
*/
AZN_EXTSPEC
azn_string_t
azn_init_extern_authzn_svc;
Use
each
of
the
above
attributes
to
define
a
service
of
that
particular
type.
The
format
of
the
string
attribute
values
is
described
in
“Constructing
a
service
definition”
on
page
82.
Each
part
of
service
definition,
such
as
<service
id>,
represents
a
separate
string
value
for
the
attribute.
Each
attribute
can
have
multiple
service
definitions.
Use
the
function
azn_attrlist_add_entry()
to
add
the
attribute
and
string
values
to
the
attribute
list.
The
following
example
shows
source
code
for
configuring
an
entitlement
service
programmatically.
azn_status_t
status;
azn_attrlist_h_t
init_data
=
AZN_C_INVALID_HANDLE;
azn_attrlist_h_t
init_info
=
AZN_C_INVALID_HANDLE;
84
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
azn_string_t
service_entry;
azn_attrlist_create(&init_data);
azn_attrlist_create(&init_info);
/*
*
Load
an
entitlement
service
programmatically.
The
service
*
entry
will
load
the
DLL
“mysvc”
and
associate
it
with
the
*
service
ID
“MYSVC”.
The
dispatcher
will
automatically
search
*
the
library
search
path
for
the
platform
specific
DLL
name
*
variations
of
this
name.
On
NT:
mysvc.dll,
and
on
Unix:
*
libmysvc.so.
The
parameters
-server
and
-port
will
be
passed
*
to
the
azn_svc_initialize()
interface
of
the
service
in
the
*
argv
array.
*/
service_entry
=
“MYSVC=mysvc
&
-server
barney
-port
1234";
status
=
azn_attrlist_add_entry(init_data,
azn_init_ent_svc,
service_entry);
if
(status
!=
AZN_S_COMPLETE)
{
fprintf(stderr,
“azn_attrlist_add_entry_failed:
[%08X:%08X]\n”,
azn_error_major(status),
azn_error_minor(status));
exit
-1;
}
/*
*
Call
initialize
*/
status
=
azn_initialize(init_data,
&init_info);
if
(status
!=
AZN_S_COMPLETE)
{
fprintf(stderr,
“\nazn_initialize
failed:
[%08X:%08X]\n”,
azn_error_major(status),
azn_error_minor(status));
exit
-1;
}
Chapter
6.
Authorization
service
plug-ins
85
Implementing
service
interfaces
The
implementation
of
a
service
plug-in
consists
of
building
a
shared
library.
The
shared
library
must
contain
interfaces
that
are
specific
to
the
type
of
service.
These
interfaces
perform
the
work
that
is
specific
to
the
service.
A
calling
application
sends
a
request
to
the
authorization
API,
which
vectors
the
request
to
the
appropriate
service
plug-in.
The
service
plug-in
shared
library
must
contain
an
implementation
of
the
authorization
API
interface
that
will
perform
the
tasks
specific
to
the
service
plug-in.
The
following
table
shows
the
authorization
API
interface
that
is
invoked
by
the
calling
application,
and
the
corresponding
authorization
API
interface
that
is
implemented
in
the
service
plug-in
shared
library.
Service
API
function
invoked
by
the
calling
application
Function
implemented
by
the
service
plug-in
Entitlement
service
azn_entitlement_get_entitlements()
azn_svc_entitlement_get_entitlements()
Credentials
modification
service
azn_creds_modify()
azn_svc_creds_modify()
Privilege
attribute
certificate
service
azn_creds_get_pac()
azn_svc_creds_get_pac()
azn_pac_get_creds()
azn_svc_pac_get_creds()
Administration
service
ivadmin_protobj_get2()
azn_admin_get_object()
ivadmin_protobj_list3()
azn_admin_get_objectlist()
ivadmin_server_gettasklist()
azn_admin_get_tasklist()
ivadmin_server_performtask()
azn_admin_perform_task()
External
authorization
service
azn_decision_access_allowed()
azn_decision_access_allowed_ext()
azn_svc_decision_access_allowed_ext()
Note
that
the
name
of
the
authorization
API
function
that
is
invoked
by
the
calling
application
and
the
name
of
the
authorization
API
function
that
is
invoked
by
the
service
plug-in
shared
library
are
often
the
same.
Note,
however,
that
these
are
two
separate
implementations
of
the
interface
(function).
The
service
plug-in
shared
library
implements
its
own
version
of
the
interface,
in
order
to
perform
service
type-specific
tasks.
For
example,
calling
applications
often
call
azn_decision_access_allowed_ext()
to
request
an
authorization
decision.
When
the
authorization
API
has
been
configured
to
recognize
an
external
authorization
service,
this
call
to
azn_decision_access_allowed_ext()
is
routed
through
the
service
dispatcher
to
the
appropriate
external
authorization
service
plug-in
shared
library.
Within
this
library
the
plug-in
developer
will
have
implemented
a
local
version
of
azn_svc_decision_access_allowed_ext()
that
can
make
authorization
decisions
based
on
conditions
or
rules
that
are
potentially
unknown
to
the
core
Tivoli
Access
Manager
authorization
engine.
As
long
as
the
implementation
of
the
interface
within
the
service
plug-in
satisfies
the
interface
(function)
signature
of
the
authorization
API
function,
the
service
plug-in
shared
library
can
augment
the
default
authorization
process
with
code
specific
to
the
plug-in.
86
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
Note
that
the
interfaces
described
in
this
section
are
in
addition
to
the
interfaces
that
are
generic
to
all
types
of
service
plug-ins.
These
generic
interfaces
include
initialization
and
shutdown.
Chapter
6.
Authorization
service
plug-ins
87
Using
error
codes
The
authorization
API
service
plug-in
interface
defines
a
number
of
major
error
codes.
The
interface
also
defines
a
minor
error
code
mask
and
an
error
code
creation
utility
which
service
plug-ins
must
use
to
construct
error
codes.
Use
of
this
error
mask
ensures
that
the
32
bit
major
and
minor
error
codes
are
correctly
translated
to
a
32
bit
error
code
for
return
to
the
calling
application.
The
calling
application
parses
the
returned
error
code
into
its
major
and
minor
error
code
components
by
the
using
the
azn_error_major()
and
azn_error_minor()
function
calls.
Developers
of
service
plug-ins
should
use
the
authorization
API
utility
function
azn_util_errcode()
to
construct
valid
error
codes
to
return
to
the
calling
application.
The
function
azn_util_errcode()
takes
major
and
minor
integer
error
code
values
and
converts
them
in
to
an
azn_status_t
value.
The
minor
error
code
must
be
defined
as
described
in
“Minor
error
codes”
on
page
90.
Major
error
codes
Authorization
service
plug-ins
should
return
all
applicable
major
error
codes
that
are
defined
by
the
authorization
API.
service
plug-ins
should
also
return
the
major
error
codes
defined
for
a
particular
type
of
service
plug-in,
such
as
the
entitlement
service.
Note:
Some
error
codes
do
not
apply
to
all
service
plug-in
types.
The
following
additional
major
error
codes
are
defined
for
the
authorization
API
service
modules
in
ogauthzn.h.
The
service
dispatcher
returns
only
some
of
the
error
codes,
while
other
error
codes
are
returned
only
by
the
service
plug-in.
The
following
table
shows
the
error
codes
that
the
service
dispatcher
returns.
Error
Description
AZN_S_SVC_DEFINITION_ERROR
The
service
dispatcher
returns
this
error
when
the
service
definition
is
constructed
incorrectly
in
the
Service
stanza
of
the
configuration
file
or
in
a
value
that
is
passed
in
the
init_data
attribute
list
of
azn_intialize().
AZN_S_SVC_SERVICE_NOT_FOUND
The
service
dispatcher
returns
this
error
when
it
cannot
locate
the
authorization
API
service
plug-in.
The
service
dispatcher
also
returns
this
error
when
it
cannot
load
the
service
plug-in.
AZN_S_SVC_INITIALIZE_NOT_FOUND
The
service
dispatcher
returns
this
error
when
it
encounters
an
error
while
either
locating
or
loading
a
service
interface
within
a
specific
service
plug-in.
For
example,
the
service
dispatcher
returns
this
error
if
the
azn_svc_initialize()
interface
could
not
be
found
in
the
loaded
service
plug-in.
AZN_S_INVALID_MOD_FUNCTION
The
supplied
modification
service
identifier
is
invalid.
AZN_S_INVALID_PAC_SVC
The
identifier
(id)
of
the
PAC
service
is
invalid.
AZN_S_SVC_DISPATCHER_FAILURE
88
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
Error
Description
The
service
dispatcher
failed.
This
can
be
caused
by
incorrect
initialization
of
the
authorization
API.
AZN_S_SVC_DLL_LOAD_FAILED
The
DLL
for
a
service
plug-in
failed
to
load
correctly
AZN_S_SVC_SERVICE_IS_REGISTERED
The
service
ID
cannot
be
registered
because
it
is
already
listed
as
registered
by
the
service
dispatcher.
AZN_S_SVC_INITIALIZE_NOT_FOUND
The
azn_svc_intialize()
function
was
not
found.
AZN_S_SVC_SHUTDOWN_NOT_FOUND
The
azn_svc_shutdown()
function
was
not
found.
AZN_S_SVC_ENT_FUNC_NOT_FOUND
The
azn_entitlement_get_entitlements()
function
was
not
found.
AZN_S_SVC_PAC_FUNC_NOT_FOUND
One
of
either
azn_pac_get_creds()
or
azn_creds_get_pac()
was
not
found.
AZN_S_SVC_CRED_MOD_FUNC_NOT_FOUND
The
azn_creds_modify()
function
was
not
found.
AZN_S_SVC_EAS_FUNC_NOT_FOUND
One
of
either
azn_decision_access_allowed()
or
azn_decision_access_allowed_ext()
was
not
found.
AZN_S_SVC_ADMIN_POBJ_FUNC_NOT_FOUND
One
of
either
azn_admin_get_object()
or
azn_admin_get_objectlist()
was
not
found.
AZN_S_SVC_ADMIN_TASK_FUNC_NOT_FOUND
One
of
either
azn_admin_perform_task()
or
azn_admin_get_tasklist()
was
not
found.
The
following
table
shows
the
major
error
codes
that
service
plug-ins
return:
Error
Description
AZN_S_SVC_INIT_FAILED
The
service
plug-in
returns
this
error
when
it
encounters
an
error
during
initialization.
AZN_S_SVC_SHUTDOWN_FAILED
The
service
plug-in
returns
this
error
when
it
encounters
an
error
during
shutdown.
AZN_S_SVC_AUTHORIZATION_FAILURE
The
service
plug-in
returns
this
error
when
the
calling
application
lacks
authorization
to
invoke
the
Service.
In
addition
to
the
generic
major
codes
that
apply
to
all
types
of
service
plug-ins,
there
exist
generic
major
codes
that
apply
to
a
specific
service
plug-in.
These
major
codes
are
defined
in
ogauthzn.h.
Chapter
6.
Authorization
service
plug-ins
89
Error
Code
Prefix
Description
AZN_S_SVC_ADMIN_*
Administration
service
plug-in
major
error
codes.
AZN_S_SVC_ENT_*
Entitlement
service
plug-in
major
error
codes.
AZN_S_SVC_EAS_*
External
authorization
service
plug-in
major
error
codes
AZN_S_SVC_CRED_MOD_*
Credentials
modification
service
plug-in
major
error
codes.
AZN_S_SVC_PAC_*
Privilege
attribute
certificate
services
plug-in
major
error
codes
In
all
of
the
above
cases,
the
application
developer
may
also
insert
an
implementation
specific
minor
error
code
into
the
status
code.
The
minor
error
code
provides
the
calling
application
with
further
information
on
the
error
that
the
service
plug-in
encountered.
The
calling
application
uses
azn_error_minor()
to
extract
the
minor
error
code.
Minor
error
codes
The
service
plug-in
modules
define
minor
error
codes.
Each
minor
error
code
is
specific
to
a
particular
service
plug-in.
Developers
should
define
the
minor
error
codes
in
the
interface
file
for
the
service
plug-in.
The
interface
file
also
contains
other
details
specific
to
the
service
plug-in,
such
as
the
names
of
the
attributes
recognized
by
the
service.
Applications
that
use
the
service
plug-in
will
include
and
reference
the
service
interface
file.
The
authorization
API
encodes
all
minor
error
codes
by
using
a
table
of
known
message
catalog
prefixes.
There
is
one
prefix
for
all
service
plug-ins
of
the
same
type.
For
example,
all
entitlement
service
plug-ins
use
the
same
prefix.
The
file
ogauthzn.h
defines
the
following
prefixes:
Service
Prefix
Entitlements
azn_ent_svc_err_prefix
Credentials
Modification
azn_mod_svc_err_prefix
Privilege
Attribute
Certificate
azn_pac_svc_err_prefix
Administration
service
azn_admin_svc_err_prefix
External
authorization
service
azn_eas_svc_err_prefix
The
service
plug-in
developer
must
use
these
prefixes
to
define
the
minor
error
codes
for
each
service
plug-in.
The
azn_util_errcode()
interface
uses
these
prefixes
to
properly
encode
each
minor
error
into
an
azn_status_t.
For
example,
the
prefix
for
Entitlement
Services
is
defined
as
follows
in
the
file
ogauthzn.h:
extern
unsigned
int
azn_ent_svc_err_prefix;
Entitlement
service
developers
should
define
their
error
messages
in
terms
of
azn_ent_svc_err_prefix.
90
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
For
example,
minor
error
codes
for
authorization
API
entitlement
service
plug-ins
are
defined
in
the
interface
file
as
follows:
#define
ENT_SVC_CORE_DUMP
(azn_ent_svc_err_prefix
|
0x1)
#define
ENT_SVC_INVALID_ATTRIBUTE
(azn_ent_svc_err_prefix
|
0x2)
#define
ENT_SVC_BAD_FILENAME
(azn_ent_svc_err_prefix
|
0x3)
The
service
plug-in
developer
has
16
bits
of
the
minor
error
code
to
use
for
minor
error
codes
specific
to
a
service.
The
16
bit
error
code
can
be
personalized
for
the
service,
to
avoid
conflicts
with
other
service
plug-ins
of
the
same
type.
For
example:
#define
MY_ENTSVC_ERR
(0xE000)
#define
ENT_SVC_CORE_DUMP
\
(azn_ent_svc_err_prefix
|
(MY_ENTSVC_ERR
|
0x1))
Chapter
6.
Authorization
service
plug-ins
91
Shut
down
Applications
shut
down
the
service
plug-ins
as
part
of
shutting
down
the
authorization
API.
The
application
calls
azn_shutdown().
If
a
Service
is
initialized,
azn_shutdown()
calls
the
azn_svc_shutdown()
interface
of
the
service
plug-in.
The
azn_svc_shutdown()
interface
is
called
with
the
same
argc
and
argv
parameters
that
were
passed
to
the
azn_svc_initialize()
interface
when
the
service
plug-in
was
first
initialized.
The
azn_svc_shutdown()
also
takes
the
optional
input
parameter
svc_init,
which
specifies
an
attribute
list.
The
service
plug-in
developer
can
use
the
attribute
list
to
pass
additional
information
to
the
service
plug-in.
Currently,
there
are
no
defined
attributes
for
svc_init.
The
service
plug-in
can
return
information
to
the
service
dispatcher
through
the
optional
output
parameter
svc_info.
For
more
information,
see
the
reference
page
for
“azn_svc_shutdown()”
on
page
249.
92
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
Example
service
source
code
This
section
contains
source
code
for
an
example
implementation
of
an
entitlement
service
plug-in.
This
code
demonstrates
configuration,
initialization,
shutdown,
and
implementation
of
interfaces
specific
to
the
service
type.
/*
*
FILENAME
*
mysvc.cpp
*
*
DESCRIPTION
*
*
Example
entitlement
service
for
the
aznAPI.
*
*/
#include
<stdio.h>
#include
<ogauthzn.h>
#include
<aznutils.h>
#ifdef
_WIN32
#define
AZN_DECLSPEC
__declspec(dllexport)
#else
#define
AZN_DECLSPEC
#endif
#define
MY_SVC_VER
“Example
Entitlement
Service
v1.0”
/*
*
Define
a
mask
to
identify
minor
errors
that
originate
from
this
*
service.
All
3rd
party
entitlement
services
must
use
the
*
azn_ent_svc_err_prefix
to
prefix
minor
code
definitions.
The
lower
*
16
bits
should
be
differentiated
from
other
installed
entitlements
*
services.
eg.
in
this
case
0x8000
identifies
the
error
as
originating
*
from
this
service.
*/
#define
AZN_MYSVC_ERROR_MASK
(azn_ent_svc_err_prefix
|
0x8000)
#define
AZN_MYSVC_INVALID_SVCINFO_HDL
(AZN_MYSVC_ERROR_MASK
|
1)
#define
AZN_MYSVC_INVALID_ARG_COUNT
(AZN_MYSVC_ERROR_MASK
|
2)
#define
AZN_MYSVC_INVALID_ARG_ARRAY
(AZN_MYSVC_ERROR_MASK
|
3)
#ifdef
__cplusplus
extern
“C”
{
#endif
/**********************************************************************
*
Interface
function
definitions.
***********************************************************************/
/*
*
FUNCTION
NAME
*
azn_svc_initialize
*
*
DESCRIPTION
*
init
the
entitlement
service
*
*
ARGUMENTS
*
[in]
argc
The
count
of
arguments
to
the
service.
*
[in]
argv
The
array
of
argument
strings.
*
[in]
svc_init
List
of
initialization
attributes
for
the
service.
*
[out]
svc_info
attr
list
ptr
for
attributes
returned
by
the
*
service.
*
*
RETURN
VALUE
*
AZN_S_COMPLETE
on
success,
error
code
on
failure
Chapter
6.
Authorization
service
plug-ins
93
*/
AZN_DECLSPEC
azn_status_t
AZN_CALLTYPE
azn_svc_initialize(
int
argc,
/*
in
*/
char
**argv,
/*
in
*/
azn_attrlist_h_t
svc_init,
/*
in
*/
azn_attrlist_h_t
*svc_info
/*
out
*/
)
{
azn_status_t
st;
azn_boolean_t
freeAttrlist
=
FALSE;
/*
svc_info
must
not
be
NULL
*/
if
(svc_info
==
NULL)
{
return
(azn_util_errcode(AZN_S_FAILURE,
AZN_MYSVC_INVALID_SVCINFO_HDL));
}
/*
ensure
argc
is
valid
*/
if
(argc
<
0
||
(argc
==
0
&&
argv
!=
NULL))
{
return
(azn_util_errcode(AZN_S_FAILURE,
AZN_MYSVC_INVALID_ARG_COUNT));
}
if
(argc
>
0
&&
argv
==
NULL)
{
return
(azn_util_errcode(AZN_S_FAILURE,
AZN_MYSVC_INVALID_ARG_ARRAY));
}
/*
*
*
Process
arguments
and
initialize
service.
*
*/
/*
return
the
service
version
to
the
dispatcher
*/
if
(*svc_info
==
AZN_C_INVALID_HANDLE)
{
azn_attrlist_create(svc_info);
freeAttrlist
=
TRUE;
}
st
=
azn_attrlist_add_entry(*svc_info,
azn_svc_version,
MY_SVC_VER);
if
(st
!=
AZN_S_COMPLETE)
{
if
(freeAttrlist)
{
azn_attrlist_delete(svc_info);
}
return
(st);
}
return
(AZN_S_COMPLETE);
}
/*
*
FUNCTION
NAME
*
azn_svc_shutdown
*
*
DESCRIPTION
*
Shutdown
the
entitlement
service.
*
The
initialization
parameters
are
passed
in
*
again
on
shutdown
but
are
ignored.
No
version
*
info
is
returned.
*
94
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
*
ARGUMENTS
*
[in]
argc
The
count
of
arguments
to
the
service.
*
[in]
argv
The
array
of
argument
strings.
*
[in]
svc_init
List
of
initialization
attributes
for
the
service.
*
*
[out]
svc_info
attr
list
ptr
for
attributes
returned
by
the
*
service.
*
*
RETURN
VALUE
*
AZN_S_COMPLETE
*/
AZN_DECLSPEC
azn_status_t
AZN_CALLTYPE
azn_svc_shutdown(
int
argc,
/*
in
*/
char
**argv,
/*
in
*/
azn_attrlist_h_t
svc_init,
/*
in
*/
azn_attrlist_h_t
*svc_info
/*
out
*/
)
{
return
(AZN_S_COMPLETE);
}
/*
*
FUNCTION
NAME
*
azn_svc_entitlement_get_entitlements
*
*
DESCRIPTION
*
Returns
entitlements
information
associated
with
*
the
credential
and
context
info
passed
in.
*
*
ARGUMENTS
*
[in]
creds
The
credentials
of
the
caller
*
[in]
svc_id
The
id
of
the
entitlement
service
*
[in]
app_context
attribute
list
containing
information
*
regarding
the
type
of
object
we
are
*
operating
on
*
[out]
entitlements
attribute
list
containing
the
*
entitlements
associated
with
the
specified
*
object
*
*
RETURN
VALUE
*
AZN_S_COMPLETE
on
success,
error
code
on
failure
*/
AZN_DECLSPEC
azn_status_t
AZN_CALLTYPE
azn_svc_entitlement_get_entitlements(
azn_creds_h_t
creds,
/*
in
*/
azn_string_t
svc_id,
/*
in
*/
azn_attrlist_h_t
app_context,
/*
in
*/
azn_attrlist_h_t
*entitlements
/*
out
*/
)
{
/*
Obtain
entitlements
data
from
back-end
database
*/
return
(AZN_S_COMPLETE);
}
#ifdef
__cplusplus
}
#endif
Chapter
6.
Authorization
service
plug-ins
95
Supplied
implementations
for
service
plug-ins
The
Tivoli
Access
Manager
authorization
ADK
supplies
implementations
for
a
number
of
different
service
plug-in
types.
Some
of
these
implementations
are
built
into
the
authorization
API.
Others
consist
of
separate
shared
libraries.
The
name
for
each
implementation
that
consists
of
a
shared
library
is
specified
as
the
short
name
in
the
table
in
each
of
the
following
sections.
You
can
use
the
short
name
when
specifying
the
plug-in
location,
as
part
of
constructing
the
service
definition.
For
more
information,
see
“Constructing
a
service
definition”
on
page
82.
The
following
sections
describe
the
supplied
service
implementations:
v
“Entitlement
services”
on
page
97
v
“Credentials
modification
service”
on
page
101
v
“Privilege
attribute
certificate
service”
on
page
102
v
“External
authorization
service”
on
page
102
96
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
Entitlement
services
Tivoli
Access
Manager
provides
the
following
entitlement
services:
v
Tivoli
Access
Manager
protected
objects
entitlement
service
This
is
the
default
entitlement
service.
v
Extended
attributes
entitlement
service
v
IBM
Tivoli
Access
ManagerAttribute
Retrieval
Service
v
Credential
attributes
entitlement
service
These
services
are
described
in
the
following
tables:
Service
Plug-in
Summary
Category
Description
Name
Protected
objects
entitlement
service
Service
ID
NULL
Plug-in
Short
Name
Not
applicable
(implemented
internally)
Parameters
app_context
(input)
The
entitlement
service
accepts
a
single,
multi-valued
string
attribute
that
specifies
the
root
node(s)
for
searching
the
Tivoli
Access
Manager
protected
object
namespace.
This
enables
the
application
to
limit
its
search
to
a
particular
set
of
protected
objects
in
the
web
space,
rather
than
search
the
entire
web
space.
Because
the
attribute
can
contain
multiple
values,
the
application
can
specify
multiple
root
nodes
for
the
search.
The
app_context
attribute
list
contains
these
attributes:
v
azn_ent_svc_pd_pobj_path
(multi-valued)
v
azn_ent_svc_pd_pobj_reqd_ops
(single
value)
This
attribute
contains
a
string
to
denote
the
set
of
operations
that
the
credential
must
have
upon
the
protected
object.
For
example:
rxT.
entitlements
(output)
Entitlements
data
is
returned
as
a
multi-valued
attribute
list
of
protected
objects
for
each
search
tree
root
node
passed
in
to
the
azn_entitlement_get_entitlements()
call.
The
list
only
contains
objects
underneath
the
specified
root
node
that
have
an
ACL
explicitly
attached
to
them.
The
attribute
list
is
appended
with
the
attribute
azn_ent_svc_pd_pobj_matches,
which
contains
string
protected
object
names.
The
attribute
list
may
contain
AZN_C_INVALID_HANDLE
if
there
are
no
protected
objects
that
match.
Chapter
6.
Authorization
service
plug-ins
97
Service
Plug-in
Summary
Category
Description
Description
The
service
returns
a
list
of
protected
resources
in
the
database
that
have
an
ACL
explicitly
attached
to
them
and
for
which
the
ACL
allows
the
specified
credential
the
specified
access
privilege.
For
example,
the
application
can
request
the
service
to
return
a
list
of
HTML
objects
under
/WebSEAL/srvA/staff
for
which
a
specified
user
has
read
permission.
A
graphical
user
interface
application
can
use
the
returned
entitlements
(protected
object
names)
to
determine
which
buttons
the
specified
user
can
see
when
the
GUI
application
is
loaded.
This
entitlement
service
should
be
configured
in
secure
domains
with
Tivoli
Access
Manager
servers
that
have
been
configured
and
are
running.
The
following
table
describes
the
extended
attributes
entitlement
service:
Service
Plug-in
Summary
Category
Description
Name
Extended
attributes
entitlement
service
Service
ID
User
specified
in
the
service
definition.
Plug-in
Short
Name
azn_ent_ext_attr
Parameters
app_context
(input)
Input
attribute
name:
One
of
“POP”,
“ACL”
or
“OBJ”.
This
attribute
contains
the
protected
object
name
that
is
the
target
for
the
request.
entitlements
(output)
An
list
of
the
extended
attributes
that
are
defined
for
the
target
object.
Description
Returns
the
extended
attributes
defined
for
an
ACL,
POP
or
protected
object.
The
protected
object
to
which
the
ACL
or
POP
is
attached
or
that
is
the
target
for
the
operation
is
specified
as
a
parameter.
98
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
The
following
table
describes
the
IBM
Tivoli
Access
Manager
Attribute
Retrieval
Service,
a
customizable
web
service-based
dynamic
ADI
retrieval
entitlement
service:
Service
Plug-in
Summary
Category
Description
Name
AMWebARS
(Web
service-based
dynamic
ADI
retrieval
entitlement
service)
Service
ID
User
specified
in
the
service
definition.
Plug-in
Short
Name
azn_ent_amwebars
Parameters
app_context
(input)
Input
attribute
name:
azn_perminfo_rules_adi_request.
This
attribute
contains
a
list
of
ADI
container
names
that
should
be
obtained
from
the
IBM
Tivoli
Access
Manager
Attribute
Retrieval
Service
(AMWebARS).
Additional
attributes
can
be
specified
to
Web-based
applications.
For
more
information
on
these
attributes,
see
IBM
Tivoli
Access
Manager
for
e-business
WebSEAL
Administration
Guide.
entitlements
(output)
The
entitlements
attribute
list
output
parameter
contains
the
result
of
the
request
to
the
AMWebARS.
The
AMWebARS
returns
each
ADI
container
name
specified
in
the
input
attribute
azn_perminfo_rules_adi_request
as
a
separate
attribute
entry
in
the
output
entitlements
attribute
list.
The
attribute
name
for
each
returned
ADI
value
is
the
container
name
of
the
item.
Additional
attributes
are
returned
to
Web-based
applications.
For
more
information
on
these
attributes,
see
IBM
Tivoli
Access
Manager
for
e-business
WebSEAL
Administration
Guide.
Description
Retrieves
values
for
the
requested
ADI
container
names
by
querying
the
IBM
Tivoli
Access
Manager
Attribute
Retrieval
Service
(AMWebARS).
Values
are
only
returned
for
those
container
names
that
are
supported
by
the
plug-ins
loaded
into
the
AMWebARS.
For
more
information
on
the
AMWebARS,
see
the
IBM
Tivoli
Access
Manager
for
e-business
WebSEAL
Administration
Guide.
The
status
code
returned
from
the
entitlements
call
is
AZN_S_COMPLETE,
unless
a
serious
internal
error
is
encountered.
In
this
case,
an
error
code
is
returned.
The
inability
to
fulfill
the
request
for
one
or
more
of
the
requested
ADI
container
names
is
not
an
error
condition.
Chapter
6.
Authorization
service
plug-ins
99
The
following
table
describes
the
registry
attribute
entitlement
service.
Note
that
this
is
an
implementation
of
a
credential
attribute
entitlement
service.
Service
Plug-in
Summary
Category
Description
Name
Registry
attribute
entitlement
service
Service
ID
User
specified
in
the
service
definition.
Plug-in
Short
Name
azn_ent_cred_attrs
Parameters
app_context
(input)
Input
attribute
name:
azn_ent_cred_attrs_attribute.
This
attribute
contains
a
list
of
attributes
to
obtain
from
the
user
registry.
entitlements
(output)
The
entitlements
attribute
list
output
parameter
contains
the
list
of
attributes
obtained
from
the
user
registry.
Description
This
entitlement
service
obtains
a
specified
list
of
attributes
from
the
user
registry.
The
list
can
be
specified
in
several
different
ways.
The
list
can
be
built
from
entries
placed
in
the
application
file.
The
entitlement
service
is
called
automatically
by
azn_id_get_creds(),
or
can
be
manually
called
by
azn_entitlement_get_entitlements().
For
more
information,
see
“Registry
attribute
entitlement
service
overview”
on
page
113.
100
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
Credentials
modification
service
The
Tivoli
Access
Manager
authorization
ADK
provides
two
implementations
of
a
credentials
modification
service.
One
implementation
modifies
attribute
lists.
The
other
implementation
modifies
group
memberships.
The
service
described
in
the
table
below
is
built-in
to
the
authorization
API.
Service
Plug-in
Summary
Category
Description
Name
Credentials
attribute
list
modification
service
Service
ID
Null
Plug-in
Short
Name
not
applicable
(built-in)
Parameters
creds
(input)
The
credentials
with
which
to
work.
list
(input)
The
attribute
list
to
replace.
outcred
(output)
The
credential
resulting
from
the
operation.
Description
This
service
will
replace
the
attribute
list
in
credential
creds
with
the
attribute
list
list.
Read-only
attributes,
such
as
group
UUIDs,
cannot
be
changed
by
this
service.
The
original
credential
is
left
unchanged
and
a
new
credential
containing
list
is
returned
in
outcred.
The
service
described
in
the
table
below
is
not
built
into
the
authorization
API.
Service
Plug-in
Summary
Category
Description
Name
Credentials
group
membership
modification
service
Service
ID
User
specified
in
the
service
definition.
Plug-in
Short
Name
azn_mod_rad
Parameters
creds
(input)
The
credentials
to
modify
mod_info
(input)
Input
attribute:
AZN_MOD_RAD_GROUP_NAMES
Contains
the
names
of
the
groups
to
which
the
resulting
credential
creds
will
effectively
be
added.
newcreds
(output)
A
new
credential
based
on
creds
and
built
to
include
the
groups
in
mod_info.
Description
Gives
a
credential
membership
in
a
specified
set
of
groups.
The
new
credential
is
returned
in
newcreds.
The
original
credential
is
unaffected
and
the
results
are
localized
to
authorization
checks
made
with
the
returned
credential
newcreds.
The
actual
user
registry
and
the
user’s
entry
within
the
registry
are
not
affected
by
this
modification
service.
Chapter
6.
Authorization
service
plug-ins
101
Privilege
attribute
certificate
service
This
service
is
built
in
to
the
authorization
API.
Service
Plug-in
Summary
Category
Description
Name
Tivoli
Access
Manager
privilege
attribute
certificate
(PAC)
encoding
service
Service
ID
NULL
Plug-in
Name
not
applicable
(built-in)
Parameters:
azn_creds_get_pac()
creds
(input)
Input
parameter.
The
credentials
to
be
encoded.
pac
(output)
An
azn_buffer_t
that
will
contain
the
encoded
credentials
PAC
for
creds
on
completion.
Parameters:
azn_pac_get_creds()
pac
(input)
An
encoded
PAC
to
be
decoded
into
credentials.
new_creds
(output)
A
pointer
to
an
azn_creds_h_t
that
will
refer
to
the
credential
decoded
by
the
service
from
pac.
Description
Encodes
and
decodes
a
Tivoli
Access
Manager
credential
to
or
from
a
format
that
is
transmissible
in
a
text
only
environment.
The
format
is
a
combination
of
ASN1
and
MIME
encoding.
External
authorization
service
The
Authorization
ADK
provides
a
sample
implementation
of
an
external
authorization
service
(EAS)
plug-in.
This
implementation
is
not
built-in
to
the
authorization
API.
Service
Plug-in
Summary
Category
Description
Name
Example
external
authorization
service
Service
ID
User
specified
in
the
service
definition.
Plug-in
Short
Name
azn_eas_demo
Parameters
not
applicable
Description
This
is
an
example
EAS
plug-in
which
simply
returns
AZN_C_PERMITTED
for
all
authorizations
in
which
it
is
called
to
participate.
Configure
the
EAS
to
be
called
for
a
decision
that
would
normally
return
AZN_C_NOT_PERMITTED.
The
demonstration
program
performs
some
perfunctory
checking
of
input
parameters
but
does
not
attempt
to
make
any
authorization
related
decisions
based
upon
the
incoming
access
decision
information
(ADI).
102
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
Chapter
7.
Entitlement
service
plug-ins
The
IBM
Tivoli
Access
Manager
(Tivoli
Access
Manager)
authorization
API
services
framework
provides
a
modular,
plug-in
style
architecture
that
enables
application
developers
to
supplement
Tivoli
Access
Manager
authorization
with
their
own
entitlements
models.
Developers
can
build
a
shared
library
object
that
implements
an
entitlement
service.
Developers
then
configure
the
authorization
API
to
use
their
module
by
exposing
the
appropriate
entitlements
interface.
The
entitlements
shared
library
object
is
a
plug-in
to
the
authorization
API.
Application
developers
build
their
plug-in
as
an
authorization
API
client.
The
entitlement
service
plug-in
must
know
how
to
manipulate
authorization
API
structures
such
as
user
credentials
and
attribute
lists.
In
most
cases,
the
service
plug-in
functions
as
an
authorization
API
client.
Tivoli
Access
Manager
5.1
also
supports
a
new
class
of
entitlement
service
known
as
the
dynamic
ADI
retrieval
service.
More
information
on
this
class
of
entitlement
service
is
presented
later
in
this
chapter.
This
chapter
contains
the
following
topics:
v
“Understanding
entitlements”
on
page
104
v
“Initialization,
configuration,
and
shut
down”
on
page
106
v
“Obtaining
entitlements
for
a
specified
user”
on
page
107
v
“Authorizing
a
caller
to
a
specific
entitlement
service
plug-In”
on
page
108
v
“Using
authorization
API
interfaces”
on
page
108
v
“Entitlement
service
error
codes”
on
page
109
v
“Dynamic
ADI
retrieval
services”
on
page
110
v
“Credential
attributes
entitlement
service”
on
page
112
©
Copyright
IBM
Corp.
2000,2003
103
Understanding
entitlements
An
entitlement
is
a
data
structure
that
contains
externalized
policy
information.
An
entitlement
is
policy
data
or
capabilities
that
is
formatted
in
a
way
that
is
understandable
to
a
specific
application.
The
application
uses
the
authorization
API
to
instruct
the
Tivoli
Access
Manager
authorization
service
to
obtain
and
return
the
entitlements.
For
example,
an
application
for
processing
stock
market
trading
can
define
an
entitlement
called
trading
limit.
This
entitlement
defines
the
maximum
amount
that
a
specific
trader
can
trade
in
one
transaction.
The
entitlement
can
be
set
independently
for
each
trader
known
to
the
application.
The
application
can
request
the
trading
limit
for
a
specific
trader.
The
authorization
service
returns
the
entitlement
in
a
format,
such
as
United
States
dollars,
that
the
application
can
understand.
Entitlements
to
be
brokered
by
the
service
are
designed
with
the
target
application
in
mind.
The
policy
to
be
modeled
using
entitlements
is
first
identified
and
then
the
possible
values
for
these
entitlements
are
specified.
The
authorization
API
uses
attributes
within
an
attribute
list
to
represent
individual
entitlements.
Each
attribute
within
the
list
consists
of
an
attribute
name
and
a
multi-valued
list
of
values
for
that
attribute.
Attributes
can
consist
of
values
represented
by
data
of
type
azn_string_t,
by
data
of
type
azn_buffer_t,
or
by
any
other
valid
attribute
type.
Note:
For
more
information
on
authorization
API
attribute
lists
and
data
types,
see
Chapter
2,
“Authorization
API
functions
and
data
types,”
on
page
11.
Entitlements
of
type
azn_string_t
An
example
of
an
entitlement
is
the
time
of
day
access
restrictions
for
a
particular
resource.
This
refers
to
the
time
periods
during
a
day
that
a
particular
user
is
permitted
to
access
the
resource
to
which
the
entitlement
is
attached.
The
attribute
name
defined
by
the
entitlement
service
for
this
entitlement
is
simply
a
string:
extern
azn_string_t
time_of_day_restriction;
The
value
of
the
data
returned
is
specific
to
the
implementation
and
so
may
be
returned
as
multiple
strings
identifying
times
of
the
day
in
which
the
resource
may
be
accessed.
For
example:
"mon-fri:
9am-5pm"
“mon-fri:
1pm-5pm”
“sat:
9am-12pm”
These
string
values
for
time_of_day_restriction
define
valid
access
times.
The
entitlement
service
defines
how
these
strings
are
formatted
and
interpreted
by
the
calling
application.
104
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
The
Tivoli
Access
Manager
protected
object
entitlement
service
Another
example
of
an
entitlement
is
the
data
returned
by
the
Tivoli
Access
Manager
protected
object
entitlement
service.
This
service
returns
a
list
of
objects
within
the
protected
object
space
for
which
the
given
user
credential
has
the
specified
access
privileges.
An
application
could
use
this
information
to
create
a
portal
interface
specifically
for
each
user
that
invokes
the
application.
The
services
that
each
user
can
employ
are
returned
to
the
application
as
a
list
of
strings.
Each
string
represents
a
protected
object
within
the
Tivoli
Access
Manager
protected
object
space
that
the
caller
with
the
specified
privileges
can
access.
Entitlements
of
type
azn_buffer_t
Entitlement
services
may
also
define
an
entitlement
as
a
blob
of
data
using
an
azn_buffer_t
value
for
the
attribute.
This
may
be
used
by
distributed
object
based
applications
such
as
Common
Object
Request
Broker
Architecture
(CORBA)
to
retrieve
encoded
CORBA
objects
from
the
entitlement
service
that
can
then
be
used
to
perform
an
operation
for
the
calling
application.
The
contents
of
the
azn_buffer_t
data
type
are
opaque
to
the
authorization
service.
For
more
information
on
data
type
azn_buffer_t,
see
“Buffers”
on
page
14.
Chapter
7.
Entitlement
service
plug-ins
105
Initialization,
configuration,
and
shut
down
Each
entitlement
service
plug-in
is
a
standalone
module
that
is
dynamically
loaded
into
the
authorization
service.
The
Tivoli
Access
Manager
authorization
service
recognizes
and
registers
entitlement
service
plug-ins
with
the
service
dispatcher
by
reading
entries
in
the
aznapi.conf
configuration
file
.
Entitlement
service
plug-ins
are
declared
in
the
configuration
file
under
the
following
stanza
entry:
[aznapi-entitlement-services]
The
Tivoli
Access
Manager
authorization
service
also
recognizes
and
registers
entitlement
service
plug-ins
through
arguments
passed
to
the
init_data
parameter
of
the
azn_initialize()
function.
For
complete
configuration
specifications,
see
“Initialization
and
configuration
of
service
plug-ins”
on
page
82.
The
authorization
API
service
plug-in
model
provides
standard
interfaces
to
the
service
dispatcher
to
initialize
and
shut
down
all
types
of
service
plug-ins.
Developers
of
entitlement
service
plug-ins
should
provide
the
standard
functions.
See
the
following
sections:
For
more
information,
see
the
following
sections:
v
“Initialization
and
configuration
of
service
plug-ins”
on
page
82
v
“Shut
down”
on
page
92
See
also
the
reference
pages
for
“azn_svc_initialize()”
on
page
244
and
“azn_svc_shutdown()”
on
page
249.
106
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
Obtaining
entitlements
for
a
specified
user
The
authorization
API
provides
the
azn_entitlement_get_entitlements()
interface
for
obtaining
entitlements
for
a
specified
user.
The
service
plug-in
must
provide
the
azn_svc_entitlement_get_entitlements()
interface,
which
has
the
following
input
parameters:
Input
Parameter
Type
Parameter
Description
azn_creds_h_t
creds
The
credentials
of
the
user
for
whom
the
calling
application
wants
the
list
of
entitlements.
azn_string_t
svc_id
The
service
identification
string
of
the
entitlement
service
plug-in.
azn_attrlist_h_t
app_context
The
resource
within
the
protected
object
space,
and
the
action
requested.
The
authorization
API
service
dispatcher
directs
the
request
to
the
appropriate
service
plug-in,
based
on
the
svc_id
parameter.
The
service
plug-in
also
takes
the
above
parameters
as
input,
and
returns
the
requested
entitlements
in
the
attribute
list
entitlements.
The
service
plug-in
is
not
required
to
use
the
input
parameters,
but
it
is
required
to
return
valid
data
in
the
entitlements
output
parameter.
Entitlement
service
plug-ins
share
the
address
space
of
both
the
calling
application
and
the
authorization
API
shared
library.
Service
plug-ins
can
assume
that
pointers
passed
in
through
the
app_context
parameter
are
valid
within
the
address
space
of
the
service
plug-in.
Credential
and
attribute
list
handles
are
also
valid
to
use
within
the
service
plug-in.
Chapter
7.
Entitlement
service
plug-ins
107
Authorizing
a
caller
to
a
specific
entitlement
service
plug-In
Entitlement
service
plug-ins
typically
supply
information
in
a
directory
service,
such
as
LDAP,
or
in
a
data
store,
such
a
DB2
database,
to
the
application
caller.
These
directory
services
or
data
stores
may
require
a
proprietary
authentication
step
before
permitting
access
to
stored
information.
The
developer
of
each
entitlement
service
plug-in
must
implement
these
proprietary
authentication
steps.
The
authorization
API
does
not
provide
functions
to
implement
proprietary
authentication
models.
The
authorization
API
does,
however,
provide
the
plug-in
initialization
interface
azn_svc_initialize().
This
interface
permits
the
passing
of
proprietary
data
in
parameters
to
the
service
initialization
function.
Alternately,
the
developer
can
use
the
initialization
parameters
to
authenticate
the
authorization
API
application
before
loading
the
entitlement
service
plug-in.
In
this
case,
the
entitlement
service
plug-in
can
inherit
privileges
from
the
authorization
API
application.
Using
authorization
API
interfaces
Entitlement
service
plug-ins
should
access
the
contents
of
passed
parameters
using
the
authorization
API.
The
entitlement
service
plug-ins
are
not
required
to
make
use
of
any
other
features
or
interfaces
of
the
authorization
API
other
than
those
that
provide
access
to
these
data
types.
The
entitlement
service
plug-in
becomes
part
of
the
authorization
API
application’s
address
space.
The
service
plug-in
can
assume
that
if
it
is
denied
access
to
a
particular
authorization
API
interface
that
the
calling
application
was
not
allowed
to
perform
the
operation.
108
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
Entitlement
service
error
codes
The
following
functions
can
receive
an
error
code
as
a
result
of
calling
an
entitlement
service:
v
azn_initialize()
v
azn_shutdown()
v
azn_entitlement_get_entitlements()
For
information
on
error
codes
for
azn_initialize()
and
azn_shutdown(),
see
“Using
error
codes”
on
page
88.
The
azn_entitlement_get_entitlements()
function
returns
the
following
error
codes:
Error
Code
Description
AZN_S_INVALID_CREDS_HDL
The
credentials
handle
supplied
is
invalid.
AZN_S_INVALID_ENTITLEMENTS_SVC
The
entitlement
service
identifier
is
invalid.
AZN_S_INVALID_APP_CONTEXT_HDL
The
attribute
list
handle
for
the
application
context
is
invalid.
AZN_S_INVALID_ENTITLEMENTS_HDL
The
attribute
list
handle
for
the
entitlements
is
invalid.
AZN_S_FAILURE
An
implementation
specific
error
or
failure
has
occurred.
An
implementation
specific
minor
error
code
should
be
returned
in
the
status
code
for
the
caller
to
extract
with
azn_error_minor().
Each
entitlement
service
plug-in
can
optionally
return
minor
error
codes
that
express
errors
specific
to
the
service
plug-in
implementation.
For
more
information
on
implementing
minor
error
codes,
see
“Minor
error
codes”
on
page
90.
Chapter
7.
Entitlement
service
plug-ins
109
Dynamic
ADI
retrieval
services
This
class
of
entitlement
service
is
designed
to
fulfill
requests
for
access
decision
information
(ADI)
that
is
needed
for
the
Tivoli
Access
Manager
authorization
engine
to
perform
an
authorization
rule
evaluation.
To
meet
the
classification
of
attribute
retrieval
service
the
entitlement
service
needs
to
take
a
specific
set
of
inputs
and
return
to
the
caller
a
specific
set
of
outputs
in
XML
format.
Dynamic
ADI
retrieval
services
are
configured
in
the
same
way
as
other
entitlement
services.
To
have
the
authorization
rules
evaluator
call
a
dynamic
ADI
retrieval
service
when
ADI
is
required
to
complete
a
rule
evaluation,
you
must
specify
the
service
ID
of
the
entitlement
service
as
a
value
for
the
configuration
file
entry
dynamic-adi-entitlement-services
or
specified
to
the
azn_initialize()
application
interface
using
the
initialization
attribute
azn_init_dynamic_adi_entitlement_services.
Multiple
service
IDs
can
be
specified
in
this
way.
They
are
called
in
the
order
in
which
they
are
specified
in
the
configuration
setting
or
initialization
parameter.
Note:
Tivoli
Access
Manager
also
supports
authorization
rule
evaluation
when
attribute
retrieval
services
are
not
required.
For
more
information
on
authorization
rules,
see
IBM
Tivoli
Access
Manager
Base
Administration
Guide.
An
entitlement
service
may
provide
other
classes
of
entitlement
services
in
addition
to
providing
a
attribute
retrieval
service.
Existing
entitlement
services
may
be
adapted
to
include
attribute
retrieval
service
functionality.
The
Tivoli
Access
Manager
authorization
ADK
package
includes
an
example
entitlement
service.
The
source
file
is
azn_ent_svc_demo.c.
This
example
file
shows
how
an
entitlement
service
can
be
written
to
perform
the
function
of
a
standard
authorization
API
entitlement
service
to
be
called
from
azn_entitlement_get_entitlements().
This
example
file
also
shows
how
an
entitlement
service
can
perform
the
functions
of
a
dynamic
ADI
retrieval
service
and
a
credential
attribute
retrieval
service.
In
addition,
the
Tivoli
Access
Manager
runtime
provides
a
dynamic
ADI
entitlement
service
that
can
be
used
to
retrieve
dynamic
ADI
attributes
for
use
in
authorization
rules
from
the
Tivoli
Access
Manager
user
registry.
For
more
information,
see
“Registry
attribute
entitlement
service
overview”
on
page
113.
The
attribute
retrieval
service
must
accept
the
azn_perminfo_rules_adi_request
attribute
as
input.
This
is
the
same
attribute
that
can
be
returned
as
permission
information
by
the
azn_decision_access_allowed_ext()
authorization
API
call.
The
values
for
the
attribute
are
also
the
same.
This
attribute
is
a
request
from
the
authorization
engine
for
ADI
that
it
needs
in
order
to
evaluate
a
rule.
The
attribute
retrieval
service
must
scan
the
list
of
ADI
container
names
found
in
the
azn_perminfo_rules_adi_request
attribute.
If
it
can
provide
the
data
for
any
of
these
ADI,
it
must
return
the
data
to
the
caller
as
an
attribute
name/value
pair
in
the
entitlements
attribute
list
parameter.
Each
item
of
ADI
found
will
be
added
as
a
separate
attribute
in
the
output
attribute
list,
with
an
attribute
name
that
corresponds
to
the
ADI
container
name.
The
value
of
the
ADI
item
is
added
as
a
value
to
the
attribute.
ADI
can
have
multiple
values
so
additional
values
can
be
added
to
the
same
attribute
name.
If
the
value
of
the
ADI
data
is
a
simple
type,
for
example
a
string
or
a
numeric
value,
then
the
attribute
type
can
be
either
a
string
or
unsigned
long
type.
If
the
110
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
data
is
a
complex
data
type,
the
value
can
be
expressed
in
XML
as
a
single
string,
in
which
case
the
attribute
type
is
string.
ADI
values
formatted
in
XML
must
be
formatted
as
an
XML
element
with
the
element
name
matching
the
container
name
of
the
ADI
item.
For
example,
given
a
request
for
an
ADI
item
called
customer,
which
contains
the
customer
name,
address
and
credit
card
data,
the
attribute
retrieval
service
would
format
the
following
XML
data
as
a
single
string
and
add
it
as
an
attribute
value
to
an
attribute
named
customer:
<customer>
<name>John
Smith</name>
<address>3004
Mission
St,
Santa
Cruz,
CA</address>
<credit_card>5555
5555
5555
5555</credit_card>
</customer>
The
attribute
retrieval
service
must
be
aware
of
namespace
identifiers
in
ADI
container
names
when
processing
requests
for
ADI.
If
the
customer
item
above
was
defined
within
an
XML
namespace
with
the
ID
arl,
then
the
container
name
requested
by
the
authorization
engine
would
be
arl:customer.
When
the
attribute
retrieval
service
is
processing
the
container
name,
it
should
consider
that
a
namespace
ID
might
be
prepended
to
an
ADI
container
name.
If
the
container
name
contains
a
namespace
ID,
then
the
customer
XML
element
definition
should
also
include
the
appropriate
namespace
declaration
for
the
item.
The
declaration
should
also
match
any
similar
declaration
made
in
the
xsl-stylesheet-prolog
configuration
entry
in
the
authorization
client’s
configuration
file.
The
namespace
declaration
is
included
in
the
element
start
token
which,
in
the
example
container
name
of
arl:customer,
now
becomes
<arl:customer>.
To
properly
define
the
arl:customer
item
to
be
in
the
namespace
with
an
ID
of
arl,
the
<customer>
and
</customer>
elements
in
the
above
example
would
be
replaced
as
follows:
<arl:customer
xmlns:arl="http://www.arl.com.au">
<name>John
Smith</name>
<address>3004
Mission
St,
Santa
Cruz,
CA</address>
<credit_card>5555
5555
5555
5555</credit_card>
</arl:customer>
If
the
attribute
retrieval
service
can’t
provide
data
for
some
or
all
of
the
requested
items,
it
should
return
values
for
the
container
names
that
it
knows
about,
along
with
a
status
of
AZN_S_COMPLETE.
It
should
not
return
an
error
if
it
can’t
provide
values
for
the
ADI.
However,
it
can
and
should
return
an
error
if
the
service
is
configured
incorrectly
or
it
encounters
other
problems
during
execution.
Note:
For
optimum
security,
ensure
that
this
service
is
installed
with
permissions
that
permit
only
the
owner
of
the
service
to
modify
it.
Chapter
7.
Entitlement
service
plug-ins
111
Credential
attributes
entitlement
service
This
class
of
entitlement
service
is
designed
to
provide
attributes
to
the
authorization
credential
building
process
performed
by
azn_id_get_creds().
When
a
credential
attribute
entitlement
service
is
configured,
azn_id_get_creds()
calls
out
to
this
service
using
the
azn_entitlement_get_entitlements()
interface
and
then
inserts
the
returned
attributes
into
the
authorization
credential
it
is
building.
This
class
of
entitlement
service
conforms
to
the
general
requirements
of
all
authorization
entitlement
services.
There
are
no
specific
requirements
placed
upon
credential
attribute
entitlement
services
since
they
are
called
by
azn_id_get_creds()
with
no
specific
parameters
other
than
those
passed
to
a
normal
entitlement
service.
Credential
attribute
retrieval
entitlement
services
are
configured
in
the
same
way
as
other
entitlement
services.
To
have
the
azn_id_get_creds()
call
your
credential
attributes
entitlement
service
when
authorization
credentials
are
being
built,
you
must
specify
the
service
ID
of
the
entitlement
service
as
a
value
for
the
configuration
file
entry
cred-attribute-entitlement-services
or
specify
the
azn_initialize()
application
interface
using
the
initialization
attribute
azn_init_cred_attribute_entitlement_services.
Multiple
service
IDs
can
be
specified
in
this
way.
They
are
called
in
the
order
in
which
they
are
specified
in
the
configuration
file
or
the
initialization
parameter.
The
Tivoli
Access
Manager
authorization
ADK
package
includes
an
example
entitlement
service.
The
source
file
is
azn_ent_svc_demo.c.
This
example
file
shows
how
an
entitlement
service
can
be
written
to
perform
the
function
of
a
standard
authorization
API
entitlement
service
to
be
called
from
azn_entitlement_get_entitlements().
This
example
file
also
shows
how
an
entitlement
service
can
perform
the
functions
of
a
dynamic
ADI
retrieval
service
and
a
credential
attribute
retrieval
service.
The
following
section
describes
a
credential
attributes
entitlement
service
that
is
supplied
with
the
Tivoli
Access
Manager
authorization
runtime
package
and
that
can
be
used
to
retrieve
attributes
from
the
Tivoli
Access
Manager
user
registry.
This
section
contains
the
following
topics:
v
“Registry
attribute
entitlement
service
overview”
on
page
113
v
“Registry
attribute
entitlement
service
configuration”
on
page
115
v
“Migration
from
a
previous
release”
on
page
118
v
“Configuring
a
credential
attributes
entitlement
service
as
a
dynamic
ADI
retrieval
service”
on
page
119
112
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
Registry
attribute
entitlement
service
overview
This
entitlement
service
retrieves
attributes
and
values
from
the
user
registry.
This
entitlement
service
is
a
shared
library
that
is
dynamically
loaded
during
the
authorization
API
application
initialization.
The
attributes
that
are
retrieved
from
the
user
registry
can
be
utilized
in
the
following
ways:
v
To
add
extended
attributes
to
the
user
credential
v
To
use
registry
data
during
an
authorization
rule
evaluation
v
For
any
other
application-specific
purpose
that
can
utilize
an
attribute
list
retrieved
by
either
azn_id_get_creds()
or
azn_entitlement_get_entitlements()..
When
using
this
entitlement
service
to
provide
data
for
customizing
user
credentials,
the
administrator
must
specify
which
attributes
are
to
be
added
to
the
credential.
The
attributes
must
be
declared
in
the
application
configuration
file
or
in
an
entitlement
service
configuration
file,
or
passed
to
azn_entitlement_get_entitlements()
in
the
input
parameter
app_context.
Tivoli
Access
Manager,
when
asked
to
build
a
credential
for
a
user,
maps
these
configuration
file
entries
to
Tivoli
Access
Manager
attribute
names.
For
each
name,
the
entitlement
service
retrieves
the
corresponding
value
from
the
user
registry,
and
the
new
attribute
name/value
pairs
are
added
to
the
credential
attribute
list.
The
process
flow
is:
1.
The
application
starts
and
initializes
the
authorization
API.
During
initialization
the
authorization
API
loads
any
entitlement
services
that
are
configured.
2.
The
application
calls
azn_id_get_creds()
to
obtain
a
credential
for
the
client.
This
function
call
looks
for
a
list
of
credential
attribute
entitlement
service
IDs
to
call.
When
one
or
more
service
IDs
are
found,
the
function
calls
out
to
the
entitlement
service
for
each
service
ID.
3.
The
service
dispatcher
loads
the
registry
attribute
entitlement
service
(as
identified
by
a
service
ID
for
a
credential
attribute
entitlement
service)
with
a
parameter
that
specifies
a
configuration
file
name.
The
configuration
file
contains
the
name/value
(also
called
tag/value)
attributes
to
retrieve.
4.
The
service
takes
the
values
from
the
registry
and
adds
them
into
an
authorization
API
attributes
list.
The
attribute
names
are
made
from
the
tags
configured
in
the
configuration
file.
The
values
are
the
values
in
the
user
registry.
The
entitlement
service
returns
this
list
to
the
authorization
API.
5.
The
azn_id_get_creds()
function
adds
this
attribute
list
as
part
of
the
credential
and
returns
to
the
caller.
The
attributes
retrieved
by
the
credential
attributes
entitlement
service
do
not
necessarily
have
to
be
placed
directly
into
a
user
credential.
These
name/value
pairs
from
the
user
registry
are
placed
into
an
attribute
list,
which
can
then
be
used
for
purposes
other
than
adding
information
to
a
user
credential.
In
this
case,
the
process
flow
is:
1.
The
application
starts
and
initializes
the
authorization
API.
During
initialization
the
authorization
API
loads
any
entitlement
services
that
are
configured
2.
The
application
calls
azn_entitlement_get_entitlements(),
specifying
the
service
ID
of
the
registry
attribute
retrieval
service,
in
order
to
obtain
the
attribute
list.
The
authorization
API
initialization
algorithm
enables
users
to
override
configuration
information
specified
in
a
configuration
file.
The
caller
can
do
Chapter
7.
Entitlement
service
plug-ins
113
this
through
either
command
line
arguments
or
through
API
initialization
parameters.
Use
the
app_context
input
parameter
to
azn_entitlement_get_entitlements()
to
specify
exactly
which
objects
are
to
be
retrieved.
By
this
method,
you
do
not
have
to
retrieve
all
objects
for
the
user.
Alternatively,
the
list
of
attributes
can
also
be
configured
in
a
file,
and
the
file
name
passed
as
an
argument
to
the
entitlement
service
library
at
load
time.
3.
The
entitlement
service
is
initialized
with
a
parameter
that
specifies
a
configuration
file
name.
The
configuration
file
contains
the
name/value
(also
called
tag/value)
attributes
to
retrieve.
4.
The
registry
attribute
retrieval
service
takes
the
values
from
the
registry
and
adds
them
into
an
authorization
API
attributes
list.
The
attribute
names
are
made
from
the
tags
configured
in
the
configuration
file.
The
values
are
the
values
in
the
user
registry.
The
entitlement
service
returns
this
list
to
the
authorization
API.
5.
The
azn_entitlement_get_entitlements()
function
call
returns
the
attribute
list.
If
no
attributes
are
returned
from
the
registry,
the
attribute
list
is
returned
empty.
6.
The
application
does
whatever
it
wants
with
the
attribute
list.
114
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
Registry
attribute
entitlement
service
configuration
This
section
contains
a
configuration
overview
and
a
set
of
configuration
steps:
v
“Configuration
overview”
v
“Step
1
—
Declare
a
Service
ID
and
a
library
name”
v
“Step
2
—
Enable
automatic
startup
of
the
entitlement
service”
on
page
116
v
“Step
3
—
Specify
the
attributes
to
be
added
to
the
credential”
on
page
116
v
“Obtaining
attributes
through
an
entitlement
service
without
accessing
a
user
credential”
on
page
117
Configuration
overview
Use
of
a
credential
attribute
entitlement
service
is
specified
in
the
application
configuration
file.
The
example
configuration
file
is
aznapi.conf.
Alternatively,
you
can
specify
the
credential
attribute
entitlement
service
by
supplying
a
parameter
to
init_data
when
calling
azn_initialize()
to
initialize
the
authorization
API.
v
Attribute
List
Entry:
azn_init_cred_attribute_entitlement_services
v
Configuration
File
Entry:
cred-attribute-entitlement-services
v
Configuration
File
Stanza:
[aznapi-configuration]
Each
entry
is
part
of
a
list
of
authorization
API
entitlement
service
IDs
that
will
be
queried
by
the
azn_id_get_creds()
interface
to
compile
a
list
of
attributes
to
be
added
to
the
user
credential
while
the
credential
is
being
built.
Each
service
ID
is
queried
in
the
order
of
declaration
here
and
the
attributes
returned
in
the
entitlements
parameter
are
inserted
into
the
credential
attribute
list
of
each
principal
built
with
the
azn_id_get_creds()
call.
cred-attribute-entitlement-services
=
myEntSvcID
cred-attribute-entitlement-services
=
myOtherEntSvcID
This
mechanism
cannot
be
used
to
override
the
read-only
attributes
in
the
credential
attribute
list,
which
includes
the
principal
name,
principal
UUID,
and
others.
The
read-only
attributes
are
listed
in
“Modifying
the
contents
of
a
credential”
on
page
64.
The
exception
to
this
rule
is
for
the
azn_cred_groups
attribute.
If
this
attribute
is
found
in
the
list
of
returned
attributes,
then
azn_id_get_creds()
will
first
determine
whether
the
application
has
loaded
the
credential
group
modification
authorization
service,
azn_mod_rad
If
this
specific
group
modification
service
has
been
loaded,
azn_id_get_creds()
automatically
calls
the
service
to
add
the
new
groups
to
the
credential.
Administrators
who
do
not
want
this
capability
should
ensure
that
the
azn_mod_rad
service
is
not
and
cannot
be
loaded
by
the
application.
Note:
For
more
information
on
this
service,
see
“Credentials
modification
service”
on
page
101.
Step
1
—
Declare
a
Service
ID
and
a
library
name
A
user-defined
service
ID
specifies
this
service.
For
example,
MY_CRED_ATTRS_SVC.
The
value
assigned
to
this
ID
can
be
either
the
service,
or
an
entirely
different
one
written
by
an
authorization
API
application
developer.
The
value
for
the
registry
attribute
retrieval
service
that
is
part
of
the
Tivoli
Access
Manager
runtime
environment
is
azn_ent_cred_attrs.
For
example:
[aznapi-entitlement-services]
MY_CRED_ATTRS_SVC
=
azn_ent_cred_attrs
YOUR_CRED_ATTRS_SVC
=
name_of_shared_library&
name_of_configuration_file
Chapter
7.
Entitlement
service
plug-ins
115
The
command-line
arguments
are
optional.
The
Tivoli
Access
Manager
shared
library
takes
one
optional
argument.
This
argument
must
be
the
name
of
the
configuration
file
that
contains
the
attributes
stanzas.
Note
that
this
optional
argument
takes
precedence
over
any
entry
that
you
might
have
configured
in
the
application
configuration
file.
Note:
For
optimum
security,
ensure
that
this
service
is
installed
with
permissions
that
permit
only
the
owner
of
the
service
to
modify
it.
Step
2
—
Enable
automatic
startup
of
the
entitlement
service
Services
to
be
automatically
called
by
azn_id_get_creds()
must
also
be
listed
in
the
[aznapi-configuration]
stanza.
Services
listed
under
this
stanza
are
enabled
and
called
automatically.
To
specify
that
the
service
ID
refers
to
a
credential
attributes
entitlement
service,
you
must
use
the
keyword
cred-attributes-entitlement-services.
For
example:
[aznapi-configuration]
cred-attribute-entitlement-services
=
MY_CRED_ATTRS_SVC
cred-attribute-entitlement-services
=
YOUR_CRED_ATTRS_SVC
Step
3
—
Specify
the
attributes
to
be
added
to
the
credential
The
attributes
to
be
added
to
the
credential
are
configured
in
several
stanzas.
This
information
can
go
in
the
application
configuration
file,
or
as
a
separate
file
that
is
passed
in
to
the
service
[MY_CRED_ATTRS_SVC]
user
=
azn_cred_authzn_id
group
=
cn=enterprise,
o=tivoli
[MY_CRED_ATTRS_SVC:user]
credattrs_lastname
=
sn
credattrs_employeetype
=
employeetype
credattrs_address
=
homepostaladdress
credattrs_email
=
[MY_CRED_ATTRS_SVC:group]
credattrs_businesscategory
=
businesscategory
The
stanza
name
[MY_CRED_ATTRS_SVC]
is
the
Service
ID.
Inside
this
stanza
are
sources
of
attributes
to
be
retrieved.
The
source
names,
such
as
user
and
group
are
used
to
identify
the
source
location
in
the
registry
and
are
defined
by
the
user.
The
values
for
these
sources
are
registry
identifiers
that
exist
in
the
registry.
The
values
can
be
existing
credential
attribute
names.
If
this
is
the
case,
the
service
automatically
finds
and
uses
the
respective
values.
Configure
the
registry
attribute
for
each
of
the
sources
in
a
separate
stanza.
The
syntax
of
the
separate
stanza
is
the
service
ID
library
name
followed
by
a
colon
(:)
and
then
the
source
name.
This
connection
is
necessary
because
more
than
one
service
can
be
configured
in
the
same
file.
The
configuration
file
entries
contain
mappings
of
user
registry
attribute
to
user-defined
credential
attributes.
For
example,
in
an
LDAP
user
registry,
the
DN
for
a
user
could
be
cn=joeuser,
o=tivoli
For
this
user,
the
LDAP
user
registry
entries
could
be:
116
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
sn=Smith
employeetype=bankteller
homepostaladdress="3004
Mission
St
Santa
Cruz
CA
95060"
businesscategory=finance
Using
the
example
configuration
entries
shown
above,
the
attribute
list
returned
by
either
azn_id_get_creds()
or
azn_entitlement_get_entitlements()
would
have
the
following
entries
Attribute
name
Attribute
value
credattrs_lastname
Smith
credattrs_employeetype
bankteller
credattrs_address
3004
Mission
St
Santa
Cruz
CA
95060
credattrs_email
credattrs_businesscategory
finance
Note
that
the
service,
source,
and
attributes
can
be
multi-valued.
If
you
specify
the
same
attribute
name
as
a
stanza
entry
keyword,
then
the
attributes
retrieved
will
be
added
as
a
multi-valued
attribute
even
when
they
come
from
different
sources.
For
example,
more
than
one
entitlement
service
can
be
chained
together.
Chaining
enables
values
retrieved
from
one
service
to
be
used
as
input
values
for
another
service.
Likewise,
attributes
can
be
retrieved
from
more
than
one
DN
in
the
user
registry.
Thus,
using
the
example
above,
you
could
add
values
from
multiple
users
(DNs)
to
one
credattrs_businesscategory
attribute,
if
you
wanted
a
list
of
all
the
businesscategory
entries
for
a
group
of
users.
For
example,
if
you
want
to
build
an
attribute
called
myemployeeinfo
to
add
to
the
credential,
and
you
want
this
attribute
to
contain
the
last
name
and
employee
type
of
everyone
who
authenticates,
you
could
then
define
the
following:
[myID]
source
=
azn_cred_authzn_id
[myID:source]
myemployeeinfo
=
lastname
myemployeeinfo
=
employeetype
Obtaining
attributes
through
an
entitlement
service
without
accessing
a
user
credential
You
can
use
the
azn_entitlement_get_entitlements()
call
to
use
the
registry
attribute
entitlement
service
without
accessing
the
user
credential,
as
described
in
“Registry
attribute
entitlement
service
overview”
on
page
113.
To
do
this,
you
need
to
add
the
attribute
azn_ent_cred_attrs_attribute
to
the
app_context
attribute
list
that
is
passed
as
an
input
parameter
to
azn_entitlement_get_entitlements().
The
values
for
attribute
name
azn_ent_cred_attrs_attribute
must
be
of
the
form
registry_id:attribute.
For
example,
a
value
for
azn_ent_cred_attrs_attirbute
would
be:
azn_cred_authzn_id:employeetype
The
format
of
the
returned
entitlements
attribute
list
is:
name
=
registry_id:attribute,
value
=
value
Chapter
7.
Entitlement
service
plug-ins
117
Migration
from
a
previous
release
Developers
that
have
used
the
tag/value
function
in
previous
versions
of
Tivoli
Access
Manager
can
migrate
their
existing
deployments
to
Version
5.1.
The
migration
requires
one
manual
step:
v
The
stanza
[ldap-ext-cred-tags]
and
its
contents
must
be
manually
copied
from
the
previous
version
pd.conf
to
the
new
application
configuration
file.
For
example,
webseald.conf,
or
aznapi.conf,
or
your_app_name.conf.
v
Tivoli
Access
Manager
will
automatically
migrate
the
data
to
the
new
information
format
For
example,
in
the
old
pd.conf
file:
[ldap-ext-cred-tags]
attribute1
=
address
attribute2
=
The
information
above
is
migrated
in
the
new
configuration
files,
where
the
following
new
entries
are
added
or
created
as
needed:
[aznapi-configuration]
cred-attribute-entitlement-services
=
LEGACY_ldap-ext-cred-tags
[aznapi-entitlement-services]
LEGACY_ldap-ext-cred-tags
=
azn_ent_cred_attrs
[LEGACY_ldap-ext-cred-tags]
registry_id
=
azn_cred_registry_id
[LEGACY_ldap-ext-cred-tags:registry_id]
tagvalue_attribute1
=
address
tagvalue_attribute2
=
Note
that
the
original
pd.conf
file
is
not
changed.
The
source
name
DN
comes
from
the
caller
credential
attribute
azn_cred_registry_id.
The
prefix
tagvalue_
is
prepended
to
each
source
attribute
name
to
ensure
backwards
compatibility
with
the
previous
version.
Note
that
in
the
previous
version,
the
prefix
was
hard-coded.
Note
that
the
attribute
value
azn_cred_registry_id
can
be
changed
to
a
more
generic
keyword,
such
as
azn_cred_authzn_id
after
migration
is
completed.
This
change
would
reflect
the
change
from
the
previous
version
support
(LDAP
only)
to
the
current
version
support
(more
than
LDAP).
118
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
Configuring
a
credential
attributes
entitlement
service
as
a
dynamic
ADI
retrieval
service
The
credential
attributes
entitlement
service
can
be
used
by
the
authorization
rules
evaluator
to
retrieve
registry
data
dynamically
for
rule
evaluation.
No
new
interfaces
are
required.
A
special
input
parameter
azn_perminfo_rules_adi_request
indicates
that
this
is
a
dynamic
ADI
request.
The
result
is
returned
in
a
specific
format
as
required
by
the
attribute
retrieval
entitlement
service
interface.
In
this
case,
the
entitlement
service
ID
is
added
as
an
entry
to
the
dynamic-adi-entitlement-service
entry
in
the
[aznapi-configuration]
stanza.
The
service
can
be
called
from
multiple
applications.
To
use
credential
attributes
entitlement
service
as
an
attribute
retrieval
service,
complete
the
following
steps:
v
“Step
1
—
Define
a
policy
to
be
enforced
as
an
authorization
rule”
v
“Step
2
—
Declare
a
Service
ID
and
a
library
name”
v
“Step
3
—
Enable
automatic
startup
of
the
entitlement
service
as
a
dynamic
ADI
retrieval
service”
on
page
120
v
“Step
4
—
Define
a
namespace
in
the
resource
manager
configuration
file”
on
page
120
v
“Step
5—
Define
the
namespace
in
the
policy
server
configuration
file”
on
page
120
v
“Step
6:
Create
an
authorization
rule”
on
page
121
You
can
also
obtain
entitlements
without
calling
azn_id_get_creds():
v
“Obtaining
entitlements
through
a
dynamic
ADI
retrieval
service
without
accessing
a
user
credential”
on
page
121
Step
1
—
Define
a
policy
to
be
enforced
as
an
authorization
rule
To
use
the
authorization
rules
engine,
you
must
define
a
policy
that
will
be
used
to
test
a
condition
when
evaluating
an
access
request.
For
example,
the
policy
could
be
stated
as
follows:
Allow
access
to
this
protected
resource
only
if
the
user
requesting
access
has
an
LDAP
user
registry
that
has
a
UID
entry
with
the
value
joeuser.
This
policy
will
need
to
be
expressed
as
configuration
file
settings
and
as
an
authorization
rule.
These
actions
are
taken
by
the
remaining
steps
in
this
set
of
instructions.
These
configuration
steps
will
use
the
following
information:
v
You
can
use
the
azn_cred_registry_id
permission
info
attribute
in
the
user
credential
to
obtain
the
user
registry
entry
for
the
user.
In
the
case
of
an
LDAP
user
registry,
azn_cred_registry_id
contains
the
Distinguished
Name
(DN).
v
LDAP
user
registry
entries
consist
of
name=value
pairs.
There
can
be
a
UID=user_name.
In
this
case,
the
rule
will
be
looking
for
UID=joeuser.
Step
2
—
Declare
a
Service
ID
and
a
library
name
A
user-defined
service
ID
specifies
this
service.
For
example,
MY_CRED_ATTR_SVC.
The
value
assigned
to
this
ID
can
be
either
the
default
credentials
attribute
entitlement
service,
or
an
entirely
different
one
written
by
an
authorization
API
application
developer.
The
default
credentials
attribute
entitlement
service
which
is
part
of
the
Tivoli
Access
Manager
runtime
environment
is
azn_ent_cred_attrs.
Chapter
7.
Entitlement
service
plug-ins
119
For
example:
[aznapi-entitlement-services]
MY_CRED_ATTRS_SVC
=
azn_ent_cred_attrs
The
command-line
arguments
are
optional.
The
Tivoli
Access
Manager
built-in
credentials
attribute
entitlement
service
takes
one
optional
argument.
This
argument
must
be
the
name
of
the
configuration
file
that
contains
the
attributes
stanzas.
Note
that
this
optional
argument
takes
precedence
over
any
entry
that
you
might
have
configured
in
the
application
configuration
file.
Note:
For
optimum
security,
ensure
that
this
service
is
installed
with
permissions
that
permit
only
the
owner
of
the
service
to
modify
it.
Step
3
—
Enable
automatic
startup
of
the
entitlement
service
as
a
dynamic
ADI
retrieval
service
Services
to
be
automatically
called
by
azn_id_get_creds()
must
also
be
listed
in
the
[aznapi-configuration]
stanza.
Services
listed
under
this
stanza
are
enabled
and
called
automatically.
The
credential
attributes
entitlement
service
can
optionally
be
called
by
the
rules
evaluator
as
a
attribute
retrieval
service.
To
specify
that
the
service
ID
refers
to
a
credential
attributes
entitlement
service
that
is
being
used
as
an
attribute
retrieval
service,
you
must
use
the
keyword
dynamic-adi-entitlement-services.
For
example:
[aznapi-configuration]
dynamic-adi-entitlement-services
=
MY_CRED_ATTRS_SVC
Step
4
—
Define
a
namespace
in
the
resource
manager
configuration
file
The
resource
manager
is
the
application
that
makes
the
access
decision
by
calling
azn_decision_access_allowed()
or
azn_decision_access_allowed_ext().
The
resource
manager
can
be
an
application
(such
as
WebSEAL)
provided
by
Tivoli
Access
Manager
or
can
be
an
authorization
API
client.
1.
Add
entries
to
the
[aznapi-configuration]
stanza
to
specify
the
namespace
that
will
be
used
by
the
authorization
rules
evaluator.
In
the
following
example,
the
text
in
bold
has
been
added
to
the
default
template:
[aznapi-configuration]
xsl-stylesheet-prolog
=
<xml
version=’1.0’
encoding=’UTF-8’?>
>
<xsl:stylesheet
xmlns:xsl=’http://www.w3.org/1999/XSL/Transform’
xmlns:azn_cred_registry_id=’http://my.company.com’
version=’1.0’>
<xsl:template
match=’text()’>
</xsl:template>
2.
Define
the
namespace
in
the
[xmladi-attribute-definitions]
stanza:
[xmladi-attribute-definitions]
xmlns:azn_cred_registry_id=
"http://my.company.com"
appID
=
"my
app
id"
Step
5—
Define
the
namespace
in
the
policy
server
configuration
file
When
the
policy
server
runs,
it
builds
the
authorization
database.
When
building
this
database,
the
policy
server
builds
authorization
rules
based
on
the
namespaces
that
are
defined
in
the
policy
server
configuration
file,
ivmgrd.conf.
Add
the
same
configuration
file
entries
to
the
policy
server
configuration
file.
[aznapi-configuration]
xsl-stylesheet-prolog
=
<xml
version=’1.0’
encoding=’UTF-8’?>
<xsl:stylesheet
xmlns:xsl=’http://www.w3.org/1999/XSL/Transform’
xmlns:azn_cred_registry_id=’http://my.company.com’
version=’1.0’>
<xsl:template
match=’text()’>
</xsl:template>
120
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
[xmladi-attribute-definitions]
xmlns:azn_cred_registry_id=
"http://my.company.com"
appID
=
"my
app
id"
Step
6:
Create
an
authorization
rule
Create
a
rule
that
identifies
the
user
whose
credential
information
must
be
accessed
for
whom
authorization
rule
information.
The
rule
says
to
grant
access
to
the
specified
user,
when
the
UID
of
the
user
is
an
attribute
of
the
credential.
This
attribute
value
is
obtained
from
the
azn_cred_registry_id:
<xsl:if
test=’azn_cred_registry_id:uid="joeuser"’>!TRUE!</xsl:if>
The
azn_cred_registry_id
specifies
a
user
DN.
The
entitlement
service
retrieves
the
user
registry
entries
for
the
DN.
The
authorization
rule
engine
then
checks
to
see
if
the
value
of
the
UID
entry
is
joeuser.
If
it
is,
access
is
allowed.
If
it
is
not,
access
is
denied.
You
can
use
either
the
Web
Portal
Manager
utility
or
pdadmin
to
create
authorization
rules.
For
more
information,
see
IBM
Tivoli
Access
Manager
Base
Administration
Guide.
Obtaining
entitlements
through
a
dynamic
ADI
retrieval
service
without
accessing
a
user
credential
You
can
use
the
azn_entitlement_get_entitlements()
call
to
use
the
credential
attributes
entitlement
service
without
accessing
the
user
credential,
as
described
in
“Registry
attribute
entitlement
service
overview”
on
page
113.
You
can
also
use
azn_entitlement_get_entitlements()
to
use
the
credential
attributes
entitlement
service
as
a
dynamic
ADI
retrieval
service.
To
do
this,
you
need
to
add
the
permission
attribute
azn_perminfo_rules_adi_request
to
the
app_context
attribute
list
that
is
passed
as
an
input
parameter
to
azn_entitlement_get_entitlements().
The
values
for
attribute
name
azn_perminfo_rules_adi_request
must
be
of
the
form
source:attr.
For
example,
using
the
policy
defined
in
“Step
1
—
Define
a
policy
to
be
enforced
as
an
authorization
rule”
on
page
119,
the
value
for
azn_perminfo_rules_adi_request
would
be:
azn_cred_registry_id:uid
Chapter
7.
Entitlement
service
plug-ins
121
122
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
Chapter
8.
Administration
service
plug-ins
This
chapter
contains
the
following
topics:
v
“Understanding
administration
service
plug-ins”
on
page
124
v
“Configuring
administration
service
plug-ins”
on
page
127
v
“Initializing
and
shutting
down
administration
service
plug-ins”
on
page
129
v
“Using
an
administration
service
plug-in”
on
page
130
v
“Error
codes”
on
page
132
v
“Deploying
an
administration
service
plug-in”
on
page
135
©
Copyright
IBM
Corp.
2000,2003
123
Understanding
administration
service
plug-ins
The
administration
service
makes
available
to
applications
several
administrative
functions
that
operate
on
objects
in
the
IBM
Tivoli
Access
Manager
(Tivoli
Access
Manager)
protected
object
namespace.
Application
developers
can
write
a
plug-in
to
the
administration
service
that
applies
these
administrative
functions
to
objects
in
a
section
of
the
namespace
that
is
specific
to
the
application.
Through
the
plug-in,
application
developers
can
also
specify
administrative
actions
that
are
specific
to
objects
in
the
application-specific
namespace.
The
administration
service
differs
from
other
authorization
API
services
in
that
it
does
not
provide
direct
access
to
the
administrative
function
to
the
calling
applications.
Instead,
the
calling
applications
use
the
Tivoli
Access
Manager
administration
API
to
send
a
request.
For
example,
the
administration
service
functions
are
called
in
response
to
administrative
operations
that
are
issued
by
a
calling
application
such
as
the
pdadmin
command
line
interface,
the
Tivoli
Access
Manager
Web
Portal
Manager
graphical
console,
or
a
third-party
application
that
has
been
written
to
use
the
Tivoli
Access
Manager
administration
API.
The
administration
service
maps
the
administration
API
calls
to
the
corresponding
administration
service
API
calls,
and
carries
out
the
requested
action.
There
is
a
one-to-one
mapping
between
several
administration
API
functions
and
a
corresponding
administration
service
function.
The
administration
service
supports
dynamic
object
creation
and
task
execution
by
adding
an
externalized
administration
family
of
functions
to
the
authorization
API.
The
name
of
each
of
these
functions
is
prefixed
by
azn_admin.
You
implement
these
functions
within
libraries
that
are
registered
with
the
Authorization
administration
service
by
an
authorization
API
client
application.
124
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
In
Figure
4,
the
user
application
or
GUI
sends
an
administrative
operation
through
the
Tivoli
Access
Manager
administration
API
to
the
Tivoli
Access
Manager
policy
server.
The
Tivoli
Access
Manager
policy
server
forwards
the
call
to
the
administration
service
interface
of
the
authorization
API
resource
manager
application
that
is
configured
to
administer
the
target
protected
object
space
for
the
administration
request.
The
service
dispatcher
within
the
authorization
API
resource
manager
application
calls
the
applicable
service
interface
of
all
administration
service
plug-ins
that
have
registered
to
service
this
type
of
request.
Each
plug-in’s
service
interface
is
called
in
turn
by
the
dispatcher
and
the
results
are
returned
to
the
Tivoli
Access
Manager
policy
server.
The
Tivoli
Access
Manager
policy
server
then
returns
the
results
to
the
calling
application.
Note
that
the
diagram
above
shows
three
different
administration
service
plug-ins.
You
do
not
need
to
implement
more
than
one
plug-in,
but
multiple
plug-ins
are
supported.
Do
not
confuse
the
Tivoli
Access
Manager
authorization
administration
service
with
the
Tivoli
Access
Manager
administration
API.
The
Tivoli
Access
Manager
Access ManagerPolicy Server
AdministrationService Plug-in
A
database
AdministrationService Plug-in
B
AdministrationService Plug-in
C
database database
Access Manager Administration API
pdadminAccess
Manager WebPortal Manager
UserApplication or
GUI
Service Dispatcher
Authorization APIAdministration
Service APIInterface
AuthorizationEngine
Figure
4.
The
administration
service
plug-in
to
the
authorization
API
Chapter
8.
Administration
service
plug-ins
125
administration
API
provides
a
series
of
programmatic
interfaces
that
a
calling
application
can
use
to
send
requests
to
the
Tivoli
Access
Manager
policy
server.
In
most
cases,
applications
can
use
the
administration
API
independent
from
any
use
of
the
authorization
administration
service.
However,
application
developers
can
use
the
authorization
administration
service
plug-in
to
provide
“back-end”
authorization
functions
that
can
leverage
administration
API
functions
to
execute
application-specific
administrative
commands.
This
is
described
in
more
detail
in
“Using
an
administration
service
plug-in”
on
page
130.
Most
of
the
Tivoli
Access
Manager
administration
API
functions
provide
programmatic
equivalents
to
each
of
the
pdadmin
command
line
interfaces.
The
names
of
the
administration
API
functions
begin
with
the
ivadmin_
prefix.
The
functions
are
described
in
the
ivadminapi.h
header
file.
For
more
information
on
the
Tivoli
Access
Manager
administration
API,
see
the
IBM
Tivoli
Access
Manager
for
e-business
Administration
C
API
Developer
Reference.
126
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
Configuring
administration
service
plug-ins
You
can
configure
an
administration
service
plug-in
either
manually
or
programmatically.
Manual
configuration
is
accomplished
by
setting
values
in
a
configuration
file.
Programmatic
configuration
is
accomplished
by
passing
attributes
to
the
administration
API
at
API
initialization.
These
methods
correspond
directly
to
the
registration
steps
used
by
all
types
of
authorization
service
plug-ins,
as
described
in
“Constructing
a
service
definition”
on
page
82.
Configuration
of
an
administration
service
plug-in
is
describe
d
in
the
following
sections:
v
“Creating
a
configuration
file
entry
for
an
administration
service”
v
“Configuring
an
administration
service
programmatically”
on
page
128
Creating
a
configuration
file
entry
for
an
administration
service
Administration
service
plug-ins
are
typically
configured
in
aznapi.conf,
under
the
following
stanza:
[aznapi-admin-services]
The
administration
services
definition
syntax
is
as
follows:
<service-id>
=
<plug-in
location>
[-pobj
<protected
object
hierarchy
name>]
[&
<plug-in
parameters>]
The
protected
object
hierarchy
name
is
an
optional
parameter.
This
parameter
refers
to
either
the
name
of
a
protected
object
space
(hierarchy)
or
simply
to
a
protected
object.
The
authorization
service
takes
the
remainder
of
the
string
following
the
ampersand
&,
breaks
the
string
up
into
white
space
separated
tokens,
and
passes
the
tokens
directly
to
the
administration
service’s
initialization
interface,
azn_svc_initialize(),
in
the
argv
array
parameter.
The
number
of
strings
in
the
argv
array
is
indicated
by
the
argc
function
parameter.
Here
is
an
example
configuration
file
entry:
[aznapi-admin-services]
adminsvc1
=
/lib/libadminsvc1.so
-pobj
/Printers/printer1
&
-printer
sequoia
adminsvc2
=
/lib/libadminsvc2.so
-pobj
/Printers/printer2
&
-printer
sequoia
adminsvc3
=
/lib/libadminsvc3.so
&
-printer
sequoia
adminsvc4
=
/lib/libadminsvc4.so
As
shown
in
the
example
above,
an
authorization
API
application
can
register
more
than
one
administration
service
plug-in,
but
each
must
have
a
unique
service
ID.
Each
authorization
service
plug-in
passes
the
administration
service
definitions
to
the
Tivoli
Access
Manager
policy
server
during
the
azn_initialize()
call.
This
enables
the
Tivoli
Access
Manager
policy
server
to
know
the
mapping
of
a
protected
object
hierarchy
name
to
the
authorization
API
client
application
that
has
registered
an
administration
service
plug-in
for
it.
This
is
important
for
object
space
oriented
administration
API
interfaces
which
operate
on
the
objects
within
the
object
space.
Since
this
mapping
is
global,
care
must
be
taken
to
specify
protected
object
space
mappings
that
do
not
conflict
across
authorization
API
client
applications.
Thus,
protected
object
hierarchy
names
must
be
unique
for
each
administration
service
plug-in
within
the
scope
of
an
authorization
API
application.
Multiple
Chapter
8.
Administration
service
plug-ins
127
authorization
API
application
instances,
however,
can
register
to
service
the
same
protected
object
hierarchy
name(s).
This
can
be
used
to
provide
failover
support
for
administration
of
an
object
space
in
the
event
that
a
particular
authorization
API
application
server
fails.
Configuring
an
administration
service
programmatically
The
authorization
API
header
file
ogauthzn.h
contains
a
service
definition
attribute:
azn_string_t
azn_init_admin_svc
Complete
the
following
steps
to
use
this
service
definition
attribute
to
configure
an
administration
service
plug-in.
1.
Use
the
azn_attrlist_add_entry()
API
to
assign
to
the
init_data
attribute
list
as
many
values
to
the
azn_init_admin_svc
attribute
as
the
number
of
Administrative
service
plug-ins
needed.
These
values
are
expressed
as
strings,
and
need
to
conform
to
the
administration
service
definition
syntax
specified
in
“Initialization
and
configuration
of
service
plug-ins”
on
page
82.
Ensure
that
protected
object
hierarchies
that
are
specified
as
part
of
the
service
definition
attribute
are
unique.
See
the
discussion
just
above
in
“Creating
a
configuration
file
entry
for
an
administration
service”
on
page
127.
2.
Pass
the
init_data
attribute
to
the
azn_initialize()
call
to
ensure
that
the
specified
administration
service
plug-ins
are
loaded.
128
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
Initializing
and
shutting
down
administration
service
plug-ins
Each
administration
service
plug-in
is
a
standalone
module
that
is
dynamically
loaded
into
the
authorization
service.
The
authorization
API
service
plug-in
model
provides
standard
interfaces
to
the
service
dispatcher
to
initialize
and
shut
down
all
types
of
service
plug-ins.
Developers
of
administration
service
plug-ins
should
provide
the
standard
functions.
See
the
following
sections:
v
“Initialization
and
configuration
of
service
plug-ins”
on
page
82
v
“Shut
down”
on
page
92
For
more
information,
see
the
reference
pages
for
“azn_svc_initialize()”
on
page
244
and
“azn_svc_shutdown()”
on
page
249.
Chapter
8.
Administration
service
plug-ins
129
Using
an
administration
service
plug-in
The
administration
service
supports
the
following
authorization
API
functions:
Function
Description
azn_admin_get_object()
Retrieves
a
potential
protected
object.
Tests
for
the
existence
of
a
protected
object.
azn_admin_get_objectlist()
Accesses
the
administration
service
to
provide
a
list
of
all
potential
protected
objects
that
are
children
of
the
specified
parent
object.
azn_admin_perform_task()
Instructs
the
service
to
perform
an
administration
task.
The
service
returns
the
results
of
the
task.
azn_admin_get_tasklist()
Returns
a
list
of
all
the
supported
administration
tasks.
Each
of
the
functions
above
maps
to
an
equivalent
administration
API
function
and
an
equivalent
pdadmin
command
line
interface.
The
mappings
are
shown
in
the
table
below.
Authorization
API
administration
Function
Administration
API
function
pdadmin
command
line
interface
azn_admin_get_object()
ivadmin_protobj_get2()
pdadmin
object
show
object_name
azn_admin_get_objectlist()
ivadmin_protobj_list3()
pdadmin
object
list
object_name
pdadmin
object
listandshow
object_name
azn_admin_perform_task()
ivadmin_server_performtask()
pdadmin
server
task
server_name
task
azn_admin_get_tasklist()
ivadmin_server_gettasklist()
pdadmin
server
listtasks
server_name
The
Tivoli
Access
Manager
policy
server
uses
these
mappings
to
redirect
the
administration
API
calls
(ivadmin_*)
and
the
pdadmin
command
lines
that
correspond
to
the
azn_admin_get_object()
and
azn_admin_get_objectlist()
APIs
to
the
appropriate
administration
service
plug-in.
When
processing
the
administration
APIs
(ivadmin_*)
and
the
pdadmin
command
lines
that
correspond
to
the
azn_admin_perform_task()
and
azn_admin_get_tasklist()
APIs,
the
Tivoli
Access
Manager
policy
server
just
forwards
them
as
a
single
unparsed
string
to
the
corresponding
authorization
API
client
application.
An
authorization
API
administration
service
should
provide
a
server
task
to
handle
help
requests
for
every
command
it
supports.
A
valid
response
should
be
produced
for
any
pdadmin
server
task
server-name
help
command-name
command
for
a
supported
command-name.
However,
in
response
to
a
pdadmin
server
task
server-name
help
command,
a
major
error
code
of
AZN_S_SVC_ADMIN_INVALID_TASK
should
be
returned,
as
the
service
does
not
know
about
other
administration
services
that
could
be
registered
for
the
same
server.
Not
all
of
the
authorization
API
administration
service
interfaces
are
relevant
to
every
Authorization
administration
service
plug-in.
Therefore,
a
result
of
not
supported
is
returned
for
each
administration
service
interface
not
implemented
by
the
authorization
service
plug-in.
The
administration
service
plug-ins
make
use
of
the
following
attributes
in
the
outdata
attribute
list
that
the
authorization
API
administration
service
interfaces
130
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
return.
Attribute
Description
azn_admin_svc_pobj
Administration
service
protected
object
attribute,
of
type
azn_string_t.
azn_admin_svc_task
Administration
service
task
attribute,
of
type
azn_string_t.
azn_admin_svc_results
Administration
service
results
attribute,
of
type
azn_string_t.
For
more
information
on
the
authorization
API
administration
functions,
see
the
following
reference
pages:
v
“azn_admin_get_object()”
on
page
224
v
“azn_admin_get_objectlist()”
on
page
226
v
“azn_admin_get_tasklist()”
on
page
228
v
“azn_admin_perform_task()”
on
page
231
Chapter
8.
Administration
service
plug-ins
131
Error
codes
This
section
contains
the
following
topics:
v
“Errors
when
registering
the
administration
service
plug-in”
v
“Errors
when
registering
administration
definitions”
on
page
132
v
“Major
errors
from
administration
service
functions”
on
page
133
v
“Minor
errors
from
administration
service
functions”
on
page
133
v
“Error
codes
specific
to
an
authorization
services
plug-in”
on
page
133
Errors
when
registering
the
administration
service
plug-in
The
authorization
API
initialization
function
azn_initialize()
fails
when
the
Authorization
administration
service
definitions
made
by
a
single
authorization
API
application
result
in
following
error
conditions:
Error
Code
Description
AZN_S_SERVICE_IS_REGISTERED
Attempted
to
register
more
than
one
service
definition
with
the
same
service-id
AZN_S_SVC_ADMIN_POBJ_ALREADY_REGISTERED
Attempted
to
register
more
than
one
service
definition
with
the
same
protected
object
hierarchy
name
AZN_S_SVC_ADMIN_POBJ_FUNC_NOT_FOUND
The
-pobj
option
is
specified
for
an
administration
service
definition,
but
the
specified
plug-in
does
not
contain
the
azn_admin_get_objectlist()
and
the
azn_admin_get_object()
functions.
When
the
-pobj
option
is
not
specified,
the
plug-in
is
not
required
to
support
either
of
these
functions.
AZN_S_SVC_ADMIN_TASK_FUNC_NOT_FOUND
The
administration
service
plug-in
supports
only
one
of
the
task
related
functions
azn_admin_get_tasklist()
and
azn_admin_perform_task().
Each
Administration
service
plug-in
must
support
either
both
the
task-related
functions
or
support
none
of
them.
AZN_S_INVALID_LISTENING_PORT
When
the
administration
service
plug-in
registration
succeeds,
but
the
ssl-listening-port
has
not
been
specified
as
part
of
the
authorization
API
initialization,
azn_initialize()
returns
this
error.
Errors
when
registering
administration
definitions
The
authorization
API
registers
the
administration
service
definitions
with
the
Tivoli
Access
Manager
policy
server
during
the
azn_initialize()
call.
The
policy
server
stores
the
registered
administration
service
definitions
in
persistent
store
and
overwrites
an
existing
registration
when
it
receives
a
new
registration
from
the
same
authorization
API
application.
When
the
authorization
API
cannot
contact
the
Tivoli
Access
Manager
policy
server
during
azn_initialize(),
it
skips
registration
of
the
specified
administration
132
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
service
definitions,
logs
a
message
describing
that
failure,
loads
the
associated
plug-ins,
and
completes
the
azn_initialize()
call.
The
failure
of
the
authorization
API
to
contact
the
Tivoli
Access
Manager
policy
server
can
occur
within
one
of
the
following
contexts:
v
The
administration
services
have
already
been
registered
with
the
policy
server.
In
this
case,
when
the
policy
server
becomes
operational
again,
any
administration
API
functions
or
pdadmin
command
lines
that
are
handled
by
the
administration
service
definitions
will
automatically
succeed
again.
v
The
administration
service
definitions
have
not
been
registered
with
the
policy
server,
because
this
was
the
first
attempt
to
register
them.
In
this
case,
the
authorization
API
must
be
re-initialized
so
that
it
can
register
the
administration
service
definitions.
Once
contact
with
the
policy
server
succeeds,
the
administration
API
functions
and
pdadmin
commands
will
succeed.
v
The
authorization
API
has
already
registered
the
administration
services
with
the
policy
server.
However,
the
service
definitions
being
registered
now
differ
from
definitions
that
are
already
registered.
In
this
case,
the
new
service
definitions
have
not
successfully
registered,
and
the
administration
API
functions
and
pdadmin
commands
will
fail
once
the
policy
server
starts.
The
authorization
API
needs
to
be
restarted.
This
causes
the
authorization
API
to
be
re-initialized,
which
results
in
the
policy
server
registering
the
new
service
definitions
and
deleting
the
old
ones.
Major
errors
from
administration
service
functions
The
authorization
service
APIs
are
not
invoked
directly
by
the
end
user.
They
are
invoked
by
policy
server
in
response
to
certain
administration
API
functions
or
pdadmin
commands.
The
administration
service
plug-ins
can
return
the
major
error
codes
specified
for
the
authorization
API,
as
well
as
those
specified
generically
for
all
authorization
service
plug-ins.
The
authorization
service
APIs
can
also
return
the
AZN_S_SVC_ADMIN_*
major
status
codes
that
are
generic
for
all
Authorization
administration
service
plug-ins.
The
authorization
API
forwards
these
return
codes
to
the
policy
server,
which
returns
them
to
the
administration
API
or
pdadmin
command.
The
final
return
code
sent
to
the
end-user
conforms
to
the
error
codes
returned
by
the
administration
API
functions
or
the
pdadmin
commands.
Minor
errors
from
administration
service
functions
The
administration
service
functions
conform
to
the
authorization
services
plug-in
model
for
using
azn_util_errorcode()
to
return
plug-in
specific
error
return
codes
within
the
16-bit
minor
error
code
portion
of
azn_status_t.
The
returned
minor
error
code
must
be
a
valid
Tivoli
Access
Manager
minor
error
code,
in
order
for
the
Tivoli
Access
Manager
policy
server
to
generate
a
message
for
it.
If
the
returned
minor
code
is
invalid,
an
error
message
of
unknown
error
is
returned
to
the
pdadmin
command
or
administration
API
function
that
issued
the
request.
For
more
information
on
authorization
service
minor
error
codes,
see
“Minor
error
codes”
on
page
90.
Error
codes
specific
to
an
authorization
services
plug-in
Administration
service
plug-ins
can
also
return
implementation-specific
return
codes
in
the
outdata
output
parameter
for
the
azn_admin_*
calls.
For
example,
the
Chapter
8.
Administration
service
plug-ins
133
functions
can
return
status
codes
of
type
unsigned
long
by
using
the
azn_attrlist_add_entry_ulong()API
to
add
unsigned
long
values
to
a
pre-defined
attribute
in
the
outdata
attribute
list.
The
administration
service
functions
can
return
results
strings
(which
are
displayed
at
the
pdadmin
CLI)
as
values
for
the
azn_admin_svc_results
attribute
of
the
outdata
attribute
list.
These
results
strings
are
forwarded
by
the
policy
server
to
the
pdadmin
command
line
interface
or
to
the
application
using
the
administration
API
functions.
The
administration
service
functions
can
also
return
other
attributes
of
their
choice.
These
attributes
are
added
to
the
outdata
attribute
list
and
directly
forwarded
to
the
caller
of
the
administration
API.
134
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
Deploying
an
administration
service
plug-in
When
you
have
developed
your
administration
service
plug-in,
and
are
ready
to
deploy
it,
complete
the
following
steps:
v
Run
svrsslcfg
for
the
authorization
API
application.
Specify
the
appropriate
input
parameters.
For
more
information
on
the
svrsslcfg
command
line
utility,
see
the
IBM
Tivoli
Access
Manager
for
e-business
Command
Reference.
v
When
configuring
the
authorization
API
calling
application,
use
pdadmin
or
the
administration
API
to
create
the
application-specific
portion
of
the
protected
object
namespace.
v
Create
the
appropriate
protected
objects
under
the
application-specific
portion
of
the
protected
object
namespace.
v
Register
the
administration
service
plug-ins
for
the
protected
objects
created
in
the
previous
step.
See
“Configuring
administration
service
plug-ins”
on
page
127.
Chapter
8.
Administration
service
plug-ins
135
136
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
Chapter
9.
External
authorization
service
plug-ins
This
sections
consists
of
the
following
topics:
v
“Introducing
the
external
authorization
service”
on
page
138
v
“Understanding
the
external
authorization
service”
on
page
139
v
“Configuring
an
external
authorization
service
plug-in”
on
page
143
v
“Initializing
and
shutting
down
external
authorization
service
plug-Ins”
on
page
145
v
“Obtaining
an
authorization
decision”
on
page
146
v
“Error
codes”
on
page
147
©
Copyright
IBM
Corp.
2000,2003
137
Introducing
the
external
authorization
service
The
external
authorization
service
is
a
modular
authorization
service
plug-in
that
allows
system
designers
to
supplement
IBM
Tivoli
Access
Manager
(Tivoli
Access
Manager)
authorization
with
their
own
authorization
models.
Developers
can
build
a
shared
library
object
that
implements
an
external
authorization
service.
You
can
configure
the
authorization
API
client
to
use
this
plug-in
by
ensuring
that
the
appropriate
interfaces
are
exposed
within
the
library.
The
external
authorization
service
is
implemented
as
an
authorization
API
client
so
that
the
plug-in
can
manipulate
authorization
API
data
structures
such
as
the
credentials
and
attribute
lists.
External
authorization
service
plug-ins
are
called
only
by
local-mode
authorization
API
client.
Remote-mode
authorization
API
clients
do
not
have
a
local
authorization
server
and
thus
cannot
call
out
to
an
external
authorization
service.
The
configuration
of
external
authorization
service
plug-ins
is
applicable
only
to
local-mode
authorization
API
clients.
The
external
authorization
service
plug-in
model
includes
a
Distributed
Computing
Environment
(DCE)
Remote
Procedure
Call
(RPC)
based
external
authorization
service,
for
backwards
compatibility
with
previous
versions
of
the
Tivoli
SecureWay
Policy
Director
product.
This
plug-in
transforms
the
parameters
of
the
new
plug-in
interface
into
those
used
by
the
RPC
interface
in
Policy
Director
Version
3.7
and
earlier.
Clients
that
want
to
consult
an
RPC-based
external
authorization
service
need
to
deploy
a
DCE
client
on
the
client
machine.
Configuration
of
external
authorization
service
plug-ins
is
performed
in
the
same
way
as
other
authorization
service
plug-ins.
Initialization
settings
are
specified
either
through
a
configuration
file
or
programmatically
through
the
initialization
attribute
list
of
the
azn_initialize()
function.
For
legacy
DCE-RPC
external
authorization
servers,
the
configuration
that
was
previously
stored
in
the
authorization
database
is
now
configured
for
each
local
mode
authorization
API
client.
This
configuration
information
is
passed
to
the
plug-in
as
parameters
that
are
specific
to
the
individual
plug-in.
Initialization
settings
consist
of
a
service
definition
that
specifies
a
policy
trigger
for
which
the
external
authorization
service
is
invoked,
a
weighting
that
is
assigned
in
the
access
decision
process
to
the
particular
external
authorization
service,
and
the
location
of
the
dynamically-loadable
library
module
that
performs
the
authorization
work
specific
to
the
external
authorization
service.
The
concepts
of
policy
triggers
and
weightings
are
described
later
in
this
section.
Each
external
authorization
service
plug-in
must
expose
three
interfaces
to
the
authorization
service:
v
azn_svc_intialize()
v
azn_svc_shutdown()
v
azn_svc_decision_access_allowed_ext()
The
external
authorization
service
plug-ins
follow
the
service
plug-in
model
for
returning
error
messages
by
combining
major
error
codes
and
application-specific
minor
error
codes
to
produce
valid
error
codes
that
can
be
returned
to
the
calling
applications.
138
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
Understanding
the
external
authorization
service
This
section
consists
of
the
following
topics:
v
“External
authorization
service
architecture”
v
“Policy
triggers”
on
page
140
v
“Weightings”
on
page
142
External
authorization
service
architecture
The
external
authorization
service
architecture
is
derived
directly
from
the
general
authorization
service
plug-in
architecture.
The
calling
application
is
represented
by
the
authorization
API
application
object
in
the
above
diagram.
The
calling
application
sends
access
decision
information
(ADI)
to
the
authorization
engine
to
request
an
authorization
decision.
The
authorization
LDAPDatabase
OracleDatabase
Authorization API Application
OtherDatabase
EAS Plug-in A EAS Plug-in B EAS Plug-in C
Authorization API
Authorization Engine
Authorization Decision Combinator
Service Dispatcher
Figure
5.
The
external
authorization
service
architecture
Chapter
9.
External
authorization
service
plug-ins
139
engine
first
makes
an
access
decision
based
on
the
ADI
that
was
passed-in
and
on
the
credentials
of
the
requesting
user.
The
decision
is
assigned
an
integer
value
called
a
weighting.
Next,
the
Access
Decision
Combinator
is
called.
It
returns
a
weighted
access
decision
result,
based
on
calls
to
all
applicable
external
authorization
service
plug-ins.
The
Combinator
is
responsible
for
identifying
and
invoking
each
external
authorization
service
that
is
applicable
to
the
authorization
decision
request.
The
Combinator
uses
policy
trigger
information
to
call
the
service
dispatcher
to
identify
a
list
of
external
authorization
service
plug-ins
which
must
be
called.
The
Combinator
then
calls
each
external
authorization
service
in
turn.
The
permission
value
returned
from
each
call
is
multiplied
by
the
weighting
for
the
specific
EAS.
The
weighted
result
is
then
passed
to
the
Tivoli
Access
Manager
authorization
engine.
The
service
dispatcher
for
the
external
authorization
service
plug-ins
manages
the
location,
configuration,
and
loading
of
the
available
EAS
plug-ins.
The
service
dispatcher
handles
EAS
plug-ins
in
the
same
manner
as
other
types
of
plug-ins,
such
as
entitlements
services,
administration
services,
and
credentials
modification
services.
Policy
triggers
Policy
triggers
refer
to
the
set
of
policy
circumstances
that
trigger
a
particular
EAS
to
be
invoked
for
any
particular
access
decision.
In
prior
versions
of
Tivoli
Access
Manager,
an
EAS
could
only
be
triggered
if
a
predetermined
action
bit
was
present
in
the
ACL
on
the
object.
The
effect
of
this
trigger
was
much
like
protected
object
policy
in
that
the
EAS
was
always
invoked
on
that
object
if
the
predetermined
bit
was
present
in
the
ACL.
The
action
bits
used
for
EAS
triggers
could
not
be
used
for
other
purposes
and
vice-versa.
This
behavior
changed
in
Version
3.8
to
move
the
protected
object
oriented
nature
of
the
previous
ACL
trigger
mechanism
into
the
POP
policy.
This
is
done
by
using
a
trigger
attribute
that
is
attached
to
the
POP.
The
POP
object
is
a
more
suitable
place
to
store
protected
object
policy.
The
nature
of
ACL
triggers
has
changed
to
become
operation
oriented.
From
Version
3.8
onward,
the
operation
set
triggers
the
EAS
when
the
user
requests
the
exact
set
of
operations
in
the
trigger.
This
reorients
the
ACL
trigger
mechanism
to
allow
policy
administrators
to
define
policy
based
on
the
operation
that
the
user
actually
wants
to
perform
on
the
target
object.
These
triggers
are
now
called
operation-based
triggers.
Unlike
versions
prior
to
Version
3.8,
the
set
of
operations
used
to
trigger
an
EAS
can
include
multiple
operations,
or
action
bits,
and
the
bits
do
not
have
to
be
exclusive
of
bits
that
are
already
being
used
for
another
purpose
in
the
access
decision
environment.
For
example,
the
x
bit
is
used
by
many
resource
manager
applications
to
represent
the
execute
operation.
If
desired,
the
policy
administrator
may
set
a
trigger
for
this
operation
using
the
x
action
bit,
and
invoke
an
EAS
anytime
a
request
to
execute
a
target
object
is
made
upon
any
object
in
the
protected
object
space.
The
trigger
can
be
made
even
more
discriminating
by
adding
a
second
action
bit
to
the
trigger.
For
example,
adding
the
l
action
bit,
where
l
indicates
that
the
executed
program
can
return
data
(lx),
would
only
invoke
the
EAS
if
the
user
requested
that
the
target
object
execute,
and
then
return
the
data
after
doing
so.
In
this
case,
simply
requesting
that
the
target
object
be
executed
will
not
trigger
the
EAS
to
be
called.
The
operations
trigger
can
also
include
an
action
group
specification
if
action
groups
are
used
in
the
policy
implementation.
For
instance,
an
action
group
140
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
defining
the
operations
that
can
be
performed
on
a
printer
object
may
be
defined
in
an
action
group
called
Printer.
To
trigger
an
EAS
based
on
a
printer
operation,
you
can
specify
the
action
group
in
the
EAS
trigger
definition.
For
example,
[Printer]s
to
specify
an
s
(system
administrator)
operation
on
the
printer
object.
POP-based
policy
triggers
have
taken
over
the
role
of
the
ACL
bit
trigger
(also
known
as
k
bit
functionality)
implemented
in
versions
of
Tivoli
Access
Manager
prior
to
3.8.
POP-based
policy
triggers
allow
an
EAS
to
be
called
for
one
or
more
specific
protected
objects
within
the
protected
object
space.
The
POP
trigger
is
defined
as
an
extended
attribute
within
the
POP.
Its
value
is
set
to
the
specific
policy
trigger
string
needed
to
trigger
the
target
EAS.
The
policy
trigger
is
simply
the
service
ID
of
the
target
EAS.
When
the
extended
attribute
value
is
not
NULL,
the
POP
is
evaluated
as
part
of
the
authorization
process
in
the
Tivoli
Access
Manager
authorization
engine.
The
attribute
name
to
be
used
must
be
specifically
for
the
purpose
of
EAS
registration.
The
attribute
name
can
have
more
than
one
value.
This
means
that
multiple
policy
triggers
can
be
configured
for
the
one
POP.
Each
policy
trigger
is
called
in
turn.
The
EAS
are
called
in
the
order
in
which
they
were
first
added
to
the
attribute.
Configuring
a
POP
policy
trigger
POP
objects
reserve
the
extended
attribute
name
eas-trigger
for
the
purpose
of
registering
EAS
triggers.
New
POP
objects
have
no
entry
for
this
name
by
default.
User
must
explicitly
register
an
policy
trigger
with
the
POP
through
pdadmin
or
the
administration
API.
To
be
valid,
the
extended
attribute
must
contains
one
or
more
values
that
must
match
the
policy
trigger
field
in
the
service
definition
of
at
least
one
of
the
EAS
modules
that
are
loaded
when
the
authorization
API
is
initialized.
The
following
examples
show
the
pdadmin
commands
for
adding
and
removing
policy
triggers
from
POP
objects.
pdadmin>
pop
show
<pop-name>
attribute
eas-trigger
pdadmin>
pop
modify
<pop-name>
set
attribute
eas-trigger
trigger-string
pdadmin>
pop
modify
<pop-name>
delete
attribute
eas-trigger
pdadmin>
pop
modify
<pop-name>
delete
attribute
eas-trigger
trigger-string
By
passing
the
trigger
string
as
a
parameter
to
the
set
command
you
can
add
a
specific
trigger
from
the
list
of
configured
triggers.
Likewise,
by
passing
the
trigger
string
as
a
parameter
to
the
delete
command
you
can
remove
a
specific
trigger
from
the
list
of
configured
triggers.
You
can
also
use
the
Tivoli
Access
Manager
administration
API
to
add
and
delete
policy
triggers
within
the
POP
extended
attributes.
In
each
of
the
cases
shown
in
the
table
below,
the
caller
passes
the
string
eas-trigger
as
the
attr_key
input
string.
Administration
API
Function
Description
ivadmin_pop_attrget()
Get
the
EAS
policy
triggers
for
a
POP
ivadmin_pop_attrput()
Set
an
EAS
policy
trigger
for
a
POP
ivadmin_pop_attrdelkey()
Delete
all
the
EAS
policy
triggers
for
a
POP
ivadmin_pop_attrdelval()
Delete
a
specific
EAS
policy
trigger
for
a
POP
Chapter
9.
External
authorization
service
plug-ins
141
Weightings
The
Tivoli
Access
Manager
authorization
service
provides
the
core
authorization
engine
responsible
for
making
authorization
decisions.
You
can
add
one
or
more
external
authorization
service
plug-ins
to
provide
additional
authorization
decision-making
decisions.
When
you
have
more
than
one
authorization
decision-making
process,
you
must
specify
the
relative
rank
or
priority
that
each
decision
carries.
You
can
use
the
concept
of
a
weighting
to
specify
this
rank
or
priority.
For
each
external
authorization
service,
you
specify
the
appropriate
weighting
in
the
service
definition
that
is
used
to
configure
the
external
authorization
service.
The
weight
parameter
is
an
unsigned
size_t
value
and
is
optional.
The
default
Tivoli
Access
Manager
Authorization
engine
has
a
weight
of
100.
The
weight
of
each
EAS
is
relative
to
other
external
authorization
services,
and
to
the
core
authorization
engine.
When
the
weighting
for
an
external
authorization
service
is
not
specified
a
default
value
of
101
is
assigned.
When
the
Tivoli
Access
Manager
authorization
engine
or
an
EAS
returns
an
access
permitted
decision,
the
value
of
the
overall
access
decision
is
increased
by
the
integer
amount
of
the
applicable
weighting.
When
the
authorization
engine
or
an
EAS
returns
an
access
denied
decision,
the
value
of
the
overall
access
decision
is
decreased
by
the
integer
amount
of
the
applicable
weighting.
When
the
value
of
the
overall
decision
is
greater
than
zero
(0),
the
access
request
is
approved.
When
the
value
of
the
overall
decision
is
less
than
zero
(0),
the
access
request
is
denied.
When
the
value
equals
zero,
the
access
decision
is
made
based
on
the
value
returned
by
the
Tivoli
Access
Manager
authorization
engine.
Thus,
the
authorization
engine
takes
precedence
over
the
external
authorization
services
when
the
sum
total
of
the
supplemental
external
authorization
services’
decisions
is
not
sufficient
to
override
the
decisions
made
by
the
core
engine.
For
example,
the
core
engine
has
a
weight
of
100,
and
when
it
returns
an
access
permitted
decision,
the
value
of
the
result
is
+100.
When
an
external
authorization
service
with
a
weighting
of
60
is
then
called,
and
returns
an
access
denied
decision,
then
this
final
result
value
is
modified
to
+40.
If
another
EAS
with
weighting
of
60
is
called,
and
it
also
returns
an
access
denied
decision,
then
the
final
result
is
-20.
In
this
case,
access
is
denied
because
the
overall
result
is
less
than
zero.
Each
external
authorization
service
has
the
option
of
not
participating
in
a
specific
access
decision.
The
EAS
can
return
a
permission
value
of
AZN_C_INDIFFERENT.
When
this
occurs,
the
Tivoli
Access
Manager
authorization
service
does
not
factor
the
weighting
for
the
EAS
into
the
final
result.
142
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
Configuring
an
external
authorization
service
plug-in
You
can
configure
an
external
authorization
service
plug-in
either
manually
or
programmatically.
Manual
configuration
is
accomplished
by
setting
values
in
a
configuration
file.
Programmatic
configuration
is
accomplished
by
passing
attributes
to
the
administration
API
at
API
initialization.
These
methods
correspond
directly
to
the
registration
steps
used
by
all
types
of
authorization
service
plug-ins,
as
described
in
“Constructing
a
service
definition”
on
page
82.
Configuration
of
an
external
authorization
service
plug-in
is
described
in
the
following
sections:
v
“Using
a
configuration
file
entry”
v
“Configuring
an
external
authorization
service
programmatically”
on
page
144
Using
a
configuration
file
entry
External
authorization
service
plug-ins
are
typically
configured
in
aznapi.conf,
under
the
following
stanza:
[aznapi-external-authzn-services]
The
external
authorization
services
definition
syntax
is
as
follows:
<policy-trigger>
=
<plug-in
location>
[-weight
<N>]
[&
<plug-in
parameters>]
For
example:
Printer:rxT
=
eas_plugin
-weight
60
&
-server
barney
Or
webseal_pop_trigger
=
eas_plugin_2
-weight
70
&
-hostname
fred
The
policy-trigger
can
be
any
string
that
is
recognized
as
a
valid
key
name.
Stanza
key
names
cannot
contain
white
space
or
the
open
bracket
“[“
and
close
bracket
“]”
characters.
The
bracket
characters
are
used
to
define
new
stanza
names.
The
policy-trigger
is
case
sensitive
for
action
set
definitions
because
the
actions
themselves
are
case
sensitive.
However,
the
policy-trigger
is
case
insensitive
if
the
trigger
is
a
POP
attribute.
The
first
example
above
shows
an
operation-based
trigger
with
a
user-defined
action
group
of
Printer
and
the
actions
rxT
within
that
group.
To
specify
the
primary
action
group
you
would
specify
only
:rxT.
The
primary
action
group
can
be
represented
with
an
empty
action
group
name
or
the
string
primary
can
be
used
explicitly.
All
lowercase
letters
are
required
if
primary
is
used
explicitly.
Any
policy-trigger
that
does
not
contain
a
colon
“:”
character
is
considered
to
be
a
protected
object
policy
(POP)
attribute
name.
The
second
example
above
is
for
a
POP
attribute
trigger
called
webseal_pop_trigger.
When
a
POP
that
contains
a
reference
to
this
string
is
passed
to
the
Combinator,
the
appropriate
external
authorization
service
is
called
to
take
part
in
the
access
decision.
Note
that
the
POP
configuration
must
have
been
completed
previously
by
the
secure
domain
administrator,
using
the
pdadmin
command.
The
plug-in
location
is
the
path
name
to
the
shared
library
or
DLL
module
that
contains
the
implementation
of
the
plug-in
that
matches
the
policy
trigger.
The
path
name
can
be
in
a
truncated
form
if
the
external
authorization
service
is
to
be
Chapter
9.
External
authorization
service
plug-ins
143
loaded
by
clients
on
multiple
platforms.
In
this
case,
the
service
dispatcher
searches
for
the
plug-in
using
platform-specific
prefixes
and
suffixes
to
match
DLL
names.
The
weight
parameter
is
an
unsigned
size_t
value
and
is
optional.
The
value
signifies
the
weight
that
any
decision
returned
by
this
external
authorization
service
should
be
given
in
the
entire
decision
process.
Optionally,
the
external
authorization
service
can
be
passed
additional
initialization
information
in
the
form
of
arguments.
The
arguments
must
be
preceded
by
the
ampersand
“&”.
The
authorization
service
takes
the
remainder
of
the
string
following
the
ampersand
&,
breaks
the
string
up
into
white
space
separated
tokens,
and
passes
the
tokens
directly
to
the
administration
service’s
initialization
interface,
azn_svc_initialize(),
in
the
argv
array
parameter.
The
number
of
strings
in
the
argv
array
is
indicated
by
the
argc
function
parameter.
The
optional
arguments
in
the
first
example
above
are
&
-server
-barney
Configuring
an
external
authorization
service
programmatically
The
authorization
API
header
file
ogauthzn.h
contains
a
service
definition
attribute:
azn_string_t
azn_init_extern_authzn_svc
The
value
of
the
attribute
is
a
string
of
the
format:
policy-trigger
=
plug-in_location
[-weight
N]
[&
plug-in_parameters]
For
example:
POP_EAS_A
=
my_eas_pop_1
-weight
50
&
-server
fred
Or
:rmx
=
my_acl_ops_pop_1
-weight
60
&
-server
barney
Complete
the
following
steps
to
use
this
service
definition
attribute
to
configure
an
external
authorization
service
plug-in.
1.
Use
the
azn_attrlist_add_entry()
API
to
assign
to
the
init_data
attribute
list
as
many
values
to
the
azn_init_extern_authzn_svc
attribute
as
the
number
of
Administrative
service
plug-ins
needed.
These
values
are
expressed
as
strings,
and
need
to
conform
to
the
external
authorization
service
definition
syntax
specified
in
“Using
a
configuration
file
entry”
on
page
143.
2.
Pass
the
init_data
attribute
to
the
azn_initialize()
call
to
ensure
that
the
specified
Administration
service
plug-ins
are
loaded.
144
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
Initializing
and
shutting
down
external
authorization
service
plug-Ins
Each
external
authorization
service
plug-in
is
a
standalone
module
that
is
dynamically
loaded
into
the
authorization
service.
The
authorization
API
service
plug-in
model
provides
standard
interfaces
to
the
service
dispatcher
to
initialize
and
shut
down
all
types
of
service
plug-ins.
Developers
of
external
authorization
service
plug-ins
should
provide
the
standard
functions.
See
the
following
sections:
v
“Initialization
and
configuration
of
service
plug-ins”
on
page
82
v
“Shut
down”
on
page
92
When
the
authorization
API
is
initialized
the
configuration
file
is
parsed
and
each
external
authorization
service
plug-in
listed
in
the
[aznapi-external-authzn-service]
stanza
is
loaded
and
resolved
by
the
service
plug-in
dispatcher.
The
authorization
API
also
recognizes
the
external
authorization
service
plug-ins
specified
by
the
azn_init_extern_authzn_svc
attribute
in
the
init_data
attribute
list
that
is
passed
as
input
to
azn_initialize().
Each
of
those
plug-ins
is
also
loaded
and
resolved
by
the
service
plug-in
dispatcher.
If
a
plug-in
is
configured
incorrectly,
or
the
plug-in
module
can’t
be
found,
the
azn_initialize()
function
returns
an
appropriate
error.
When
each
external
authorization
service
plug-in
has
been
successfully
loaded,
the
authorization
service
initialization
interface
is
called
with
the
parameters
specified
after
the
ampersand
“&”
character
in
the
service
definition.
For
more
information
on
initialization
and
shutdown
of
service
plug-ins,
see
the
reference
pages
for
“azn_svc_initialize()”
on
page
244
and
“azn_svc_shutdown()”
on
page
249.
Chapter
9.
External
authorization
service
plug-ins
145
Obtaining
an
authorization
decision
The
service
dispatcher
calls
this
interface
to
request
an
access
decision
from
the
EAS
plug-in.
This
interface
is
called
by
the
azn_decision_access_allowed()
and
azn_decision_access_allowed_ext()
API
interfaces
and
is
expected
to
return
both
permission
codes
and
error
codes
consistent
with
that
required
by
authorization
API
interface
specification
for
the
those
interfaces.
For
example:
azn_status_t
azn_svc_decision_access_allowed_ext(
const
azn_creds_h_t
creds,
/*
input
*/
const
azn_string_t
protected_resource,
/*
input
*/
const
azn_string_t
operation,
/*
input
*/
const
azn_attrlist_h_t
app_context,
/*
input
*/
int
*permission,
/*
output
*/
azn_attrlist_h_t
*permission_info
/*
output
*/
);
The
azn_svc_decision_access_allowed_ext()
function
returns
the
same
permission
code
values
as
its
counterpart
calls
do
in
the
authorization
API.
The
EAS
can
return
one
of
three
possible
permission
values
to
the
authorization
engine:
AZN_C_PERMITTED
0
AZN_C_NOT_PERMITTED
1
AZN_C_INDIFFERENT
-1
The
EAS
returns
AZN_C_INDIFFERENT
when
it
does
not
care
about
the
access
decision
in
question.
For
example,
this
can
occur
when
a
minimum
requirement
for
the
input
conditions
was
not
met.
Alternatively,
the
EAS
may
decide
it
does
not
have
jurisdiction
for
the
decision.
In
these
cases,
the
Combinator
ignores
the
return
value
from
this
EAS
when
calculating
the
result
of
the
access
decision.
The
permission_info
parameter
should
contain
any
decision-related
information
attributes
that
the
EAS
wants
to
return
to
the
calling
application.
If
an
initialized
attribute
list
handle
is
passed
back
to
the
service
dispatcher,
then
the
attributes
are
added
to
the
permission_info
list
that
is
passed
back
to
the
caller.
Ensure
that
your
implementation
of
azn_svc_decision_access_allowed_ext()
is
thread-safe.
Input
parameters
must
not
be
modified.
You
can
assume
that
the
calling
application
will
free
the
output
parameters
that
are
returned.
This
interface
returns
AZN_S_COMPLETE
when
successful,
or
an
error
when
it
fails.
146
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
Error
codes
The
authorization
service
plug-in
interface,
including
the
EAS
plug-in
interface,
defines
a
number
of
major
error
codes
and
a
minor
error
code
mask
that
an
EAS
must
use
to
construct
error
codes
to
return
to
the
calling
application.
The
error
codes
returned
by
the
plug-in
interfaces
are
not
parsed
or
modified
by
the
authorization
API
runtime
functions.
These
codes
are
passed
back
unmodified
to
the
calling
application.
Thus,
the
error
code
that
is
returned
must
be
able
to
be
parsed
into
its
major
and
minor
error
code
components
by
the
calling
application.
The
calling
application
uses
azn_error_major()
and
azn_error_minor()
to
complete
the
parsing.
To
properly
construct
the
error
codes,
the
authorization
API
provides
a
utility
function
that
enables
developers
of
third-party
extensions,
(including
service
plugs-in
such
as
the
EAS)
to
the
authorization
API
to
construct
valid
error
codes
to
return
to
application
programmers.
This
function
is
azn_util_errcode().
This
function
takes
a
major
and
minor
integer
error
code
value
and
converts
them
into
an
azn_status_t
value.
The
minor
error
code
returned
must
be
defined
in
accordance
with
the
rules
below.
Major
error
codes
External
authorization
service
plug-ins
should
return
all
applicable
major
error
codes
that
are
defined
for
returning
status
from
the
azn_decision_access_allowed()
and
azn_decision_access_allowed_ext()
interfaces.
Note
that
not
all
error
codes
will
apply
to
all
plug-in
services.
The
following
table
shows
major
error
codes:
Error
Code
Description
AZN_S_INVALID_CREDS_HDL
The
credentials
handle
supplied
is
invalid
AZN_S_INVALID_PROTECTED_RESOURCE
The
protected_resource
string
supplied
is
invalid.
AZN_S_INVALID_OPERATION
The
operation
string
supplied
is
invalid.
AZN_S_INVALID_EAS_ACL_TRIGGER
The
EAS
ACL
policy
trigger
specified
is
invalid.
AZN_S_INVALID_EAS_POP_TRIGGER
The
EAS
POP
policy
trigger
specified
is
invalid.
AZN_S_INVALID_EAS_WEIGHTING
The
EAS
weighting
specified
is
invalid.
An
absolute
size_t
value
is
required.
AZN_S_UNKNOWN_EAS_SVC_PARAMETER
A
parameter
other
than
-weight
was
specified
in
an
external
authorization
service
definition.
AZN_S_INVALID_APP_CONTEXT_HDL
The
attribute
list
handle
for
the
application
context
is
invalid.
AZN_S_INVALID_PERMISSION_REF
The
integer
pointer
for
the
permission
parameter
is
invalid.
AZN_S_FAILURE
Chapter
9.
External
authorization
service
plug-ins
147
Error
Code
Description
An
implementation
specific
error
or
failure
has
occurred.
An
implementation
specific
minor
error
code
should
be
returned
in
the
status
code
for
the
caller
to
extract
with
azn_error_minor().
The
following
additional
major
error
codes
are
defined
for
authorization
API
service
modules
in
ogauthzn.h.
Some
of
the
following
error
codes
are
returned
only
by
the
service
dispatcher,
and
some
are
returned
only
by
the
service
plug-in.
The
returning
entity
is
noted
in
the
description
of
each
error
code.
Error
Code
Description
AZN_S_SVC_DEFINITION_ERROR
Returned
by
the
service
dispatcher
when
an
error
has
been
found
in
the
service
definition
in
the
authorization
API
configuration
file.
AZN_S_SVC_NOT_FOUND
Returned
by
the
service
dispatcher
when
an
error
occurs
either
while
locating
or
loading
an
authorization
service
plug-in.
AZN_S_SVC_INITIALIZE_NOT_FOUND
AZN_S_SVC_SHUTDOWN_NOT_FOUND
AZN_S_SVC_EAS_FUNC_NOT_FOUND
Returned
by
the
service
dispatcher
when
an
error
occurs
either
locating
or
loading
a
service
interface
within
a
particular
plug-in.
For
example,
this
is
returned
by
the
dispatcher
if
the
azn_svc_initialize()
interface
was
not
found
in
the
loaded
plug-in.
AZN_S_SVC_INIT_FAILED
Returned
by
the
plug-in
when
an
error
occurs
while
it
is
initializing.
AZN_S_SVC_SHUTDOWN_FAILED
Returned
by
the
plug-in
when
an
error
occurs
while
it
is
shutting
down.
AZN_S_SVC_AUTHORIZATION_FAILED
The
calling
application
does
not
possess
the
authority
required
to
invoke
the
services
of
this
plug-in.
Minor
error
codes
Minor
error
codes
are
encoded
by
the
authorization
API
using
a
table
of
known
message
catalogue
prefixes.
All
Tivoli
Access
Manager
messages
are
composed
of
a
prefix
value
and
the
specific
error
code
within
that
message
set.
When
the
authorization
API
encodes
a
minor
error
code,
using
azn_util_errcode(),
the
prefix
is
removed
from
the
minor
code
and
cross-referenced
with
a
table
of
known
prefixes.
When
the
prefix
is
identified,
it
is
converted
into
a
mask,
which
is
then
inserted
into
the
major
error
portion
of
the
azn_status_t
code
returned.
The
reverse
operation
is
performed
by
the
azn_error_minor()
function
to
rebuild
the
original
minor
error
code.
To
enable
minor
error
codes
returned
by
authorization
API
services
to
be
properly
encoded
by
azn_util_errcode()
an
appropriate
prefix
must
be
defined
for
authorization
API
service
plug-ins.
The
same
prefix
is
shared
by
all
services
of
the
same
type.
The
prefix
for
all
external
authorization
services
is
defined
in
ogauthzn.h
as
follows:
extern
unsigned
int
azn_eas_svc_err_prefix;
148
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
Define
error
messages
for
your
external
authorization
service
by
using
the
azn_eas_svc_err_prefix.
For
example,
minor
error
codes
for
an
external
authorization
service
plug-in
are
defined
in
the
interface
file
as
follows:
#define
EAS_SVC_CORE_DUMP(azn_eas_svc_err_prefix
|
0x1)
#define
EAS_SVC_INVALID_ATTRIBUTE(azn_eas_svc_err_prefix
|
0x2)
#define
EAS_SVC_BAD_FILENAME(azn_eas_svc_err_prefix
|
0x3)
Chapter
9.
External
authorization
service
plug-ins
149
150
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
Appendix
A.
Authorization
API
reference
This
section
contains
the
following
reference
pages:
v
azn_attrlist_add_entry()
v
azn_attrlist_add_entry_buffer()
v
“azn_attrlist_add_entry_pobj()”
on
page
155
v
“azn_attrlist_add_entry_ulong()”
on
page
156
v
“azn_attrlist_copy()”
on
page
157
v
“azn_attrlist_create()”
on
page
158
v
“azn_attrlist_delete()”
on
page
159
v
“azn_attrlist_delete_entry()”
on
page
160
v
“azn_attrlist_delete_entry_value()”
on
page
161
v
“azn_attrlist_get_entry_buffer_value()”
on
page
162
v
“azn_attrlist_get_entry_pobj_value()”
on
page
164
v
“azn_attrlist_get_entry_string_value()”
on
page
165
v
“azn_attrlist_get_entry_type()”
on
page
167
v
“azn_attrlist_get_entry_ulong_value()”
on
page
169
v
“azn_attrlist_get_names()”
on
page
170
v
“azn_attrlist_name_get_num()”
on
page
171
v
“azn_creds_combine()”
on
page
172
v
“azn_creds_copy()”
on
page
174
v
“azn_creds_create()”
on
page
175
v
“azn_creds_delete()”
on
page
176
v
“azn_creds_equal()”
on
page
177
v
“azn_creds_for_subject()”
on
page
178
v
“azn_creds_get_attr_value_string()”
on
page
180
v
“azn_creds_get_attrlist_for_subject()”
on
page
181
v
“azn_creds_get_pac()”
on
page
183
v
“azn_creds_modify()”
on
page
185
v
“azn_creds_num_of_subjects()”
on
page
188
v
“azn_creds_set_attr_value_string()”
on
page
190
v
“azn_decision_access_allowed()”
on
page
192
v
“azn_decision_access_allowed_ext()”
on
page
194
v
“azn_entitlement_get_entitlements()”
on
page
197
v
“azn_error_get_string()”
on
page
199
v
“azn_error_major()”
on
page
200
v
“azn_error_minor()”
on
page
201
v
“azn_error_minor_get_string()”
on
page
202
v
“azn_id_get_creds()”
on
page
203
v
“azn_initialize()”
on
page
207
v
“azn_pac_get_creds()”
on
page
210
v
“azn_release_buffer()”
on
page
212
v
“azn_release_pobj()”
on
page
213
©
Copyright
IBM
Corp.
2000,2003
151
v
“azn_release_string()”
on
page
214
v
“azn_release_strings()”
on
page
215
v
“azn_shutdown()”
on
page
216
v
“azn_util_errcode()”
on
page
217
v
“azn_util_handle_is_valid()”
on
page
218
v
“azn_util_password_authenticate()”
on
page
219
v
“azn_util_password_change()”
on
page
221
152
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
azn_attrlist_add_entry()
Adds
a
name
or
string-value
entry
to
an
attribute
list
Syntax
azn_status_t
azn_attrlist_add_entry(
const
azn_attrlist_h_t
attr_list,
const
azn_string_t
attr_name,
const
azn_string_t
string_value
);
Parameters
Input
attr_list
Handle
to
an
attribute
list.
The
attribute
list
handle
can
be
one
of
the
following:
v
An
attribute
list
handle
for
a
new,
empty
attribute
list,
which
has
been
initialized
by
a
call
to
azn_attrlist_create().
v
An
attribute
list
handle
for
an
existing,
non-empty
attribute
list
which
contains
valid
data.
attr_name
Attribute
name
of
the
entry
to
be
added.
string_value
String
attribute
value
to
be
added.
Description
This
function
adds
a
string
value
to
the
attribute
attr_name
within
the
attribute
list
attr_list.
If
the
attribute
attr_name
already
exists
in
the
list
then
the
value
is
appended
to
the
existing
list
of
values
for
attr_name.
The
values
under
attr_name
are
stored
in
the
order
in
which
they
were
inserted
into
the
list.
There
is
no
checking
performed
upon
values
in
the
list;
therefore
duplicate
values
are
permitted.
Return
Values
If
successful,
the
function
will
return
AZN_S_COMPLETE.
If
the
returned
status
code
is
not
equal
to
AZN_S_COMPLETE,
the
major
error
codes
will
be
derived
from
the
returned
status
code
with
azn_error_major().
v
AZN_S_COMPLETE
Successful
completion.
v
AZN_S_INVALID_ATTRLIST_HDL
Attribute
list
handle
is
invalid.
v
AZN_S_INVALID_ATTR_NAME
Attribute
name
is
invalid.
v
AZN_S_INVALID_STRING_VALUE
Attribute
value
is
invalid.
v
AZN_S_FAILURE
An
error
or
failure
has
occurred.
Use
azn_minor_error()
to
derive
specific
minor
error
codes
from
the
returned
status
code.
Appendix
A.
Authorization
API
reference
153
azn_attrlist_add_entry_buffer()
Adds
a
name/buffer
value
entry
to
an
attribute
list.
Syntax
azn_status_t
azn_attrlist_add_entry_buffer(
const
azn_attrlist_h_t
attr_list,
const
azn_string_t
attr_name,
const
azn_buffer_t
buffer_value
);
Parameters
Input
attr_list
Handle
to
an
attribute
list.
The
attribute
list
handle
can
be
one
of
the
following:
v
An
attribute
list
handle
for
a
new,
empty
attribute
list,
which
has
been
initialized
by
a
call
to
azn_attrlist_create().
v
An
attribute
list
handle
for
an
existing,
non-empty
attribute
list
which
contains
valid
data.
attr_name
Attribute
name
of
the
entry
to
be
added.
buffer_value
Buffer
attribute
value
to
be
added.
Description
This
function
adds
a
buffer
value
to
the
attribute
attr_name
within
the
attribute
list
attr_list.
If
the
attribute
attr_name
already
exists
in
the
list
then
the
value
is
appended
to
the
existing
list
of
values
for
attr_name.
The
values
under
attr_name
are
stored
in
the
order
in
which
they
were
inserted
into
the
list.
There
is
no
checking
performed
upon
values
in
the
list;
therefore
duplicate
values
are
permitted.
Return
Values
If
successful,
the
function
returns
AZN_S_COMPLETE.
If
the
returned
status
code
is
not
equal
to
AZN_S_COMPLETE,
the
major
error
codes
will
be
derived
from
the
returned
status
code
with
azn_error_major.
v
AZN_S_COMPLETE
Successful
completion.
v
AZN_S_INVALID_ATTRLIST_HDL
Attribute
list
handle
is
invalid.
v
AZN_S_INVALID_ATTR_NAME
Attribute
name
is
invalid.
v
AZN_S_INVALID_BUFFER
Attribute
buffer
is
invalid.
v
AZN_S_FAILURE
An
error
or
failure
has
occurred.
Use
azn_minor_error()
to
derive
specific
minor
error
codes
from
the
returned
status
code.
154
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
azn_attrlist_add_entry_pobj()
Adds
the
name
of
a
protected
object
entry
to
the
attribute
list.
Syntax
azn_status_t
azn_attrlist_add_entry_pobj(
const
azn_attrlist_h_t
attr_list,
const
azn_string_t
attr_name,
const
azn_pobj_t
pobj_value
);
Parameters
Input
attr_list
Handle
to
an
attribute
list.
The
attribute
list
handle
can
be
one
of
the
following:
v
An
attribute
list
handle
for
a
new,
empty
attribute
list,
which
has
been
initialized
by
a
call
to
azn_attrlist_create().
v
An
attribute
list
handle
for
an
existing,
non-empty
attribute
list
which
contains
valid
data.
attr_name
Name
of
the
attribute
to
which
the
value
is
to
be
added.
pobj_value
Protected
object
attribute
value
to
be
added.
Description
This
function
adds
a
protected
object
value
to
the
attribute
attr_name
within
the
attribute
list
attr_list.
If
the
attribute
attr_name
already
exists
in
the
list
then
the
value
is
appended
to
the
existing
list
of
values
for
attr_name.
The
values
under
attr_name
are
stored
in
the
order
in
which
they
were
inserted
into
the
list.
There
is
no
checking
performed
upon
values
in
the
list;
therefore
duplicate
values
are
permitted.
Return
Values
When
successful,
the
function
returns
AZN_S_COMPLETE.
When
unsuccessful,
the
function
returns
one
of
the
following
major
error
codes:
v
AZN_S_INVALID_ATTRLIST_HDL
The
attribute
list
is
invalid.
v
AZN_S_INVALID_ATTR_NAME
The
attribute
list
name
is
invalid.
v
AZN_S_INVALID_POBJ
The
protected
object
value
is
NULL.
Appendix
A.
Authorization
API
reference
155
azn_attrlist_add_entry_ulong()
Adds
an
unsigned
long
entry
to
the
attribute
list.
Syntax
azn_status_t
azn_attrlist_add_entry_ulong(
const
azn_attrlist_h_t
attr_list,
const
azn_string_t
attr_name,
const
azn_ulong_t
ulong_value
);
Parameters
Input
attr_list
Handle
to
an
attribute
list.
The
attribute
list
handle
can
be
one
of
the
following:
v
An
attribute
list
handle
for
a
new,
empty
attribute
list,
which
has
been
initialized
by
a
call
to
azn_attrlist_create().
v
An
attribute
list
handle
for
an
existing,
non-empty
attribute
list
which
contains
valid
data.
attr_name
Iterate
name
to
which
the
value
is
to
be
added.
ulong_value
Ulong
attribute
value
to
be
added.
Description
This
function
adds
a
ulong
value
to
the
attribute
attr_name
within
the
attribute
list
attr_list.
If
the
attribute
attr_name
already
exists
in
the
list
then
the
value
is
appended
to
the
existing
list
of
values
for
attr_name.
The
values
under
attr_name
are
stored
in
the
order
in
which
they
were
inserted
into
the
list.
There
is
no
checking
performed
upon
values
in
the
list;
therefore
duplicate
values
are
permitted.
Return
Values
When
successful,
the
function
returns
AZN_S_COMPLETE.
When
unsuccessful,
the
function
returns
one
of
the
following
major
error
codes:
v
AZN_S_INVALID_ATTRLIST_HDL
The
attribute
list
is
invalid.
v
AZN_S_INVALID_ATTR_NAME
The
attribute
list
name
is
invalid.
156
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
azn_attrlist_copy()
Copies
a
valid
attribute
list
to
a
new
attribute
list.
Syntax
azn_attrlist_h_t
azn_attrlist_copy(
const
azn_attrlist_h_t
attr_list
);
Parameters
Input
attr_list
Handle
to
an
attribute
list.
The
attribute
list
handle
can
be
one
of
the
following:
v
An
attribute
list
handle
for
a
new,
empty
attribute
list,
which
has
been
initialized
by
a
call
to
azn_attrlist_create().
v
An
attribute
list
handle
for
an
existing,
non-empty
attribute
list
which
contains
valid
data.
Description
This
function
copies
an
existing
attribute
list
and
returns
a
handle
to
the
new
attribute
list.
Return
Values
If
unsuccessful,
the
function
will
return
AZN_S_INVALID_HANDLE.
Appendix
A.
Authorization
API
reference
157
azn_attrlist_create()
Creates
a
valid,
empty
attribute
list,
assigns
it
a
handle,
and
returns
the
handle.
Syntax
azn_status_t
azn_attrlist_create(
azn_attrlist_h_t
*new_attr_list
);
Parameters
Output
new_attr_list
Pointer
to
an
azn_attrlist_h_t
variable
that
will
contain
the
handle
to
the
new
attribute
list
upon
successful
completion.
Description
This
function
creates
a
new
and
empty
attribute
list,
assigns
it
a
handle
new_attr_list,
and
returns
a
pointer
to
the
handle.
Note:
Alternatively,
when
you
are
declaring
an
attribute
list
handle
to
for
use
as
an
authorization
API
output
parameter
you
can
declare
the
handle
and
assign
it
the
value
AZN_C_INVALID_HANDLE,
which
indicates
that
it
is
uninitialized.
In
this
case
when
the
authorization
API
function
returns
data
in
the
parameter,
it
will
automatically
create
an
attribute
list
and
return
the
handle
in
the
output
parameter.
When
new_attr_list
is
no
longer
needed,
its
storage
should
be
released
by
calling
azn_attrlist_delete().
Return
Values
If
successful,
the
function
will
return
AZN_S_COMPLETE.
If
the
returned
status
code
is
not
equal
to
AZN_S_COMPLETE,
the
major
error
codes
will
be
derived
from
the
returned
status
code
with
azn_error_major().
v
AZN_S_COMPLETE
Successful
completion.
v
AZN_S_INVALID_ATTRLIST_HDL
Attribute
list
handle
is
invalid.
v
AZN_S_FAILURE
An
error
or
failure
has
occurred.
Use
azn_error_minor()
to
derive
specific
minor
error
codes
from
the
returned
status
code.
158
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
azn_attrlist_delete()
Deletes
the
attribute
list
associated
with
the
attribute
list
handle.
Syntax
azn_status_t
azn_attrlist_delete(
azn_attrlist_h_t
*old_attr_list
);
Parameters
Input
old_attr_list
Pointer
to
the
attribute
list
handle
for
the
attribute
list
to
be
deleted.
The
attribute
list
handle
can
be
one
of
the
following:
v
An
attribute
list
handle
for
a
new,
empty
attribute
list,
which
has
been
initialized
by
a
call
to
azn_attrlist_create().
v
An
attribute
list
handle
for
an
existing,
non-empty
attribute
list
which
contains
valid
data.
Output
old_attr_list
NULL
pointer
to
an
attribute
list
handle
that
is
invalid
upon
return.
Description
This
function
deletes
the
attribute
list
associated
with
the
handle
old_attr_list.
This
function
will
set
the
input
attribute
list
handle
to
an
invalid
value
to
ensure
that
it
cannot
be
used
in
future
functions.
Return
Values
If
successful,
the
function
will
return
AZN_S_COMPLETE.
If
the
returned
status
code
is
not
equal
to
AZN_S_COMPLETE,
the
major
error
codes
will
be
derived
from
the
returned
status
code
with
azn_error_major().
v
AZN_S_COMPLETE
Successful
completion.
v
AZN_S_INVALID_ATTRLIST_HDL
Attribute
list
handle
is
invalid.
v
AZN_S_FAILURE
An
error
or
failure
has
occurred.
Use
azn_error_minor()
to
derive
specific
minor
error
codes
from
the
returned
status
code.
Appendix
A.
Authorization
API
reference
159
azn_attrlist_delete_entry()
Deletes
the
specified
attribute
associated
with
the
attribute
list
handle.
Syntax
azn_status_t
azn_attrlist_delete_entry(
const
azn_attrlist_h_t
attr_list,
const
azn_string_t
attr_name
);
Parameters
Input
attr_list
Handle
to
an
attribute
list.
The
attribute
list
handle
should
be
a
handle
for
an
existing,
non-empty
attribute
list
which
contains
valid
data.
attr_name
The
name
of
an
attribute
contained
within
the
attribute
list
that
is
referenced
by
attr_list.
Description
This
function
deletes
the
specified
attribute
attr_name
from
the
attribute
list
associated
with
the
handle
attr_list.
Return
Values
If
successful,
the
function
will
return
AZN_S_COMPLETE.
If
the
returned
status
code
is
not
equal
to
AZN_S_COMPLETE,
the
major
error
codes
will
be
derived
from
the
returned
status
code
with
azn_error_major().
v
AZN_S_COMPLETE
Successful
completion.
v
AZN_S_INVALID_ATTRLIST_HDL
Attribute
list
handle
is
invalid.
v
AZN_S_FAILURE
An
error
or
failure
has
occurred.
Use
azn_error_minor()
to
derive
specific
minor
error
codes
from
the
returned
status
code.
160
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
azn_attrlist_delete_entry_value()
Deletes
the
specified
value
associated
with
the
attribute
name
in
the
specified
attribute
list.
Syntax
azn_status_t
azn_attrlist_delete_entry_value(
azn_attrlist_h_t
attr_list,
const
azn_string_t
attr_name,
const
unsigned
int
value_index
);
Parameters
Input
attr_list
Handle
to
an
attribute
list.
The
attribute
list
handle
should
be
a
handle
for
an
existing,
non-empty
attribute
list
which
contains
valid
data.
attr_name
The
name
of
an
attribute
contained
within
the
attribute
list
that
is
referenced
by
attr_list.
value_index
An
integer
index
into
the
array
of
values
assigned
to
attr_name.
Specifies
the
value
to
be
deleted.
Output
attr_list
Handle
to
an
attribute
list.
The
attribute
list
handle
should
be
a
handle
for
an
existing,
non-empty
attribute
list
which
contains
valid
data.
Description
This
function
deletes
the
value
at
position
value_index
in
the
array
of
values
for
attribute
attr_name,
from
the
specified
attribute
list
associated
with
the
handle
attr_list.
Return
Values
If
successful,
the
function
will
return
AZN_S_COMPLETE.
If
the
returned
status
code
is
not
equal
to
AZN_S_COMPLETE,
the
major
error
codes
will
be
derived
from
the
returned
status
code
with
azn_error_major().
v
AZN_S_COMPLETE
Successful
completion.
v
AZN_S_INVALID_ATTRLIST_HDL
Attribute
list
handle
is
invalid.
v
AZN_S_FAILURE
An
error
or
failure
has
occurred.
Use
azn_error_minor()
to
derive
specific
minor
error
codes
from
the
returned
status
code.
Appendix
A.
Authorization
API
reference
161
azn_attrlist_get_entry_buffer_value()
Returns
a
single
specified
value
attribute
for
a
name
attribute
that
has
multiple
values
that
are
contained
in
buffers.
Syntax
azn_status_t
azn_attrlist_get_entry_buffer_value(
const
azn_attrlist_h_t
attr_list,
const
azn_string_t
attr_name,
const
unsigned
int
value_index,
azn_buffer_t
*buffer_value
);
Parameters
Input
attr_list
Handle
to
an
attribute
list.
The
attribute
list
handle
should
be
a
handle
for
an
existing,
non-empty
attribute
list
which
contains
valid
data.
attr_name
Name
attribute
of
the
entry
from
which
the
value
attribute
is
to
be
returned.
value_index
Index
within
the
entry
of
the
value
attribute
to
be
returned.
Output
buffer_value
Pointer
to
an
azn_buffer_t
variable
that
will
contain
the
address
of
the
buffer
data
upon
successful
completion
of
the
routine.
Description
This
function
returns
one
buffer-type
value
attribute
in
buffer_value.
The
returned
value
attribute
is
the
one
at
position
value_index
within
the
entry
whose
name
attribute
is
specified
by
attr_name.
The
first
value
attribute
for
any
particular
name
attribute
within
an
attribute
list
has
index
0.
When
buffer_value
is
no
longer
needed,
its
storage
should
be
released
by
calling
azn_release_buffer().
Return
Values
If
successful,
the
function
will
return
AZN_S_COMPLETE.
If
the
returned
status
code
is
not
equal
to
AZN_S_COMPLETE,
the
major
error
codes
will
be
derived
from
the
returned
status
code
with
azn_major_error().
v
AZN_S_COMPLETE
Successful
completion.
v
AZN_S_INVALID_ATTRLIST_HDL
Attribute
list
handle
is
invalid.
v
AZN_S_INVALID_ATTR_NAME
Attribute
name
is
invalid.
v
AZN_S_INVALID_BUFFER_REF
162
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
Buffer
reference
is
not
valid.
v
AZN_S_ATTR_VALUE_NOT_BUFFER_TYPE
The
value
attributes
of
this
entry
are
not
of
type
buffer.
v
AZN_S_ATTR_INVALID_INDEX
Index
is
not
valid
(no
value
exists
for
this
index).
v
AZN_S_FAILURE
An
error
or
failure
has
occurred.
Use
azn_error_minor()
to
derive
specific
minor
error
codes
from
the
returned
status
code.
Appendix
A.
Authorization
API
reference
163
azn_attrlist_get_entry_pobj_value()
Returns
a
single
specified
value
attribute
for
a
name
attribute
that
has
one
or
more
values
that
contain
protected
object
information.
Syntax
azn_status_t
azn_attrlist_get_entry_pobj_value(
const
azn_attrlist_h_t
attr_list,
const
azn_string_t
attr_name,
const
unsigned
int
value_index,
azn_pobj_t
*pobj_value
);
Parameters
Input
attr_list
Handle
to
an
attribute
list.
The
attribute
list
handle
should
be
a
handle
for
an
existing,
non-empty
attribute
list
which
contains
valid
data.
attr_name
Name
of
the
attribute
from
which
the
value
needs
to
be
returned.
value_index
Index
within
the
entry
of
the
value
attribute
to
be
returned
Output
pobj_value
Pointer
to
an
azn_pobj_t
variable
that
will
contain
the
address
of
the
protected
object
information
upon
successful
completion
of
the
routine.
Description
Returns
a
single
specified
value
attribute
for
a
name
attribute
that
has
one
or
more
values
that
contain
protected
object
information.
When
pobj_value
is
longer
needed,
call
azn_release_pobj()
to
release
its
storage.
Return
Values
When
successful,
the
function
returns
AZN_S_COMPLETE
When
unsuccessful,
the
function
returns
one
of
the
following
major
error
codes:
v
AZN_S_INVALID_ATTRLIST_HDL
The
attribute
list
is
invalid.
v
AZN_S_INVALID_ATTR_NAME
The
attribute
name
is
NULL,
or
the
attribute
name
is
not
found.
v
AZN_S_INVALID_INDEX
The
index
value_index
is
invalid.
v
AZN_S_INVALID_POBJ_REF
The
pobj_value
pointer
is
NULL.
v
AZN_S_ATTR_VALUE_NOT_POBJ_TYPE
The
value
type
at
the
specified
index
is
not
of
type
pobj.
164
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
azn_attrlist_get_entry_string_value()
Returns
a
single
specified
value
attribute
for
a
name
attribute
that
has
multiple
values
that
are
strings.
Syntax
azn_status_t
azn_attrlist_get_entry_string_value(
const
azn_attrlist_h_t
attr_list,
const
azn_string_t
attr_name,
const
unsigned
int
value_index,
azn_string_t
*string_value
);
Parameters
Input
attr_list
Handle
to
an
attribute
list.
The
attribute
list
handle
should
be
a
handle
for
an
existing,
non-empty
attribute
list
which
contains
valid
data.
attr_name
Name
attribute
of
the
entry
from
which
the
value
attribute
is
to
be
returned.
value_index
Index
within
the
entry
of
the
value
attribute
to
be
returned
Output
string_value
Pointer
to
an
azn_string_t
variable
that
will
contain
the
string
data
upon
successful
completion
of
the
routine.
Description
This
function
returns
one
string-type
value
attribute
in
string_value.
The
returned
value
attribute
is
the
one
at
position
value_index
within
the
set
of
value
attributes
belonging
to
the
name
attribute
that
is
specified
by
attr_name.
The
first
value
attribute
for
a
specified
name
attribute
within
an
attribute
list
has
index
0.
When
string_value
is
no
longer
needed,
call
azn_release_string()
to
release
its
storage.
Return
Values
If
successful,
the
function
will
return
AZN_S_COMPLETE.
If
the
returned
status
code
is
not
equal
to
AZN_S_COMPLETE,
the
major
error
codes
will
be
derived
from
the
returned
status
code
with
azn_error_major().
v
AZN_S_COMPLETE
Successful
completion.
v
AZN_S_INVALID_ATTRLIST_HDL
Attribute
list
handle
is
invalid.
v
AZN_S_INVALID_ATTR_NAME
Attribute
name
is
invalid.
v
AZN_S_INVALID_STRING_REF
Appendix
A.
Authorization
API
reference
165
String
reference
is
invalid.
v
AZN_S_ATTR_VALUE_NOT_STRING_TYPE
Value
attributes
of
this
entry
are
not
of
type
string.
v
AZN_S_ATTR_INVALID_INDEX
Index
is
invalid
(no
value
exists
for
this
index).
v
AZN_S_FAILURE
An
error
or
failure
has
occurred.
Use
azn_error_minor()
to
derive
specific
minor
error
codes
from
the
returned
status
code.
166
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
azn_attrlist_get_entry_type()
Returns
the
type
of
a
specified
value
entry
for
a
specified
attribute
name
within
a
specified
attribute
list.
Syntax
azn_status_t
azn_attrlist_get_entry_type
(
const
azn_attrlist_h_t
attr_list
/*
in
*/,
const
azn_string_t
attr_name
/*
in
*/,
const
unsigned
int
value_index
/*
in
*/,
unsigned
long
*value_type
/*
out
*/
);
Parameters
Input
attr_list
Handle
to
an
attribute
list.
The
attribute
list
handle
should
be
a
handle
for
an
existing,
non-empty
attribute
list
which
contains
valid
data.
attr_name
Name
attribute
of
the
entry
from
which
the
type
of
the
type
is
to
be
returned.
value_index
Index
within
the
entry
of
the
value
attribute
to
be
returned.
Output
value_type
A
pointer
to
an
unsigned
long.
Contains
the
type
of
the
value
of
the
attribute
at
index
value_index.
Description
Returns
the
type
of
a
specified
value
entry
for
a
specified
attribute
name
within
a
specified
attribute
list.
Supported
types
are
string,
buffer,
pobj
(protected
object),
ulong.
Supported
return
values:
#define
AZN_VALUE_TYPE_NONE
0
#define
AZN_VALUE_TYPE_STRING
1
#define
AZN_VALUE_TYPE_BUFFER
2
#define
AZN_VALUE_TYPE_POBJ
3
(Reserved)
4
#define
AZN_VALUE_TYPE_ULONG
5
#define
AZN_VALUE_TYPE_MAX
5
Return
Values
If
successful,
the
function
will
return
AZN_S_COMPLETE.
If
the
returned
status
code
is
not
equal
to
AZN_S_COMPLETE,
the
major
error
codes
will
be
derived
from
the
returned
status
code
with
azn_error_major().
v
AZN_S_COMPLETE
Successful
completion.
v
AZN_S_INVALID_ATTRLIST_HDL
Appendix
A.
Authorization
API
reference
167
Attribute
list
handle
is
invalid.
v
AZN_S_INVALID_STRING_REF
String
reference
is
invalid.
v
AZN_S_FAILURE
An
error
or
failure
has
occurred.
Use
azn_error_minor()
to
derive
specific
minor
error
codes
from
the
returned
status
code.
168
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
azn_attrlist_get_entry_ulong_value()
Returns
a
single
specified
value
for
a
name
attribute
that
has
one
or
more
values
that
are
of
type
unsigned
long.
Syntax
azn_status_t
azn_attrlist_get_entry_ulong_value(
const
azn_attrlist_h_t
attr_list,
const
azn_string_t
attr_name,
const
unsigned
int
value_index,
azn_ulong_t
*ulong_value
);
Parameters
Input
attr_list
Handle
to
an
attribute
list.
The
attribute
list
handle
should
be
a
handle
for
an
existing,
non-empty
attribute
list
which
contains
valid
data.
attr_name
Name
attribute
of
the
entry
from
which
the
value
attribute
is
to
be
returned.
value_index
Index
within
the
entry
of
the
value
attribute
to
be
returned.
Output
ulong_value
Pointer
to
an
unsigned
long
variable
that
holds
the
value
of
the
returned
attribute.
Description
Returns
a
single
specified
value
for
a
name
attribute
that
has
one
or
more
values
that
are
of
type
unsigned
long.
Return
Values
When
successful,
the
function
returns
AZN_S_COMPLETE.
When
the
returned
status
code
is
not
equal
to
AZN_S_COMPLETE,
the
major
error
codes
are
derived
from
the
returned
status
code
with
azn_major_error().
v
AZN_S_INVALID_ATTRLIST_HDL
Attribute
list
handle
is
invalid.
v
AZN_S_INVALID_ATTR_NAME
Attribute
name
is
invalid
or
the
attribute
name
is
not
found.
v
AZN_S_INVALID_INDEX
The
variable
value_index
is
not
valid.
v
AZN_S_ATTR_VALUE_NOT_ULONG_TYPE
The
value
attributes
of
this
entry
are
not
of
type
ulong.
Appendix
A.
Authorization
API
reference
169
azn_attrlist_get_names()
Returns
the
list
of
all
name
attributes
appearing
in
entries
of
the
attribute
list.
Syntax
azn_status_t
azn_attrlist_get_names(
const
azn_attrlist_h_t
attr_list,
azn_string_t
*attr_names[]
);
Parameters
Input
attr_list
Handle
to
an
attribute
list.
The
attribute
list
handle
should
be
a
handle
for
an
existing,
non-empty
attribute
list
which
contains
valid
data.
Output
attr_names
Pointer
to
an
array
of
NULL-terminated
strings
that
hold
the
returned
list
of
name
attributes.
The
last
entry
in
the
array
is
denoted
by
a
NULL
azn_string_t.
Description
This
function
returns
a
list
of
names
attributes
as
an
array
of
NULL
terminated
strings.
When
the
attr_names
array
is
no
longer
required,
call
azn_release_strings()
to
release
its
storage.
Return
Values
If
successful,
the
function
will
return
AZN_S_COMPLETE.
If
the
returned
status
code
is
not
equal
to
AZN_S_COMPLETE,
the
major
error
codes
will
be
derived
from
the
returned
status
code
with
azn_error_major().
v
AZN_S_COMPLETE
Successful
completion.
v
AZN_S_INVALID_ATTRLIST_HDL
Attribute
list
handle
is
invalid.
v
AZN_S_INVALID_STRING_REF
String
reference
is
invalid.
v
AZN_S_FAILURE
An
error
or
failure
has
occurred.
Use
azn_error_minor()
to
derive
specific
minor
error
codes
from
the
returned
status
code.
170
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
azn_attrlist_name_get_num()
Returns
the
number
of
value
attributes
for
a
specified
name
attribute
in
a
specified
attribute
list.
Syntax
azn_status_t
azn_attrlist_name_get_num(
const
azn_attrlist_h_t
attr_list,
const
azn_string_t
attr_name,
unsigned
int
*num_values
);
Description
Input
attr_list
Handle
to
an
attribute
list.
The
attribute
list
handle
should
be
a
handle
for
an
existing,
non-empty
attribute
list
which
contains
valid
data.
attr_name
Name
attribute
for
the
entry
whose
number
of
value
attributes
is
to
be
returned.
Output
num_values
Pointer
to
an
integer
through
which
the
number
of
value
attributes
(in
the
entry
whose
name
attribute
is
specified
by
attr_name)
is
returned.
Description
This
function
returns
the
number
of
value
attributes
for
a
specified
name
attribute
in
a
specified
attribute
list.
Return
Values
If
successful,
the
function
will
return
AZN_S_COMPLETE.
If
the
returned
status
code
is
not
equal
to
AZN_S_COMPLETE,
the
major
error
codes
will
be
derived
from
the
returned
status
code
with
azn_error_major().
v
AZN_S_COMPLETE
Successful
completion.
v
AZN_S_INVALID_ATTRLIST_HDL
Attribute
list
handle
is
invalid.
v
AZN_S_INVALID_ATTR_NAME
Attribute
name
is
invalid.
v
AZN_S_INVALID_INTEGER_REF
Integer
reference
is
invalid.
v
AZN_S_FAILURE
An
error
or
failure
has
occurred.
Use
azn_error_minor()
to
derive
specific
minor
error
codes
from
the
returned
status
code.
Appendix
A.
Authorization
API
reference
171
azn_creds_combine()
Combines
two
authorization
credentials
chains
and
a
returns
a
pointer
to
a
handle
to
the
resulting
combined
credentials
chain.
Syntax
azn_status_t
azn_creds_combine(
const
azn_creds_h_t
creds,
const
azn_creds_h_t
creds_to_add,
azn_creds_h_t
*combined_creds
);
Parameters
Input
creds
Handle
to
an
credentials
chain
whose
first
indexed
entry
is
the
credential
of
the
initiator
of
the
request.
The
credential
handle
should
be
a
handle
for
an
existing,
non-empty
credential
which
contains
valid
data.
creds_to_add
Handle
to
the
credentials
chain
to
be
appended
to
creds.
The
credential
handle
should
be
a
handle
for
an
existing,
non-empty
credential
which
contains
valid
data.
Output
combined_creds
Pointer
to
a
handle
to
the
returned
new
credentials
chain,
which
consists
of
the
credentials
chain
referenced
by
creds
followed
by
the
credentials
chain
referenced
by
creds_to_add.
The
credential
handle
pointer
passed
as
the
combined_creds
parameter
can
point
to
one
of
the
following:
v
A
credential
handle
for
a
new,
valid,
empty
credential.
v
A
credential
handle
initialized
to
AZN_C_INVALID_HANDLE.
Description
This
function
takes
a
credential
handle
creds_to_add,
which
refers
to
a
credentials
chain,
and
adds
it
to
the
end
of
a
chain
of
one
or
more
credentials,
which
are
referenced
by
the
credential
handle
creds.
The
credentials
chain
referenced
by
creds
must
contain
as
its
first
indexed
credential
the
credentials
of
the
initiator.
The
credentials
chain
referenced
by
creds
might
also
contain
the
(previously
combined)
credentials
of
one
or
more
of
the
initiator’s
proxies.
A
handle
to
the
combined
credentials
is
returned
through
combined_creds.
The
input
credential
handles
and
the
credentials
chains
to
which
they
refer
are
not
modified
in
any
way
by
this
call.
Later
changes
to
these
structures,
including
the
releasing
of
their
storage,
will
have
no
effect
on
combined_creds.
Note:
This
call
uses
the
new
credential
handle
combined_creds.
When
you
declare
a
new
credential
handle,
always
initialize
it
to
AZN_C_INVALID_HANDLE
before
using
it.
172
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
Return
Values
If
successful,
the
function
will
return
AZN_S_COMPLETE.
If
the
returned
status
code
is
not
equal
to
AZN_S_COMPLETE,
the
major
error
codes
will
be
derived
from
the
returned
status
code
with
azn_error_major().
v
AZN_S_COMPLETE
Successful
completion.
v
AZN_S_API_UNINITIALIZED
This
function
has
been
called
before
azn_initialize().
v
AZN_S_INVALID_CREDS_HDL
Handle
passed
as
creds
is
invalid.
v
AZN_S_INVALID_ADDED_CREDS_HDL
Credentials
handle
passed
as
creds_to_add
is
invalid.
v
AZN_S_INVALID_COMB_CREDS_HDL
Credentials
handle
passed
as
combined_creds
is
invalid.
v
AZN_S_UNIMPLEMENTED_FUNCTION
This
function
is
not
supported
by
the
implementation.
v
AZN_S_FAILURE
An
error
or
failure
has
occurred.
Use
azn_error_minor()
to
derive
specific
minor
error
codes
from
the
returned
status
code.
The
minor
error
code
ivacl_s_unauthorized
is
returned
when
the
caller
is
not
authorized
to
use
this
function.
Authorization
might
fail
because
the
caller
does
not
belong
to
the
correct
group
for
the
authorization
API
mode
(remote
or
local),
or
because
of
issues
specific
to
the
authentication
mechanism.
See
pdbaclmsg.h
for
a
complete
list
of
minor
error
codes
that
describe
access
control
problems.
Appendix
A.
Authorization
API
reference
173
azn_creds_copy()
Creates
a
reference
copy
of
the
target
credential.
Syntax
azn_creds_h_t
azn_creds_copy(
const
azn_creds_h_t
creds
);
Parameters
Input
creds
Handle
to
a
credential.
The
handle
can
be
one
of
the
following:
v
A
credential
handle
for
a
new,
empty
credential,
which
has
been
initialized
by
a
call
to
azn_creds_create().
v
A
handle
for
an
existing,
non-empty
credential
which
contains
valid
data.
Description
This
function
creates
a
reference
copy
of
the
target
credential.
This
function
does
not
make
a
new
copy
of
the
original
credential.
It
creates
a
duplicate
credentials
handle
to
the
original
credential.
Use
azn_id_get_creds()
to
create
an
entirely
new
copy
of
a
credential.
Return
Values
If
unsuccessful,
the
function
will
return
AZN_S_INVALID_HANDLE.
Otherwise
it
will
return
another
handle
to
the
credential
creds.
174
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
azn_creds_create()
Creates
a
new,
empty
credentials
chain,
assigns
it
a
handle,
and
returns
a
pointer
to
the
handle.
Syntax
azn_status_t
azn_creds_create(
azn_creds_h_t
*creds
);
Parameters
Output
creds
A
pointer
to
an
azn_creds_h_t
variable
that
will
contain
the
handle
to
the
new
credential
chain
upon
successful
completion.
Description
This
function
creates
a
new,
empty
credentials
chain,
assigns
it
a
handle,
and
returns
a
pointer
to
the
handle.
Note:
Alternatively,
when
you
are
declaring
an
attribute
list
handle
to
for
use
as
an
authorization
API
output
parameter
you
can
declare
the
handle
and
assign
it
the
value
AZN_C_INVALID_HANDLE,
which
indicates
that
it
is
uninitialized.
In
this
case
when
the
authorization
API
function
returns
data
in
the
parameter,
it
will
automatically
create
an
attribute
list
and
return
the
handle
in
the
output
parameter.
When
creds
is
no
longer
required,
call
azn_creds_delete()
to
release
its
storage.
Return
Values
If
successful,
the
function
will
return
AZN_S_COMPLETE.
If
the
returned
status
code
is
not
equal
to
AZN_S_COMPLETE,
the
major
error
codes
will
be
derived
from
the
returned
status
code
with
azn_error_major().
v
AZN_S_COMPLETE
Successful
completion.
v
AZN_S_API_UNINITIALIZED
This
function
has
been
called
before
azn_initialize().
v
AZN_S_INVALID_CREDS_HDL
The
credentials
handle
supplied
is
invalid.
v
AZN_S_FAILURE
An
error
or
failure
has
occurred.
Use
azn_error_minor()
to
derive
specific
minor
error
codes
from
the
returned
status
code.
The
minor
error
code
ivacl_s_unauthorized
is
returned
when
the
caller
is
not
authorized
to
use
this
function.
Authorization
might
fail
because
the
caller
does
not
belong
to
the
correct
group
for
the
authorization
API
mode
(remote
or
local),
or
because
of
issues
specific
to
the
authentication
mechanism.
See
pdbaclmsg.h
for
a
complete
list
of
minor
error
codes
that
describe
access
control
problems.
Appendix
A.
Authorization
API
reference
175
azn_creds_delete()
Deletes
the
credentials
chain
associated
with
the
credential
handle.
Syntax
azn_status_t
azn_creds_delete(
azn_creds_h_t
*creds
);
Parameters
Input
creds
Pointer
to
the
credential
handle
for
the
credential
chain
to
be
deleted.
The
handle
should
be
a
handle
for
an
existing,
non-empty
credentials
chain
which
contains
valid
data.
Output
creds
NULL
pointer
to
a
credentials
handle
that
is
invalid
upon
return.
Description
This
function
deletes
the
credentials
chain
associated
with
the
handle
creds.
This
function
sets
the
input
credentials
handle
to
an
invalid
value
to
ensure
that
it
cannot
be
used
in
future
functions.
Return
Values
If
successful,
the
function
will
return
AZN_S_COMPLETE.
If
the
returned
status
code
is
not
equal
to
AZN_S_COMPLETE,
the
major
error
codes
will
be
derived
from
the
returned
status
code
with
azn_error_major().
v
AZN_S_COMPLETE
Successful
completion.
v
AZN_S_API_UNINITIALIZED
This
function
has
been
called
before
azn_initialize().
v
AZN_S_INVALID_CREDS_HDL
The
credentials
handle
supplied
is
invalid.
v
AZN_S_FAILURE
An
error
or
failure
has
occurred.
Use
azn_error_minor()
to
derive
specific
minor
error
codes
from
the
returned
status
code.
The
minor
error
code
ivacl_s_unauthorized
is
returned
when
the
caller
is
not
authorized
to
use
this
function.
Authorization
might
fail
because
the
caller
does
not
belong
to
the
correct
group
for
the
authorization
API
mode
(remote
or
local),
or
because
of
issues
specific
to
the
authentication
mechanism.
See
pdbaclmsg.h
for
a
complete
list
of
minor
error
codes
that
describe
access
control
problems.
176
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
azn_creds_equal()
Compares
the
contents
of
two
credentials.
Syntax
azn_status_t
azn_creds_equal(
const
azn_creds_h_t
cred1,
const
azn_creds_h_t
cred2,
azn_boolean_t
*is_equal
);
Parameters
Input
cred1
Handle
to
a
credential.
The
credential
handle
should
be
a
handle
for
an
existing,
non-empty
credential
which
contains
valid
data.
cred2
Handle
to
a
credential.
The
credential
handle
should
be
a
handle
for
an
existing,
non-empty
credential
which
contains
valid
data.
Output
is_equal
A
pointer
to
an
azn_boolean_t
variable
that
will
receive
the
boolean
result
of
this
call.
azn_creds_equal()
returns
a
boolean
value
of
true
or
false,
indicating
if
the
two
compared
credentials
are
equal.
This
value
is
true
when
the
credentials
are
equal,
and
false
when
the
credentials
are
not
equal.
Description
This
function
compares
the
contents
of
two
credentials.
The
function
returns
true
when
the
credentials
are
identical
and
false
when
the
credentials
differ.
The
value
is
returned
in
the
output
parameter
is_equal.
Return
Values
If
the
returned
status
code
is
not
equal
to
AZN_S_COMPLETE,
the
major
error
codes
will
be
derived
from
the
returned
status
code
with
azn_error_major().
v
AZN_S_COMPLETE
Successful
completion.
v
AZN_S_API_UNINITIALIZED
This
function
has
been
called
before
azn_initialize().
v
AZN_S_INVALID_CREDS_HDL
Handle
passed
as
cred1
or
cred
2
is
invalid.
v
AZN_S_FAILURE
An
error
or
failure
has
occurred.
Use
azn_error_minor()
to
derive
specific
minor
error
codes
from
the
returned
status
code.
The
minor
error
code
ivacl_s_unauthorized
is
returned
when
the
caller
is
not
authorized
to
use
this
function.
Authorization
might
fail
because
the
caller
does
not
belong
to
the
correct
group
for
the
authorization
API
mode
(remote
or
local),
or
because
of
issues
specific
to
the
authentication
mechanism.
Appendix
A.
Authorization
API
reference
177
azn_creds_for_subject()
Returns
a
pointer
to
a
handle
to
a
credentials
chain.
The
handle
is
used
to
extract
an
individual
credentials
chain
from
a
longer
chain
containing
the
combined
credentials
chains
of
several
subjects.
Syntax
azn_status_t
azn_creds_for_subject(
const
azn_creds_h_t
creds,
const
unsigned
int
subject_index,
azn_creds_h_t
*new_creds);
Parameters
Input
creds
Handle
to
a
credentials
structure
representing
the
combined
credentials
chain
of
several
subjects.
The
combined
credentials
chain
contains
a
list
of
1
or
more
individual
credentials
chains.
When
this
function
returns,
the
structure
referred
to
by
creds
is
unchanged.
The
credentials
handle
should
be
a
handle
for
an
existing,
non-empty
credentials
chain
which
contains
valid
data.
subject_index
Index
of
the
requested
individual
credentials
chain
within
the
combined
credentials
chain.
The
index
of
the
first
credentials
chain
in
the
combined
credentials
chain,
which
should
be
that
of
the
initiator,
is
zero
(0).
Output
new_creds
Pointer
to
the
handle
to
the
new
credentials
structure
that
is
returned.
Description
This
function
returns
a
handle,
new_creds,
to
a
credentials
chain
for
the
individual
credential
at
index
subject_index
within
the
credentials
chain
creds.The
chain
creds
contains
the
combined
credentials
of
several
subjects.
This
function
does
not
modify
the
input
handle
creds
and
the
credentials
chain
to
which
it
refers.
Later
changes
to
this
structure,
including
the
release
of
its
storage,
have
no
effect
on
new_creds.
Combined
credentials
chains
are
created
by
azn_creds_combine().
The
first
credential
chain
in
a
combined
credentials
chain
is
that
of
the
initiator,
and
its
index
is
zero
(0).
Callers
can
retrieve
the
credentials
of
the
initiator
by
passing
the
constant
AZN_C_INITIATOR_INDEX
as
the
value
of
subject_index.
Note:
This
call
uses
the
new
credential
handle
new_creds.
When
you
declare
a
new
credential
handle,
always
initialize
it
to
AZN_C_INVALID_HANDLE
before
using
it.
When
new_creds
is
no
longer
required,
use
azn_creds_delete()
to
release
its
storage.
178
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
Use
azn_creds_num_of_subjects()
to
determine
the
total
number
of
credentials
chains
in
a
combined
credentials
chain.
Return
Values
If
successful,
the
function
will
returns
AZN_S_COMPLETE.
If
the
returned
status
code
is
not
equal
to
AZN_S_COMPLETE,
the
major
error
codes
will
be
derived
from
the
returned
status
code
with
azn_error_major().
v
AZN_S_COMPLETE
Successful
completion.
v
AZN_S_API_UNINITIALIZED
This
function
has
been
called
before
azn_initialize().
v
AZN_S_INVALID_CREDS_HDL
The
credentials
handle
supplied
as
creds
is
invalid.
v
AZN_S_INVALID_NEW_CREDS_HDL
The
pointer
to
the
new
credentials
handle
supplied
as
new_creds
is
invalid.
v
AZN_S_INVALID_SUBJECT_INDEX
The
supplied
index
is
invalid.
v
AZN_S_UNIMPLEMENTED_FUNCTION
This
function
is
not
supported
by
the
implementation.
v
AZN_S_FAILURE
An
error
or
failure
has
occurred.
Use
azn_error_minor()
to
derive
specific
minor
error
codes
from
the
returned
status
code.
The
minor
error
code
ivacl_s_unauthorized
is
returned
when
the
caller
is
not
authorized
to
use
this
function.
Authorization
might
fail
because
the
caller
does
not
belong
to
the
correct
group
for
the
authorization
API
mode
(remote
or
local),
or
because
of
issues
specific
to
the
authentication
mechanism.
See
pdbaclmsg.h
for
a
complete
list
of
minor
error
codes
that
describe
access
control
problems.
Appendix
A.
Authorization
API
reference
179
azn_creds_get_attr_value_string()
Obtains
the
string
value
of
the
specified
attribute
in
the
specified
credential
Syntax
azn_status_t
azn_creds_get_attr_value_string(
const
azn_creds_h_t
creds,
const
unsigned
int
subject_index,
const
azn_string_t
attr_name,
azn_string_t
*attr_value
);
Parameters
Input
creds
Handle
to
a
credential
list.
The
credentials
handle
should
be
a
handle
for
an
existing,
non-empty
credentials
chain
which
contains
valid
data.
subject_index
The
index
of
the
specified
credential
with
the
credential
chain
for
which
the
attribute
value
is
to
be
retrieved.
attr_name
The
attribute
name.
Output
attr_value
Pointer
to
an
azn_string_t
variable
that
will
contain
the
address
of
the
attribute
string
value
upon
successful
completion
of
the
routine.
Description
This
function
retrieves
attribute
values
from
a
user
credential.
This
function
accesses
the
attribute
list
of
the
specified
credential
directly
and
gets
the
string
value
of
the
specified
attribute
from
it.
When
attr_value
is
no
longer
needed,
call
azn_release_string()
to
release
its
storage.
Return
Values
When
successful,
the
function
returns
AZN_S_COMPLETE.
When
the
returned
status
code
is
not
equal
to
AZN_S_COMPLETE,
the
major
error
codes
will
be
derived
from
the
returned
status
code
with
azn_error_major().
v
AZN_S_INVALID_STRING_REF
The
specified
attribute
name
is
invalid.
v
AZN_S_INVALID_CREDS_HDL
The
specified
credentials
handle
is
invalid.
v
AZN_S_INVALID_SUBJECT_INDEX
The
index
into
the
credentials
chain
is
invalid.
180
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
azn_creds_get_attrlist_for_subject()
Returns
information
from
a
specified
subject’s
credentials
chain
within
a
specified
(and
possibly
combined)
credentials
chain.
Syntax
azn_status_t
azn_creds_get_attrlist_for_subject
(
const
azn_creds_h_t
creds,
const
unsigned
int
subject_index,
azn_attrlist_h_t
*creds_attrlist
);
Parameters
Input
creds
Handle
to
a
credentials
chain.
The
credentials
handle
should
be
a
handle
for
an
existing,
non-empty
credentials
chain
which
contains
valid
data.
subject_index
Index
of
the
requested
individual
subject
within
the
credentials
chain.
The
index
of
the
first
credential
in
the
combined
credentials
chain,
which
should
be
that
of
the
initiator,
is
zero
(0).
Output
creds_attrlist
Pointer
to
the
handle
of
an
attribute
list
that
holds
the
specified
subject’s
attribute
information
on
return.
The
attribute
list
handle
pointer
passed
as
the
creds_attrlist
parameter
can
point
to
one
of
the
following:
v
An
attribute
list
handle
that
has
been
initialized
to
AZN_C_INVALID_HANDLE.
v
An
attribute
list
handle
for
a
new,
empty
attribute
list,
which
has
been
initialized
by
a
call
to
azn_attrlist_create().
v
An
attribute
list
handle
for
an
existing,
non-empty
attribute
list
which
contains
valid
data.
In
this
case,
attribute
list
data
is
appended
to
the
existing
attribute
list.
Description
This
function
returns
an
attribute
list
containing
privilege
attribute
information
from
the
credentials
chain
for
the
individual
subject
at
index
subject_index
within
a
credentials
chain
creds.
Combined
credentials
chains
are
created
by
azn_creds_combine().
The
first
credential
chain
in
a
combined
credentials
chain
is
that
of
the
initiator,
and
its
index
will
be
zero
(0).
Callers
can
retrieve
the
attributes
of
the
credentials
chain
of
the
initiator
by
passing
the
constant
AZN_C_INITIATOR_INDEX
as
the
value
of
subject_index.
This
function
does
not
modify
the
input
handle
creds
and
the
credentials
chain
to
which
it
refers.
Later
changes
to
creds,
including
releasing
its
storage,
will
have
no
effect
on
creds_attrlist.
Appendix
A.
Authorization
API
reference
181
Use
the
azn_attrlist*
functions
to
retrieve
individual
attribute
values
from
creds_attrlist.
See
ogauthzn.h
for
a
list
of
attribute
names.
The
audit
identifier
associated
with
the
specified
credentials
structure
is
present
in
the
returned
attribute
list.
It
is
the
value
attribute
of
an
entry
whose
name
attribute
is
AZN_C_AUDIT_ID.
Note:
This
function
uses
a
new
credentials
handle,
creds.
When
declaring
a
new
credential
handle
or
attribute
list
handle
always
initialize
it
to
AZN_C_INVALID_HANDLE
before
using
it.
When
creds_attrlist
is
no
longer
required,
call
azn_attrlist_delete()
to
release
its
storage.
Return
Values
If
successful,
the
function
will
return
AZN_S_COMPLETE.
If
the
returned
status
code
is
not
equal
to
AZN_S_COMPLETE,
the
major
error
codes
will
be
derived
from
the
returned
status
code
with
azn_error_major().
v
AZN_S_COMPLETE
Successful
completion.
v
AZN_S_API_UNINITIALIZED
This
function
has
been
called
before
azn_initialize().
v
AZN_S_INVALID_CREDS_HDL
The
credentials
handle
supplied
is
invalid.
v
AZN_S_INVALID_SUBJECT_INDEX
The
supplied
index
is
invalid.
v
AZN_S_INVALID_ATTRLIST_HDL
The
attribute
list
handle
supplied
is
invalid.
v
AZN_S_UNIMPLEMENTED_FUNCTION
This
function
is
not
supported
by
the
implementation.
v
AZN_S_FAILURE
An
error
or
failure
has
occurred.
Use
azn_error_minor()
to
derive
specific
minor
error
codes
from
the
returned
status
code.
The
minor
error
code
ivacl_s_unauthorized
is
returned
when
the
caller
is
not
authorized
to
use
this
function.
Authorization
might
fail
because
the
caller
does
not
belong
to
the
correct
group
for
the
authorization
API
mode
(remote
or
local),
or
because
of
issues
specific
to
the
authentication
mechanism.
See
pdbaclmsg.h
for
a
complete
list
of
minor
error
codes
that
describe
access
control
problems.
182
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
azn_creds_get_pac()
Creates
and
returns
a
privilege
attribute
certificate
(PAC)
by
invoking
a
specified
PAC
service
on
the
supplied
credentials
chain.
Syntax
azn_status_t
azn_creds_get_pac(
const
azn_creds_h_t
creds,
const
azn_string_t
pac_svc_id,
azn_buffer_t
*pac
);
Parameters
Input
creds
Handle
to
the
credentials
chain
whose
information
is
used
to
build
the
PAC.
The
credentials
handle
should
be
a
handle
for
an
existing,
non-empty
credentials
chain
which
contains
valid
data.
pac_svc_id
Identification
(id)
of
the
PAC
service
that
produces
the
PAC.
Output
pac
Pointer
to
an
azn_buffer_t
variable
that
will
contain
the
address
of
the
buffer
data
upon
successful
completion
of
the
routine.
Description
This
function
uses
the
PAC
service
whose
identification
is
supplied
as
pac_svc_id
to
build
a
new
PAC.
The
PAC
service
uses
the
information
in
the
supplied
credentials
chain
to
build
the
PAC.
Different
PAC
services
might
produce
PACs
with
different
formats.
Some
PAC
services
can
cryptographically
protect
or
sign
the
PACs
they
produce.
When
pac_svc_id
is
NULL,
the
default
PAC
service
returns
an
architecture-independent
and
network-independent
encoding
of
the
specified
credentials
chain.
This
PAC
can
be
safely
transmitted.
The
receiver
of
the
PAC
can
use
azn_pac_get_creds()
to
decode
the
PAC
and
obtain
a
valid
copy
of
the
original
credentials
chain.
This
function
takes
as
an
input
parameter
a
handle
to
an
existing
credentials
structure,
and
returns
a
pointer
to
the
output
PAC
in
an
authorization
API
buffer.
This
function
does
not
modify
the
input
handle
creds
and
the
credentials
chain
to
which
it
refers.
Later
changes
to
creds,
including
releasing
its
storage,
will
have
no
effect
on
pac.
When
pac
is
no
longer
required,
call
azn_release_buffer()
to
release
its
storage.
Return
Values
If
successful,
the
function
will
return
AZN_S_COMPLETE.
Appendix
A.
Authorization
API
reference
183
If
the
returned
status
code
is
not
equal
to
AZN_S_COMPLETE,
the
major
error
codes
will
be
derived
from
the
returned
status
code
with
azn_error_major().
v
AZN_S_COMPLETE
Successful
completion.
v
AZN_S_API_UNINITIALIZED
This
function
has
been
called
before
azn_initialize().
v
AZN_S_INVALID_CREDS_HDL
The
credentials
handle
supplied
is
invalid.
v
AZN_S_INVALID_PAC_SVC
The
privilege
attribute
certificate
service
identifier
is
invalid.
v
AZN_S_SVC_SERVICE_NOT_FOUND
The
service
with
the
specified
identification
number
was
not
found
in
the
list
of
configured
services.
v
AZN_S_SVC_AUTHORIZATION_FAILED
The
caller
is
not
authorized
to
make
calls
to
the
service.
The
minor
error
code
contains
additional
information
about
the
reason
for
the
failure.
v
AZN_S_SVC_DISPATCHER_FAILURE
The
service
dispatcher
failed.
This
can
be
caused
by
incorrect
initialization
of
the
authorization
API.
v
AZN_S_UNIMPLEMENTED_FUNCTION
This
function
is
not
supported
by
the
implementation.
v
AZN_S_FAILURE
An
error
or
failure
has
occurred.
Use
azn_error_minor()
to
derive
specific
minor
error
codes
from
the
returned
status
code.
The
minor
error
code
ivacl_s_unauthorized
is
returned
when
the
caller
is
not
authorized
to
use
this
function.
Authorization
might
fail
because
the
caller
does
not
belong
to
the
correct
group
for
the
authorization
API
mode
(remote
or
local),
or
because
of
issues
specific
to
the
authentication
mechanism.
See
pdbaclmsg.h
for
a
complete
list
of
minor
error
codes
that
describe
access
control
problems.
184
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
azn_creds_modify()
Modifies
an
existing
credentials
chain
and
returns
a
pointer
to
the
handle
to
a
new
credentials
chain
containing
the
modifications.
Syntax
azn_status_t
azn_creds_modify(
const
azn_creds_h_t
creds,
const
azn_string_t
mod_svc_id,
const
azn_attrlist_h_t
mod_info,
azn_creds_h_t
*new_creds
);
Parameters
Input
creds
Handle
to
the
authorization
credentials
chain
to
be
modified.
The
credentials
handle
should
be
a
handle
for
an
existing,
non-empty
credentials
chain
which
contains
valid
data.
mod_svc_id
Identification
(id)
of
the
credential
modification
service.
mod_info
Attribute
list
containing
modification
service-specific
or
application-specific
data
that
describes
the
desired
credential
modifications.
Attribute
lists
that
are
empty
are
inserted
into
the
credentials.
The
attribute
list
handle
can
be
one
of
the
following:
v
An
attribute
list
handle
that
has
been
initialized
to
AZN_C_INVALID_HANDLE.
v
An
attribute
list
handle
for
a
new,
empty
attribute
list,
which
has
been
initialized
by
a
call
to
azn_attrlist_create().
v
An
attribute
list
handle
for
an
existing,
non-empty
attribute
list
which
contains
valid
data.
In
this
case,
attribute
list
data
is
appended
to
the
existing
attribute
list.
Output
new_creds
Pointer
to
a
handle
to
a
credentials
chain
that
contains
the
modified
credentials
chain
upon
return.
The
credentials
handle
pointer
passed
as
the
new_creds
parameter
can
point
to
one
of
the
following:
v
A
credentials
handle
that
has
been
initialized
to
AZN_C_INVALID_HANDLE.
Note
that
this
will
result
in
an
empty
output
credential.
v
A
credentials
handle
for
a
new,
empty
credential,
which
has
been
initialized
by
a
call
to
azn_creds_create().
Note
that
this
will
result
in
an
empty
output
credential.
Description
This
function
uses
the
specified
modification
service
mod_svc_id,
and
optionally
an
attribute
list
mod_info
which
contains
modification
information
provided
by
the
caller,
to
modify
a
copy
of
the
supplied
credentials
chain
creds.
The
function
Appendix
A.
Authorization
API
reference
185
returns
a
pointer
to
a
handle
to
a
new
credentials
chain
new_creds
containing
the
requested
modifications.
The
supplied
credentials
chain
is
unchanged.
When
mod_svc_id
is
NULL,
this
function
modifies
an
existing
credential
chain
creds
by
adding
the
attribute
list
mod_info
to
the
credentials
chain,
and
returning
the
modified
credential
in
new_creds.
The
following
credential
attributes
are
considered
readonly
and
can
not
be
modified
by
azn_creds_modify().
If
any
of
these
attributes
are
specified
in
the
mod_info
input
attribute
list,
they
are
ignored:
v
azn_cred_principal_uuid
v
azn_cred_principal_name
v
azn_cred_principal_domain
v
azn_cred_version
v
azn_cred_mech_id
v
azn_cred_group_uuids
v
azn_cred_group_names
v
azn_cred_authzn_id
v
azn_cred_ldap_dn
If
the
input
creds
handle
references
a
combined
credentials
chain
with
more
than
one
element,
only
the
first
element
will
be
modified.
This
is
the
default
behavior
when
mod_svc_id
is
NULL.
In
this
case,
the
output
chain
consists
of
the
modified
first
element
followed
by
unmodified
copies
of
the
remaining
elements
in
the
input
combined
credentials
chains.
The
elements
in
the
output
credentials
chain
are
kept
in
the
same
order
as
their
counterparts
in
the
input
credentials
chain.
Note:
This
function
uses
a
new
credential
handle,
new_creds.
When
declaring
a
new
credential
handle,
always
initialize
it
to
AZN_C_INVALID_HANDLE
before
using
it.
When
new_creds
is
no
longer
required,
call
azn_creds_delete()
to
release
its
storage.
Return
Values
If
successful,
the
function
will
return
AZN_S_COMPLETE.
If
the
returned
status
code
is
not
equal
to
AZN_S_COMPLETE,
the
major
error
codes
will
be
derived
from
the
returned
status
code
with
azn_error_major().
v
AZN_S_COMPLETE
Successful
completion.
v
AZN_S_API_UNINITIALIZED
This
function
has
been
called
before
azn_initialize().
v
AZN_S_INVALID_CREDS_HDL
The
credentials
handle
supplied
is
invalid.
v
AZN_S_INVALID_MOD_FUNCTION
The
supplied
modification
service
identifier
is
invalid.
v
AZN_S_INVALID_ATTRLIST_HDL
The
attribute
list
handle
is
invalid.
v
AZN_S_INVALID_NEW_CREDS_HDL
186
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
The
pointer
to
the
new
credentials
handle
that
references
the
new
output
credentials
chain
is
invalid.
v
AZN_S_UNIMPLEMENTED_FUNCTION
This
function
is
not
supported
by
the
implementation.
v
AZN_S_SVC_SERVICE_NOT_FOUND
The
service
with
the
specified
identification
number
was
not
found
in
the
list
of
configured
services.
v
AZN_S_SVC_AUTHORIZATION_FAILED
The
caller
is
not
authorized
to
make
calls
to
the
service.
The
minor
error
code
contains
additional
information
about
the
reason
for
the
failure.
v
AZN_S_SVC_DISPATCHER_FAILURE
The
service
dispatcher
failed.
This
can
be
caused
by
incorrect
initialization
of
the
authorization
API.
v
AZN_S_FAILURE
An
error
or
failure
has
occurred.
Use
azn_error_minor()
to
derive
specific
minor
error
codes
from
the
returned
status
code.
The
minor
error
code
ivacl_s_unauthorized
is
returned
when
the
caller
is
not
authorized
to
use
this
function.
Authorization
might
fail
because
the
caller
does
not
belong
to
the
correct
group
for
the
authorization
API
mode
(remote
or
local),
or
because
of
issues
specific
to
the
authentication
mechanism.
See
pdbaclmsg.h
for
a
complete
list
of
minor
error
codes
that
describe
access
control
problems.
Appendix
A.
Authorization
API
reference
187
azn_creds_num_of_subjects()
Returns
the
number
of
individual
subjects’
credentials
chains
in
a
combined
credentials
chain.
Syntax
azn_status_t
azn_creds_num_of_subjects(
const
azn_creds_h_t
creds,
unsigned
int
*num_of_subjects
);
Parameters
Input
creds
Handle
to
a
credentials
chain.
The
credentials
handle
should
be
a
handle
for
an
existing,
non-empty
credentials
chain
which
contains
valid
data.
Output
num_of_subjects
Pointer
to
an
unsigned
int
variable
that
will
contain
the
number
of
individual
credentials
within
the
credential
chain
upon
successful
completion
of
the
routine.
Note
that
if
the
credentials
handle
passed
in
as
an
input
parameter
is
invalid
(AZN_C_INVALID_HANDLE)
or
points
to
an
empty
credentials
list,
an
error
will
be
generated
and
num_of_subjects
will
be
set
to
0.
Description
This
function
returns
the
number
of
individual
subjects,
num_of_subjects,
whose
credentials
appear
in
a
credentials
chain
creds.
Combined
credentials
chains
are
created
by
the
azn_creds_combine()
function.
Return
Values
If
successful,
the
function
will
return
AZN_S_COMPLETE.
If
the
returned
status
code
is
not
equal
to
AZN_S_COMPLETE,
the
major
error
codes
will
be
derived
from
the
returned
status
code
with
azn_error_major().
v
AZN_S_COMPLETE
Successful
completion.
v
AZN_S_API_UNINITIALIZED
This
function
has
been
called
before
azn_initialize().
v
AZN_S_INVALID_CREDS_HDL
The
credentials
handle
supplied
is
invalid.
v
AZN_S_ATTR_INVALID_INTEGER_REF
The
integer
reference
is
invalid.
v
AZN_S_UNIMPLEMENTED_FUNCTION
This
function
is
not
supported
by
the
implementation.
v
AZN_S_FAILURE
188
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
An
error
or
failure
has
occurred.
Use
azn_error_minor()
to
derive
specific
minor
error
codes
from
the
returned
status
code.
The
minor
error
code
ivacl_s_unauthorized
is
returned
when
the
caller
is
not
authorized
to
use
this
function.
Authorization
might
fail
because
the
caller
does
not
belong
to
the
correct
group
for
the
authorization
API
mode
(remote
or
local),
or
because
of
issues
specific
to
the
authentication
mechanism.
See
pdbaclmsg.h
for
a
complete
list
of
minor
error
codes
that
describe
access
control
problems.
Appendix
A.
Authorization
API
reference
189
azn_creds_set_attr_value_string()
Sets
the
value
of
the
specified
attribute
in
the
specified
user
credential.
Syntax
azn_status_t
azn_creds_set_attr_value_string
const
azn_creds_h_t
creds,
const
unsigned
int
subject_index,
const
azn_string_t
attr_name,
const
azn_string_t
attr_value
);
Parameters
Input
creds
Handle
to
the
credentials
chain.
The
credentials
handle
should
be
a
handle
for
an
existing,
non-empty
credentials
chain
which
contains
valid
data.
subject_index
The
index
of
the
specified
credential
within
the
credential
chain.
attr_name
The
name
of
the
attribute
to
be
modified.
attr_value
The
string
value
to
be
assigned
to
the
attribute.
Description
Use
this
function
to
modify
the
attribute
values
in
a
user
credential.
This
function
edits
the
attribute
list
of
the
specified
credential
and
sets
the
specified
attribute
to
the
specified
string
value.
The
following
credential
attributes
are
considered
readonly
and
must
not
be
modified
using
this
API.
v
azn_cred_principal_uuid
v
azn_cred_principal_name
v
azn_cred_principal_domain
v
azn_cred_version
v
azn_cred_mech_id
v
azn_cred_group_uuids
v
azn_cred_group_names
v
azn_cred_authzn_id
v
azn_cred_ldap_dn
Return
Values
When
successful,
the
function
returns
AZN_S_COMPLETE.
When
the
returned
status
code
is
not
equal
to
AZN_S_COMPLETE,
the
major
error
codes
will
be
derived
from
the
returned
status
code
with
azn_error_major().
v
AZN_S_INVALID_STRING_VALUE
The
specified
string
value
is
invalid.
190
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
v
AZN_S_INVALID_CREDS_HDL
The
specified
credentials
handle
is
invalid.
v
AZN_S_INVALID_SUBJECT_INDEX
The
index
into
the
credentials
chain
is
invalid.
v
AZN_S_ATTR_READONLY
Modification
of
the
attribute
is
prohibited.
Appendix
A.
Authorization
API
reference
191
azn_decision_access_allowed()
Makes
an
access
control
decision.
Syntax
azn_status_t
azn_decision_access_allowed(
const
azn_creds_h_t
creds,
const
azn_string_t
protected_resource,
const
azn_string_t
operation,
const
int
*permission
);
Parameters
Input
creds
Handle
to
the
initiator’s
credential
chain.
The
credentials
handle
should
be
a
handle
for
an
existing,
non-empty
credentials
chain
which
contains
valid
data.
protected_resource
Name
of
the
request’s
target.
operation
Name
of
the
requested
operation.
Output
permission
Pointer
to
an
integer
variable
that
will
contain
the
appropriate
permission
code
upon
successful
completion
of
the
routine.
When
the
returned
status
value
is
AZN_S_COMPLETE,
the
returned
permission
is
either
AZN_C_PERMITTED
or
AZN_C_NOT_PERMITTED.
When
the
returned
status
code
is
not
AZN_S_COMPLETE,
the
returned
permission
is
set
to
AZN_C_NOT_PERMITTED.
If
additional
information
beyond
a
boolean
result
is
needed,
use
azn_decision_access_allowed_ext().
Description
This
function
decides
whether
the
initiator
specified
by
credentials
creds
is
authorized
to
perform
the
operation
operation
on
the
target
protected_resource.
The
decision
is
returned
through
permission.
azn_decision_access_allowed()
is
semantically
equivalent
to
azn_decision_access_allowed_ext()
when
app_context=NULL
and
permission_info=NULL.
Return
Values
If
successful,
the
function
will
return
AZN_S_COMPLETE.
If
the
returned
status
code
is
not
equal
to
AZN_S_COMPLETE,
the
major
error
codes
will
be
derived
from
the
returned
status
code
with
azn_error_major().
v
AZN_S_COMPLETE
192
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
Successful
completion.
v
AZN_S_API_UNINITIALIZED
This
function
has
been
called
before
azn_initialize().
v
AZN_S_INVALID_CREDS_HDL
The
credentials
handle
supplied
is
invalid.
v
AZN_S_INVALID_PROTECTED_RESOURCE
The
target
name
is
invalid.
v
AZN_S_INVALID_OPERATION
The
operation
has
no
meaning
for
the
specified
target.
v
AZN_S_INVALID_PERMISSION_REF
The
integer
reference
to
return
the
permission
is
invalid.
v
AZN_S_FAILURE
An
error
or
failure
has
occurred.
Use
azn_error_minor()
to
derive
specific
minor
error
codes
from
the
returned
status
code.
The
minor
error
code
ivacl_s_unauthorized
is
returned
when
the
caller
is
not
authorized
to
use
this
function.
Authorization
might
fail
because
the
caller
does
not
belong
to
the
correct
group
for
the
authorization
API
mode
(remote
or
local),
or
because
of
issues
specific
to
the
authentication
mechanism.
See
pdbaclmsg.h
for
a
complete
list
of
minor
error
codes
that
describe
access
control
problems.
Appendix
A.
Authorization
API
reference
193
azn_decision_access_allowed_ext()
Makes
an
access
control
decision
using
application-specific
context
information;
returns
information
about
why
the
decision
was
made.
Syntax
azn_status_t
azn_decision_access_allowed_ext(
const
azn_creds_h_t
creds,
const
azn_string_t
protected_resource,
const
azn_string_t
operation,
const
azn_attrlist_h_t
app_context,
int
*permission,
azn_attrlist_h_t
*permission_info
);
Parameters
Input
creds
Handle
to
the
initiator’s
credentials
chain.
The
credentials
handle
should
be
a
handle
for
an
existing,
non-empty
credentials
chain
which
contains
valid
data.
protected_resource
Name
of
the
target
of
the
request.
operation
Name
of
the
requested
operation.
app_context
Attribute
list
containing
application-specific
context
access
control
information.
A
NULL
value
indicates
there
is
no
context
access
control
information.
The
attribute
list
handle
can
be
one
of
the
following:
v
An
attribute
list
handle
that
has
been
initialized
to
AZN_C_INVALID_HANDLE.
v
An
attribute
list
handle
for
a
new,
empty
attribute
list,
which
has
been
initialized
by
a
call
to
azn_attrlist_create().
v
An
attribute
list
handle
for
an
existing,
non-empty
attribute
list
which
contains
valid
data.
In
this
case,
attribute
list
data
is
appended
to
the
existing
attribute
list.
permission_info
Pointer
to
an
attribute
list
through
which
the
implementation
might
return
implementation-specific
information
about
the
decision.
If
a
NULL
value
is
passed
as
input,
then
no
information
will
be
returned.
Output
permission
Pointer
to
an
integer
variable
that
will
contain
the
appropriate
permission
code
upon
successful
completion
of
the
routine.
When
the
returned
status
value
is
AZN_S_COMPLETE,
the
returned
permission
is
either
AZN_C_PERMITTED
or
AZN_C_NOT_PERMITTED.
When
the
returned
status
code
is
not
AZN_S_COMPLETE,
the
returned
permission
is
set
to
AZN_C_NOT_PERMITTED.
194
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
permission_info
Pointer
to
an
attribute
list
through
which
the
implementation
can
return
implementation-specific
information
about
the
decision.
When
a
NULL
pointer
is
passed
as
input,
no
information
is
returned.
The
information
contained
in
the
attribute
list
is
added
to
the
list
when
the
attribute
list
handle
is
one
of
the
following:
v
An
attribute
list
handle
for
a
new,
empty
attribute
list,
which
has
been
initialized
by
a
call
to
azn_attrlist_create().
v
An
attribute
list
handle
for
an
existing,
non-empty
attribute
list
which
contains
valid
data.
The
output
parameter
permission_info
can
be
used
to
return
implementation-specific
qualifiers
to
AZN_C_NOT_PERMITTED.
The
qualifiers
can
be
used
to
assist
the
calling
application
or
the
initiator
in
formulating
a
request
which
will
be
authorized.
Examples
of
such
qualifiers
might
include:
“not
permitted
yet,”
“requires
additional
privilege
attributes,”
or
“permissible
with
restrictions.”
For
more
information,
see
“Enabling
the
return
of
permission
information”
on
page
47.
Description
This
function
decides
whether
the
initiator
specified
by
the
credentials
chain
creds
is
authorized
to
perform
the
operation
operation
on
the
target
protected_resource.
Optionally,
callers
can
supply
application-specific
context
access
control
information
using
the
app_context
argument.
The
decision
is
returned
through
permission.
Optionally,
the
implementation
can
return
implementation-specific
information
about
the
decision
through
permission_info.
For
example,
the
information
can
indicate
which
rule
was
responsible
for
granting
or
denying
access.
Note:
This
function
uses
a
new
attribute
list
handle,
permission_info.
When
declaring
a
new
attribute
list
handle,
always
initialize
it
to
AZN_C_INVALID_HANDLE
before
using
it.
Return
Values
If
successful,
the
function
will
return
AZN_S_COMPLETE.
If
the
returned
status
code
is
not
equal
to
AZN_S_COMPLETE,
the
major
error
codes
will
be
derived
from
the
returned
status
code
with
azn_error_major().
v
AZN_S_COMPLETE
Successful
completion.
v
AZN_S_API_UNINITIALIZED
This
function
has
been
called
before
azn_initialize().
v
AZN_S_INVALID_CREDS_HDL
The
credentials
handle
supplied
is
invalid.
v
AZN_S_INVALID_PROTECTED_RESOURCE
The
target
name
is
invalid.
v
AZN_S_INVALID_OPERATION
The
operation
has
no
meaning
for
the
specified
target.
Appendix
A.
Authorization
API
reference
195
v
AZN_S_INVALID_PERMISSION_REF
The
integer
reference
to
return
the
permission
is
invalid.
v
AZN_S_INVALID_APP_CONTEXT_HDL
The
attribute
list
handle
for
the
context
access
control
information
(ACI)
is
invalid.
v
AZN_S_INVALID_ATTRLIST_HDL
The
attribute
list
handle
for
the
returned
permission
information
is
invalid.
v
AZN_S_UNIMPLEMENTED_FUNCTION
This
function
is
not
supported
by
the
implementation.
v
AZN_S_FAILURE
An
error
or
failure
has
occurred.
Use
azn_error_minor()
to
derive
specific
minor
error
codes
from
the
returned
status
code.
The
minor
error
code
ivacl_s_unauthorized
is
returned
when
the
caller
is
not
authorized
to
use
this
function.
Authorization
might
fail
because
the
caller
does
not
belong
to
the
correct
group
for
the
authorization
API
mode
(remote
or
local),
or
because
of
issues
specific
to
the
authentication
mechanism.
See
pdbaclmsg.h
for
a
complete
list
of
minor
error
codes
that
describe
access
control
problems.
196
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
azn_entitlement_get_entitlements()
Returns
entitlements
of
an
initiator.
Syntax
azn_status_t
azn_entitlement_get_entitlements(
const
azn_creds_h_t
creds,
const
azn_string_t
entitlements_svc_id,
const
azn_attrlist_h_t
app_context,
azn_attrlist_h_t
*entitlements
);
Parameters
Input
creds
Handle
to
the
credentials
of
the
subject
whose
entitlements
are
to
be
returned.
The
credentials
handle
should
be
a
handle
for
an
existing,
non-empty
credentials
chain
which
contains
valid
data.
entitlements_svc_id
The
id
of
the
entitlement
service
to
be
used
app_context
Handle
to
an
attribute
list
containing
application-specific
or
entitlements-service-specific
context
information.
A
NULL
value
should
be
used
if
no
application
state
is
passed.
The
attribute
list
handle
can
be
one
of
the
following:
v
An
attribute
list
handle
that
has
been
initialized
to
AZN_C_INVALID_HANDLE.
v
An
attribute
list
handle
for
a
new,
empty
attribute
list,
which
has
been
initialized
by
a
call
to
azn_attrlist_create().
v
An
attribute
list
handle
for
an
existing,
non-empty
attribute
list
which
contains
valid
data.
In
this
case,
attribute
list
data
is
appended
to
the
existing
attribute
list.
Output
entitlements
Pointer
to
a
attribute
list
handle
variable
which
will
hold
the
entitlement
information
on
return.
The
attribute
list
handle
pointer
passed
as
the
entitlements
parameter
can
point
to
one
of
the
following:
v
A
attribute
list
handle
that
has
been
initialized
to
AZN_C_INVALID_HANDLE.
v
A
attribute
list
handle
for
a
new,
empty
attribute
list,
which
has
been
initialized
by
a
call
to
azn_attrlist_create().
v
An
attribute
list
handle
for
an
existing,
non-empty
attribute
list
which
contains
valid
data.
Description
This
uses
an
entitlement
service
identified
by
entitlements_svc_id
to
return
the
entitlements
of
an
initiator
identified
by
credentials
creds.
The
calling
application
Appendix
A.
Authorization
API
reference
197
may
pass
application-specific
or
entitlements-service-specific
context
data
using
an
attribute
list
app_context.
The
entitlements
are
returned
using
the
attribute
list
entitlements.
Note:
This
function
declares
a
new
attribute
list
handle,
entitlements.
When
declaring
a
new
attribute
list
handle,
always
initialize
it
to
AZN_C_INVALID_HANDLE
before
using
it.
The
constants
AZN_C_REQUEST_TIME,
AZN_C_AUTHN_QUALITY,
AZN_C_REQUESTER_LOC,
and
AZN_C_REQUEST_ROUTE_QOP,
may
be
used
as
name
attribute
of
entries
in
the
app_context
attribute
list
to
communicate
common
types
of
context
information.
Return
Values
If
successful,
the
function
returns
AZN_S_COMPLETE.
If
the
returned
status
code
is
not
equal
to
AZN_S_COMPLETE,
the
major
error
codes
can
be
derived
from
the
returned
status
code
with
azn_error_major().
v
AZN_S_COMPLETE
Successful
completion.
v
AZN_S_INVALID_CREDS_HDL
The
creds
handle
supplied
is
invalid.
v
AZN_S_INVALID_ENTITLEMENT_SVC
The
entitlement
service
identifier
is
invalid.
v
AZN_S_INVALID_APP_CONTEXT_HDL
The
attribute
list
handle
for
the
application
context
is
invalid.
v
AZN_S_INVALID_ENTITLEMENTS_HDL
The
attribute
list
handle
for
the
entitlements
is
invalid.
v
AZN_S_AUTHORIZATION_FAILURE
The
caller
does
not
possess
the
authority
required
to
invoke
this
function.
v
AZN_S_UNIMPLEMENTED_FUNCTION
This
function
is
not
supported
by
the
implementation.
v
AZN_S_FAILURE
An
implementation
specific
error
or
failure
has
occurred.
Implementation
specific
minor
error
codes
can
be
derived
from
the
returned
status
code
with
azn_error_minor().
198
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
azn_error_get_string()
Returns
the
Policy
Director
Serviceability
message
string
for
the
specified
data
structure
of
type
azn_status_t.
Syntax
azn_status_t
azn_error_get_string(
const
azn_status_t
aznstatus,
azn_string_t
*error_string,
);
Parameters
Input
aznstatus
Authorization
API
status
Output
error_string
Pointer
to
an
azn_string_t
variable
that
will
contain
the
error
string
upon
successful
completion
of
the
routine.
Description
This
interface
returns
the
Policy
Director
Serviceability
(PDSVC)
message
string
for
the
authorization
API
status
that
is
passed
in.
It
returns
the
message
string
for
the
minor
error
code
if
one
exists.
When
a
minor
error
code
does
not
exist,
it
returns
the
message
string
for
the
major
error
code.
Return
Values
When
successful,
the
function
returns
AZN_S_COMPLETE.
When
unsuccessful,
the
function
returns
one
of
the
following
major
error
codes:
v
AZN_S_INVALID_MAJOR_CODE
The
major
error
code
is
invalid.
v
AZN_S_MAJOR_CODE_MESSAGE_NOT_FOUND
There
is
no
message
in
the
message
table
for
the
major
error
code.
v
AZN_S_MINOR_CODE_MESSAGE_NOT_FOUND
The
minor
error
code
is
invalid.
Alternately,
this
error
message
can
mean
that
there
is
no
message
in
the
message
table
for
the
minor
error
code.
v
AZN_S_INVALID_STRING_REF
The
pointer
of
type
error_string
is
NULL.
Appendix
A.
Authorization
API
reference
199
azn_error_major()
Returns
the
major
error
code
that
is
associated
with
a
returned
status
code.
Syntax
unsigned
int
azn_error_major(
const
azn_status_t
status_code
);
Parameters
Input
status_code
Previously
returned
status
code
by
any
of
the
azn_*
routines.
Description
This
function
returns
the
major
error
code
associated
with
a
previously
returned
status
code.
Return
Values
Any
of
the
defined
major
error
codes,
AZN_S_*.
For
a
list
of
error
codes,
see
ogauthzn.h
and
aznutils.h.
200
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
azn_error_minor()
Returns
the
implementation-specific
minor
error
code
that
is
associated
with
a
returned
status
code.
Syntax
unsigned
int
azn_error_minor(
const
azn_status_t
status_code
);
Parameters
Input
status_code
Previously
returned
status
code
by
any
of
the
azn_*
routines.
Description
The
function
returns
the
minor
error
code
associated
with
a
previously
returned
status
code.
Return
Values
An
implementation
specific
minor
error
code
is
returned.
For
a
complete
list
of
minor
error
codes,
see
the
file
pdbaclmsg.h.
Appendix
A.
Authorization
API
reference
201
azn_error_minor_get_string()
Returns
a
string
describing
the
implementation-specific
minor
error
code.
Syntax
azn_status_t
azn_error_minor_get_string(
const
unsigned
int
minor_error
azn_string_t
*minor_error_string
);
Parameters
Input
minor_error
Minor
error
code
previously
returned
by
azn_error_minor().
Output
minor_error_string
Pointer
to
an
azn_string_t
variable
that
will
contain
the
minor
error
string
upon
successful
completion
of
the
routine.
Description
This
function
returns
a
string
that
describes
the
error
corresponding
to
a
previously
returned
minor
error
status
code.
When
minor_error_string
is
no
longer
needed,
use
azn_release_string()
to
release
its
storage.
Return
Values
If
successful,
the
function
will
return
AZN_S_COMPLETE.
If
the
returned
status
code
is
not
equal
to
AZN_S_COMPLETE,
the
major
error
codes
will
be
derived
from
the
returned
status
code
with
azn_error_major().
v
AZN_S_COMPLETE
Successful
completion.
v
AZN_S_MINOR_CODE_MESSAGE_NOT_FOUND
The
specified
minor
code
has
not
corresponding
error
message
in
the
catalog.
This
message
also
appears
when
a
minor
code
of
0
(success)
is
passed.
v
AZN_S_INVALID_STRING_REF
The
minor
error
string
is
NULL.
202
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
azn_id_get_creds()
Returns
a
handle
to
the
credentials
chain
associated
by
a
specified
authorization
authority
with
a
specified
identity.
Syntax
azn_status_t
azn_id_get_creds(
const
azn_string_t
authzn_authority,
const
azn_string_t
mechanism_id,
const
azn_buffer_t
mechanism_info,
azn_creds_h_t
*new_creds
);
Parameters
Input
authzn_authority
The
name
of
the
Tivoli
Access
Manager
secure
domain.
Use
this
value
to
specify
the
domain
when
operating
in
a
multiple-domain
environment.
The
domain
name
must
match
the
name
of
the
domain
that
was
configured
for
the
client
by
svrsslcfg.
You
can
leave
this
value
NULL.
In
this
case,
the
name
of
the
secure
domain
is
automatically
determined
from
the
value
specified
in
the
configuration
file.
mechanism_id
Authentication
mechanism
that
is
used
to
generate
the
identity
passed
through
mechanism_info.
A
NULL
input
value
selects
a
default
authentication
mechanism.
mechanism_info
Buffer
containing
initiator
access
control
information,
which
consists
of
identity
information
obtained
from
an
authentication
service.
The
authentication
service
used
to
produce
this
information
should
be
identified
using
the
mechanism_id
argument.
A
NULL
input
value
denotes
the
default
identity
for
the
selected
authentication
mechanism
from
the
environment.
Output
new_creds
Pointer
to
the
handle
of
a
new,
empty
credentials
chain
that
will
hold
the
returned
credentials.
The
credentials
handle
pointer
passed
as
the
new_creds
parameter
can
be
one
of
the
following:
v
A
credentials
handle
that
has
been
initialized
to
AZN_C_INVALID_HANDLE.
v
A
credentials
handle
for
a
new,
empty
credentials
list,
which
has
been
initialized
by
a
call
to
azn_attrlist_create().
In
this
case,
the
handle
is
updated.
v
A
credentials
handle
for
an
existing,
non-empty
credentials
list
which
contains
valid
data.
In
this
case,
the
handle
is
updated.
Appendix
A.
Authorization
API
reference
203
Description
This
function
builds
an
authorization
credentials
chain,
referenced
by
the
returned
handle
new_creds,
for
the
identity
corresponding
to
the
initiator
access
control
information
mechanism_info
produced
by
an
authentication
mechanism
mechanism_id.
Specifying
a
NULL
value
for
authzn_authority
causes
the
default
domain
to
be
used.
When
a
non-NULL
value
is
used,
it
must
match
the
name
of
the
domain
that
was
configured
for
the
client
by
svrsslcfg.
If
it
does
not
match,
the
call
will
fail
with
AZN_S_DOMAIN_CONFLICT.
Specifying
NULL
values
for
mechanism_id
and
causes
the
default
authentication
mechanism
to
be
the
installed
user
registry
in
the
Policy
Director
secure
domain.
For
more
information,
see
“Default
user
registry
information
structure”
on
page
16.
The
azn_id_get_creds()
interface
also
calls
out
to
the
list
of
configured
entitlement
services.
The
credential
is
built
from
registry
attributes
first
and
then
each
configured
entitlement
service
is
called
in
turn
to
get
a
list
of
attributes.
The
attributes
are
then
added
to
the
credential.
When
the
attribute
list
returned
from
the
entitlement
service
includes
the
reserved
credential
attribute
azn_cred_groups,
azn_id_get_creds()
calls
the
credential
groups
modification
service,
azn_mod_rad.
If
this
credentials
modification
service
has
been
configured
by
the
administrator,
then
the
groups
are
automatically
added
to
the
user
credential
by
this
service.
Note:
This
function
declares
a
new
credential
handle,
new_creds.
When
declaring
a
new
credential
handle,
always
initialize
it
to
AZN_C_INVALID_HANDLE
before
using
it.
Return
Values
If
successful,
the
function
will
return
AZN_S_COMPLETE.
If
the
returned
status
code
is
not
equal
to
AZN_S_COMPLETE,
the
major
error
codes
will
be
derived
from
the
returned
status
code
with
azn_error_major().
v
AZN_S_COMPLETE
Successful
completion.
v
AZN_S_API_UNINITIALIZED
This
function
has
been
called
before
azn_initialize().
v
AZN_S_INVALID_AUTHORITY
The
authorization
authority
identification
(id)
is
invalid.
v
AZN_S_INVALID_MECHANISM
The
security
mechanism
identification
(id)
is
not
supported
by
the
selected
authorization
authority.
v
AZN_S_INVALID_MECHANISM_INFO
The
security
mechanism
information
is
invalid.
v
AZN_S_INVALID_NEW_CREDS_HDL
The
credentials
handle
supplied
for
the
new
credentials
chain
is
invalid.
v
AZN_S_DOMAIN_CONFLICT
The
domain
name
specified
in
the
authzn_authority
parameter
does
not
match
the
domain
name
that
was
used
when
the
authorization
API
client
was
configured.
204
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
v
AZN_S_FAILURE
An
error
or
failure
has
occurred.
Use
azn_error_minor()
to
derive
specific
minor
error
codes
from
the
returned
status
code.
The
minor
error
code
ivacl_s_unauthorized
is
returned
when
the
caller
is
not
authorized
to
use
this
function.
Authorization
might
fail
because
the
caller
does
not
belong
to
the
correct
group
for
the
authorization
API
mode
(remote
or
local),
or
because
of
issues
specific
to
the
authentication
mechanism.
See
pdbaclmsg.h
for
a
complete
list
of
minor
error
codes
that
describe
access
control
problems.
Appendix
A.
Authorization
API
reference
205
azn_init_set_code_set()
Informs
the
authorization
API
of
the
codeset
of
the
calling
application.
Codeset
to
be
UTF-8
or
the
local
codeset.
Syntax
azn_status_t
azn_init_set_code_set(
const
azn_string_t
codeset
);
Parameters
Input
codeset
Specifies
whether
the
codeset
is
UTF-8
or
a
local
codeset.
This
value
is
one
of
the
predefined
azn_string_t
constants:
AZN_EXTPSEC_CONST
azn_string_t
azn_code_set_utf8
AZN_EXTPSEC_CONST
azn_string_t
azn_code_set_local
Description
Informs
the
authorization
API
(and
the
attribute
list
implementation
in
particular)
of
the
codeset
of
the
calling
application.
When
this
function
is
not
called,
the
default
is
that
the
caller
is
running
in
the
local
codeset.
When
you
are
running
in
UTF-8
codeset,
and
intend
to
call
the
authorization
API
with
strings
in
UTF-8,
use
this
function
to
notify
the
authorization
API
client.
The
input
parameter
codeset
takes
a
predefined
azn_string_t
codeset
specifier
constant.
To
declare
use
of
UTF-8,
use
azn_codeset_utf8.
Note
that
azn_codeset_local
is
NULL,
which
is
the
default.
Return
Values
If
successful,
the
function
will
return
AZN_S_COMPLETE.
If
the
returned
status
code
is
not
equal
to
AZN_S_COMPLETE,
the
major
error
codes
will
be
derived
from
the
returned
status
code
with
azn_error_major().
v
AZN_S_COMPLETE
Successful
completion.
v
AZN_S_FAILURE
An
error
or
failure
has
occurred.
Use
azn_error_minor()
to
derive
specific
minor
error
codes
from
the
returned
status
code.
The
minor
error
code
ivacl_s_invalid_codeset
is
returned
when
the
value
supplied
for
codeset
is
not
one
of
the
predefined
constants.
206
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
azn_initialize()
Initializes
the
authorization
service.
Syntax
azn_status_t
azn_initialize(
const
azn_attrlist_h_t
init_data,
azn_attrlist_h_t
*init_info
);
Parameters
Input
init_data
Handle
to
an
attribute
list
containing
implementation-specific
initialization
data.
The
credentials
handle
should
be
a
handle
for
an
existing,
non-empty
credentials
chain
which
contains
valid
data.
Output
init_info
Pointer
to
a
handle
to
an
attribute
list
through
which
implementation-specific
information
is
returned
from
initialization.
The
attribute
list
handle
pointer
passed
as
the
init_info
parameter
can
be
one
of
the
following:
v
A
attribute
list
handle
that
has
been
initialized
to
AZN_C_INVALID_HANDLE.
v
A
attribute
list
handle
for
a
new,
empty
attribute
list,
which
has
been
initialized
by
a
call
to
azn_attrlist_create().
v
A
credentials
handle
for
an
existing,
non-empty
attribute
list
which
contains
valid
data.
Description
This
function
must
be
called
before
calling
most
other
authorization
API
functions.
The
exceptions
to
this
rule
are
the
attribute
list
functions
(azn_attrlist_*)
and
the
error
handling
functions
(azn_error_*).
Upon
return
from
this
call,
the
attribute
list
referenced
by
init_info
contains
the
authorization
API
version
number,
which
is
returned
as
the
value
for
the
attribute
AZN_C_VERSION.
When
init_info
is
no
longer
required,
use
azn_attrlist_delete()
to
release
its
storage.
Note:
This
function
declares
a
new
attribute
list
handle,
init_info.
When
declaring
a
new
attribute
list
handle,
always
initialize
it
to
AZN_C_INVALID_HANDLE
before
using
it.
When
using
this
function
on
Windows
NT,
do
not
call
it
from
dllMain().
The
function
dllMain()
is
run
as
one
thread,
which
prevents
azn_initialize()
from
spawning
other
threads.
When
programming
in
C++
on
Windows
NT,
do
not
call
Appendix
A.
Authorization
API
reference
207
azn_initialize()
from
a
global
or
statically
defined
class
constructor
because
these
constructors
are
run
from
dllMain().
Return
Values
If
successful,
the
function
will
return
AZN_S_COMPLETE.
If
the
returned
status
code
is
not
equal
to
AZN_S_COMPLETE,
the
major
error
codes
will
be
derived
from
the
returned
status
code
with
azn_error_major().
v
AZN_S_COMPLETE
Successful
completion.
v
AZN_S_API_ALREADY_INITIALIZED
azn_initialize()
has
been
called
twice
without
an
intervening
call
to
azn_shutdown().
v
AZN_S_CONFIG_INVALID_LISTENING_PORT
An
Administration
Service
plug-in
was
registered
but
no
ssl-listening-port
was
specified.
v
AZN_S_INVALID_INIT_DATA_HDL
The
attribute
list
handle
for
the
initialization
information
is
invalid.
v
AZN_S_INVALID_INIT_INFO_HDL
The
attribute
list
handle
for
the
output
initialization
information
is
invalid.
v
AZN_S_SVC_DEFINITION_ERROR
A
service
has
been
defined
incorrectly.
The
error
condition
is
caused
either
by
invalid
entries
in
the
service
definition
attributes
that
are
passed
as
input
to
azn_initialize(),
or
by
invalid
entries
in
the
configuration
file.
v
AZN_S_SVC_INIT_FAILED
A
service
failed
to
initialize
correctly.
The
minor
error
code
contains
additional
information
about
the
reason
for
the
failure.
v
AZN_S_SVC_AUTHORIZATION_FAILED
The
caller
is
not
authorized
to
make
calls
to
the
service.
The
minor
error
code
contains
additional
information
about
the
reason
for
the
failure.
v
AZN_S_SVC_DLL_LOAD_FAILED
The
DLL
for
a
service
failed
to
load
correctly
v
AZN_S_SVC_INITIALIZE_NOT_FOUND
The
azn_svc_initialize()
interface
was
not
found
in
the
DLL
module
for
a
service.
v
AZN_S_SVC_SHUTDOWN_NOT_FOUND
The
azn_svc_shutdown()
interface
was
not
found
in
the
DLL
module
for
a
service.
v
AZN_S_SVC_ENT_FUNC_NOT_FOUND
The
azn_entitlement_get_entitlements()
interface
was
not
found
in
the
DLL
module
for
an
entitlement
service.
v
AZN_S_SVC_PAC_FUNC_NOT_FOUND
The
azn_pac_get_creds()
or
azn_creds_get_pac()
interface
was
not
found
in
the
DLL
module
for
a
PAC
service.
v
AZN_S_SVC_CRED_MOD_FUNC_NOT_FOUND
The
azn_creds_modify()
interface
was
not
found
in
the
DLL
module
for
a
credentials
modification
service.
v
AZN_S_SVC_SERVICE_IS_REGISTERED
The
service
ID
cannot
be
registered
because
it
is
already
listed
as
registered
by
the
Service
Dispatcher.
208
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
v
AZN_S_SVC_DISPATCHER_FAILURE
The
service
dispatcher
failed.
This
can
be
caused
by
incorrect
initialization
of
the
authorization
API.
v
AZN_S_SVC_ADMIN_UNKNOWN_PARAMETER
The
service
definition
for
the
Administration
Service
plug-in
contained
an
invalid
parameter.
v
AZN_S_SVC_ADMIN_POBJ_NOT_SPECIFIED
The
Administration
Service
plug-in
definition
specified
the
-pboj
parameter
but
failed
to
specify
the
name
of
the
protected
object
hierarchy.
v
AZN_S_SVC_ADMIN_POBJ_ALREADY_REGISTERED
The
protected
object
hierarchy
name
has
already
been
registered
by
another
Administration
service
definition
within
this
authorization
API
application.
v
AZN_S_SVC_ADMIN_TASK_FUNC_NOT_FOUND
The
Administration
Service
plug-in
implemented
either
azn_admin_get_tasklist()
or
azn_admin_perform_task()
but
did
not
implement
both
interfaces.
Administration
Service
plug-ins
must
implement
either
both
or
none.
v
AZN_S_FAILURE
An
error
or
failure
has
occurred.
Use
azn_error_minor()
to
derive
specific
minor
error
codes
from
the
returned
status
code.
The
minor
error
code
ivacl_s_unauthorized
is
returned
when
the
caller
is
not
authorized
to
use
this
function.
Authorization
might
fail
because
the
caller
does
not
belong
to
the
correct
group
for
the
authorization
API
mode
(remote
or
local),
or
because
of
issues
specific
to
the
authentication
mechanism.
See
pdbaclmsg.h
for
a
complete
list
of
minor
error
codes
that
describe
access
control
problems.
Appendix
A.
Authorization
API
reference
209
azn_pac_get_creds()
Returns
a
handle
to
new
credentials
chain
that
is
derived
from
a
privilege
attribute
certificate
(PAC)
by
a
specified
PAC
service.
Syntax
azn_status_t
azn_pac_get_creds(
const
azn_buffer_t
pac,
const
azn_string_t
pac_svc_id,
azn_creds_h_t
*new_creds
);
Parameters
Input
pac
Buffer
structure
that
holds
the
supplied
PAC.
pac_svc_id
Identification
(id)
of
the
PAC
service
that
produces
the
credentials
chain.
Output
new_creds
Pointer
to
a
handle
to
the
returned
credentials
chain.
The
credentials
handle
pointer
passed
as
the
new_creds
parameter
can
be
one
of
the
following:
v
A
credentials
handle
that
has
been
initialized
to
AZN_C_INVALID_HANDLE.
v
A
credentials
handle
for
a
new,
empty
credential,
which
has
been
initialized
by
a
call
to
azn_creds_create().
In
this
case,
the
handle
is
updated
(overwritten)
with
new
credentials.
v
A
credentials
handle
for
an
existing,
non-empty
credential
chain
which
contains
valid
data.
In
this
case,
the
handle
is
updated
(overwritten)
with
new
credentials.
Description
This
function
uses
the
identified
PAC
service
(pac_svc_id)
to
build
a
new
credentials
chain
using
the
information
in
the
supplied
PAC
(pac).
Some
PAC
services
will
cryptographically
verify
the
protection
or
signature
on
the
received
PAC,
and
will
return
an
error
if
the
PAC
cannot
be
verified.
Note:
This
function
declares
a
new
credentials
handle,
new_creds.
When
declaring
a
new
credentials
handle,
always
initialize
it
to
AZN_C_INVALID_HANDLE
before
using
it.
This
function
decodes
PACs
that
are
built
by
azn_creds_get_pac().
Return
Values
If
successful,
the
function
will
return
AZN_S_COMPLETE.
If
the
returned
status
code
is
not
equal
to
AZN_S_COMPLETE,
the
major
error
codes
will
be
derived
from
the
returned
status
code
with
azn_error_major().
210
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
v
AZN_S_COMPLETE
Successful
completion.
v
AZN_S_API_UNINITIALIZED
This
function
has
been
called
before
azn_initialize().
v
AZN_S_INVALID_PAC
The
PAC
is
invalid
or
could
not
be
verified
by
the
PAC
service.
v
AZN_S_INVALID_PAC_SVC
The
id
of
the
PAC
service
is
invalid.
v
AZN_S_INVALID_NEW_CREDS_HDL
The
credentials
handle
supplied
for
new_creds
is
invalid.
v
AZN_S_UNIMPLEMENTED_FUNCTION
This
function
is
not
supported
by
the
implementation.
v
AZN_S_SVC_SERVICE_NOT_FOUND
The
service
with
the
specified
identification
number
was
not
found
in
the
list
of
configured
services.
v
AZN_S_SVC_AUTHORIZATION_FAILED
The
caller
is
not
authorized
to
make
calls
to
the
service.
The
minor
error
code
contains
additional
information
about
the
reason
for
the
failure.
v
AZN_S_SVC_DISPATCHER_FAILURE
The
service
dispatcher
failed.
This
can
be
caused
by
incorrect
initialization
of
the
authorization
API.
v
AZN_S_FAILURE
An
error
or
failure
has
occurred.
Use
azn_error_minor()
to
derive
specific
minor
error
codes
from
the
returned
status
code.
The
minor
error
code
ivacl_s_unauthorized
is
returned
when
the
caller
is
not
authorized
to
use
this
function.
Authorization
might
fail
because
the
caller
does
not
belong
to
the
correct
group
for
the
authorization
API
mode
(remote
or
local),
or
because
of
issues
specific
to
the
authentication
mechanism.
See
pdbaclmsg.h
for
a
complete
list
of
minor
error
codes
that
describe
access
control
problems.
Appendix
A.
Authorization
API
reference
211
azn_release_buffer()
Frees
storage
associated
with
a
buffer.
Syntax
azn_status_t
azn_release_buffer(
azn_buffer_t
*buffer
);
Parameters
Input
buffer
Pointer
to
the
buffer
whose
memory
is
to
be
released.
Output
buffer
Pointer
to
the
buffer
whose
memory
is
released.
The
pointer
is
set
to
an
invalid
value
upon
successful
completion.
Description
This
function
releases
the
specified
azn_buffer_t
structure.
The
input
buffer
pointer
is
set
to
an
invalid
value
to
ensure
that
it
cannot
be
used
in
future
function
calls.
Return
Values
If
successful,
the
function
will
return
AZN_S_COMPLETE.
If
the
returned
status
code
is
not
equal
to
AZN_S_COMPLETE,
the
major
error
codes
will
be
derived
from
the
returned
status
code
with
azn_error_major().
v
AZN_S_COMPLETE
Successful
completion.
v
AZN_S_INVALID_BUFFER_REF
The
pointer
to
the
buffer
is
invalid.
v
AZN_S_FAILURE
An
error
or
failure
has
occurred.
Use
azn_error_minor()
to
derive
specific
minor
error
codes
from
the
returned
status
code.
212
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
azn_release_pobj()
Releases
storage
associated
with
a
protected
object
data
structure.
Syntax
azn_status_t
azn_release_pobj(
azn_pobj_t
*
pobj
);
Parameters
Input
pobj
Pointer
to
a
protected
object
structure
whose
storage
is
to
be
released.
Output
pobj
Pointer
to
a
protected
object
structure
whose
storage
is
released.
The
pointer
is
set
to
an
invalid
value
upon
successful
completion.
Description
Releases
storage
associated
with
a
protected
object
structure.
Return
Values
When
successful,
the
function
returns
AZN_S_COMPLETE.
If
the
returned
status
code
is
not
equal
to
AZN_S_COMPLETE,
the
major
error
codes
will
be
derived
from
the
returned
status
code
with
azn_error_major().
v
AZN_S_INVALID_POBJ_REF
The
pointer
to
the
protected
object
is
NULL.
Appendix
A.
Authorization
API
reference
213
azn_release_string()
Frees
storage
that
is
associated
with
a
string.
Syntax
azn_status_t
azn_release_string(
azn_string_t
*string
);
Parameters
Input
string
Pointer
to
the
string
to
be
released.
Output
string
Pointer
to
the
string
whose
memory
is
released.
The
pointer
is
set
to
an
invalid
value
upon
successful
completion.
Description
This
function
releases
the
specified
azn_string_t
structure.
The
input
string
pointer
is
set
to
an
invalid
value
to
ensure
that
it
cannot
be
used
in
future
function
calls.
Return
Values
If
successful,
the
function
will
return
AZN_S_COMPLETE.
If
the
returned
status
code
is
not
equal
to
AZN_S_COMPLETE,
the
major
error
codes
will
be
derived
from
the
returned
status
code
with
azn_error_major().
v
AZN_S_COMPLETE
Successful
completion.
v
AZN_S_INVALID_STRING_REF
The
pointer
to
the
string
is
invalid.
v
AZN_S_FAILURE
An
error
or
failure
has
occurred.
Use
azn_error_minor()
to
derive
specific
minor
error
codes
from
the
returned
status
code.
214
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
azn_release_strings()
Frees
storage
that
is
associated
with
an
array
of
strings.
Syntax
azn_status_t
azn_release_strings(
azn_string_t
*strings[]
);
Parameters
Input
strings
Pointer
to
the
array
of
azn_string_t
structures
to
be
released
upon
successful
completion.
Description
This
function
releases
a
NULL-terminated
array
of
azn_string_t
structures.
The
input
string
pointer
is
set
to
an
invalid
value
to
ensure
that
it
cannot
be
used
in
future
function
calls.
Return
Values
If
successful,
the
function
will
return
AZN_S_COMPLETE.
If
the
returned
status
code
is
not
equal
to
AZN_S_COMPLETE,
the
major
error
codes
will
be
derived
from
the
returned
status
code
with
azn_error_major().
v
AZN_S_COMPLETE
Successful
completion.
v
AZN_S_INVALID_STRING_REF
Pointer
to
the
array
of
strings
is
invalid.
v
AZN_S_FAILURE
An
error
or
failure
has
occurred.
Use
azn_error_minor()
to
derive
specific
minor
error
codes
from
the
returned
status
code.
Appendix
A.
Authorization
API
reference
215
azn_shutdown()
Cleans
up
internal
authorization
service
state
in
preparation
for
shutdown.
Syntax
azn_status_t
azn_shutdown();
Description
Useazn_shutdown()
to
clean
up
the
authorization
API’s
memory
and
other
internal
implementation
state
before
the
application
exits.
This
function
shuts
down
the
implementation
state
created
by
azn_initialize().
The
only
authorization
API
functions
that
can
be
used
after
calling
azn_shutdown(),
prior
to
calling
azn_initialize()
again,
are
the
attribute
list
functions
(azn_attrlist_*),
the
error
handling
functions
(azn_error_*),
and
the
memory
release
functions
(azn_*_delete
and
azn_release_*).
Return
Values
If
successful,
the
function
will
return
AZN_S_COMPLETE.
If
the
returned
status
code
is
not
equal
to
AZN_S_COMPLETE,
the
major
error
codes
will
be
derived
from
the
returned
status
code
with
azn_error_major().
v
AZN_S_COMPLETE
Successful
completion.
v
AZN_S_API_UNINITIALIZED
This
function
has
been
called
before
azn_initialize().
v
AZN_S_SVC_SHUTDOWN_FAILED
A
service
failed
to
shutdown
correctly.
The
minor
error
code
contains
additional
information
about
the
reason
for
the
failure.
v
AZN_S_SVC_AUTHORIZATION_FAILED
The
caller
is
not
authorized
to
make
calls
to
the
service.
The
minor
error
code
contains
additional
information
about
the
reason
for
the
failure.
v
AZN_S_SVC_DISPATCHER_FAILURE
The
service
dispatcher
failed.
This
can
be
caused
by
incorrect
initialization
of
the
authorization
API.
v
AZN_S_FAILURE
An
error
or
failure
has
occurred.
Use
azn_error_minor()
to
derive
specific
minor
error
codes
from
the
returned
status
code.
The
minor
error
code
ivacl_s_unauthorized
is
returned
when
the
caller
is
not
authorized
to
use
this
function.
Authorization
might
fail
because
the
caller
does
not
belong
to
the
correct
group
for
the
authorization
API
mode
(remote
or
local),
or
because
of
issues
specific
to
the
authentication
mechanism.
See
pdbaclmsg.h
for
a
complete
list
of
minor
error
codes
that
describe
access
control
problems.
216
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
azn_util_errcode()
Builds
an
azn_status_t
error
code
from
a
major
and
minor
status.
Syntax
azn_status_t
azn_util_errcode(
const
unsigned
int
major,
const
unsigned
int
minor
);
Description
Builds
an
azn_status_t
error
code
from
a
major
and
minor
status.
Parameters
Input
major
The
major
component
of
the
error
status.
minor
The
minor
component
of
the
error
status.
Return
Values
Returns
complete
azn_status_t
error
code.
Appendix
A.
Authorization
API
reference
217
azn_util_handle_is_valid()
Determine
if
the
handle
references
a
valid
data
structure.
Syntax
azn_boolean_t
azn_util_handle_is_valid(
long
handle
);
Parameters
Input
handle
A
handle
to
an
attribute
list.
Description
This
function
determines
if
the
specified
handle
references
a
valid
data
structure.
Note:
When
declaring
a
new
credential
handle,
always
initialize
it
to
AZN_C_INVALID_HANDLE
before
using
it.
Return
Values
Returns
true
if
the
handle
is
valid
or
false
if
the
handle
is
invalid.
218
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
azn_util_password_authenticate()
Performs
a
login
for
a
user
name
and
password
pair,
and
returns
authentication
information
if
the
login
was
successful.
Syntax
azn_status_t
azn_util_password_authenticate(
const
azn_string_t
principal_name,
const
azn_string_t
password,
azn_string_t
*mechanism_id,
azn_buffer_t
*authinfo
);
Parameters
Input
principal_name
Name
of
the
user
(principal)
used
to
log
in.
If
LDAP
authentication
is
used,
this
will
be
a
DN
string.
password
Password
for
the
user.
Output
mechanism_id
Pointer
to
a
string
identifying
the
authentication
mechanism
with
which
the
user
is
authenticated.
authinfo
Pointer
to
a
buffer
that
is
loaded
with
the
authentication
information
that
is
returned
by
a
successful
login
attempt.
Description
This
function
performs
a
login
for
a
user
name
and
password
pair,
and
returns
authentication
information
when
the
login
is
successful.
The
authentication
mechanism
used
depends
upon
the
underlying
authentication
mechanism
that
was
configured
when
the
authorization
API
was
installed.
This
function
does
not
establish
a
security
context
for
the
application.
The
mechanism_id
and
authinfo
returned
can
be
appended
with
data
specific
to
the
principal
and
passed
into
the
azn_id_get_creds()
function.
The
mechanism_id
string
is
allocated
by
the
utility
function
and
must
be
freed
using
azn_release_string()
when
no
longer
needed.
The
authinfo
buffer
must
be
freed
using
azn_release_buffer().
Return
Values
Returns
AZN_S_COMPLETE
on
success,
or
an
error
code
on
failure.
The
minor
error
code
ivacl_s_unauthorized
is
returned
when
the
caller
is
not
authorized
to
use
this
function.
Authorization
might
fail
because
the
caller
does
not
belong
to
the
correct
group
for
the
authorization
API
mode
(remote
or
local),
or
because
of
issues
specific
to
the
authentication
mechanism.
Appendix
A.
Authorization
API
reference
219
Note:
When
used
with
Domino
or
Active
Directory,
additional
error
codes
can
be
returned,
in
cases
where
there
is
more
than
one
error
in
the
input
parameters.
See
pdbaclmsg.h
for
a
complete
list
of
minor
error
codes
that
describe
access
control
problems.
When
unsuccessful,
the
following
major
error
codes
are
returned:
v
AZN_S_FAILURE
An
error
has
been
encountered.
v
AZN_S_U_INVALID_PASSWORD
The
password
is
not
valid.
v
AZN_S_U_INVALID_PRINC_NAME
The
principal
name
is
unknown.
v
AZN_S_U_LDAP_AUTHEN_FAILED
Authentication
to
the
LDAP
user
registry
failed.
v
AZN_S_U_URAF_AUTHEN_FAILED
URAF
authentication
failed
v
AZN_S_U_PASSWORD_EXPIRED
The
user
authenticated
correctly
but
the
password
has
expired
and
must
be
changed.
Mechanism_id
and
authinfo
are
not
returned.
v
AZN_S_U_PASSWORD_ACCT_DISABLED
The
account
has
been
disabled
due
to
too
many
failed
login
attempts.
v
AZN_S_U_ACCOUNT_DISABLED
The
account
has
been
disabled
by
the
administrator.
v
AZN_S_U_TOD_ACCESS_DENIED
The
login
failed
due
to
policy
restrictions
based
on
Time
of
Day.
v
AZN_S_U_ACCOUNT_LOCKEDOUT
The
account
has
been
locked
because
too
many
invalid
login
attempts
have
been
made.
The
number
of
invalid
attempts
and
the
logout
period
can
be
configured
through
policy.
v
AZN_S_U_INSUFFICIENT_ACCESS
The
caller
of
this
function
has
insufficient
privileges
to
perform
the
requested
operation.
v
AZN_S_API_UNINITIALIZED
This
function
has
been
called
before
azn_initialize().
220
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
azn_util_password_change()
Changes
the
password
for
the
specified
Tivoli
Access
Manager
principal
in
the
registry.
Syntax
azn_status_t
azn_util_password_change(
const
azn_string_t
principal_name,
const
azn_string_t
password
);
Parameters
Input
principal_name
Name
of
the
principal
who’s
password
is
to
change.
When
using
an
LDAP
registry
for
authentication,
this
may
also
be
a
Distinguished
Name
(DN)
string.
password
New
password
for
the
principal.
Description
Changes
the
password
for
a
username
pair.
The
method
of
changing
the
password
is
selected
automatically
according
to
the
underlying
authentication
mechanism
with
which
the
authorization
API
was
installed.
Examples
of
authentication
mechanisms
are
LDAP,
Lotus
Domino
Server,
and
Microsoft
Active
Directory.
Limitations:
This
call
can
succeed
even
though
the
calling
application
server
lacks
sufficient
access,
when
used
with
either
Lotus
Domino
Server
or
Microsoft
Active
Directory
authentication.
On
Lotus
Domino
Server,
this
is
because
the
server
uses
the
local
Lotus
Notes
ID
file,
and
hence
always
has
the
authority
to
change
the
password.
On
Active
Directory,
the
authorization
to
make
this
call
is
taken
from
the
Active
Directory
system
group
membership,
not
from
a
Tivoli
Access
Manager
group.
Use
the
following
command,
entered
all
on
one
line,
to
add
the
application
to
the
appropriate
system
group
membership:
uraftool.exe
-p
Admin_Password
-c
"rgyid_addmem
group
\"cn=Domain
Admin,cn=users\"
application_server_ID
On
LDAP-based
user
registries,
use
the
pdadmin
command
to
add
the
application
server
to
the
appropriate
Tivoli
Access
Manager
group:
pdadmin
group
modify
SecurityGroup
add
application_server_ID
Return
Values
Returns
AZN_S_COMPLETE
on
success,
or
an
error
code
on
failure.
The
minor
error
code
ivacl_s_unauthorized
is
returned
when
the
caller
is
not
authorized
to
use
this
function.
Authorization
might
fail
because
the
caller
does
not
belong
to
the
correct
group
for
the
authorization
API
mode
(remote
or
local),
or
because
of
issues
specific
to
the
authentication
mechanism.
Appendix
A.
Authorization
API
reference
221
See
pdbaclmsg.h
for
a
complete
list
of
minor
error
codes
that
describe
access
control
problems.
Note:
When
used
with
Lotus
Domino
Server
or
Microsoft
Active
Directory,
additional
error
codes
can
be
returned,
in
cases
where
there
is
more
than
one
error
in
the
input
parameters.
When
unsuccessful,
the
following
major
error
codes
are
returned:
v
AZN_S_FAILURE
v
AZN_S_U_ACCOUNT_DISABLED
The
user
account
is
disabled
by
the
administrator.
v
AZN_S_U_ACCOUNT_LOCKEDOUT
The
account
has
been
locked
because
too
many
invalid
login
attempts
have
been
made.
The
number
of
invalid
attempts
and
the
logout
period
can
be
configured
through
policy.
v
AZN_S_U_INSUFFICIENT_ACCESS
The
caller
of
this
function
has
insufficient
privileges
to
perform
the
requested
operation.
v
AZN_S_U_INVALID_PASSWORD
The
password
is
not
valid.
v
AZN_S_U_INVALID_PRINC_NAME
The
principal
name
is
unknown.
v
AZN_S_U_LDAP_AUTHEN_FAILED
Authentication
to
the
LDAP
user
registry
failed.
v
AZN_S_U_PASSWORD_EXPIRED
The
user
password
has
expired.
v
AZN_S_U_PASSWORD_HAS_SPACES
The
user
password
contains
spaces.
v
AZN_S_U_PASSWORD_TOO_FEW_ALPHA
The
user
password
must
have
more
alphanumeric
characters.
v
AZN_S_U_PASSWORD_TOO_FEW_NONALPHA
The
user
password
must
have
more
non-alphanumeric
characters.
v
AZN_S_U_PASSWORD_TOO_MANY_REPEATED
The
user
password
has
one
or
more
characters
that
are
repeated
too
many
times.
v
AZN_S_U_PASSWORD_TOO_SHORT
The
user
password
must
contain
more
characters.
v
AZN_S_U_URAF_AUTHEN_FAILED
URAF
authentication
failed
v
AZN_S_U_TOD_ACCESS_DENIED
Access
denied
because
time
or
day
restrictions
prevent
access
at
the
current
time.
v
AZN_S_API_UNINITIALIZED
This
function
has
been
called
before
azn_initialize().
222
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
Appendix
B.
Authorization
service
plug-in
API
reference
This
chapter
contains
the
following
reference
pages:
v
“azn_admin_get_object()”
on
page
224
v
“azn_admin_get_objectlist()”
on
page
226
v
“azn_admin_get_tasklist()”
on
page
228
v
“azn_admin_perform_task()”
on
page
231
v
“azn_svc_creds_get_pac()”
on
page
234
v
“azn_svc_creds_modify()”
on
page
236
v
“azn_svc_decision_access_allowed_ext()”
on
page
239
v
“azn_svc_entitlement_get_entitlements()”
on
page
242
v
“azn_svc_initialize()”
on
page
244
v
“azn_svc_pac_get_creds()”
on
page
247
v
“azn_svc_shutdown()”
on
page
249
©
Copyright
IBM
Corp.
2000,2003
223
azn_admin_get_object()
Retrieves
a
potential
protected
object.
Tests
for
the
existence
of
a
protected
object.
Syntax
azn_status_t
azn_admin_get_object(
azn_creds_h_t
creds,
azn_string_t
locale,
azn_string_t
path,
azn_attrlist_h_t
indata,
azn_attrlist_h_t
outdata
);
Parameters
Input
creds
Credentials
of
the
identity
requesting
the
object.
The
administration
service
must
verify
that
the
credentials
have
sufficient
authorization
to
perform
the
requested
operation.
The
Tivoli
Access
Manager
policy
server
forwards
the
credentials
of
the
administrator
when
performing
this
function.
locale
Locale
of
the
caller
at
the
client
machine.
The
locale
is
the
string
equal
to
LC_MESSAGES
returned
from
the
client
machine.
Note:
This
parameter
is
not
used
in
Tivoli
Access
Manager
Version
5.1,
but
is
maintained
for
compatibility
with
Tivoli
SecureWay
Policy
Director
Version
3.8.
path
The
complete
path
name
of
the
protected
object.
indata
An
undefined
(free
form)
attribute
list
that
can
be
used
for
agreed
upon
communication
between
the
administration
service
implementation
and
a
custom
user
interface.
Output
outdata
An
undefined
(free
form)
attribute
list.
This
attribute
list
is
allocated
by
the
administration
service
implementation.
See
the
Description
section
immediately
below
for
a
discussion
of
how
to
use
this
output
parameter.
Description
This
function
returns
information
about
an
object
in
the
Tivoli
Access
Manager
protected
object
namespace.
The
credentials
of
the
identity
requesting
the
object
are
forwarded
by
the
Tivoli
Access
Manager
policy
server
when
this
function
is
called.
When
the
caller
has
sufficient
permissions,
the
protected
object
information
is
placed
into
a
authorization
API
attribute
list.
This
list
is
returned
as
the
output
parameter
outdata.
The
administration
service
must
pass
the
protected
object
information
in
the
azn_admin_svc_pobj
attribute.
Use
azn_attrlist_add_entry_pobj()
to
add
this
attribute
to
the
attribute
list.
224
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
The
administration
service
must
pass
the
result
strings
information
in
the
azn_admin_svc_results
attribute.
Use
azn_attrlist_add_entry_pobj()
to
add
this
attribute
to
the
attribute
list.
Typically,
these
strings
include
error,
warning,
and
information
messages.
The
administration
service
and
the
custom
user
interface
can
exchange
information
of
their
choice
by
setting
other
attributes.
Use
the
azn_attrlist_add_entry_*
APIs
to
set
attributes.
The
Tivoli
Access
Manager
policy
server
passes
these
other
attributes
in
the
outdata
parameter
of
the
corresponding
administration
API
function
call.
Multiple
authorization
API
applications
can
register
to
service
the
protected
object
hierarchy
name
for
the
protected
object.
You
can
use
this
feature
to
provide
failover
support
in
the
event
that
a
particular
application
server
fails.
If
the
authorization
API
implementation
fails
to
connect
to
a
registered
service
implementation,
it
attempts
to
contact
other
service
implementations
until
a
connection
is
successful
or
until
the
list
of
appropriate
service
implementations
is
exhausted.
Return
Values
When
successful,
the
function
returns
AZN_S_COMPLETE.
When
the
returned
status
code
is
not
equal
to
AZN_S_COMPLETE,
the
major
error
codes
are
derived
from
the
returned
status
code
with
azn_error_major().
When
this
function
calls
another
authorization
API
function,
and
the
called
function
returns
an
error,
this
function
should
return
the
error
to
the
calling
application.
v
AZN_S_SVC_ADMIN_OUT_OF_MEMORY
A
memory
allocation
error
has
occurred.
v
AZN_S_SVC_ADMIN_INVALID_SVCINFO_HDL
The
svc_info
passed
to
the
administration
service
plug-in
shared
library
is
invalid.
v
AZN_S_SVC_ADMIN_INVALID_ARG_COUNT
The
argument
count
argc
passed
to
the
administration
service
plug-in
shared
library
is
invalid.
v
AZN_S_SVC_ADMIN_INVALID_ARG_ARRAY
The
argument
array
passed
to
the
administration
service
plug-in
shared
library
is
invalid.
v
AZN_S_SVC_ADMIN_INVALID_ARGUMENT
One
or
more
of
the
arguments
passed
in
to
initialize
the
administration
service
plug-in
is
invalid.
v
AZN_S_FAILURE
An
implementation
specific
error
or
failure
has
occurred.
An
implementation
specific
minor
error
code
should
be
returned
in
the
status
code
for
the
caller
to
extract
with
azn_error_minor().
Appendix
B.
Authorization
service
plug-in
API
reference
225
azn_admin_get_objectlist()
Accesses
the
administration
service
to
provide
a
list
of
all
potential
protected
objects
that
are
children
of
the
specified
parent
object.
Syntax
azn_status_t
azn_admin_get_object(
azn_creds_h_t
creds,
azn_string_t
locale,
azn_string_t
path,
azn_attrlist_h_t
indata,
azn_attrlist_h_t
outdata
);
Parameters
Input
creds
Credentials
of
the
identity
requesting
the
object.
The
administration
service
must
verify
that
the
credentials
have
sufficient
authorization
to
perform
the
requested
operation.
The
Tivoli
Access
Manager
policy
server
forwards
the
credentials
of
the
administrator
when
performing
this
function.
locale
Locale
of
the
caller
at
the
client
machine.
The
locale
is
the
string
equal
to
LC_MESSAGES
returned
from
the
client
machine.
Note:
This
parameter
is
not
used
in
Tivoli
Access
Manager
Version
5.1..
path
The
complete
path
name
of
the
protected
object.
indata
An
undefined
(free
form)
attribute
list
that
can
be
used
for
agreed
upon
communication
between
the
administration
service
implementation
and
a
custom
user
interface.
Output
outdata
An
undefined
(free
form)
attribute
list.
This
attribute
list
is
allocated
by
the
administration
service
implementation.
See
the
Description
section
immediately
below
for
a
discussion
of
how
to
use
this
output
parameter.
Description
This
function
returns
information
about
objects
in
the
Tivoli
Access
Manager
protected
object
namespace.
The
credentials
of
the
identity
requesting
the
objects
are
forwarded
by
the
Tivoli
Access
Manager
policy
server
when
this
function
is
called.
When
the
caller
has
sufficient
permissions,
the
protected
object
information
is
placed
into
a
authorization
API
attribute
list.
This
list
is
returned
as
the
output
parameter
outdata.
226
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
The
administration
service
plug-in
must
pass
the
protected
object
information
in
the
azn_admin_svc_pobj
attribute.
Use
azn_attrlist_add_entry_pobj()
to
add
this
attribute
to
the
attribute
list.
The
administration
service
plug-in
must
pass
the
result
strings
information
in
the
azn_admin_svc_results
attribute.
Use
azn_attrlist_add_entry_pobj()
to
add
this
attribute
to
the
attribute
list.
Typically,
these
strings
include
error,
warning,
and
information
messages.
The
administration
service
and
the
custom
user
interface
can
exchange
information
of
their
choice
by
setting
other
attributes.
Use
the
azn_attrlist_add_entry_*
APIs
to
set
attributes.
The
Tivoli
Access
Manager
policy
server
passes
these
other
attributes
in
the
outdata
parameter
of
the
corresponding
administration
API
function
call.
Multiple
authorization
API
applications
can
register
to
service
the
protected
object
hierarchy
name
for
the
protected
object.
You
can
use
this
feature
to
provide
failover
support
in
the
event
that
a
particular
application
server
fails.
If
the
authorization
API
implementation
fails
to
connect
to
a
registered
service
implementation,
it
attempts
to
contact
other
service
implementations
until
a
connection
is
successful
or
until
the
list
of
appropriate
service
implementations
is
exhausted.
Return
Values
When
successful,
the
function
returns
AZN_S_COMPLETE.
When
the
returned
status
code
is
not
equal
to
AZN_S_COMPLETE,
the
major
error
codes
are
derived
from
the
returned
status
code
with
azn_error_major().
When
this
function
calls
another
authorization
API
function,
and
the
called
function
returns
an
error,
this
function
should
return
the
error
to
the
calling
application.
v
AZN_S_SVC_ADMIN_OUT_OF_MEMORY
A
memory
allocation
error
has
occurred.
v
AZN_S_SVC_ADMIN_INVALID_SVCINFO_HDL
The
svc_info
passed
to
the
administration
service
plug-in
shared
library
is
invalid.
v
AZN_S_SVC_ADMIN_INVALID_ARG_COUNT
The
argument
count
argc
passed
to
the
administration
service
plug-in
shared
library
is
invalid.
v
AZN_S_SVC_ADMIN_INVALID_ARG_ARRAY
The
argument
array
passed
to
the
administration
service
plug-in
shared
library
is
invalid.
v
AZN_S_SVC_ADMIN_INVALID_ARGUMENT
One
or
more
of
the
arguments
passed
in
to
initialize
the
administration
service
plug-in
is
invalid.
v
AZN_S_FAILURE
An
implementation
specific
error
or
failure
has
occurred.
An
implementation
specific
minor
error
code
should
be
returned
in
the
status
code
for
the
caller
to
extract
with
azn_error_minor().
Appendix
B.
Authorization
service
plug-in
API
reference
227
azn_admin_get_tasklist()
Returns
a
list
of
all
the
supported
administration
tasks.
Syntax
azn_status_t
azn_admin_get_tasklist(
azn_creds_h_t
creds,
azn_string_t
locale,
azn_attrlist_h_t
indata,
azn_attrlist_h_t
outdata
);
Parameters
Input
creds
Credentials
of
the
identity
requesting
the
object.
The
administration
service
must
verify
that
the
credentials
have
sufficient
authorization
to
perform
the
requested
operation.
The
Tivoli
Access
Manager
policy
server
forwards
the
credentials
of
the
administrator
when
performing
this
function.
locale
Locale
of
the
caller
at
the
client
machine.
The
locale
is
the
string
equal
to
LC_MESSAGES
returned
from
the
client
machine.
Note:
This
parameter
is
not
used
in
Tivoli
Access
Manager
Version
5.1.
indata
An
undefined
(free
form)
attribute
list
that
can
be
used
for
agreed
upon
communication
between
the
administration
service
implementation
and
a
custom
user
interface.
commands[]
A
NULL
terminated
list
of
administration
commands
supported
by
this
service
implementation.
Commands
should
conform
to
pdadmin
command
line
interface
syntax
rules.
The
command
list
may
be
state
sensitive.
Only
commands
that
can
be
successful
in
the
current
state
can
be
returned.
Thus
the
returned
list
does
not
include
all
possible
commands.
Output
outdata
An
undefined
(free
form)
attribute
list.
This
attribute
list
is
allocated
by
the
administration
service
implementation.
Description
Returns
a
list
of
all
the
supported
administration
tasks.
The
list
is
obtained
from
the
administration
service.
The
administration
service
plug-in
must
pass
the
task
information
in
the
azn_admin_svc_task
attribute.
Use
the
azn_attrlist_add_entry()
API
to
build
the
list.
Information
about
each
specific
task
is
a
value
of
this
attribute.
228
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
The
administration
service
plug-in
must
pass
the
result
strings
information
in
the
azn_admin_svc_results
attribute.
Use
azn_attrlist_add_entry_pobj()
to
add
this
attribute
to
the
attribute
list.
Typically,
these
strings
include
error,
warning,
and
information
messages.
Each
value
for
the
azn_admin_svc_results
attribute
indicates
any
result
information
for
the
azn_admin_get_tasklist()
call.
These
results
are
displayed
by
pdadmin
in
response
to
typing
the
command
server
listtasks
server
name
at
the
pdadmin
command
line
interface.
For
example,
if
this
call
was
successful,
the
implementer
may
choose
not
to
return
anything
in
the
azn_admin_svc_results
attribute.
If
this
call
was
unsuccessful,
the
implementer
can
return
implementation-specific
error
messages
in
the
adm_admin_svc_results
attribute.
The
administration
service
and
the
custom
user
interface
can
exchange
information
of
their
choice
by
setting
other
attributes.
Use
the
azn_attrlist_add_entry_*
APIs
to
set
attributes.
The
Tivoli
Access
Manager
policy
server
passes
these
other
attributes
in
the
outdata
parameter
of
the
corresponding
administration
API
function
call.
The
authorization
API
invokes
this
function
on
all
registered
administration
service
plug-ins
and
returns
the
output
back
from
all
of
them.
If
two
plug-ins
return
the
same
task
names,
both
are
returned.
If
any
of
the
plug-ins
return
an
error,
the
remaining
plug-ins
do
not
get
invoked.
The
results
obtained
thus
far
are
returned
along
with
the
error
that
occurred.
If
a
plug-in
does
not
support
any
tasks,
it
should
return
an
AZN_S_COMPLETE
major
code
so
that
this
function
can
be
invoked
on
the
remaining
plug-ins
(if
any).
Each
value
for
the
azn_admin_svc_task
attribute
needs
to
be
the
complete
specification
of
how
to
invoke
the
task.
These
values
are
displayed
in
response
to
typing
the
command
server
listtasks
server
name
at
the
pdadmin
command
line
interface.
These
value
could
also
potentially
be
used
by
a
graphical
user
interface,
so
they
must
to
be
complete.
Return
Values
When
successful,
the
function
returns
AZN_S_COMPLETE.
When
the
returned
status
code
is
not
equal
to
AZN_S_COMPLETE,
the
major
error
codes
are
derived
from
the
returned
status
code
with
azn_error_major().
When
this
function
calls
another
authorization
API
function,
and
the
called
function
returns
an
error,
this
function
should
return
the
error
to
the
calling
application.
v
AZN_S_SVC_ADMIN_OUT_OF_MEMORY
A
memory
allocation
error
has
occurred.
v
AZN_S_SVC_ADMIN_INVALID_SVCINFO_HDL
The
svc_info
passed
to
the
administration
service
plug-in
shared
library
is
invalid.
v
AZN_S_SVC_ADMIN_INVALID_ARG_COUNT
The
argument
count
argc
passed
to
the
administration
service
plug-in
shared
library
is
invalid.
v
AZN_S_SVC_ADMIN_INVALID_ARG_ARRAY
The
argument
array
passed
to
the
administration
service
plug-in
shared
library
is
invalid.
Appendix
B.
Authorization
service
plug-in
API
reference
229
v
AZN_S_SVC_ADMIN_INVALID_ARGUMENT
One
or
more
of
the
arguments
passed
in
to
initialize
the
administration
service
plug-in
is
invalid.
v
AZN_S_FAILURE
An
implementation
specific
error
or
failure
has
occurred.
An
implementation
specific
minor
error
code
should
be
returned
in
the
status
code
for
the
caller
to
extract
with
azn_error_minor().
230
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
azn_admin_perform_task()
Instructs
the
service
to
perform
an
administration
task.
The
service
returns
the
results
of
the
task.
Syntax
azn_status_t
azn_admin_perform_task(
azn_creds_h_t
creds,
azn_string_t
locale,
azn_string_t
command,
azn_attrlist_h_t
indata,
azn_attrlist_h_t
outdata
);
Parameters
Input
creds
Credentials
of
the
identity
requesting
the
object.
The
administration
service
must
verify
that
the
credentials
have
sufficient
authorization
to
perform
the
requested
operation.
The
Tivoli
Access
Manager
policy
server
forwards
the
credentials
of
the
administrator
when
performing
this
function.
locale
Locale
of
the
caller
at
the
client
machine.
The
locale
is
the
string
equal
to
LC_MESSAGES
returned
from
the
client
machine.
Note:
This
parameter
is
not
used
in
Tivoli
Access
Manager
Version
5.1.
command
Command
string
that
identifies
the
task
to
be
performed.
The
string
must
conforms
to
the
pdadmin
command
line
interface
syntax
rules.
indata
An
undefined
(free
form)
attribute
list
that
can
be
used
for
agreed
upon
communication
between
the
administration
service
implementation
and
a
custom
user
interface.
Output
outdata
An
undefined
(free
form)
attribute
list.
This
attribute
list
is
allocated
by
the
administration
service
implementation.
Description
Instructs
the
service
to
perform
an
administration
task.
The
caller
must
have
credentials
with
sufficient
permission
to
perform
the
task.
The
service
returns
the
results
of
the
task
in
the
outdata
attribute
list.
The
administration
service
must
pass
the
result
strings
information
in
the
azn_admin_svc_results
attribute.
Use
azn_attrlist_add_entry_pobj()
to
add
this
attribute
to
the
attribute
list.
Typically,
these
strings
include
error,
warning,
and
information
messages.
The
administration
service
and
the
custom
user
interface
can
exchange
information
of
their
choice
by
setting
other
attributes.
Use
the
azn_attrlist_add_entry_*
APIs
Appendix
B.
Authorization
service
plug-in
API
reference
231
to
set
attributes.
The
Tivoli
Access
Manager
policy
server
passes
these
other
attributes
in
the
outdata
parameter
of
the
corresponding
administration
API
function
call.
The
authorization
API
implementation
invokes
this
function
on
all
registered
administration
service
plug-ins
until
it
finds
one
that
implements
this
interface.
If
more
than
one
service
plug-in
supports
this
task,
the
first
plug-in
is
selected
to
execute
the
task.
The
service
plug-in
should
return
an
AZN_S_SVC_ADMIN_INVALID_TASK
major
code
if
it
is
passed
on
a
task
that
it
cannot
perform.
The
ssl-v3-timeout
parameter
specified
in
the
[ssl]
stanza
of
the
authorization
configuration
file
determines
the
timeout
for
the
communication
between
the
authorization
AP
application
and
Tivoli
Access
Manager
policy
server,
and
for
the
communication
between
the
Tivoli
Access
Manager
policy
server
and
the
pdadmin
utility
command
line
interface.
A
value
of
zero
specifies
an
infinite
timeout.
Other
values
represent
the
actual
amount
of
time
within
which
a
response
is
expected
for
a
request.
If
the
task
being
performed
by
azn_admin_perform_task()
takes
a
long
time,
this
communication
could
time
out
and
cause
an
SSL
error.
Therefore,
this
timeout
value
needs
to
be
set
properly
in
the
[ssl]
stanza
in
the
various
configuration
files.
The
relevant
configuration
files
include
ivmgrd.conf,
the
authorization
API
configuration
file,
ivacld.conf,
and
pd.conf.
Return
Values
When
successful,
the
function
returns
AZN_S_COMPLETE.
When
the
returned
status
code
is
not
equal
to
AZN_S_COMPLETE,
the
major
error
codes
are
derived
from
the
returned
status
code
with
azn_error_major().
When
this
function
calls
another
authorization
API
function,
and
the
called
function
returns
an
error,
this
function
should
return
the
error
to
the
calling
application.
v
AZN_S_SVC_ADMIN_OUT_OF_MEMORY
A
memory
allocation
error
has
occurred.
v
AZN_S_SVC_ADMIN_INVALID_TASK
The
passed-in
task
is
not
implemented
by
this
administration
service
plug-in.
Use
the
pdadmin
server
listtasks
authorization_API_application_name
command
to
determine
the
list
of
tasks
supported
by
this
authorization
API
application.
If
the
task
in
question
is
not
shown
on
the
list,
make
sure
that
the
authorization
administration
service
plug-in
that
implements
this
task
is
registered
by
the
authorization
API
application.
v
AZN_S_SVC_ADMIN_INVALID_SVCINFO_HDL
The
svc_info
passed
to
the
administration
service
plug-in
shared
library
is
invalid.
v
AZN_S_SVC_ADMIN_INVALID_ARG_COUNT
The
argument
count
argc
passed
to
the
administration
service
plug-in
shared
library
is
invalid.
v
AZN_S_SVC_ADMIN_INVALID_ARG_ARRAY
The
argument
array
passed
to
the
administration
service
plug-in
shared
library
is
invalid.
232
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
v
AZN_S_SVC_ADMIN_INVALID_ARGUMENT
One
or
more
of
the
arguments
passed
in
to
initialize
the
administration
service
plug-in
is
invalid.
v
AZN_S_FAILURE
An
implementation
specific
error
or
failure
has
occurred.
An
implementation
specific
minor
error
code
should
be
returned
in
the
status
code
for
the
caller
to
extract
with
azn_error_minor().
Appendix
B.
Authorization
service
plug-in
API
reference
233
azn_svc_creds_get_pac()
Authorization
API
privilege
attribute
certificate
(PAC)
service
interface
prototype
to
build
an
authorization
credential
from
a
proprietary
formatted
PAC.
Syntax
azn_status_t
azn_svc_creds_get_pac(
const
azn_creds_h_t
creds,
const
azn_string_t
pac_svc_id,
azn_buffer_t
*pac
);
Parameters
Input
creds
Handle
to
the
credentials
chain
whose
information
is
used
to
build
the
PAC.
The
credentials
handle
should
be
a
handle
for
an
existing,
non-empty
credentials
chain
which
contains
valid
data.
pac_svc_id
Identification
(id)
of
the
PAC
service
that
produces
the
PAC.
Output
pac
Pointer
to
an
azn_buffer_t
variable
that
will
contain
the
address
of
the
buffer
data
upon
successful
completion
of
the
routine.
Description
Authorization
API
privilege
attribute
certificate
(PAC)
service
interface
prototype
to
build
an
authorization
credential
from
a
proprietary
formatted
PAC.
This
function
uses
the
PAC
service
whose
identification
is
supplied
as
pac_svc_id
to
build
a
new
PAC.
The
PAC
service
uses
the
information
in
the
supplied
credentials
chain
to
build
the
PAC.
Different
PAC
services
might
produce
PACs
with
different
formats.
Some
PAC
services
can
cryptographically
protect
or
sign
the
PACs
they
produce.
When
pac_svc_id
is
NULL,
the
default
PAC
service
returns
an
architecture-independent
and
network-independent
encoding
of
the
specified
credentials
chain.
This
PAC
can
be
safely
transmitted.
The
receiver
of
the
PAC
can
use
azn_svc_pac_get_creds()
to
decode
the
PAC
and
obtain
a
valid
copy
of
the
original
credentials
chain.
This
function
takes
as
an
input
parameter
a
handle
to
an
existing
credentials
structure,
and
returns
a
pointer
to
the
output
PAC
in
an
authorization
API
buffer.
This
function
does
not
modify
the
input
handle
creds
and
the
credentials
chain
to
which
it
refers.
Later
changes
to
creds,
including
releasing
its
storage,
will
have
no
effect
on
pac.
When
pac
is
no
longer
required,
call
azn_release_buffer()
to
release
its
storage.
234
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
Return
Values
If
successful,
the
function
will
return
AZN_S_COMPLETE.
If
the
returned
status
code
is
not
equal
to
AZN_S_COMPLETE,
the
major
error
codes
will
be
derived
from
the
returned
status
code
with
azn_error_major().
v
AZN_S_COMPLETE
Successful
completion.
v
AZN_S_API_UNINITIALIZED
This
function
has
been
called
before
azn_initialize().
v
AZN_S_INVALID_CREDS_HDL
The
credentials
handle
supplied
is
invalid.
v
AZN_S_INVALID_PAC_SVC
The
privilege
attribute
certificate
service
identifier
is
invalid.
v
AZN_S_SVC_SERVICE_NOT_FOUND
The
service
with
the
specified
identification
number
was
not
found
in
the
list
of
configured
services.
v
AZN_S_SVC_AUTHORIZATION_FAILED
The
caller
is
not
authorized
to
make
calls
to
the
service.
The
minor
error
code
contains
additional
information
about
the
reason
for
the
failure.
v
AZN_S_SVC_DISPATCHER_FAILURE
The
service
dispatcher
failed.
This
can
be
caused
by
incorrect
initialization
of
the
authorization
API.
v
AZN_S_UNIMPLEMENTED_FUNCTION
This
function
is
not
supported
by
the
implementation.
v
AZN_S_FAILURE
An
error
or
failure
has
occurred.
Use
azn_error_minor()
to
derive
specific
minor
error
codes
from
the
returned
status
code.
The
minor
error
code
ivacl_s_unauthorized
is
returned
when
the
caller
is
not
authorized
to
use
this
function.
Authorization
might
fail
because
the
caller
does
not
belong
to
the
correct
group
for
the
authorization
API
mode
(remote
or
local),
or
because
of
issues
specific
to
the
authentication
mechanism.
See
pdbaclmsg.h
for
a
complete
list
of
minor
error
codes
that
describe
access
control
problems.
Appendix
B.
Authorization
service
plug-in
API
reference
235
azn_svc_creds_modify()
Manipulates
the
attributes
in
a
credential
based
upon
an
original
credential
and
attributes
passed
into
the
service
interface.
Modifies
an
existing
credentials
chain
and
returns
a
pointer
to
the
handle
to
a
new
credentials
chain
containing
the
modifications.
Syntax
azn_status_t
azn_svc_creds_modify(
const
azn_creds_h_t
creds,
const
azn_string_t
mod_svc_id,
const
azn_attrlist_h_t
mod_info,
azn_creds_h_t
*new_creds
);
Parameters
Input
creds
Handle
to
the
authorization
credentials
chain
to
be
modified.
The
credentials
handle
should
be
a
handle
for
an
existing,
non-empty
credentials
chain
which
contains
valid
data.
mod_svc_id
Identification
(id)
of
the
credential
modification
service.
mod_info
Attribute
list
containing
modification
service-specific
or
application-specific
data
that
describes
the
desired
credential
modifications.
Attribute
lists
that
are
empty
are
inserted
into
the
credentials.
The
attribute
list
handle
can
be
one
of
the
following:
v
An
attribute
list
handle
that
has
been
initialized
to
AZN_C_INVALID_HANDLE.
v
An
attribute
list
handle
for
a
new,
empty
attribute
list,
which
has
been
initialized
by
a
call
to
azn_attrlist_create().
v
An
attribute
list
handle
for
an
existing,
non-empty
attribute
list
which
contains
valid
data.
In
this
case,
attribute
list
data
is
appended
to
the
existing
attribute
list.
Output
new_creds
Pointer
to
a
handle
to
a
credentials
chain
that
contains
the
modified
credentials
chain
upon
return.
The
credentials
handle
pointer
passed
as
the
new_creds
parameter
can
point
to
one
of
the
following:
v
A
credentials
handle
that
has
been
initialized
to
AZN_C_INVALID_HANDLE.
Note
that
this
will
result
in
an
empty
output
credential.
v
A
credentials
handle
for
a
new,
empty
credential,
which
has
been
initialized
by
a
call
to
azn_creds_create().
Note
that
this
will
result
in
an
empty
output
credential.
236
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
Description
Manipulates
the
attributes
in
a
credential
based
upon
an
original
credential
and
attributes
passed
into
the
service
interface.
This
function
uses
the
specified
modification
service
mod_svc_id,
and
optionally
an
attribute
list
mod_info
which
contains
modification
information
provided
by
the
caller,
to
modify
a
copy
of
the
supplied
credentials
chain
creds.
The
function
returns
a
pointer
to
a
handle
to
a
new
credentials
chain
new_creds
containing
the
requested
modifications.
The
supplied
credentials
chain
is
unchanged.
When
mod_svc_id
is
NULL,
this
function
modifies
an
existing
credential
chain
creds
by
adding
the
attribute
list
mod_info
to
the
credentials
chain,
and
returning
the
modified
credential
in
new_creds.
The
following
credential
attributes
are
considered
readonly
and
can
not
be
modified
by
azn_svc_creds_modify().
If
any
of
these
attributes
are
specified
in
the
mod_info
input
attribute
list,
they
are
ignored:
v
azn_cred_principal_uuid
v
azn_cred_principal_name
v
azn_cred_principal_domain
v
azn_cred_version
v
azn_cred_mech_id
v
azn_cred_group_uuids
v
azn_cred_group_names
v
azn_cred_authzn_id
v
azn_cred_ldap_dn
If
the
input
creds
handle
references
a
combined
credentials
chain
with
more
than
one
element,
only
the
first
element
will
be
modified.
This
is
the
default
behavior
when
mod_svc_id
is
NULL.
In
this
case,
the
output
chain
consists
of
the
modified
first
element
followed
by
unmodified
copies
of
the
remaining
elements
in
the
input
combined
credentials
chains.
The
elements
in
the
output
credentials
chain
are
kept
in
the
same
order
as
their
counterparts
in
the
input
credentials
chain.
Note:
This
function
uses
a
new
credential
handle,
new_creds.
When
declaring
a
new
credential
handle,
always
initialize
it
to
AZN_C_INVALID_HANDLE
before
using
it.
When
new_creds
is
no
longer
required,
call
azn_creds_delete()
to
release
its
storage.
Return
Values
If
successful,
the
function
will
return
AZN_S_COMPLETE.
If
the
returned
status
code
is
not
equal
to
AZN_S_COMPLETE,
the
major
error
codes
will
be
derived
from
the
returned
status
code
with
azn_error_major().
v
AZN_S_COMPLETE
Successful
completion.
v
AZN_S_API_UNINITIALIZED
This
function
has
been
called
before
azn_initialize().
v
AZN_S_INVALID_CREDS_HDL
The
credentials
handle
supplied
is
invalid.
Appendix
B.
Authorization
service
plug-in
API
reference
237
v
AZN_S_
INVALID_MOD_FUNCTION
The
supplied
modification
service
identifier
is
invalid.
v
AZN_S_INVALID_ATTRLIST_HDL
The
attribute
list
handle
is
invalid.
v
AZN_S_INVALID_NEW_CREDS_HDL
The
pointer
to
the
new
credentials
handle
that
references
the
new
output
credentials
chain
is
invalid.
v
AZN_S_UNIMPLEMENTED_FUNCTION
This
function
is
not
supported
by
the
implementation.
v
AZN_S_SVC_SERVICE_NOT_FOUND
The
service
with
the
specified
identification
number
was
not
found
in
the
list
of
configured
services.
v
AZN_S_SVC_AUTHORIZATION_FAILED
The
caller
is
not
authorized
to
make
calls
to
the
service.
The
minor
error
code
contains
additional
information
about
the
reason
for
the
failure.
v
AZN_S_SVC_DISPATCHER_FAILURE
The
service
dispatcher
failed.
This
can
be
caused
by
incorrect
initialization
of
the
authorization
API.
v
AZN_S_FAILURE
An
error
or
failure
has
occurred.
Use
azn_error_minor()
to
derive
specific
minor
error
codes
from
the
returned
status
code.
The
minor
error
code
ivacl_s_unauthorized
is
returned
when
the
caller
is
not
authorized
to
use
this
function.
Authorization
might
fail
because
the
caller
does
not
belong
to
the
correct
group
for
the
authorization
API
mode
(remote
or
local),
or
because
of
issues
specific
to
the
authentication
mechanism.
See
pdbaclmsg.h
for
a
complete
list
of
minor
error
codes
that
describe
access
control
problems.
238
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
azn_svc_decision_access_allowed_ext()
External
authorization
service
(EAS)
interface
prototype.
Makes
an
access
control
decision
using
application-specific
context
information;
returns
information
about
why
the
decision
was
made.
Syntax
azn_status_t
azn_svc_decision_access_allowed_ext(
const
azn_creds_h_t
creds,
const
azn_string_t
protected_resource,
const
azn_string_t
operation,
const
azn_attrlist_h_t
app_context,
int
*permission,
azn_attrlist_h_t
*permission_info
);
Parameters
Input
creds
Handle
to
the
initiator’s
credentials
chain.
The
credentials
handle
should
be
a
handle
for
an
existing,
non-empty
credentials
chain
which
contains
valid
data.
protected_resource
Name
of
the
target
of
the
request.
operation
Name
of
the
requested
operation.
app_context
Attribute
list
containing
application-specific
context
access
control
information.
A
NULL
value
indicates
there
is
no
context
access
control
information.
The
attribute
list
handle
can
be
one
of
the
following:
v
An
attribute
list
handle
that
has
been
initialized
to
AZN_C_INVALID_HANDLE.
v
An
attribute
list
handle
for
a
new,
empty
attribute
list,
which
has
been
initialized
by
a
call
to
azn_attrlist_create().
v
An
attribute
list
handle
for
an
existing,
non-empty
attribute
list
which
contains
valid
data.
In
this
case,
attribute
list
data
is
appended
to
the
existing
attribute
list.
permission_info
Pointer
to
an
attribute
list
through
which
the
implementation
might
return
implementation-specific
information
about
the
decision.
If
a
NULL
value
is
passed
as
input,
then
no
information
will
be
returned.
Output
permission
Pointer
to
an
integer
variable
that
will
contain
the
appropriate
permission
code
upon
successful
completion
of
the
routine.
When
the
returned
status
value
is
AZN_S_COMPLETE,
the
returned
permission
is
either
AZN_C_PERMITTED
or
AZN_C_NOT_PERMITTED.
Appendix
B.
Authorization
service
plug-in
API
reference
239
When
the
returned
status
code
is
not
AZN_S_COMPLETE,
the
returned
permission
is
set
to
AZN_C_NOT_PERMITTED.
permission_info
Pointer
to
an
attribute
list
through
which
the
implementation
can
return
implementation-specific
information
about
the
decision.
When
a
NULL
pointer
is
passed
as
input,
no
information
is
returned.
The
information
contained
in
the
attribute
list
is
added
to
the
list
when
the
attribute
list
handle
is
one
of
the
following:
v
An
attribute
list
handle
for
a
new,
empty
attribute
list,
which
has
been
initialized
by
a
call
to
azn_attrlist_create().
v
An
attribute
list
handle
for
an
existing,
non-empty
attribute
list
which
contains
valid
data.
The
output
parameter
permission_info
can
be
used
to
return
implementation-specific
qualifiers
to
AZN_C_NOT_PERMITTED.
The
qualifiers
can
be
used
to
assist
the
calling
application
or
the
initiator
in
formulating
a
request
which
will
be
authorized.
Examples
of
such
qualifiers
might
include:
“not
permitted
yet,”
“requires
additional
privilege
attributes,”
or
“permissible
with
restrictions.”
For
more
information,
see
“Enabling
the
return
of
permission
information”
on
page
47.
Description
This
function
decides
whether
the
initiator
specified
by
the
credentials
chain
creds
is
authorized
to
perform
the
operation
operation
on
the
target
protected_resource.
Optionally,
callers
can
supply
application-specific
context
access
control
information
using
the
app_context
argument.
The
decision
is
returned
through
permission.
Optionally,
the
implementation
can
return
implementation-specific
information
about
the
decision
through
permission_info.
For
example,
the
information
can
indicate
which
rule
was
responsible
for
granting
or
denying
access.
Note:
This
function
uses
a
new
attribute
list
handle,
permission_info.
When
declaring
a
new
attribute
list
handle,
always
initialize
it
to
AZN_C_INVALID_HANDLE
before
using
it.
Return
Values
If
successful,
the
function
will
return
AZN_S_COMPLETE.
If
the
returned
status
code
is
not
equal
to
AZN_S_COMPLETE,
the
major
error
codes
will
be
derived
from
the
returned
status
code
with
azn_error_major().
v
AZN_S_COMPLETE
Successful
completion.
v
AZN_S_API_UNINITIALIZED
This
function
has
been
called
before
azn_initialize().
v
AZN_S_INVALID_CREDS_HDL
The
credentials
handle
supplied
is
invalid.
v
AZN_S_INVALID_PROTECTED_RESOURCE
The
target
name
is
invalid.
240
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
v
AZN_S_INVALID_OPERATION
The
operation
has
no
meaning
for
the
specified
target.
v
AZN_S_INVALID_PERMISSION_REF
The
integer
reference
to
return
the
permission
is
invalid.
v
AZN_S_INVALID_APP_CONTEXT_HDL
The
attribute
list
handle
for
the
context
access
control
information
(ACI)
is
invalid.
v
AZN_S_INVALID_ATTRLIST_HDL
The
attribute
list
handle
for
the
returned
permission
information
is
invalid.
v
AZN_S_UNIMPLEMENTED_FUNCTION
This
function
is
not
supported
by
the
implementation.
v
AZN_S_FAILURE
An
error
or
failure
has
occurred.
Use
azn_error_minor()
to
derive
specific
minor
error
codes
from
the
returned
status
code.
The
minor
error
code
ivacl_s_unauthorized
is
returned
when
the
caller
is
not
authorized
to
use
this
function.
Authorization
might
fail
because
the
caller
does
not
belong
to
the
correct
group
for
the
authorization
API
mode
(remote
or
local),
or
because
of
issues
specific
to
the
authentication
mechanism.
See
pdbaclmsg.h
for
a
complete
list
of
minor
error
codes
that
describe
access
control
problems.
Appendix
B.
Authorization
service
plug-in
API
reference
241
azn_svc_entitlement_get_entitlements()
Returns
entitlements
in
the
form
of
authorization
API
attributes.
Syntax
azn_status_t
azn_svc_entitlement_get_entitlements(
const
azn_creds_h_t
creds,
const
azn_string_t
entitlements_svc_id,
const
azn_attrlist_h_t
app_context,
azn_attrlist_h_t
*entitlements
);
Parameters
Input
creds
Handle
to
the
credentials
of
the
subject
whose
entitlements
are
to
be
returned.
The
credentials
handle
should
be
a
handle
for
an
existing,
non-empty
credentials
chain
which
contains
valid
data.
entitlements_svc_id
The
id
of
the
entitlement
service
to
be
used
app_context
Handle
to
an
attribute
list
containing
application-specific
or
entitlements-service-specific
context
information.
A
NULL
value
should
be
used
if
no
application
state
is
passed.
The
attribute
list
handle
can
be
one
of
the
following:
v
An
attribute
list
handle
that
has
been
initialized
to
AZN_C_INVALID_HANDLE.
v
An
attribute
list
handle
for
a
new,
empty
attribute
list,
which
has
been
initialized
by
a
call
to
azn_attrlist_create().
v
An
attribute
list
handle
for
an
existing,
non-empty
attribute
list
which
contains
valid
data.
In
this
case,
attribute
list
data
is
appended
to
the
existing
attribute
list.
Output
entitlements
Pointer
to
a
attribute
list
handle
variable
which
will
hold
the
entitlement
information
on
return.
The
attribute
list
handle
pointer
passed
as
the
entitlements
parameter
can
point
to
one
of
the
following:
v
A
attribute
list
handle
that
has
been
initialized
to
AZN_C_INVALID_HANDLE.
v
A
attribute
list
handle
for
a
new,
empty
attribute
list,
which
has
been
initialized
by
a
call
to
azn_attrlist_create().
v
An
attribute
list
handle
for
an
existing,
non-empty
attribute
list
which
contains
valid
data.
Description
Returns
entitlements
in
the
form
of
authorization
attributes
to
the
caller
from
an
external
entitlements
source.
242
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
This
uses
an
entitlement
service
identified
by
entitlements_svc_id
to
return
the
entitlements
of
an
initiator
identified
by
credentials
creds.
The
calling
application
may
pass
application-specific
or
entitlements-service-specific
context
data
using
an
attribute
list
app_context.
The
entitlements
are
returned
using
the
attribute
list
entitlements.
Note:
This
function
declares
a
new
attribute
list
handle,
entitlements.
When
declaring
a
new
attribute
list
handle,
always
initialize
it
to
AZN_C_INVALID_HANDLE
before
using
it.
The
constants
AZN_C_REQUEST_TIME,
AZN_C_AUTHN_QUALITY,
AZN_C_REQUESTER_LOC,
and
AZN_C_REQUEST_ROUTE_QOP,
may
be
used
as
name
attribute
of
entries
in
the
app_context
attribute
list
to
communicate
common
types
of
context
information.
Return
Values
If
successful,
the
function
returns
AZN_S_COMPLETE.
If
the
returned
status
code
is
not
equal
to
AZN_S_COMPLETE,
the
major
error
codes
can
be
derived
from
the
returned
status
code
with
azn_error_major().
v
AZN_S_COMPLETE
Successful
completion.
v
AZN_S_INVALID_CREDS_HDL
The
creds
handle
supplied
is
invalid.
v
AZN_S_INVALID_ENTITLEMENT_SVC
The
entitlement
service
identifier
is
invalid.
v
AZN_S_INVALID_APP_CONTEXT_HDL
The
attribute
list
handle
for
the
application
context
is
invalid.
v
AZN_S_INVALID_ENTITLEMENTS_HDL
The
attribute
list
handle
for
the
entitlements
is
invalid.
v
AZN_S_AUTHORIZATION_FAILURE
The
caller
does
not
possess
the
authority
required
to
invoke
this
function.
v
AZN_S_UNIMPLEMENTED_FUNCTION
This
function
is
not
supported
by
the
implementation.
v
AZN_S_FAILURE
An
implementation
specific
error
or
failure
has
occurred.
Implementation
specific
minor
error
codes
can
be
derived
from
the
returned
status
code
with
azn_error_minor().
Appendix
B.
Authorization
service
plug-in
API
reference
243
azn_svc_initialize()
Initialize
the
specified
authorization
service
plug-in.
Syntax
azn_status_t
azn_service_initialize(
const
int
argc,
const
char
**argv,
const
azn_attrlist_h_t
svcInit,
azn_attrlist_h_t
*svcInfo);
Description
Use
this
initialization
function
to
initialize
a
service
plug-in.
The
service
dispatcher
calls
this
function
prior
to
calling
the
functions
that
are
specific
to
each
plug-in.
For
example,
this
function
is
called
before
calling
azn_entitlement_get_entitlements()
to
obtain
entitlements
information
from
the
service
plug-in.
The
input
parameters
argc
and
argv
are
built
from
the
parameters
that
are
specified
in
the
service
definition
for
the
service
instance.
A
sample
service
definition
for
an
entitlement
service
named
entsvc
is:
entsvc
=
/lib/libentsvc.so
&
-server
barney
For
the
service
definition
above
azn_service_initialize()
is
called
with
an
argc
value
of
2.
The
argv
array
contains
the
following
values:
argv[0]
=
“-server”
argv[1]
=
“barney”
In
this
example,
the
argv
values
are
used
to
specify
the
server
system
where
the
entitlement
service
plug-in
is
to
be
loaded.
The
service
information
returned
by
the
service
plug-in
in
svc_info
can
contain
the
version
number
of
the
service.
This
value
is
defined
in
ogauthzn.h:
extern
azn_string_t
azn_svc_version;
The
service
plug-in
can
assume
that
the
service
dispatcher
will
release
the
attribute
list
returned
in
svc_info
when
it
has
finished
with
it.
Plug-ins
are
only
required
to
return
service
information
when
the
dispatcher
specifically
requests
this
information.
Input
parameters
should
not
be
modified.
The
prototype
for
this
function
is
included
in
the
file
azn_svc_protos.h,
in
the
Tivoli
Access
Manager
include
directory.
Parameters
Input
argc
The
number
of
arguments
contained
in
the
argv
array.
argv
The
string
arguments
passed
in
the
service
definition
for
this
service
instance.
244
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
svcInit
The
svcInit
parameter
is
an
attribute
list
containing
attributes
that
are
specified
by
the
service
dispatcher
to
either
configure
or
request
initialization
information
from
the
service
plug-in.
Output
svcInfo
The
svcInfo
parameter
is
a
list
of
attributes
returned
by
the
service
plug-in
to
request
specific
treatment
by
the
service
dispatcher
or
to
inform
the
service
dispatcher
of
the
operational
parameters
of
service.
An
example
of
the
information
listed
in
the
attributes
is
the
version
of
the
service.
Return
Values
If
successful,
the
function
will
return
AZN_S_COMPLETE.
If
the
returned
status
code
is
not
equal
to
AZN_S_COMPLETE,
the
major
error
codes
will
be
derived
from
the
returned
status
code
with
azn_error_major().
Each
of
the
following
error
messages
also
returns
an
implementation-specific
minor
error
code.
Use
azn_error_minor()
to
derive
specific
minor
error
codes
from
the
returned
status
code.
v
AZN_S_SVC_DEFINITION_ERROR
Returned
by
the
service
dispatcher
when
an
error
has
been
found
in
the
service
definition
in
the
authorization
API
configuration
file
aznapi.conf.
v
AZN_S_SVC_NOT_FOUND
Returned
by
the
service
dispatcher
when
an
error
occurs
either
while
locating
or
loading
an
authorization
API
service
plug-in.
v
AZN_S_SVC_INTERFACE_NOT_FOUND
Returned
by
the
service
dispatcher
when
an
error
occurs
either
locating
or
loading
a
service
interface
within
a
particular
plug-in.
For
example,
the
dispatcher
returns
this
error
if
the
azn_service_initialize()
interface
was
not
found
in
the
loaded
plug-in.
v
AZN_S_
SVC_INIT_FAILED
Returned
by
the
entitlement
service
plug-in
if
an
error
occurs
when
the
entitlement
service
is
initializing.
v
AZN_S_SVC_AUTHORIZATION_FAILURE
Returned
when
the
calling
application
does
not
have
sufficient
authority
to
invoke
the
services
of
this
service
plug-in.
v
AZN_S_SVC_ADMIN_INVALID_SVCINFO_HDL
The
svcInfo
passed
to
the
administration
service
plug-in
shared
library
is
invalid.
v
AZN_S_SVC_ADMIN_INVALID_ARG_COUNT
The
argument
count
argc
passed
to
the
administration
service
plug-in
shared
library
is
invalid.
v
AZN_S_SVC_ADMIN_INVALID_ARG_ARRAY
The
argument
array
passed
to
the
administration
service
plug-in
shared
library
is
invalid.
v
AZN_S_SVC_ADMIN_INVALID_ARGUMENT
One
or
more
of
the
arguments
passed
in
to
initialize
the
administration
service
plug-in
is
invalid.
v
AZN_S_FAILURE
Appendix
B.
Authorization
service
plug-in
API
reference
245
An
implementation
specific
error
or
failure
has
occurred.
An
implementation
specific
minor
error
code
should
be
returned
in
the
status
code
for
the
caller
to
extract
with
azn_error_minor().
246
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
azn_svc_pac_get_creds()
Returns
a
handle
to
new
credentials
chain
that
is
derived
from
a
privilege
attribute
certificate
(PAC)
by
a
specified
PAC
service.
Syntax
azn_status_t
azn_svc_pac_get_creds(
const
azn_buffer_t
pac,
const
azn_string_t
pac_svc_id,
azn_creds_h_t
*new_creds
);
Parameters
Input
pac
Buffer
structure
that
holds
the
supplied
PAC.
pac_svc_id
Identification
(id)
of
the
PAC
service
that
produces
the
credentials
chain.
Output
new_creds
Pointer
to
a
handle
to
the
returned
credentials
chain.
The
credentials
handle
pointer
passed
as
the
new_creds
parameter
can
be
one
of
the
following:
v
A
credentials
handle
that
has
been
initialized
to
AZN_C_INVALID_HANDLE.
v
A
credentials
handle
for
a
new,
empty
credential,
which
has
been
initialized
by
a
call
to
azn_creds_create().
In
this
case,
the
handle
is
updated
(overwritten)
with
new
credentials.
v
A
credentials
handle
for
an
existing,
non-empty
credential
chain
which
contains
valid
data.
In
this
case,
the
handle
is
updated
(overwritten)
with
new
credentials.
Description
This
function
uses
the
identified
PAC
service
(pac_svc_id)
to
build
a
new
credentials
chain
using
the
information
in
the
supplied
PAC
(pac).
Some
PAC
services
will
cryptographically
verify
the
protection
or
signature
on
the
received
PAC,
and
will
return
an
error
if
the
PAC
cannot
be
verified.
Note:
This
function
declares
a
new
credentials
handle,
new_creds.
When
declaring
a
new
credentials
handle,
always
initialize
it
to
AZN_C_INVALID_HANDLE
before
using
it.
This
function
decodes
PACs
that
are
built
by
azn_creds_get_pac().
Return
Values
If
successful,
the
function
will
return
AZN_S_COMPLETE.
If
the
returned
status
code
is
not
equal
to
AZN_S_COMPLETE,
the
major
error
codes
will
be
derived
from
the
returned
status
code
with
azn_error_major().
Appendix
B.
Authorization
service
plug-in
API
reference
247
v
AZN_S_COMPLETE
Successful
completion.
v
AZN_S_API_UNINITIALIZED
This
function
has
been
called
before
azn_initialize().
v
AZN_S_INVALID_PAC
The
PAC
is
invalid
or
could
not
be
verified
by
the
PAC
service.
v
AZN_S_INVALID_PAC_SVC
The
id
of
the
PAC
service
is
invalid.
v
AZN_S_INVALID_NEW_CREDS_HDL
The
credentials
handle
supplied
for
new_creds
is
invalid.
v
AZN_S_UNIMPLEMENTED_FUNCTION
This
function
is
not
supported
by
the
implementation.
v
AZN_S_SVC_SERVICE_NOT_FOUND
The
service
with
the
specified
identification
number
was
not
found
in
the
list
of
configured
services.
v
AZN_S_SVC_AUTHORIZATION_FAILED
The
caller
is
not
authorized
to
make
calls
to
the
service.
The
minor
error
code
contains
additional
information
about
the
reason
for
the
failure.
v
AZN_S_SVC_DISPATCHER_FAILURE
The
service
dispatcher
failed.
This
can
be
caused
by
incorrect
initialization
of
the
authorization
API.
v
AZN_S_FAILURE
An
error
or
failure
has
occurred.
Use
azn_error_minor()
to
derive
specific
minor
error
codes
from
the
returned
status
code.
The
minor
error
code
ivacl_s_unauthorized
is
returned
when
the
caller
is
not
authorized
to
use
this
function.
Authorization
might
fail
because
the
caller
does
not
belong
to
the
correct
group
for
the
authorization
API
mode
(remote
or
local),
or
because
of
issues
specific
to
the
authentication
mechanism.
See
pdbaclmsg.h
for
a
complete
list
of
minor
error
codes
that
describe
access
control
problems.
248
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
azn_svc_shutdown()
Shut
down
the
specified
service
plug-in.
Syntax
azn_status_t
azn_svc_shutdown(
const
int
argc,
const
char
**argv,
const
azn_attrlist_h_t
svcInit,
azn_attrlist_h_t
*svcInfo
);
Description
The
authorization
API
service
dispatcher
calls
this
interface
to
shut
down
the
specified
authorization
service
plug-in
as
part
of
shutting
down
the
authorization
API.
The
input
parameters
argc
and
argv
are
built
from
the
parameters
that
were
specified
in
the
service
definition
for
this
service
instance.
A
sample
configuration
file
entry
for
an
entitlement
service
named
entsvc
is:
entsvc
=
/lib/libentsvc.so
&
-server
barney
For
the
service
definition
above
azn_svc_shutdown()
is
called
with
an
argc
value
of
2.
The
argv
array
contains
the
following
values:
argv[0]
=
“-server”
argv[1]
=
“barney”
The
service
plug-in
can
assume
that
the
service
dispatcher
will
release
the
attribute
list
returned
in
svvInfo
when
it
has
finished
with
it.
Information
that
may
be
requested
of
the
service
during
shutdown
is
not
currently
defined
but
may
be
defined
by
the
interface
in
future.
The
prototype
for
this
function
is
included
in
the
file
azn_svc_protos.h,
in
the
Tivoli
Access
Manager
include
directory.
Parameters
Input
argc
The
number
of
arguments
in
the
argv
array.
argv
The
string
arguments
contained
in
the
service
definition
for
this
service
instance.
svcInit
The
svcInit
parameter
is
an
attribute
list
containing
attributes
that
are
specified
by
the
dispatcher
to
either
unconfigure
or
request
information
from
the
service
plug-in
after
shutdown
is
complete.
Output
svcInfo
The
svcInfo
parameter
is
a
list
of
attributes
returned
by
the
entitlement
service
Appendix
B.
Authorization
service
plug-in
API
reference
249
to
request
specific
treatment
by
the
service
dispatcher
or
to
inform
the
service
dispatcher
of
the
results
of
service
shutdown.
Return
Values
If
successful,
the
function
will
return
AZN_S_COMPLETE.
If
the
returned
status
code
is
not
equal
to
AZN_S_COMPLETE,
the
major
error
codes
will
be
derived
from
the
returned
status
code
with
azn_error_major().
v
AZN_S_
SVC_SHUTDOWN_FAILED
Returned
by
the
authorization
service
plug-in
when
an
error
occurs
while
it
is
shutting
down.
v
AZN_S_FAILURE
An
implementation
specific
error
or
failure
has
occurred.
An
implementation
specific
minor
error
code
should
be
returned
in
the
status
code
for
the
caller
to
extract
with
azn_error_minor().
250
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
Appendix
C.
Attribute
names
reference
This
reference
lists
the
names
of
attributes
that
are
provided
with
the
Tivoli
Access
Manager
authorization
API.
The
attributes
are
grouped
according
to
the
area
of
the
API
to
which
they
apply.
Attribute
groupings:
v
“Initialization
attributes”
on
page
252
v
“Permission
information
attributes”
on
page
263
v
“Credential
attributes”
on
page
261
v
“Authorization
API
service
plug-in
attributes”
on
page
268
v
“Authorization
engine
attributes”
on
page
271
©
Copyright
IBM
Corp.
2000,2003
251
Initialization
attributes
Initialization
attributes
are
used
to
configure
the
Tivoli
Access
Manager
authorization
API
client
runtime.
They
are
passed
in
the
init_data
parameter
to
the
azn_initialize()
function.
The
attributes
described
in
the
following
table
are
reserved
by
the
authorization
API
client
runtime
for
use
with
its
own
internal
configuration.
Customers
can
specify
their
own
initialization
parameters
to
pass
to
custom
authorization
API
services
such
as
credential
modification
and
entitlement
services.
All
attributes,
unless
specified
otherwise,
are
of
type
azn_string_t.
Attribute
Description
azn_app_host
Authorization
API
application
host
azn_code_set_local
String
that
specifies
local
code
set.
For
use
with
the
azn_init_set_code_set()
function
and
with
the
azn_svc_init_code_set
service
initialization
attribute.
azn_code_set_utf8
String
that
specifies
UTF-8
codeset.
For
use
with
the
azn_init_set_code_set()
function
and
with
the
azn_svc_init_code_set
service
initialization
attribute.
azn_init_admin_svc
Administration
service
definition
attribute
Multi-valued
string
attributes
for
use
with
azn_initialize().
Each
string
value
is
of
the
format:
service_id
=
path_to_dll[¶meters
...
]
The
service_id
is
the
string
by
which
the
service
can
be
identified
by
the
authorization
API
client.
The
path_to_dll
is
the
fully
qualified
path
to
the
DLL
which
contains
the
service
executable
code.
Optionally
you
can
specify
parameters
to
pass
to
the
service
when
it
is
initialized
by
the
authorization
API.
The
parameters
are
considered
to
be
all
data
following
the
&
symbol
in
the
string.
azn_init_audit_attribute
Audit
additional
credential
or
application-specific
attribute.
azn_init_auditcfg
Audit
logging
configuration.
A
multi-valued
attribute
containing
entries
of
the
format:
module_id[:trace_level]
azn_init_audit_file
Audit
log
path
and
file
name
to
collect
Tivoli
Access
Manager
audit
events.
azn_init_cache_refresh_interval
Interval
in
seconds
for
local
policy
cache
polled
updates.
Values
can
be:
v
disable
v
default
v
a
string
time
in
seconds.
azn_init_cfg_file
Path
and
filename
to
be
used
to
contain
remaining
initialization
parameters.
252
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
azn_init_cred_attribute_entitlement_services
A
list
of
configured
authorization
API
entitlement
service
IDs
that
are
queried
by
azn_id_get_creds()
after
the
credential
is
built,
in
order
to
gather
attributes
to
be
placed
in
the
credential
for
attribute-based
authorization.
Each
service
ID
is
called
according
to
the
order
of
the
values
in
this
initialization
attribute
azn_init_cred_mod_svc
Credential
modification
service
definition
attribute.
Multi-valued
string
attributes
for
use
with
azn_initialize().
Each
string
value
is
of
the
format:
service_id
=
path_to_dll[¶meters
...
]
The
service_id
is
the
string
by
which
the
service
can
be
identified
by
the
authorization
API
client.
The
path_to_dll
is
the
fully
qualified
path
to
the
DLL
which
contains
the
service
executable
code.
Optionally
you
can
specify
parameters
to
pass
to
the
service
when
it
is
initialized
by
the
authorization
API.
The
parameters
are
considered
to
be
all
data
following
the
&
symbol
in
the
string.
azn_init_db_file
Path
and
filename
to
be
used
to
contain
cached
authorization
policy.
azn_init_dynamic_adi_entitlement_services
A
list
of
configured
authorization
API
entitlement
service
IDs
that
will
be
queried
by
the
rules
engine
when
missing
ADI
is
detected
during
an
authorization
rule
evaluation.
Entitlement
services
listed
as
values
for
this
attribute
must
adhere
to
the
input
and
output
specifications
for
a
dynamic
ADI
retrieval
service.
When
ADI
is
found
to
be
missing
during
a
rule
evaluation,
each
service
in
this
list
is
queried
in
the
order
defined
in
this
entry.
These
entries
must
refer
to
existing
entitlement
services
that
were
loaded
by
service
entries
in
the
entitlement
service
configuration
stanza
or
initialization
attribute.
azn_init_ent_svc
Entitlement
service
definition
attribute.
Multi-valued
string
attributes
for
use
with
azn_initialize().
Each
string
value
is
of
the
format:
service_id
=
path_to_dll[¶meters
...
]
The
service_id
is
the
string
by
which
the
service
can
be
identified
by
the
authorization
API
client.
The
path_to_dll
is
the
fully
qualified
path
to
the
DLL
which
contains
the
service
executable
code.
Optionally
you
can
specify
parameters
to
pass
to
the
service
when
it
is
initialized
by
the
authorization
API.
The
parameters
are
considered
to
be
all
data
following
the
&
symbol
in
the
string.
azn_init_extern_authzn_svc
Appendix
C.
Attribute
names
reference
253
External
authorization
service
definition
attribute.
Multi-valued
string
attributes
for
use
with
azn_initialize().
Each
string
value
is
of
the
format:
service_id
=
path_to_dll[¶meters
...
]
The
service_id
is
the
string
by
which
the
service
can
be
identified
by
the
authorization
API
client.
The
path_to_dll
is
the
fully
qualified
path
to
the
DLL
which
contains
the
service
executable
code.
Optionally
you
can
specify
parameters
to
pass
to
the
service
when
it
is
initialized
by
the
authorization
API.
The
parameters
are
considered
to
be
all
data
following
the
&
symbol
in
the
string.The
external
authorization
service
can
take
an
additional
optional
-weight
parameter
as
follows:
service_id
=
path_to_dll[
-weight
N
]
[
&
params
...
]
The
value
N
can
be
any
unsigned
long
value
whose
absolute
value
is
used
to
appropriately
weight
the
decision
of
an
external
authorization
service
for
or
against
access
to
the
object.
The
default
value
for
an
external
authorization
service
if
this
is
not
specified
is
set
to
the
value
AZN_C_DEFAULT_EAS_WEIGHTING.
The
assigned
weighting
of
the
core
authorization
engine
is
AZN_C_AUTHZN_ENGINE_WEIGHTING.
azn_init_input_adi_xml_prolog
XML
prolog
text
for
XMLADI
input
document.
This
text
is
appended
to
the
XML
input
document
that
is
created
from
the
rule
ADI
passed
in
the
application
context
and
credential
attributes.
The
default
text
is:
<?xml
version="1.0"
encoding="UTF-8"?>
azn_init_listen_flags
Flags
to
enable
the
reception
of
policy
cache
update
notifications.
Values
can
be
a
combination
of
the
following:
v
disable
This
value
overrides
all
others
and
disables
the
notification
listener.
v
enable
v
use_tcp_port
v
use_udp_port
v
dynamic_port_selection
Multiple
values
are
accepted
for
this
attribute
name
and
are
logically
OR’d
together
azn_init_ldap_authn_timeout
Client
side
timeout
setting
for
communications
to
LDAP
servers.
The
azn_init_ldap_timeout
parameter
is
an
overall
setting.
This
may
be
overridden
for
authentication
(bind
and
compare)
and
search
by
specifying
the
azn_init_ldap_authn_timeout
and/or
the
azn_init_ldap_search_timeout
parameters
respectively.
Specified
in
seconds
as
a
string
value.
By
default,
or
with
a
value
of
zero
(0),
LDAP
requests
will
not
timeout.
azn_init_ldap_bind_dn
The
distinguished
name
with
which
to
bind
to
the
LDAP
server.
azn_init_ldap_bind_pwd
The
password
for
the
distinguished
name
that
binds
to
the
LDAP
server.
254
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
azn_init_ldap_cache
Enables
caching
of
the
user,
group,
and
LDAP
policy
data
in
the
client
to
reduce
the
turnaround
of
similar
LDAP
transactions.
The
string
value
can
be
true
or
false.
The
default
value
is
false.
azn_init_ldap_host
The
LDAP
server
host
name.
azn_init_ldap_max_search_size
Set
the
maximum
number
of
entries
returned
from
an
LDAP
search.
Note
that
this
value
can
be
further
constrained
by
the
limits
set
by
the
LDAP
server.
azn_init_ldap_port
The
LDAP
server
host
port
(a
numerical
string).
This
is
the
SSL
port
when
SSL
communication
with
the
LDAP
host
is
to
be
enabled.
azn_init_ldap_prefer_rw_svr
Makes
the
writable
LDAP
server
the
preferred
one
for
the
client.
Calls
will
still
failover
to
a
read-only
server
when
the
write
server
is
offline.
The
string
value
can
be
true
or
false
The
default
value
is
false.
azn_init_ldap_replica
A
list
of
LDAP
server
replicas.
Each
string
value
is
of
the
format:
ldap_server,port,type,pref
The
values
are:
v
ldap_server
The
network
name
of
the
server.
v
port
The
port
on
the
LDAP
server.
v
type
Must
be
one
of
the
following
values
–
readonly
–
readwrite
v
pref
A
level
from
1
to
10.
10
is
the
highest
preference.
azn_init_ldap_search_timeout
Client
side
timeout
setting
for
communications
to
LDAP
servers.
The
azn_init_ldap_timeout
parameter
is
an
overall
setting.
This
may
be
overridden
for
authentication
(bind
and
compare)
and
search
by
specifying
the
azn_init_ldap_authn_timeout
and/or
the
azn_init_ldap_search_timeout
parameters
respectively.
Specified
in
seconds
as
a
string
value.
By
default,
or
with
a
value
of
zero
(0),
LDAP
requests
will
not
timeout.
azn_init_ldap_ssl_keyfile
The
LDAP
server’s
SSL
keyfile.
This
must
be
non-NULL
to
use
SSL
communication
with
the
LDAP
host.
azn_init_ldap_ssl_keyfile_dn
Appendix
C.
Attribute
names
reference
255
The
LDAP
server’s
SSL
keyfile
distinguished
name.
azn_init_ldap_ssl_keyfile_pwd
The
LDAP
server’s
SSL
keyfile
password.
azn_init_ldap_timeout
Client
side
timeout
setting
for
communications
to
LDAP
servers.
The
azn_init_ldap_timeout
parameter
is
an
overall
setting.
This
may
be
overridden
for
authentication
(bind
and
compare)
and
search
by
specifying
the
azn_init_ldap_authn_timeout
and/or
the
azn_init_ldap_search_timeout
parameters
respectively.
Specified
in
seconds
as
a
string
value.
By
default,
or
with
a
value
of
zero
(0),
LDAP
requests
will
not
timeout.
azn_init_ldap_use_compare
Chooses
whether
the
client
uses
the
ldap_compare
or
the
ldap_bind
call
to
authenticate
the
users
password.
This
applies
to
calls
to
azn_util_client_authenticate()
and
azn_util_password_authenticate()
with
an
LDAP
registry.
The
string
value
can
be
true
or
false
The
default
value
is
false,
which
means
to
use
the
ldap_bind
call.
azn_init_logging_client_id
String
ID
or
tag
to
identify
the
client
authorization
API
client.
Default
string:
aznAPI
azn_init_log_size
The
maximum
size
(in
bytes)
for
the
audit
and
debug
files.
When
the
log
size
reaches
this
value,
the
log
is
backed
up
and
a
new
log
file
is
started.
A
value
of
0
will
disable
log
rollover.
A
negative
value
will
perform
rollover
daily
regardless
of
size.
azn_init_log_flush_interval
The
audit/debug
logging
service
flush
interval
in
seconds.
A
value
of
0
sets
the
default
of
20
seconds.
Maximum
value:
3600
seconds
(6
hours).
azn_init_master_host
The
azn_init_master_host
attribute
refers
to
the
location
of
the
policy
server
(ivmgrd).
See
the
description
for
azn_init_replica
azn_init_master_port
The
azn_init_master_port
attribute
refers
to
the
location
of
the
policy
server
(ivmgrd).
See
the
description
for
azn_init_replica.
azn_init_mode
Authorization
API
authorization
engine
mode.
Valid
values
are:
v
local
This
means
you
are
using
a
policy
cache
replica
v
remote
Making
requests
to
the
authorization
server.
No
local
policy
cache.
azn_init_pac_svc
256
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
Privilege
attribute
certificate
service
definition
attribute.
Multi-valued
string
attributes
for
use
with
azn_initialize().
Each
string
value
is
of
the
format:
service_id
=
path_to_dll[¶meters
...
]
The
service_id
is
the
string
by
which
the
service
can
be
identified
by
the
authorization
API
client.
The
path_to_dll
is
the
fully
qualified
path
to
the
DLL
which
contains
the
service
executable
code.
Optionally
you
can
specify
parameters
to
pass
to
the
service
when
it
is
initialized
by
the
authorization
API.
The
parameters
are
considered
to
be
all
data
following
the
&
symbol
in
the
string.
azn_init_replica
The
azn_init_replica
attribute
is
the
location
of
an
authorization
(ivacld)
server.
There
can
be
more
than
one
azn_init_replica.
Used
in
conjunction
with
azn_init_master_host
and
azn_init_master_port.
The
authorization
server
replicas
are
of
the
format:
replica_hostname:port:preference
The
values
are:
v
replica_hostname
The
network
name
of
the
server.
v
port
The
port
on
the
server.
v
preference
A
ranking
for
attempting
contact.
Level
from
1
to
10.
10
is
the
highest
preference.
azn_init_resource_mgr_provided_adi
Resource
manager
ADI
prefix
list.
A
list
of
string
prefixes
that
identify
Access
Decision
Information
(ADI)
to
be
supplied
by
the
resource
manager.
The
resource
manager
is
the
authorization
API
client.
This
list
tells
the
authorization
engine
that
whenever
it
needs
ADI
that
has
one
of
the
prefixes
listed,
and
the
ADI
is
not
available
in
the
credential
or
application
context
passed
in
with
the
azn_decision_access_allowed_ext()
call,
that
the
engine
should
fail
the
access
decision
and
request
that
the
resource
manager
retry
the
request
and
provide
the
required
data
in
the
application
context
of
the
next
request.
For
example,
WebSEAL
as
an
Authorization
API
clients
uses
this
configuration
entry
to
notify
the
authorization
engine
that
it
is
a
source
for
HTTP
transaction
data
needed
for
rule
evaluations.
azn_init_set_perminfo_attrs
This
initialization
parameter
contains
the
set
of
attributes
that
the
caller
is
interested
in
receiving
from
the
azn_decision_access_allowed_ext()
call
in
the
permission
info
attribute
list.
By
default
there
is
no
information
returned
by
this
call.
Adding
a
value
to
this
attribute
at
initialization
time
enables
the
attribute
to
be
returned
as
permission
info
if
it
is
applicable
to
the
current
decision
call.
This
list
may
also
include
attributes
that
are
user
defined,
such
as
by
setting
an
attribute
on
an
ACL
or
POP
using
modify
set
attribute
command
of
pdadmin.
The
values
for
this
parameter
are
described
in
“Permission
information
attributes”
on
page
263.
Appendix
C.
Attribute
names
reference
257
azn_init_ssl_authn_type
The
type
of
authentication.
Possible
values
are:
v
certificate
v
password
v
none
The
default
value
is
none.
This
is
the
method
that
the
Tivoli
Access
Manager
policy
server
will
use
to
authenticate
the
authorization
API
client.
The
svrsslcfg
utility
automatically
sets
this
to
certificate.
If
the
value
is
certificate
the
Tivoli
Access
Manager
policy
server
will
map
the
certificate
provided
by
the
authorization
API
client
into
an
identity
and
authenticate
against
it.
Note
that
even
if
password
or
none
are
specified,
the
client
will
still
use
SSL
to
communicate
with
the
server.
azn_init_ssl_authn_user
The
user
name
that
is
used
if
the
authentication
type
is
password.
It
may
be
unwise
to
store
this
in
the
configuration
file,
however
it
can
be
useful
for
testing
communications.
Can
be
any
string.
azn_init_ssl_authn_pwd
The
password
that
is
used
if
the
authentication
type
is
password.
It
may
be
unwise
to
store
this
in
the
configuration
file,
however
it
can
be
useful
for
testing
communications.
azn_init_ssl_auto_refresh
Enables
or
disables
automatic
refresh
of
the
SSL
certificate
and
key
database
file
password.
When
enabled,
the
certificate
is
renewed
when
it
is
close
to
expiration.
This
means
that
the
same
public
key
gets
a
renewed
signature
from
the
certificate
authority,
which
results
in
an
extended
lifetime
for
the
certificate.
A
value
of
yes
enables
automatic
refresh.
A
value
of
no
disables
automatic
refresh.
azn_init_ssl_cert_life
SSL
certificate
life
span
for
the
principal.
Expressed
as
number
of
days.
Default
value
365.
azn_init_ssl_io_inactivity_timeout;
Inactivity
timeout
for
the
input/output
connection,
expressed
in
seconds.
The
value
is
an
integer.
The
minimum
value
is
0.
When
the
value
is
0,
no
timeout
is
enforced.
The
default
value
is
0
seconds.
The
recommended
value
is
90
seconds.
azn_init_ssl_keyfile
This
is
the
keyfile
used
to
communicate
with
the
Tivoli
Access
Manager
policy
server
and
the
Tivoli
Access
Manager
authorization
server.
It
is
created
by
the
svrsslcfg
utility.
This
can
be
any
relative
or
fully
qualified
filename.
azn_init_ssl_keyfile_label
258
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
The
label
of
the
certificate
to
use
within
the
keyfile.
In
normal
operation
this
is
not
used.
However
it
is
useful
if
the
keyfiles
are
constructed
outside
of
the
svrsslcfg
utility
and
contain
multiple
certificates.
This
can
be
any
string.
azn_init_ssl_keyfile_pwd
Password
used
to
protect
keys
in
the
keyfile.
The
value
is
a
string.
azn_init_ssl_listening_port
Use
this
value
to
specify
the
TCP
port
on
which
the
application
will
listen
for
notifications
from
the
master
database
that
is
has
changed.
All
communications
on
this
port
are
SSL
encrypted.
The
value
should
be
non-zero
and
not
used
by
any
other
service
on
the
computer.
azn_init_ssl_local_domain
The
domain
in
which
the
authorization
server
runs.
If
this
value
is
not
specified
in
the
configuration
file
or
as
an
initialization
parameter,
operations
that
rely
on
it
will
fail.
This
value
must
match
the
name
of
the
Tivoli
Access
Manager
secure
domain
that
was
specified
when
the
authorization
server
was
configured.
The
value
is
a
string.
azn_init_ssl_max_worker_threads
Maximum
number
of
worker
threads
that
are
created
by
the
server
to
handle
incoming
requests.
The
value
is
an
integer.
The
minimum
number
is
1.
The
maximum
number
is
determined
by
the
amount
of
system
resources
available.
The
default
number
is
50.
azn_init_ssl_mgr_config
The
relative
or
fully
qualified
path
name
to
the
pd.conf
file.
This
entry
is
used
to
point
to
the
configuration
file
that
was
created
as
part
of
configuring
the
Tivoli
Access
Manager
runtime
environment
(pd.conf).
When
it
is
specified,
the
values
for
master-host,
master-port,
and
master-dn
will
come
from
the
manager
stanza
of
pd.conf
and
override
any
values
specified
in
the
authorization
API
client’s
configuration
file.
azn_init_ssl_pwd_life
This
is
the
amount
of
time
before
the
password
or
stash
file
to
the
keyfile
will
expire.
The
Tivoli
Access
Manager
authorization
API
client
automatically
refreshes
the
password
or
stash
file
before
this
expiry
time,
if
automatic
refresh
is
enabled.
Can
be
any
non-negative
integer.
Default
value
is
183
days.
azn_init_ssl_stashfile
This
the
stash
file
for
the
keyfile.
It
is
created
by
the
svrsslcfg
utility.
It
is
used
as
an
obfuscated
password
to
the
keyfile.
This
file
should
be
appropriately
secured.
This
can
be
any
relative
or
fully
qualified
filename.
azn_init_ssl_timeout
Appendix
C.
Attribute
names
reference
259
This
is
the
amount
of
time
before
an
SSL
session
will
expire.
The
Tivoli
Access
Manager
authorization
API
client
automatically
create
a
new
SSL
session
with
new
keys
when
a
session
expires.
Can
be
any
non-negative
integer.
Default
value
is
7200
seconds.
azn_init_uraf_bind_id
URAF
registry
bind
ID
azn_init_uraf_bind_pwd
Password
for
URAF
registry
bind
ID
azn_init_uraf_cache_lifetime
URAF
cache
lifetime,
default
value
is
86400
sec.
(one
day)
azn_init_uraf_cache_mode
Enable
or
disable
URAF
cache.
The
default
value
is
disable.
azn_init_uraf_cache_size
URAF
cache
size.
The
default
value
is
251.
azn_init_uraf_cfg_file
URAF
registry
configuration
file
name.
azn_init_xmladi_attribute_definitions
XMLADI
attribute
definitions.
These
attribute
definitions
are
inserted
into
the
XMLADI
element
start
tag
to
enable
attributes
to
be
defined
for
the
entire
XMLADI
document
and
all
ADI
defined
therein.
The
programmatic
initialization
attribute
can
contain
multiple
attribute
values,
one
for
each
attribute
definition
to
be
added
to
the
XMLADI
element
start
tag.
The
attribute
definitions
are
in
the
format:
attribute_name
=
″attribute_value″
For
example:
xmlns:myNS
=
"http://myURI.mycompany.com"
appID
=
’"Jupiter"
-
Account
Management
Web
\
Portal
Server
#1.’
The
XMLADI
element
start
tag
built
from
these
definitions
is:
<XMLADI
xmlns:myNS="http://myURI.mycompany.com"
\
appID=’"Jupiter"
-
Account
Management
Web
Portal
\
Server
#1.’>
azn_init_xsl_stylesheet_prolog
XSL
prolog
text
for
the
XSL
rule
document.
This
text
is
appended
to
the
XSL
rule
document
that
is
created
from
the
rule
text
in
the
rule
policy
object.
This
allows
you
to
control
aspects
of
the
XSL
evaluation
process.
Modifying
this
value
is
not
recommended
as
it
can
affect
the
results
returned
by
the
processor
and
make
them
unrecognizable
by
the
rules
policy
evaluator.
To
review
the
default
text,
see
ogauthzn.h.
This
file
is
distributed
with
the
Tivoli
Access
Manager
ADK.
azn_server_name
Authorization
API
authorization
server
name
260
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
Credential
attributes
Authorization
credential
attribute
names.
Credential
attributes
are
stored
within
the
authorization
credential
of
a
user.
These
attributes
contain
information
on
the
identity
and
authorization
capability
of
the
subject
of
the
credential.
The
authorization
API
runtime
reserves
a
number
of
attributes
for
its
own
use
and
for
implementing
the
Tivoli
Access
Manager
authorization
model.
The
reserved
attributes
are
listed
in
this
section.
Some
of
the
reserved
credential
attributes
are
treated
as
read-only
by
the
authorization
API
client
runtime
because
the
information
that
they
convey
about
the
user
is
immutable
and,
if
changed,
would
alter
the
identity
of
the
user.
Other
attributes
can
be
modified
if
the
appropriate
credential
modification
service
is
used
to
do
so.
These
attributes
are
returned
by
the
azn_creds_get_attrlist_for_subject()
call.
Some
of
these
may
not
be
present
according
to
the
type
of
the
authenticated
user
and
the
information
that
was
originally
passed
to
the
call
used
to
build
a
given
credential.
Attribute
Description
″AUTHENTICATION_LEVEL″
This
AUTHENTICATION_LEVEL
credential
attribute
can
be
used
to
indicate
the
strength
of
the
authentication
mechanism
used
to
authenticate
the
user.
This
attribute
is
added
to
the
credential
by
Tivoli
Access
Manager
for
e-Business
as
part
of
the
authentication
process
if
authentication
levels
have
been
appropriately
configured
in
the
Tivoli
Access
Manager
configuration
file.
The
attribute
is
used
by
the
Tivoli
Access
Manager
authorization
engine
to
implement
step-up
authorization
and
IP
authorization
which
require
that
the
user
have
a
particular
level
authentication
for
access
to
protected
resources.
Customer’s
authorization
API
applications
may
also
add
the
AUTHENTICATION_LEVEL
attribute
to
user
credentials
so
as
to
make
use
of
step-up
authorization
and
IP
authorization
policy
that
has
been
deployed
in
the
secure
domain.
The
Tivoli
Access
Manager
authorization
engine
requires
that
the
AUTHENTICATION_LEVEL
attribute
have
a
single
numeric
value
with
0
indicating
an
unauthenticated
user
and
other
numbers,
1,
2,
3,
etc,
each
indicating
a
successively
higher
(stronger)
method
of
authentication.
azn_cred_auth_method
Any
authentication
method
information
that
was
passed
in
the
mechinfo
structure.
This
is
specified
by
caller
of
the
API.
For
example:
X509
certificate
azn_cred_authnmech_info
Any
authentication
mechanism
information
that
was
passed
in
the
mechinfo
structure.
This
is
specified
by
caller
of
the
API.
For
example:
IBM
Tivoli
Demo
Client
v5.1.0
azn_cred_authzn_id
The
user
name
or
identifier
used
to
build
the
authorization
credentials.
azn_cred_browser_info
The
browser
information
passed
in
the
mechinfo
structure.
This
is
specified
by
caller
of
the
API.
For
example:
Mozilla
azn_cred_group_registry_ids
Appendix
C.
Attribute
names
reference
261
The
string
group
name
memberships
(group
DN)
of
this
entity.
azn_cred_group_uuids
The
string
group
UUID
memberships
of
this
entity.
Each
value
is
a
UUID,
similar
to
the
value
shown
in
the
azn_cred_principal
uuid
example.
azn_cred_groups
The
string
group
name
memberships
of
this
entity.
Values
are
strings.
For
example,
engineering
azn_cred_ip_address
The
IP
address
information
passed
in
the
mechinfo
structure.
Specified
by
caller.
This
is
the
string
representation
of
the
IP
address
in
network
order.
For
example:
0x12657834
azn_cred_mech_id
The
mechanism
ID
for
this
credential.
The
ID
depends
on
the
registry
from
which
the
credential
was
built.
For
example,
when
build
from
LDAP
it
is
IV_LDAP_V3.0.
When
built
from
Domino
or
AD,
it
is
IV_URAF_V3.0.
When
the
user
credentials
are
unauthenticated,
it
is
IV_UNAUTH_V3.0.
azn_cred_principal_domain
The
local
domain
into
which
the
user
is
authenticated
(and
therefore
the
domain
in
which
the
credential
is
created).
azn_cred_principal_name
The
string
name
of
the
entity.
For
example:
fred_smith
azn_cred_principal_uuid
The
universal
unique
identifier
(UUID)
of
the
entity.
For
example:
eb529fec-6498-11d7-b236-000629ba5445
azn_cred_qop_info
The
quality
of
protection
information
passed
in
the
mechanism_info
structure.
Valid
values
are:
v
none
v
integrity
v
privacy
azn_cred_registry_id
The
registry
ID
used
to
build
these
authorization
credentials.
azn_cred_user_info
Any
user
information
that
was
passed
in
the
mechinfo
structure
that
was
defined
by
the
caller.
For
example:
Dr
Fred
Oscar
Smith
III
azn_cred_version
The
credential
version.
For
Tivoli
Access
Manager
5.1.0,
the
version
is
0x510.
262
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
Permission
information
attributes
Permission
information
attributes
are
returned
to
the
caller
of
azn_decision_access_allowed_ext()
by
the
Tivoli
Access
Manager
authorization
engine.
These
attributes
convey
information
about
the
result
of
the
access
decision
or
conditions
placed
upon
the
result
by
the
authorization
engine.
Permission
information
may
also
consist
of
the
extended
attributes
that
are
attached
to
the
target
protected
resource,
or
to
the
authorization
policy
attached
to
that
resource.
Tivoli
Access
Manager
reserves
the
permission
information
attributes
described
in
this
section
in
order
to
return
permission
information
to
the
Tivoli
Access
Manager
authorization
API
authorization
client.
These
attributes
are
returned
by
the
azn_decision_access_allowed_ext()
call.
Some
of
these
may
not
be
present
in
all
permission_info
attribute
lists
returned
according
to
the
type
of
the
access
decision
and
the
information
that
was
originally
passed
in
with
the
call.
These
attribute
names
may
also
be
passed
in
to
the
azn_initialize()
call
as
values
for
the
azn_init_set_perminfo_attrs
attribute
to
control
which
of
them
are
returned
as
permission
info
for
any
decision
call.
The
default
is
that
no
permission
information
is
returned.
All
values
are
azn_string_t
unless
otherwise
specified.
Attribute
Description
azn_acl_ext_attr_loc
When
ACL
extended
attributes
are
returned
by
the
access
decision
call,
this
attribute
holds
the
place
in
the
object
space
to
which
the
ACL
is
attached.
Use
azn_attrlist_add_entry()
to
set
this
value
in
the
azn_init_set_perminfo_attrs
attribute
in
the
init_data
parameter
to
the
azn_initialize()
call.
azn_dynadi_target_url
This
attribute
is
specific
to
WebSEAL
and
the
attribute
retrieval
service
(AMWebARS).
The
value
is
the
full
target
URL
that
the
caller
is
requesting.
This
is
required
by
AMWebARS
in
order
to
enable
it
to
return
the
browser
to
the
original
requested
URL
once
its
interaction
with
the
user
is
complete.
This
attribute
is
passed
into
the
access
decision
by
WebSEAL.
azn_perminfo_all_attrs
This
value
is
passed
in
the
azn_init_set_perminfo_attrs
attribute
to
azn_initialize()
to
specify
that
the
caller
wished
to
receive
all
attributes
that
can
potentially
be
returned
by
the
authorization
engine
on
an
extended
authorization
decision
call.
This
overrides
any
other
attributes
passed
in
the
azn_init_set_perminfo_attrs
attribute.
azn_perminfo_auditlevel_ulong
Appendix
C.
Attribute
names
reference
263
Audit
level.
Audit
events
that
are
performed
for
this
authorization
check.
The
caller
needs
to
use
azn_attrlist_add_entry()
to
set
this
value
in
the
azn_init_set_perminfo_attrs
attribute
in
the
init_data
parameter
to
the
azn_initialize()
call.
The
caller
needs
to
use
the
azn_attrlist_get_entry_ulong()
API
to
retrieve
this
attribute
from
the
permission_info
output
parameter
of
the
azn_decision_access_allowed_ext()
API.
The
audit
level
values
are
returned
in
the
azn_perminfo_auditlevel_ulong
permission
info
attribute
when
querying
the
audit
level
set
on
the
POP
attached
to
a
protected
object.
These
values
correspond
to
the
audit
values
that
are
set
using
the
administration
interfaces.
The
values
are
of
data
type
unsigned
long.
The
value
of
the
azn_perminfo_auditlevel_ulong
permission
info
attribute
is
a
bit
mask
consisting
of
an
bitwise
logical
OR
of
the
audit
level
values.
The
azn_perminfo_auditlevel_ulong
values
are:
azn_perminfo_auditlevel_all
Audit
all
events.
azn_perminfo_auditlevel_none
Do
not
audit
any
events.
azn_perminfo_auditlevel_permit
Audit
permit
events.
azn_perminfo_auditlevel_deny
Audit
deny
events.
azn_perminfo_auditlevel_error
Audit
error
messages.
azn_perminfo_auditlevel_admin
Audit
administration
events.
For
example,
when
a
POP
has
auditing
of
denials
and
errors
activated,
azn_perminfo_auditlevel_ulong
contains
the
unsigned
long
value:
(azn_perminfo_auditlevel_deny
|
azn_perminfo_auditlevel_error)
azn_perminfo_dynadi_redirect_url
This
value
is
specific
to
WebSEAL
attribute
retrieval
service
(AMWebARS).
This
is
the
URL
that
WebSEAL
should
redirect
the
user
browser
to
in
the
event
that
the
dynamic
ADI
retrieval
module
needs
to
interact
with
the
user
before
ADI
can
be
retrieved.
azn_perminfo_fail_reason
264
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
Specifies
the
reason
why
the
request
for
access
failed,
as
returned
by
the
azn_decision_access_allowed_ext()
call.
The
attribute
is
a
string
whose
value
is
constructed
from
codes
are
of
data
type
unsigned
long
The
azn_perminfo_fail_reason
may
contain
one
of
the
following
reason
codes.
azn_perminfo_fail_reason_acl
Authorization
denied
by
an
ACL
policy
azn_perminfo_fail_reason_traverse
User
does
not
have
traverse
(T)
permission
to
access
the
protected
resource.
azn_perminfo_fail_reason_tod
Authorization
denied
to
a
time
of
day
check
azn_perminfo_fail_reason_eas
An
external
authorization
service
denied
access
azn_perminfo_fail_reason_eas_override
An
external
authorization
service
denied
access,
overriding
the
prevailing
authorization
decision
which
was
to
permit
access.
azn_perminfo_fail_reason_stepup_forbidden
Step-up
authorization
policy
explicitly
denied
access
to
the
protected
resource.
azn_perminfo_fail_reason_delegate
The
user
was
denied
access
due
to
insufficient
privilege
to
delegate
the
requested
operation.
azn_perminfo_qop
The
quality
of
protection
required
between
caller
and
the
domain
before
access
to
the
protected
object
can
be
granted.
The
caller
needs
to
use
azn_attrlist_add_entry()
to
set
this
value
in
the
azn_init_set_perminfo_attrs
attribute
in
the
init_data
parameter
to
the
azn_initialize()
call.
Data
type:
const
azn_string_t
Valid
values:
v
none
v
integrity
v
privacy
azn_perminfo_qop_ulong
Appendix
C.
Attribute
names
reference
265
The
quality
of
protection
required
between
caller
and
the
domain
before
access
to
the
protected
object
can
be
granted.
This
is
the
same
as
the
azn_perminfo_qop
attribute
except
it
is
returned
as
an
unsigned
long.
The
caller
needs
to
use
azn_attrlist_add_entry()
to
set
this
value
in
the
azn_init_set_perminfo_attrs
attribute
in
the
init_data
parameter
to
the
azn_initialize()
call.
The
supported
quality
of
protection
values
are:
azn_perminfo_qop_value_integrity
Quality
of
protection
level
of
integrity.
azn_perminfo_qop_value_none
Quality
of
protection
level
of
none.
azn_perminfo_qop_value_privacy
Quality
of
protection
level
of
privacy.
The
above
values
are
of
data
type
unsigned
long.
azn_perminfo_reason_rule_failed
An
authorization
API
boolean
rules
evaluator
permission
information
attribute.
A
string
indicating
the
reason
that
a
rule
failed.
This
is
returned
in
the
permission
info
from
an
access
decision
call
when
the
rule
failed
and
a
reason
string
was
set
on
the
rule
by
the
policy
administrator.
The
string
is
user-specific
and
not
mandatory.
azn_perminfo_rules_adi_request
An
authorization
API
boolean
rules
evaluator
permission
information
attribute.
A
list
of
string
ADI
container
names
that
the
rules
evaluator
needs
in
order
to
evaluate
the
current
rule.
Upon
receiving
this
attribute
in
the
permission
info
from
an
access
decision
call,
the
resource
manager
should
collate
the
request
containers
of
data,
add
them
to
the
app_context
parameter
and
call
the
access
decision
interface
again.
azn_perminfo_stepup_level
The
authentication
level
required
to
access
the
object,
returned
as
an
unsigned
long.
For
more
information
on
the
concept
of
authentication
step-up,
see
IBM
Tivoli
Access
Manager
for
e-business
WebSEAL
Administration
Guide.
The
caller
needs
to
use
azn_attrlist_add_entry()
to
set
this
value
in
the
azn_init_set_perminfo_attrs
attribute
in
the
init_data
parameter
to
the
azn_initialize()
call.
The
caller
needs
to
use
azn_attrlist_get_entry_ulong()
to
retrieve
this
attribute
from
the
permission_info
output
parameter
of
the
azn_decision_access_allowed_ext()
call.
azn_perminfo_warningmode_ulong
266
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
Warning
mode.
When
warning
mode
is
enabled
access
is
always
granted.
If
access
should
not
have
been
granted
then
the
access
is
logged.
Data
type:
boolean
values
returned
in
unsigned
long
The
caller
needs
to
use
azn_attrlist_add_entry()
to
set
this
value
in
the
azn_init_set_perminfo_attrs
attribute
in
the
init_data
parameter
to
the
azn_initialize()
call.
The
caller
needs
to
use
azn_attrlist_get_entry_ulong()
to
retrieve
this
attribute
from
the
permission_info
output
parameter
of
azn_decision_access_allowed_ext().
azn_perminfo_warmingmodepermitted_ulong
Access
permitted
because
of
warning
mode.
The
boolean
indicator
is
used
to
tell
the
caller
that
access
was
granted
because
warning
mode
is
enabled.
Data
type:
boolean
values
returned
in
unsigned
long
The
caller
needs
to
use
azn_attrlist_add_entry()
to
set
this
value
in
the
azn_init_set_perminfo_attrs
attribute
in
the
init_data
parameter
to
the
azn_initialize()
call.
The
caller
needs
to
use
azn_attrlist_get_entry_ulong()
to
retrieve
this
attribute
from
the
permission_info
output
parameter
of
azn_decision_access_allowed_ext().
azn_pop_ext_attr_loc
When
POP
extended
attributes
are
returned
by
the
access
decision
call,
this
attribute
holds
the
place
in
the
object
space
to
which
the
POP
is
attached.
Use
azn_attrlist_add_entry()
to
set
this
value
in
the
azn_init_set_perminfo_attrs
attribute
in
the
init_data
parameter
to
the
azn_initialize()
call.
azn_rule_ext_attr_loc
When
rules
extended
attributes
are
returned
by
the
access
decision
call,
this
attribute
holds
the
place
in
the
object
space
to
which
the
rules
is
attached.
Use
azn_attrlist_add_entry()
to
set
this
value
in
the
azn_init_set_perminfo_attrs
attribute
in
the
init_data
parameter
to
the
azn_initialize()
call.
Appendix
C.
Attribute
names
reference
267
Authorization
API
service
plug-in
attributes
Authorization
API
service
plug-in
attributes
are
used
to
pass
information
into,
or
out
from,
the
authorization
API
service
dispatcher;
or
for
passing
information
to
or
from
an
authorization
API
service.
The
following
authorization
API
service
plug-in
attributes
are
reserved
for
use
with
the
authorization
API
service
dispatcher
and
with
authorization
API
services
that
are
supplied
with
the
Tivoli
Access
Manager
authorization
runtime
package.
An
example
of
an
authorization
API
service
that
is
provided
with
the
Tivoli
Access
Manager
authorization
runtime
package
is
the
credential
attributes
entitlement
service
(azn_ent_cred_attr)
which
provides
a
tag-value
capability
data
retrieval
capability
from
the
user
registry
which
can
be
called
as
a
standard
authorization
API
entitlement
service
or
as
one
of
the
entitlement
service
sub-classes
of
credential
attribute
entitlement
service
or
dynamic
ADI
retrieval
entitlement
service.
All
values
are
azn_string_t
unless
otherwise
specified.
Attribute
Description
azn_admin_svc_err_prefix
Prefix
used
by
the
administration
service
to
define
minor
error
codes.
Data
type:
unsigned
integer.
azn_admin_svc_pluginstatus
Administration
service
plug-in
status
attribute.
This
attribute
is
RESERVED
for
internal
use
by
the
authorization
API
administration
service.
azn_admin_svc_pobj
Administration
service
protected
object
attribute.
azn_admin_svc_results
Administration
service
results
attribute.
azn_admin_svc_task
Administration
service
task
attribute.
azn_eas_svc_err_prefix
Prefix
used
by
the
extended
authorization
service
to
define
minor
error
codes.
Data
type:
unsigned
integer.
azn_ent_cred_attrs_attribute
268
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
Credential
attributes
entitlement
service
attributes
A
list
of
attributes
requested
by
the
application
through
app_context
of
the
credential
attributes
entitlement
service.
The
format
of
this
string
value
is:
registry_identifier:registry_attribute_name
where
the
registry_identifier
is
the
value
used
to
do
the
registry
search.
This
can
also
be
a
credential
attribute
name
as
long
as
the
value
resolves
to
a
registry
identifier.
The
registry_attribute_name
is
the
attribute
to
be
retrieved
from
the
registry.
Examples:
cn=myname,o=myorg:address
where
cn=myname,o=myorg
is
the
registry
identifier
and
address
is
the
attribute
wanted
from
the
registry.
azn_cred_authzn_id:EmpolyeeType
where
azn_cred_authzn_id
is
an
attribute
in
the
credential
that
is
a
DN
and
EmployeeType
is
the
attribute
in
the
registry.
azn_ent_svc_err_prefix
Prefix
used
by
the
entitlement
service
to
define
minor
error
codes.
Data
type:
unsigned
integer.
azn_ent_svc_pd_pobj_matches
Output
attribute
for
the
entitlement
service.
This
is
the
list
of
objects
which
match
the
input
criteria.
See
description
of
azn_ent_svc_pd_pobj
in
this
table.
azn_ent_svc_pd_pobj
Entitlement
service
ID
for
Tivoli
Access
Manager
protected
object
entitlement
service
This
is
a
default
service.
When
a
NULL
entitlement
service
ID
is
specified
to
azn_entitlements_get_entitlements(),
this
service
is
called.
This
service
takes
a
credential,
a
directory
within
the
protected
object
tree
and
a
set
of
operations
and
returns
the
list
of
protected
objects
in
the
given
directory
and
its
subdirectories
for
which
the
given
authorization
API
credential
has
permission
to
perform
the
requested
set
of
operations.
The
output
is
returned
as
a
multi-string
valued
attribute
azn_ent_svc_pd_pobj_path
Input
attribute
for
the
entitlement
service,
specifying
the
protected
object
directory
path
to
be
searched.
See
description
of
azn_ent_svc_pd_pobj
in
this
table.
azn_ent_svc_pd_pobj_reqd_ops
Input
attribute
for
the
entitlement
service,
specifying
the
requested
set
of
operations
for
the
credential.
See
description
of
azn_ent_svc_pd_pobj
in
this
table.
azn_mod_rad_group_names
Appendix
C.
Attribute
names
reference
269
This
credential
modification
service
attribute
identifies
the
list
of
groups
to
add
Effectively
adds
the
credential
to
the
list
of
groups
specified
in
the
input
attributes
list.
Note
that
the
service
returns
a
new
credential
with
this
capability
and
the
original
credential
(and
the
registry)
are
unchanged.
azn_mod_svc_err_prefix
Prefix
used
by
the
credential
modification
service
to
define
minor
error
codes.
Data
type:
unsigned
integer.
azn_pac_svc_err_prefix;
Prefix
used
by
the
privilege
attribute
certificate
service
to
define
minor
error
codes.
Data
type:
unsigned
integer.
azn_svc_init_code_set
Valid
azn_string_t
constants
for
use
with
the
azn_init_set_code_set()
function
and
with
the
azn_svc_init_code_set
service
init
attribute.
Valid
values:
azn_code_set_utf8
azn_code_set_local
azn_svc_init_my_service_id
Used
by
the
service
dispatcher
to
pass
the
service
ID
for
a
service
module
to
the
modules
initialization
routine.
azn_svc_load_error
Returns
any
plug-in
load
errors
returned
by
the
system
in
the
format:
dll_path:
error_string
The
dll_path
is
the
filename
of
the
DLL
that
was
passed
to
the
load
routine
and
error_string
is
the
result
returned.
azn_svc_version
The
version
string
of
a
service
module.
This
is
returned
to
the
authorization
API
runtime.
270
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
Authorization
engine
attributes
Authorization
engine
attributes
are
values
supplied
by
the
authorization
engine
to
the
authorization
rules
evaluator.
When
an
authorization
rule
refers
to
one
of
the
following
reserved
authorization
engine
attributes
the
authorization
engine
will
automatically
provide
the
value
of
the
attribute
to
the
rules
evaluator.
These
values
are
passed
into
the
azn_decision_access_allowed(),
azn_decision_access_allowed_ext()
and
azn_entitlements_get_entitlements()
calls
respectively.
The
actual
string
values
of
these
operations
are
an
internal
implementation
detail
and
should
not
be
relied
upon.
The
operations
can
be
concatenated
together
to
form
complex
operation
strings.
For
example,
to
request
a
read/modify
operation.
For
example,
Attribute
Description
azn_engine_requested_actions
The
value
of
this
attribute
(passed
to
the
rules
evaluator)
is
the
value
of
the
operation
parameter
passed
into
the
azn_decision_access_allowed()
or
azn_decision_access_allowed_ext()
call.
This
operation
specifies
the
action
(type
of
access)
that
the
user
requested
for
the
protected
resource.
For
example,
if
the
operation
parameter
to
the
access
decision
is
Tr
then
the
value
of
azn_engine_requested_actions
will
be
Tr.
You
can
use
this
attribute
to
write
authorization
rules.
For
example,
to
test
the
value
of
this
attribute,
you
can
write:
<xsl:if
test="azn_engine_requested_actions
=
’Tr’>!TRUE!</xsl:if>
or,
to
check
if
the
set
of
operations
contains
the
’r’
action:
<xsl:if
test="contains(azn_requested_actions,
’r’)">!TRUE!</xsl:if>
azn_engine_target_resource
The
value
of
this
attribute
(passed
to
the
rules
evaluator)
is
the
value
of
the
protected_resource
parameter
passed
into
the
azn_decision_access_allowed()
call.
It
is
the
target
resource
for
the
authorization
request.
Appendix
C.
Attribute
names
reference
271
272
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
Appendix
D.
Authorization
API
client
configuration
file
The
initialization
and
operation
of
an
authorization
API
client
application
can
be
controlled
through
the
use
of
a
client
configuration
file.
The
example
client
configuration
file
is
aznAPI.conf.
The
name
of
an
authorization
API
client
configuration
file
is
usually
changed
to
match
the
name
of
the
application.
The
file
contains
sections
called
stanzas.
Stanza
labels
appear
within
brackets,
such
as:
[stanza_name].
For
example,
the
[ssl]
stanza
defines
the
SSL
configuration
settings
for
use
by
the
authorization
API
application.
Each
stanza
in
a
Tivoli
Access
Manager
configuration
file
contains
one
or
more
stanza
entries.
A
stanza
entry
consists
of
a
key
value
pair,
which
contains
information
that
is
expressed
as
a
paired
set
of
parameters.
Each
stanza
entry
has
the
following
format:
key
=
value
The
initial
configuration
of
an
authorization
API
client
application
establishes
some
default
values.
Some
values
are
static
and
will
never
change;
other
values
can
be
modified
to
customize
server
functionality
and
performance.
Note:
Authorization
API
client
applications
have
the
option
of
using
initialization
parameters
instead
of
using
a
configuration
file.
The
initialization
parameters
will
override
the
configuration
file
settings.
For
more
information,
see
Chapter
3,
“Initializing
the
authorization
API,”
on
page
23.
This
appendix
contains
the
following
sections:
v
“Guidelines
for
configuring
stanzas”
on
page
274
v
“How
to
change
configuration
settings”
on
page
277
v
“[authentication-mechanisms]
stanza”
on
page
278
v
“[aznapi-configuration]
stanza”
on
page
280
v
“[aznapi-admin-services]
stanza”
on
page
286
v
“[aznapi-cred-modification-services]
stanza”
on
page
287
v
“[aznapi-entitlement-services]
stanza”
on
page
288
v
“[aznapi-external-authzn-services]
stanza”
on
page
289
v
“[aznapi-pac-services]
stanza”
on
page
290
v
“[ldap]
stanza”
on
page
291
v
“[manager]
stanza”
on
page
297
v
“[meta-info]
stanza”
on
page
299
v
“[ssl]
stanza”
on
page
300
v
“[uraf-registry]
stanza”
on
page
305
©
Copyright
IBM
Corp.
2000,2003
273
Guidelines
for
configuring
stanzas
These
guidelines
are
provided
to
help
you
make
changes
to
the
authorization
API
application
configuration
file.
The
guidelines
are
divided
into
these
types:
v
General
v
Default
settings
v
Strings
v
Defined
strings
v
File
names
v
Integers
v
Boolean
values
For
instructions,
see
“How
to
change
configuration
settings”
on
page
277.
General
guidelines
Use
the
following
general
guidelines
when
making
changes
to
the
configuration
settings:
v
There
is
no
order
dependency
or
location
dependency
for
stanzas
in
any
configuration
file.
v
Stanza
entries
are
marked
as
required
or
optional.
When
an
entry
is
required,
the
entry
must
contain
a
valid
key
and
value.
v
Do
not
change
the
names
of
the
keys
in
the
configuration
files.
Changing
the
name
of
the
key
might
cause
unpredictable
results
for
the
servers.
v
Capitalization
of
the
keys
is
not
important.
For
example,
you
can
use
UseSSL
or
usessl.
v
Spaces
are
not
allowed
for
names
of
keys.
v
For
the
key
value
pair
format
of
key
=
value,
the
spaces
surrounding
the
equal
sign
(=)
are
not
required,
but
they
are
recommended.
v
Nonprintable
characters
(such
as
tabs,
carriage
returns,
and
line
feeds)
that
occur
at
the
end
of
a
stanza
entry
are
ignored.
Nonprintable
characters
are
ASCII
characters
with
a
decimal
value
less
than
32.
Default
values
Use
the
following
guidelines
when
changing
default
configuration
settings:
v
Many
values
are
created
or
modified
only
by
using
configuration
programs.
Do
not
manually
edit
these
stanzas
or
values.
v
Some
values
are
filled
in
automatically
during
configuration.
These
values
are
needed
for
the
initialization
of
the
application
after
the
configuration.
v
The
default
values
for
a
stanza
entry
might
be
different,
depending
on
the
application
configuration.
Some
key
value
pairs
are
not
applicable
to
certain
applications.
Strings
Some
values
accept
a
string
value.
When
you
manually
edit
the
configuration
file,
use
the
following
guidelines
to
change
configuration
settings
that
require
a
string:
v
String
values
must
be
part
of
the
local
codeset.
v
String
values
can
be
specified
using
any
case.
274
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
v
Valid
string
characters
are
the
letters
a-Z,
the
numbers
0-9,
a
period
(
.
),
a
comma
(
,
),
an
equal
sign
(
=
),
a
forward
slash
(
/
),
an
underscore
(
_
),
a
plus
sign
(+),
a
hyphen
(
-
),
an
at
sign
(
@
),
an
ampersand
(
&
),
and
an
asterisk
(
*
).
Some
strings
impose
additional
or
different
restrictions
on
the
set
of
allowable
string
characters.
These
restrictions
are
listed
under
the
appropriate
stanza
entry
discussion
later
in
this
chapter.
v
Double
quotation
marks
are
sometimes,
but
not
always,
required
when
you
use
spaces
or
more
than
one
word
for
values.
Refer
to
the
descriptions
or
examples
for
each
stanza
entry
when
in
doubt.
v
The
minimum
and
maximum
lengths
of
user
registry-related
string
values,
if
there
are
limits,
are
imposed
by
the
underlying
registry.
For
example,
for
Active
Directory
the
maximum
length
is
256
alphanumeric
characters.
Defined
strings
Some
values
accept
a
string
value,
but
the
value
must
be
one
of
a
set
of
defined
strings.
When
you
manually
edit
the
configuration
file,
make
sure
that
the
string
value
you
type
matches
one
of
the
valid
defined
strings
values.
For
example,
the
[aznapi-configuration]
stanza
contains
the
following
entry:
auditcfg
=
{azn|authn|mgmt}
The
value
for
auditcfg
is
expected
to
be
either
azn
or
authn
or
mgmt.
Any
other
value
is
not
valid
and
results
in
an
error.
File
names
Some
values
are
file
names.
For
each
stanza
entry
that
expects
a
file
name
as
a
value,
the
description
of
the
stanza
entry
specifies
which
of
the
following
constructs
are
valid:
v
Filename
No
directory
path
included.
v
Relative
filename
A
directory
path
is
allowed
but
not
mandatory.
These
files
typically
are
expected
to
be
located
relative
to
the
location
of
a
standard
Tivoli
Access
Manager
directory.
The
stanza
entry
for
each
relative
path
name
lists
the
root
directory
to
which
the
file
name
is
relative.
v
Fully
qualified
(absolute)
path
An
absolute
directory
path
is
required.
Note:
Some
stanza
entries
allow
more
than
one
of
the
above
choices.
The
set
of
characters
permitted
in
a
file
name
can
be
determined
by
the
file
system
and
by
the
local
codeset.
For
Windows,
file
names
cannot
have
these
characters:
a
backward
slash
(\),
a
colon
(:),
a
question
mark
(?),
or
double
quotation
marks.
Integers
Many
stanza
entries
expect
the
value
for
the
entry
to
be
expressed
as
an
integer.
v
Stanza
entries
that
take
an
integer
value
expect
integer
values
within
a
valid
range.
The
range
is
described
in
terms
of
a
minimum
value
and
a
maximum
value.
Appendix
D.
Authorization
API
client
configuration
file
275
For
example,
in
the
[logging]
stanza,
the
logflush
stanza
entry
has
a
minimum
value
of
1
second
and
a
maximum
value
of
600
seconds.
v
For
some
entries,
the
integer
value
must
be
positive,
and
the
minimum
value
is
1.
For
other
entries,
a
minimum
integer
value
of
0
is
allowed.
Use
caution
when
setting
an
integer
value
to
0.
For
example,
an
integer
value
of
0
might
the
function
that
is
controlled
by
that
stanza
entry.
For
example,
in
the
[aznapi-configuration]
stanza,
the
entry
logsize
=
0
disables
the
creation
of
a
rollover
log
file.
port
number.
Or,
an
integer
value
of
0
might
indicate
that
the
number
is
unlimited.
For
example,
in
the
[ssl]
stanza,
the
entry
ssl-io-inactivity-timeout
=
0
means
there
is
no
inactivity
timeout.
v
For
some
entries
requiring
integer
values,
Tivoli
Access
Manager
does
not
impose
an
upper
limit.
for
the
maximum
number
allowed.
For
example,
there
is
typically
no
maximum
for
port
numbers
in
the
[ldap]
stanza.
For
this
type
of
entry,
the
maximum
number
is
limited
only
by
the
size
of
memory
allocated
for
an
integer
data
type.
This
number
can
vary,
based
on
the
type
of
operating
system.
For
systems
that
allocate
4
bytes
for
an
integer,
this
value
is
2147483647.
However,
an
administrator
should
use
a
number
that
represents
the
value
that
is
most
logical
for
the
value
you
are
trying
to
set.
Boolean
values
Many
stanza
entries
represent
a
boolean
value.
Tivoli
Access
Manager
recognizes
the
boolean
values
yes
and
no.
Some
of
the
entries
in
the
configuration
files
are
read
by
other
servers
and
utilities.
For
example,
many
entries
in
the
[ldap]
stanza
are
read
by
the
LDAP
client.
Some
of
these
other
programs
recognize
additional
Boolean
characters:
v
yes
or
true
v
no
or
false
Anything
other
than
yes|true
will
be
interpreted
as
no|false,
including
a
blank
value.
The
recognized
Boolean
entries
are
listed
for
each
stanza
entry.
Refer
to
the
individual
descriptions
to
determine
when
true
or
false
are
also
recognized.
276
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
How
to
change
configuration
settings
To
change
a
configuration
setting,
do
the
following:
1.
Make
a
backup
copy
of
the
configuration
file
that
you
plan
to
modify.
The
backup
allows
you
to
return
the
configuration
file
to
a
known
working
state,
in
case
you
encounter
an
error
later.
2.
Stop
the
authorization
API
application
that
is
affected.
3.
Make
the
changes
by
doing
one
of
the
following:
v
Use
an
ASCII
text
editor
to
edit
the
configuration
file
and
make
any
necessary
changes.
Save
your
changes.
v
For
some
settings
in
the
authorization
API
client
configuration
file,
use
the
svrsslcfg
utility.
See
the
stanza
entry
descriptions
to
determine
which
entries
are
modified
by
svrsslcfg.
Many
stanzas
or
values
are
created
or
modified
only
by
using
configuration
programs.
Some
values
are
filled
in
automatically
after
the
configuration
is
completed.
Do
not
manually
edit
these
values.
4.
Restart
the
authorization
API
application
affected.
Appendix
D.
Authorization
API
client
configuration
file
277
[authentication-mechanisms]
stanza
This
stanza
defines
the
library
that
is
to
be
used
for
password
and
certificate
authentication.
The
configuration
entries
in
this
stanza
are
required
by
the
server
to
communicate
with
a
user
registry.
You
can
use
either
a
User
Registry
Adapter
Framework
(URAF)
registry
(either
Active
Directory
or
Domino)
or
an
LDAP
registry
library,
depending
on
the
type
of
user
registry.
Because
you
can
specify
only
one
type
of
user
registry,
certain
key
value
pairs
in
the
[authentication-mechanisms]
stanza
are
mutually
exclusive.
For
example:
#
passwd-uraf
=
/opt/PolicyDirector/lib/liburafauthn.a
#
cert-uraf
=
/opt/PolicyDirector/lib/liburafcertauthn.a
passwd-ldap
=
C:\pd\bin\ldapauthn.dll
&
-cfgfile
[C:/pd/etc/ivacld.conf]
cert-ldap
=
C:\pd\bin\certauthn.dll
&
-cfgfile
[C:/pd/etc/ivacld.conf]
In
this
example,
the
URAF
registry
items
are
commented
out
by
using
the
pound
sign
(#);
the
LDAP-oriented
stanza
entries
are
not
commented
out.
You
can
manually
edit
these
values;
no
configuration
utility
is
required.
[authentication-mechanisms]
stanza
passwd-uraf
=
fully_qualified_path
Location
of
the
library
to
use
for
password
authentication.
This
stanza
entry
is
required
when
you
use
a
URAF
registry
as
your
user
registry.
Default
values:
v
AIX:
/opt/PolicyDirector/lib/liburafauthn.a
v
HP:
/opt/PolicyDirector/lib/liburafauthn.sl
v
Sun:
/opt/PolicyDirector/lib/liburafauthn.so
v
Linux:
/opt/PolicyDirector/lib/liburafauthn.so
v
Windows:
install_dir\bin\urafauthn.dll
Example
for
Linux:
passwd-uraf
=
../opt/PolicyDirector/lib/liburafauthn.so
cert-uraf
=
fully_qualified_path
Location
of
the
library
to
use
for
certificate
authentication.
This
stanza
entry
is
required
when
you
use
a
URAF
registry
as
the
user
registry.
Default
values:
v
AIX:
/opt/PolicyDirector/lib/liburafcertauthn.a
v
HP:
/opt/PolicyDirector/lib/liburafcertauthn.sl
v
Solaris:
/opt/PolicyDirector/lib/liburafauthn.so
v
Linux:
/opt/PolicyDirector/lib/liburafcertauthn.so
v
Windows:
install_dir\bin\urafcertauthn.dll
Example
for
Solaris:
cert-uraf
=
../opt/PolicyDirector/lib/liburafauthn.so
278
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
passwd-ldap=fully_qualified_path
Location
of
the
library
to
use
for
LDAP
password
authentication.
This
stanza
entry
is
required
when
you
use
LDAP
as
the
user
registry.
Default
values:
v
AIX:
/opt/PolicyDirector/lib/libldapauthn.a
v
HP:
/opt/PolicyDirector/lib/libldapauthn.sl
v
Solaris:
/opt/PolicyDirector/lib/libldapauthn.so
v
Linux:
/opt/PolicyDirector/lib/libldapauthn.so
v
Windows:
install_dir\bin\ldapauthn.dll
Example
for
AIX:
passwd-ldap
=
../opt/PolicyDirector/lib/libldapauthn.a
cert-ldap
=
fully_qualified_path
Location
of
the
library
to
use
for
LDAP
certificate
authentication.
This
stanza
entry
is
required
when
you
use
LDAP
as
the
user
registry.
Default
values:
v
AIX:
/opt/PolicyDirector/lib/libcertauthn.a
v
HP:
/opt/PolicyDirector/lib/libcertauthn.sl
v
Solaris:
/opt/PolicyDirector/lib/libcertauthn.so
v
Linux:
/opt/PolicyDirector/lib/libcertauthn.so
v
Windows:
install_dirbin\certauthn.dll
Example
for
Windows:
passwd-ldap
=
C:\pd\bin\certauthn.dll
&
-cfgfile
[C:/pd/etc/ivacld.conf]
Appendix
D.
Authorization
API
client
configuration
file
279
[aznapi-configuration]
stanza
[aznapi-configuration]
stanza
azn-app-host
=
other_hostname
Attribute
that
is
used
to
customize
the
host
on
which
the
authorization
API
application
is
listening.
For
other_hostname,
you
can
provide
any
valid
Internet
host
name.
If
this
attribute
is
not
specified,
the
default
host
name
will
be
used.
By
default,
this
attribute
is
disabled.
When
disabled,
the
stanza
entry
is
commented
out
by
using
a
pound
sign
(#)
at
the
beginning
of
the
stanza
entry
in
the
configuration
file.
For
example:
#azn-app-host
=
libra
To
enable
this
value,
uncomment
the
entry
in
the
configuration
file
by
removing
the
pound
sign
(#).
Be
sure
to
include
a
host
name
value
for
the
host
on
which
the
authorization
API
application
is
listening.
This
stanza
entry
is
optional.
There
is
no
default
value.
Example:
azn-app-host
=
libra.dallas.ibm.com
cache-refresh-interval
=
{disable|default|number_seconds}
Poll
interval
between
checks
for
updates
to
the
master
authorization
policy
database.
Note:
The
local
cache
is
rebuilt
only
if
an
update
is
detected.
Valid
values:
disable
The
interval
value
in
seconds
is
not
set.
default
The
default
value
of
600
seconds
is
used.
number_seconds
The
exact
time
interval
that
you
set
by
specifying
the
number
of
seconds.
The
minimum
value
is
0
seconds.
Tivoli
Access
Manager
does
not
impose
a
maximum
other
than
the
maximum
value
allowed
by
the
memory
allocated
for
an
unsigned
integer.
This
number
is
platform-specific,
but
typically
is
136
years.
This
stanza
entry
is
optional.
Default
value:
default
Example:
cache-refresh-interval
=
500
cred-attribute-entitlement-services
=
name_of_entitlement_service
280
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
A
list
of
authorization
API
entitlement
service
IDs
that
are
queried
by
the
azn_id_get_creds()
interface
to
compile
a
list
of
attributes
to
be
added
to
the
user
credential
while
the
credential
is
being
built.
Each
service
ID
is
queried
in
the
order
of
declaration
here
and
the
attribute
returned
in
the
entitlements
parameter
are
inserted
into
the
credential
attribute
list
of
each
principal
built
with
the
azn_id_get_creds()
call.
This
stanza
entry
is
optional.
There
is
no
default
value.
For
example:
cred-attribute-entitlement-services
=
myEntSvcID
cred-attribute-entitlement-services
=
myOtherEntSvcID
For
more
information,
see
“Credential
attributes
entitlement
service”
on
page
112.
db-file
=
fully_qualified_path
Name
and
location
of
the
resource
manager
database
cache
file.
This
value
must
be
specified,
and
each
server
provides
its
own
value.
The
fully_qualified_path
value
represents
an
alphanumeric
string.
This
stanza
entry
is
required
if
logaudit
=
yes.
There
is
no
default
value.
Example
for
Windows:
db-file
=
C:\pd\db\ivacld.db
dynamic-adi-entitlement-services
=
entitlements_service_ID
A
list
of
configured
authorization
API
entitlement
service
IDs
that
will
be
queried
by
the
authorization
rules
engine
when
missing
ADI
is
detected
during
an
authorization
rule
evaluation.
Entitlement
services
listed
here
must
adhere
to
the
input
and
output
specifications
for
a
dynamic
ADI
retrieval
service.
For
more
information
on
dynamic
ADI,
see
“Dynamic
ADI
retrieval
services”
on
page
110.
When
ADI
is
found
to
be
missing
during
a
rule
evaluation,
each
service
in
this
list
is
queried
in
the
order
defined
in
this
entry.
These
entries
must
refer
to
existing
entitlement
services
that
were
loaded
by
using
service
entries
in
the
entitlement
service
configuration
stanza
or
in
an
initialization
attribute.
This
stanza
entry
is
optional.
There
is
no
default
value.
For
example:
dynamic-adi-entitlement-services
=
bank_A_ADI
dynamic-adi-entitlement-services
=
bank_B_ADI
input-adi-xml-prolog
=
string
Appendix
D.
Authorization
API
client
configuration
file
281
The
prolog
to
be
added
to
the
top
of
the
XML
document
that
is
created
using
the
Access
Decision
Information
(ADI)
needed
to
evaluate
a
boolean
authorization
rule.
When
this
entry
is
not
specified,
the
default
XML
prolog
is:
<?xml
version=’1.0’
encoding=’UTF-8’?>
Use
caution
when
changing
this
setting.
For
more
information,
see
IBM
Tivoli
Access
Manager
Base
Administration
Guide.
This
stanza
entry
is
optional.
There
is
no
default
value.
For
example:
input-adi-xml-prolog
=
<?xml
version=’1.0’
encoding=’UTF-8’?>
listen-flags
=
{enable|disable}
Indication
of
whether
to
turn
on
or
off
the
reception
of
policy
cache
update
notifications.
Valid
values:
enable
Activates
the
notification
listener.
disable
Deactivates
the
notification
listener.
This
stanza
entry
is
optional.
Default
value:
disable
Example:
listen-flags
=
enable
logcfg
=
category:{stdout|stderr|file|pipe|remote}[
[parameter=value
]
[,parameter=value]...]
282
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
Specifies
event
logging
for
the
specified
category.
For
authorization
API
clients,
the
categories
are:
v
azn
Authorization
events
v
authn
Credentials
acquisition
authentication.
Note:
Additional
categories
are
used
by
resource
managers
such
as
Tivoli
Access
ManagerWebSEAL.
Event
logging
supports
a
number
of
output
destination
types:
{stdout|stderr|file|pipe|remote}
Auditing
typically
is
configured
to
use
the
file
type.
Each
event
logging
type
supports
a
number
of
optional
parameter
=
value
options.
For
more
information
about
output
destination
types
and
optional
parameter
=
value
settings,
see
the
IBM
Tivoli
Access
Manager
Base
Administration
Guide.
This
stanza
entry
is
optional.
Multiple
entries
are
supported.
There
is
no
default
value.
Example
entries:
logcfg
=
audit.azn:file
path=audit.log,flush_interval=20,log_id=audit_log
logcfg
=
audit.authn:file
log_id=audit_log
mode
=
{local|remote}
Specifies
the
authorization
API
client
mode.
This
stanza
entry
is
set
by
svrsslcfg
during
configuration
and
should
not
be
changed
by
the
administrator.
The
value
local
means
that
the
resource
manager
(authorization
API
client)
uses
a
local
policy
cache.
The
value
remote
means
that
the
resource
manager
(authorization
API
client)
uses
a
remote
Tivoli
Access
Manager
policy
cache
maintained
by
the
authorization
server.
This
stanza
entry
is
required.
Default
value:
local
Example:
mode
=
local
permission-info-returned
=
{
attribute
attribute
....
)
Appendix
D.
Authorization
API
client
configuration
file
283
The
set
of
attributes
that
the
caller
wants
to
receive
from
the
azn_decision_access_allowed_ext()
function
in
the
permission_info
attribute
list.
When
an
attribute
name
is
added
to
this
list,
the
attribute
is
allowed
to
be
returned
as
permission
information
if
it
is
applicable
to
the
current
decision
call.
Attributes
can
be
defined
by
users,
for
example,
by
setting
an
attribute
on
an
ACL.
The
string
constants
in
the
following
list
are
recognized
by
the
authorization
engine
and
equate
to
their
corresponding
permission
information
constants
in
ogauthzn.h.
Note:
For
a
description
of
each
string
constant
listed
below,
see
“Permission
information
attributes”
on
page
263.
v
azn_acl_ext_attr_loc
v
azn_dynadi_target_url
v
azn_perminfo_all_attrs
v
azn_perminfo_auditlevel_ulong
v
azn_perminfo_dynadi_redirect_url
v
azn_perminfo_fail_reason
v
azn_perminfo_qop
v
azn_perminfo_qop_ulong
v
azn_perminfo_reason_rule_failed
v
azn_perminfo_rules_adi_request
v
azn_perminfo_stepup_level
v
azn_perminfo_warningmode_ulong
v
azn_perminfo_warmingmodepermitted_ulong
v
azn_pop_ext_attr_loc
v
azn_rule_ext_attr_loc
This
stanza
entry
is
optional.
There
are
no
default
values
(attributes).
Example:
permission-info-returned
=
azn_perminfo_qop
azn_perminfo_qop_ulong
Example
with
a
user
defined
attribute
my_attribute:
permission-info-returned
=
azn_perminfo_qop_ulong
my_attribute
policy-cache-size
=
number_of_entries
Size
of
the
in-memory
policy
cache.
The
cache
consists
of
policy
and
the
relationships
between
policy
and
resources.
The
knowledge
that
a
resource
has
no
directly
associated
policy
is
also
cached.
A
larger
cache
will
potentially
improve
the
application
performance
but
use
additional
memory
as
well.
The
maximum
cache
size
should
be
relative
to
the
number
of
policy
objects
defined
and
the
number
of
resources
protected
and
the
available
memory.
A
reasonable
algorithm
to
begin
with
is:
(number
of
policy
objects
*
3)
+
(number
of
protected
resources
*
3)
This
stanza
entry
is
optional.
There
is
no
default
value.
The
suggested
default
value
is
32768.
For
example:
policy-cache-size
=
32768
resource-manager-provided-adi
=
adi_prefix
284
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
A
list
of
string
prefixes
that
identify
Access
Decision
Information
(ADI)
to
be
supplied
by
the
resource
manager
(authorization
API
client).
When
a
prefix
is
declared
here,
the
authorization
engine
is
told
that
it
needs
to
get
ADI
with
that
prefix.
When
ADI
with
the
specified
prefix
is
not
available
in
the
credential
or
as
application
context
passed
in
with
the
access
decision
call,
the
engine
fails
the
authorization
request.
The
engine
then
requests
that
the
resource
manager
retry
the
request
and
provide
the
required
data
in
the
application
context
passed
in
with
the
next
access
decision
call.
This
stanza
entry
is
optional.
There
is
no
default
value.
For
example:
resource-manager-provided-adi
=
bank_A_
resource-manager-provided-adi
=
bank_B_
xsl-stylesheet-prolog
=
xml_declaration
The
prolog
to
be
added
to
the
top
of
the
XSL
stylesheet
that
is
created
using
the
XSL
text
that
defines
a
boolean
authorization
rule.
When
not
specified,
the
default
XSL
stylesheet
prolog
is:
!<--
Required
for
XSLT
language
-->
<?xml
version="1.0"
encoding=’UTF-8’?>
<xsl:stylesheet
xmlns:xsl=
"http://www.w3.org/1999/XSL/Transform"
version="1.0">
!<--
Required
to
constrain
output
of
rule
evaluation
-->
<xsl:output
method="text"
omit-xml-declaration="yes"
encoding=’UTF-8’
indent="no"
/>
!<--
Need
this
to
ensure
default
text
node
printing
is
off
-->
<xsl:template
match="text()"></xsl:template>
Use
caution
when
changing
this
setting.
For
more
information,
see
IBM
Tivoli
Access
Manager
Base
Administration
Guide.
This
stanza
entry
is
optional.
There
is
no
default
value.
For
example:
xsl-stylesheet-prolog
=
<?xml
version="1.0"
encoding=’UTF-8’?>
<xsl:stylesheet
xmlns:xsl=
"http://www.w3.org/1999/XSL/Transform"
version="1.0"><xsl:output
method="text"
omit-xml-declaration="yes"
encoding=’UTF-8’
indent="no"
/><xsl:template
match="text()">
</xsl:template>
Appendix
D.
Authorization
API
client
configuration
file
285
[aznapi-admin-services]
stanza
[aznapi-admin-services]
stanza
service-id
=
{short_name|path_to_dll}
[-pobj
protected_object_hierarchy_name
]
[&
params]
Defines
the
authorization
API
service
for
functions
that
enable
a
plug-in
to
obtain
the
contents
of
a
defined
portion
of
the
protected
object
hierarchy,
or
to
enable
a
plug-in
to
define
application-specific
administration
tasks
that
also
return
commands
that
perform
those
tasks.
Each
stanza
entry
defines
different
types
of
authorization
API
services,
and
each
entry
is
the
same
format
where:
service-id
Developer-specified
identification
(ID)
of
the
administration
service.
An
authorization
API
application
can
register
more
than
one
administration
service
plug-in,
but
each
must
have
a
unique
service
ID.
{short_name|path_to_dll}
The
path
to
the
dynamic
link
library
(DLL)
that
contains
the
service
executable
code.
If
the
DLL
is
located
in
a
directory
that
is
normally
searched
by
the
system
for
DLLs
(for
example,
/usr/lib
on
UNIX
platforms
and
%PATH%
on
Windows
NT),
you
do
not
need
to
specify
the
full
path
to
the
DLL,
only
the
DLL
name.
If
you
want
a
platform-independent
DLL
name,
so
it
can
be
loaded
on
any
supported
Tivoli
Access
Manager
platform,
provide
a
short
form
library
name.
The
short
name
is
prepended
and
appended
with
known
library
prefixes
and
suffixes
for
each
platform
and
each
possibility
is
searched
for
in
turn.
For
example,
using
a
short
form
library
name
of
azn_ent_user,
the
following
names
are
automatically
searched
for
on
each
platform:
Windows
azn_ent_user.dll
AIX:
libazn_ent_user.so,
libazn_ent_user.a
Solaris:
libazn_ent_user.so
HP/UX:
libazn_ent_user.sl
protected_object_hierarchy_name
The
protected
object
hierarchy
name
is
an
optional
parameter.
This
parameter
refers
to
either
the
name
of
a
protected
object
space
(hierarchy)
or
simply
to
a
protected
object.
Protected
object
hierarchy
names
must
be
unique
for
each
administration
service
plug-in
within
the
scope
of
an
authorization
API
application.
Multiple
authorization
API
application
instances,
however,
can
register
to
service
the
same
protected
object
hierarchy
names,
which
provides
failover
support
for
administration
of
an
object
space
in
the
event
that
a
particular
authorization
API
application
server
fails.
params
Optionally,
the
external
authorization
service
can
be
passed
additional
initialization
information
in
the
form
of
arguments.
The
arguments
must
be
preceded
by
the
ampersand
(for
example,
&
-server
fred).
The
authorization
service
does
not
process
the
characters
after
the
ampersand
&.
It
passes
these
characters
directly
to
the
administration
service
plug-in.
The
service
definition
is
discussed
in
more
detail
in
the
“Implementing
a
service
plug-in”
on
page
81.
This
stanza
entry
is
optional.
There
is
no
default
value.
Example:
AZN_ADMIN_SVC_TRACE
=
pdtraceadmin
286
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
[aznapi-cred-modification-services]
stanza
[aznapi-cred-modification-services]
stanza
service-id
=
short_name|path_to_dll
[
&
params
...
]
Defines
the
authorization
API
service
for
the
credentials
attribute
list
modification
service.
Each
stanza
entry
defines
different
types
of
authorization
API
service,
and
each
entry
is
the
same
format
where:
service-id
Developer-specified
identification
(ID)
of
the
credential
modification
service.
The
service
ID
string
must
be
unique.
{short_name|path_to_dll}
The
path
to
the
dynamic
link
library
(DLL)
that
contains
the
service
executable
code.
If
the
DLL
is
located
in
a
directory
that
is
normally
searched
by
the
system
for
DLLs
(for
example,
/usr/lib
on
UNIX
platforms
and
%PATH%
on
Windows
NT),
you
do
not
need
to
specify
the
full
path
to
the
DLL,
only
the
DLL
name.
If
you
want
a
platform-independent
DLL
name,
so
it
can
be
loaded
on
any
supported
Tivoli
Access
Manager
platform,
provide
a
short
form
library
name.
The
short
name
is
prepended
and
appended
with
known
library
prefixes
and
suffixes
for
each
platform
and
each
possibility
is
searched
for
in
turn.
For
example,
using
a
short
form
library
name
of
azn_ent_user,
the
following
names
are
automatically
searched
for
on
each
platform:
Windows:
azn_ent_user.dll
AIX:
libazn_ent_user.so,
libazn_ent_user.a
Solaris:
libazn_ent_user.so
HP/UX:
libazn_ent_user.sl
params
Optionally,
you
can
specify
parameters
to
pass
to
the
service
when
it
is
initialized
by
the
authorization
API.
Parameters
are
considered
to
be
all
data
following
the
ampersand
(&)
symbol
in
the
string.
The
service
definition
is
discussed
in
more
detail
in
“Implementing
a
service
plug-in”
on
page
81.
This
stanza
entry
is
optional.
There
is
no
default
value.
Example:
AZN_MOD_SVC_RAD_2AB
=
azn_mod_rad
Appendix
D.
Authorization
API
client
configuration
file
287
[aznapi-entitlement-services]
stanza
[aznapi-entitlement-services]
stanza
service-id
=
{short_name|path_to_dll}
[
&
params
...
]
Defines
the
authorization
API
service
for
the
protected
objects
entitlement
service.
Each
stanza
entry
defines
different
types
of
authorization
API
service,
and
each
entry
is
of
the
same
format
where:
service-id
Developer-specified
identification
(ID)
by
which
the
service
can
be
identified
by
the
authorization
API
client.
The
service
ID
string
must
be
unique.
{short_name|path_to_dll}
The
path
to
the
dynamic
link
library
(DLL)
that
contains
the
service
executable
code.
If
the
DLL
is
located
in
a
directory
that
is
normally
searched
by
the
system
for
DLLs
(for
example,
/usr/lib
on
UNIX
platforms
and
%PATH%
on
Windows
NT),
you
do
not
need
to
specify
the
full
path
to
the
DLL,
only
the
DLL
name.
If
you
want
a
platform-independent
DLL
name,
so
it
can
be
loaded
on
any
supported
Tivoli
Access
Manager
platform,
provide
a
short
form
library
name.
The
short
name
is
prepended
and
appended
with
known
library
prefixes
and
suffixes
for
each
platform
and
each
possibility
is
searched
for
in
turn.
For
example,
using
a
short
form
library
name
of
azn_ent_user,
the
following
names
are
automatically
searched
for
on
each
platform:
Windows:
azn_ent_user.dll
AIX:
libazn_ent_user.so,
libazn_ent_user.a
Solaris:
libazn_ent_user.so
HP/UX:
libazn_ent_user.sl
params
Optionally,
you
can
specify
one
or
more
parameters
to
pass
to
the
service
when
it
is
initialized
by
the
authorization
API.
Parameters
are
considered
to
be
all
the
data
following
the
ampersand
(&)
symbol
in
the
string.
The
service
definition
is
discussed
in
more
detail
in
“Implementing
a
service
plug-in”
on
page
81.
This
stanza
entry
is
optional.
There
is
no
default
value.
Example:
AZN_ENT_EXT_ATTR
=
azn_ent_ext_attr
288
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
[aznapi-external-authzn-services]
stanza
[aznapi-external-authzn-services]
stanza
policy-trigger
=
{short_name|path_to_dll}
[
&
params
...
]
Defines
the
authorization
API
service
for
external
authorization
service
definitions
that
force
authorization
decisions
to
be
made
based
on
application-specific
criteria.
Each
stanza
entry
defines
different
types
of
authorization
API
service,
and
each
entry
is
the
same
format
where:
policy-trigger
The
policy
trigger
is
the
means
by
which
the
external
authorization
service
is
invoked
by
the
authorization
engine.
It
is
one
of
either
a
service
ID
or
an
access
control
list
(ACL)
action
string.
For
example,
it
can
be
my_service_1
or
Trx.
If
the
service
is
defined
with
a
service
ID,
the
service
ID
will
be
used
as
an
extended
attribute
on
a
POP
policy
that
triggers
the
external
authorization
service
whenever
an
object
has
this
POP
attached
to
it.
If
the
service
is
defined
using
an
ACL
action
string,
the
service
will
be
invoked
whenever
this
ACL
action
mask
is
requested
as
part
of
an
authorization
decision.
The
policy-trigger
can
be
any
string
that
is
recognized
as
a
valid
key
name.
The
policy-trigger
string
is
case
sensitive
for
action
set
definitions
because
the
actions
themselves
are
case
sensitive.
However,
the
policy-trigger
is
not
case
sensitive
if
the
trigger
is
a
POP
attribute.
{short_name|path_to_dll}
The
path
to
the
dynamic
link
library
(DLL)
that
contains
the
service
executable
code.
If
the
DLL
is
located
in
a
directory
that
is
normally
searched
by
the
system
for
DLLs
(for
example,
/usr/lib
on
UNIX
platforms
and
%PATH%
on
Windows
NT),
you
do
not
need
to
specify
the
full
path
to
the
DLL,
only
the
DLL
name.
If
you
want
a
platform-independent
DLL
name,
so
it
can
be
loaded
on
any
supported
Tivoli
Access
Manager
platform,
provide
a
short
form
library
name.
The
short
name
is
prepended
and
appended
with
known
library
prefixes
and
suffixes
for
each
platform
and
each
possibility
is
searched
for
in
turn.
For
example,
using
a
short
form
library
name
of
azn_ent_user,
the
following
names
are
automatically
searched
for
on
each
platform:
Windows:
azn_ent_user.dll
AIX:
libazn_ent_user.so,
libazn_ent_user.a
Solaris:
libazn_ent_user.so
HP/UX:
libazn_ent_user.sl
[-weight
number]
A
weight
that
is
assigned
in
the
access
decision
process
to
the
particular
external
authorization
service.
The
weight
parameter
is
an
unsigned
size_t
value
and
is
optional.
The
value
signifies
the
weight
that
any
decision
returned
by
this
external
authorization
service
should
be
given
in
the
entire
decision
process.
The
default
value
is
101.
params
Optionally,
the
external
authorization
service
can
be
passed
additional
initialization
information
in
the
form
of
arguments.
The
arguments
must
be
preceded
by
the
ampersand
(for
example,
&
-server
fred).
The
service
definition
is
discussed
in
more
detail
in
“Implementing
a
service
plug-in”
on
page
81.
This
stanza
entry
is
optional.
There
is
no
default
value.
Appendix
D.
Authorization
API
client
configuration
file
289
[aznapi-pac-services]
stanza
[aznapi-pac-services]
stanza
service-id
=
{short_name|path_to_dll}
[
&
params
...
]
Defines
the
authorization
API
service
for
the
Tivoli
Access
Manager
privilege
attribute
certificate
(PAC)
encoding
service.
Each
stanza
entry
defines
different
types
of
authorization
API
service,
and
each
entry
is
the
same
format
where:
service-id
Developer-specified
identification
(ID)
of
the
PAC
service
that
produces
the
PAC.
The
service
ID
string
must
be
unique.
{short_name|path_to_dll}
The
path
to
the
dynamic
link
library
(DLL)
that
contains
the
service
executable
code.
If
the
DLL
is
located
in
a
directory
that
is
normally
searched
by
the
system
for
DLLs
(for
example,
/usr/lib
on
UNIX
platforms
and
%PATH%
on
Windows
NT),
you
do
not
need
to
specify
the
full
path
to
the
DLL,
only
the
DLL
name.
If
you
want
a
platform-independent
DLL
name,
so
it
can
be
loaded
on
any
supported
Tivoli
Access
Manager
platform,
provide
a
short
form
library
name.
The
short
name
is
prepended
and
appended
with
known
library
prefixes
and
suffixes
for
each
platform
and
each
possibility
is
searched
for
in
turn.
For
example,
using
a
short
form
library
name
of
azn_ent_user,
the
following
names
are
automatically
searched
for
on
each
platform:
Windows:
azn_ent_user.dll
AIX:
libazn_ent_user.so,
libazn_ent_user.a
Solaris:
libazn_ent_user.so
HP/UX:
libazn_ent_user.sl
params
Optionally,
you
can
specify
parameters
to
pass
to
the
service
when
it
is
initialized
by
the
authorization
API.
Parameters
are
considered
to
be
all
data
following
the
ampersand
(&)
symbol
in
the
string.
The
service
definition
is
discussed
in
more
detail
in
“Implementing
a
service
plug-in”
on
page
81.
This
stanza
entry
is
optional.
There
is
no
default
value.
290
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
[ldap]
stanza
[ldap]
stanza
authn-timeout
=
number_of_seconds
Number
of
seconds
allowed
for
authentication
operations
before
the
LDAP
server
is
considered
to
be
down.
A
value
of
zero
(0)
means
there
is
no
timeout.
This
stanza
entry
is
optional.
There
is
no
default
value:
Example:
authn-timeout
=
0
auth-using-compare
=
{yes|true|no|false}
Choice
of
whether
ldap_compare(
)
will
be
used
instead
of
the
ldap_bind(
)
call
to
verify
the
password
and
authenticate
the
user.
For
those
LDAP
servers
that
allow
it,
a
compare
operation
might
perform
faster
than
a
bind
operation.
The
value
for
each
server
can
be
different,
depending
on
how
the
server
was
configured.
This
option
changes
the
method
used
by
these
authorization
API
calls:
v
azn_util_client_authenticate(
)
v
azn_util_password_authenticate(
)
Valid
values:
yes|true
A
compare
operation
will
be
used
to
authenticate
LDAP
users
instead
of
a
bind
operation.
no|false
A
bind
operation
will
be
used
to
authenticate
LDAP
users
instead
of
a
compare
operation.
Anything
other
than
yes|true
will
be
interpreted
as
no|false,
including
a
blank
value.
This
stanza
entry
is
optional.
Default
value:
yes|true
Example:
auth-using-compare
=
true
bind-dn
=
LDAP_dn
LDAP
user
distinguished
name
(DN)
that
is
used
when
binding
(signing
on)
to
the
LDAP
server.
The
LDAP_dn
value
is
created,
based
on
the
server
name
that
was
specified
with
the
-n
server_name
flag
and
the
local
host
of
the
machine.
Use
the
svrsslcfg
utility
to
set
the
LDAP_dn
value.
This
stanza
entry
is
required
when
the
configured
user
registry
is
LDAP.
There
is
no
default
value.
Example:
bind-dn
=
cn=ivacld/libra,cn=SecurityDaemons,secAuthority=Default
bind-pwd
=
LDAP_password
Appendix
D.
Authorization
API
client
configuration
file
291
Password
for
the
LDAP
user
distinguished
name
identified
in
bind-dn
=
dn
key
value
pair.
The
LDAP_password
value
is
created
based
on
the
password
specified
by
using
the
-S
password
flag.
Use
the
svrsslcfg
utility
to
set
the
LDAP_password
value.
This
stanza
entry
is
required
when
the
configured
user
registry
is
LDAP.
There
is
no
default
value.
Example:
bind-pwd
=
zs77WVoLSZn1rKrL
cache-enabled
=
{yes|true|no|false}
Indication
of
whether
LDAP
client-side
caching
is
used
to
improve
performance
for
similar
LDAP
queries.
Valid
values:
yes|true
Enables
LDAP
client-side
caching.
no|false
Disables
LDAP
client-side
caching.
This
value
is
the
default
value.
Anything
other
than
yes|true
will
be
interpreted
as
no|false,
including
a
blank
value.
This
stanza
entry
is
optional.
Default
value:
no
Example:
cache-enabled
=
no
enabled
=
{yes|true|no|false}
Indication
of
whether
LDAP
is
being
used
as
the
user
registry.
Only
one
user
registry
can
be
specified
at
a
time.
Valid
values:
yes|true
Enables
LDAP
user
registry
support.
no|false
Disables
LDAP
user
registry
support
and
indicates
that
LDAP
is
not
the
user
registry
being
used.
Anything
other
than
yes|true
is
interpreted
as
no|false,
including
a
blank
value.
This
stanza
entry
is
required
when
LDAP
is
the
user
registry.
The
default
value
can
be
different,
depending
on
how
the
server
is
configured.
Example:
enabled
=
yes
host
=
host_name
292
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
Host
name
of
the
LDAP
server.
Valid
values
for
host_name
include
any
valid
Internet
Protocol
(IP)
host
name.
The
host_name
value
is
taken
from
the
pd.conf
file.
The
pd.conf
file
is
created
when
the
Tivoli
Access
Manager
runtime
component
is
configured
on
the
machine.
Use
the
svrsslcfg
utility
to
set
the
host_name
value
when
the
configured
Policy
Director
user
registry
is
LDAP.
This
stanza
entry
is
required.
There
is
no
default
value.
The
value
is
taken
from
the
pd.conf
file.
Examples
of
host
names:host
=
libra
host
=
libra.dallas.ibm.com
max-search-size
=
[0|number_entries]
Limit
for
the
maximum
search
size,
specified
as
the
number
of
entries,
that
can
be
returned
from
the
LDAP
server.
The
value
for
each
server
can
be
different,
depending
on
how
the
server
was
configured.
Note:
This
value
can
also
be
limited
by
the
LDAP
server
itself.
Valid
values:
0
The
number
is
unlimited;
there
is
no
limit
to
the
maximum
search
size.
number_entries
The
maximum
number
of
entries
for
search,
specified
as
an
integer
whole
number.
WebSEAL
does
not
impose
a
limit
on
the
value
of
this
integer.
See
the
discussion
on
maximum
integer
values
in
“Guidelines
for
configuring
stanzas”
on
page
274.
This
stanza
entry
is
optional.
Default
value:
2048
Example:
max-search-size
=
2048
port
=
port_number
Non-SSL
IP
port
number
that
is
used
for
communicating
with
the
LDAP
server.
For
port_number,
use
any
valid
port
number.
A
valid
port
number
is
any
positive
number
that
is
allowed
by
TCP/IP
and
that
is
not
currently
being
used
by
another
application.
This
stanza
entry
is
required.
Default
value:
389
Example:
port
=
389
prefer-readwrite-server
=
{yes|true|no|false}
Appendix
D.
Authorization
API
client
configuration
file
293
Indication
of
whether
the
client
can
question
the
Read/Write
LDAP
server
before
querying
any
replica
Read-only
servers
that
are
configured
in
the
domain.
The
default
value
can
be
different.
For
example,
the
default
value
for
ivmgrd.conf
is
yes
while
the
default
value
for
ivacld.conf
is
no.
Valid
values:
yes|true
Enables
the
client
to
be
able
to
question
the
Read/Write
LDAP
server.
no|false
Disables
the
client.
Anything
other
than
yes|true
will
be
interpreted
as
no|false,
including
a
blank
value.
This
stanza
entry
is
optional.
The
default
value
is
server
dependent.
Example:
prefer-readwrite-server
=
no
replica
=
ldap-server,
port,
type,
pref
Definition
of
the
LDAP
user
registry
replicas
in
the
domain
where:
v
ldap_server
is
the
network
name
of
the
server
v
port
is
the
port
number
for
the
LDAP
server.
A
valid
port
number
is
any
positive
number
that
is
allowed
by
TCP/IP
and
that
is
not
currently
being
used
by
another
application.
v
type
is
one
of
readonly
or
readwrite
v
preference
is
a
number
from
1
to
10
(10
is
the
highest
preference)
This
stanza
entry
is
optional.
Default
value
is
that
no
replicas
are
specified.
Example
of
one
replica
specified
and
two
replicas
commented
out:
replica
=
freddy,390,readonly,1
#replica
=
barney,391,readwrite,2
#replica
=
benny,392,readwrite,3
search-timeout
=
number_of_seconds
Number
of
seconds
allowed
for
authentication
operations
before
the
LDAP
server
is
considered
to
be
down.
A
value
of
zero
(0)
means
there
is
no
timeout.
This
stanza
entry
is
optional.
There
is
no
default
value:
Example:
search-timeout
=
0
ssl-enabled
=
{yes|true|no|false}
294
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
Indication
of
whether
to
enable
SSL
communication
with
the
LDAP
server.
The
value
for
each
server
can
be
different,
depending
on
how
the
server
was
configured.
Valid
values:
yes|true
Enables
SSL
communication.
no|false
Disables
SSL
communication.
Anything
other
than
yes|true
will
be
interpreted
as
no|false,
including
a
blank
value,
and
SSL
will
be
automatically
configured.
This
stanza
entry
is
optional.
The
default
value
is
server
dependent.
Example:
ssl-enabled
=
yes
ssl-keyfile
=
ldap-ssl-key-filename
SSL
key
file
name
and
location
containing
the
LDAP
server
certificate.
Use
the
SSL
key
file
to
handle
certificates
that
are
used
in
LDAP
communication.
The
file
type
can
be
anything
but
the
extension
is
usually
.kdb.
This
stanza
entry
is
required
only
when
ssl-enabled
=
yes.
Default
value
is
server
dependent.
Example
for
UNIX:
ssl-keyfile
=
/opt/PolicyDirector/keytab/ivmgrd.kdb
ssl-keyfile-dn
=
keyLabel
Key
label
of
the
client
personal
certificate
within
the
SSL
key
file.
This
key
label
is
used
to
identify
the
client
certificate
that
is
presented
to
the
LDAP
server.
This
stanza
entry
is
required
when
the
LDAP
server
is
configured
to
perform
client
authentication.
There
is
no
default
value.
Example:
ssl-keyfile-dn
=
"PD_LDAP"
ssl-keyfile-pwd
=
ldap-ssl-keyfile-password
Password
to
access
the
SSL
key
file.
Note:
The
password
associated
with
the
default
SSL
keyfile
is
gsk4ikm.
This
stanza
entry
is
required
only
if
ssl-enabled
=
yes.
There
is
no
default
value.
Example:
ssl-keyfile-pwd
=
mysslpwd
ssl-port
=
port_number
SSL
IP
port
that
is
used
to
connect
to
the
LDAP
server.
For
port_number,
use
any
valid
port
number.
A
valid
port
number
is
any
positive
number
that
is
allowed
by
TCP/IP
and
that
is
not
currently
being
used
by
another
application.
This
stanza
entry
is
required
only
if
ssl-enabled
=
yes.
Default
value:
636
Example:
ssl-port
=
636
timeout
=
number_of_seconds
Appendix
D.
Authorization
API
client
configuration
file
295
Number
of
seconds
allowed
for
authentication
or
search
operations
before
the
LDAP
server
is
considered
to
be
down.
A
value
of
zero
(0)
means
there
is
no
timeout.
This
stanza
entry
is
optional.
There
is
no
default
value:
Example:
timeout
=
0
296
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
[manager]
stanza
[manager]
stanza
management-domain
=
{default|domain_name
Name
of
the
management
domain.
This
value
is
created
and
set
by
svrsslcfg
Valid
values:
default
This
value
is
the
default
value.
domain_name
This
value
is
when
you
configure
your
own
name
for
the
domain.
The
domain_name
value
is
an
alphanumeric,
non-case
sensitive
string.
The
minimum
and
maximum
lengths
of
the
domain
name,
if
there
are
limits,
are
imposed
by
the
underlying
registry.
For
Active
Directory
the
maximum
length
is
256
alphanumeric
characters.
Valid
characters
are
the
letters
a-Z,
the
numbers
0-9,
a
period
(
.
),
an
underscore
(
_
),
a
plus
sign
(+),
a
hyphen
(
-
),
an
at
sign
(
@
),
an
ampersand
(
&
),
and
an
asterisk
(
*
).
You
cannot
use
a
space
in
the
domain
name.
This
stanza
entry
is
required.
Default
value:
Default
Example:
management-domain
=
Default
master-host
=
server_hostname
Host
name
of
the
Tivoli
Access
Manager
server.
Examples
of
valid
host
names:
v
mycomputer.city.company.com
v
mycomputer
This
stanza
entry
is
used
for
both
remote
and
local
mode.
This
stanza
entry
is
required.
There
is
no
default
value.
Example:
master-host
=
libra
master-port
=
port_number
TCP
port
on
which
the
server
is
listening
for
requests.
This
value
is
created
and
set
by
svrsslcfg
.
For
port_number,
use
any
valid
port
number.
A
valid
port
number
is
any
positive
number
that
is
allowed
by
TCP/IP
and
that
is
not
currently
being
used
by
another
application.
Use
the
default
port
number
value,
or
use
a
port
number
over
1000
that
is
currently
not
being
used.
This
stanza
entry
is
used
for
both
remote
and
local
mode.
This
stanza
entry
is
required.
Default
value:
7135
Example:
master-port
=
7135
Appendix
D.
Authorization
API
client
configuration
file
297
replica
=
hostname:port_number:preference:replica_certificate_dn
Configuration
settings
for
policy
server
replicas.
This
stanza
entry
is
used
for
remote
mode
only.
The
values
for
this
stanza
entry
are
set
by
using
the
svrsslcfg
utility
with
the
–add_replica
option.
The
values
are:
v
hostname
The
hostname
of
the
policy
server
replica.
v
port_number
The
port
on
which
to
communicate
with
the
policy
server
replica
v
preference
Integer
value
between
1
and
10,
specifying
the
priority
for
using
this
particular
replica
to
provide
authorization
decisions.
This
is
useful
when
the
domain
contains
multiple
replicas.
Replicas
are
accessed
in
order
of
their
preference
integer.
The
replica
with
the
largest
integer
value
is
accessed
first.
v
replica_certificate_DN
The
distinguished
name
used
to
access
the
replica’s
certificate.
This
stanza
entry
is
optional.
There
is
no
default
value.
Example
(entered
as
one
continuous
line):
replica
=
\
rep1.acme.com:7135:5:cn=ivmgrd/rep1.acme.com,o=Policy
Director,C=US
298
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
[meta-info]
stanza
[meta-info]
stanza
version
=
version_number
Authorization
API
version.
Expressed
as
a
decimal
equivalent
of
the
hexadecimal
value.
For
example,
the
hexadecimal
value
for
Tivoli
Access
ManagerVersion
5.1
is
0x510.
The
decimal
equivalent
is
1296.
Appendix
D.
Authorization
API
client
configuration
file
299
[ssl]
stanza
[ssl]
stanza
ssl-authn-user
=
user_name
The
user
name
that
is
used
when
the
authentication
type
is
password.
This
stanza
entry
is
optional.
There
is
no
default
value.
ssl-authn-password
=
password
The
password
for
the
user
name
that
is
used
if
the
authentication
type
is
password.
This
stanza
entry
is
optional,
but
is
required
when
ssl-authn-user
is
specified.
There
is
no
default
value.
Example:
ssl-authn-password
=
mypassw0rd
ssl-authn-type
=
certificate
Type
of
authentication.
This
value
is
created
and
the
value
is
set
by
svrsslcfg.
This
stanza
entry
is
required
when
SSL
is
enabled.
Default
value:
certificate
Example:
ssl-authn-type
=
certificate
ssl-auto-refresh
=
{yes|no}
Indication
of
whether
automatic
refresh
of
the
SSL
certificate
and
the
key
database
file
password
occur.
Valid
values:
yes
Enables
automatic
refresh.
When
enabled,
the
certificate
and
password
are
regenerated
if
either
is
in
danger
of
expiration
(less
than
half
the
time
left).
no
Turns
off
automatic
certificate
and
password
refresh.
This
value
is
created
and
the
value
is
set
by
svrsslcfg.
This
stanza
entry
is
required
when
SSL
is
enabled.
Default
value:
yes
Example:
ssl-auto-refresh
=
no
ssl-io-inactivity-timeout
=
{0|number_seconds}
300
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
Duration
(in
seconds)
that
an
SSL
connection
waits
for
a
response
before
timing
out.
There
is
no
one
default
value
because
the
default
value
is
set
by
the
configuration
program
of
each
server.
Valid
values:
0
No
timeout.
number_seconds
The
timeout
specified
in
number
of
seconds.
There
is
no
range
limitation
for
timeout
values.
The
number
of
seconds
value
is
set
by
svrsslcfg.
This
stanza
entry
is
required
when
SSL
is
enabled.
Default
value
is
server-dependent.
Example:
ssl-io-inactivity-timeout
=
90
ssl-keyfile
=
ssl-key-path
Path
location
and
file
name
of
the
local
system
of
the
SSL
key
file.
If
the
key
value
pair
does
not
exist
in
the
configuration
file,
the
application
will
fail.
The
file
extension
can
be
anything
but
it
is
usually
.kdb.
This
file
is
created
and
the
value
is
set
by
svrsslcfg.
This
stanza
entry
is
required
when
SSL
is
enabled.
Default
value
for
UNIX:
opt/PolicyDirector/keytab/ivmgrd.kdb
Default
value
for
Windows:
C:\pd\keytab\ivmgrd.kdb
Example
for
UNIX:
ssl-keyfile
=
opt/PolicyDirector/keytab/ivmgrd.kdb
ssl-keyfile-label
=
label_name
Label
for
the
authorization
API
server
certificate
in
the
keyfile.
This
stanza
entry
is
required.
The
default
value
is:
PD
Server
Example:
ssl-keyfile-label
=
PD
Server
ssl-keyfile-stash
=
ssl-stash-path
Appendix
D.
Authorization
API
client
configuration
file
301
Path
location
and
file
name
of
the
SSL
password
stash
file.
The
file
extension
can
be
anything
but
it
is
usually
.sth.
The
password
is
used
to
protect
private
keys
in
the
key
file.
The
password
might
be
stored
encrypted
in
a
stash
file.
If
both
ssl-keyfile-pwd
and
ssl-keyfile-stash
are
specified,
then
the
ssl-keyfile-pwd
value
will
be
used.
This
file
is
created
and
the
value
is
set
by
svrsslcfg.
The
path
is
defined
by
the
-d
option
to
the
svrsslcfg
utility.
The
name
is
defined
by
the
-n
option
to
the
svrsslcfg
utility.
This
stanza
entry
is
required
when
SSL
is
enabled.
Default
value
for
UNIX:
opt/PolicyDirector/keytab/ivmgrd.sth
Default
value
for
Windows:
C:\pd\keytab\ivmgrd.sth
Example
for
Windows:
ssl-keyfile-stash
=
C:\pd\keytab\ivmgrd.sth
ssl-listening-port
=
{0|port_number}
TCP
port
on
which
the
application
listens
for
incoming
requests
and
policy
cache
update
notifications.
Valid
values:
0
Disables
listening.
The
value
is
specified
during
configuration
by
using
the
svrsslcfg
utility.
port_number
Enables
listening
at
the
specified
port
number.
The
valid
range
for
port_number
is
any
positive
number
that
is
allowed
by
TCP/IP
and
is
not
currently
being
used
by
another
application.
This
stanza
entry
is
valid
only
with
the
following
mode
scenarios:
v
local
mode,
when
listen-flags
is
set
to
enable.
v
local
mode,
when
[aznapi-admin-services]
are
registered.
v
remote
mode,
when
[aznapi-admin-services]
are
registered.
This
stanza
entry
is
required
when
SSL
is
enabled.
Default
value:
0
Example:
ssl-listening-port
=
7137
ssl-local-domain
=
domain_name
Local
domain
name.
This
is
the
domain
in
which
the
authorization
API
server
runs.
When
this
value
is
not
in
the
configuration
file
then
operations
that
rely
on
its
presence
will
fail.
This
value
must
conform
to
the
value
specified
when
the
server
was
configured.
This
stanza
entry
is
required.
Default
value
(none)
Example:
ssl-local-domain
=
default
ssl-maximum-worker-threads
=
number_threads
302
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
Number
of
threads
that
can
be
created
by
the
authorization
API’s
internal
server
to
handle
incoming
requests.
Valid
values:
number_threads
Number
of
threads
that
can
be
specified.
The
valid
range
must
be
equal
to
1,
or
greater
than
1.
The
maximum
number
varies
because
it
is
dependent
on
available
system
resources.
This
stanza
entry
is
required
when
SSL
is
enabled.
Default
value:
10
Example:
ssl-maximum-worker-threads
=
80
ssl-mgr-config
=
relative_pathname
Location
of
the
configuration
file
used
to
configure
the
Tivoli
Access
Manager
runtime
environment
(pd.conf).
When
specified,
values
for
master-host,
master-port,
and
master-dn
from
pd.conf
will
override
any
values
specified
in
the
application
configuration
file
(this
file).
This
value
can
be
either
a
fully
qualified
path
or
can
be
a
relative
path
name.
When
the
relative
path
name
is
used,
the
configuration
file
is
expected
to
be
located
under
the
Tivoli
Access
Manager
installation
directory.
This
stanza
entry
is
optional.
There
is
no
default
value.
Example:
ssl-mgr-config
=
./lib/pd.conf
ssl-pwd-life
=
number_days
Password
lifetime
for
the
key
database
file,
specified
in
the
number
of
days.
For
automatic
password
renewal,
the
value
for
the
lifetime
of
a
password
is
controlled
by
the
number_days
value
when
the
server
is
started.
Valid
values
for
the
number_days
is
from
1
to
7,299
days.
For
manual
password
renewal,
the
value
is
dictated
by
the
value
supplied
to
the
svrsslcfg
–chgpwd
command.
This
value
is
also
written
into
the
appropriate
configuration
file.
Note:
If
a
certificate
and
the
password
to
the
keyring
database
file
containing
that
certificate
are
both
expired,
then
the
password
must
be
refreshed
first.
The
number
of
days
value
is
created
and
the
value
is
set
by
svrsslcfg.
This
stanza
entry
is
required
when
SSL
is
enabled.
Default
value:
183
Example:
ssl-pwd-life
=
105
ssl-v3-timeout
=
number_seconds
Appendix
D.
Authorization
API
client
configuration
file
303
Session
timeout
(in
seconds)
for
SSL
v3
connections
between
clients
and
servers.
This
timeout
value
controls
how
often
a
full
SSL
handshake
is
completed
between
Tivoli
Access
Manager
clients
and
servers.
Valid
range
of
values
for
number_seconds
is
from
10-86400
seconds,
where
86400
seconds
is
equal
to
1
day.
If
you
specify
a
number
outside
this
range,
the
default
number
will
be
used.
This
file
is
created
and
the
value
is
set
by
svrsslcfg.
The
path
is
defined
by
the
-d
option
to
the
svrsslcfg
utility.
The
name
is
defined
by
the
-n
option
to
the
svrsslcfg
utility.
Note:
Tivoli
Access
Manager
components
might
not
function
with
small
timeout
values
in
some
network
environments.
This
stanza
entry
is
required
when
SSL
is
enabled.
Default
value:
7200
Example:
ssl-v3-timeout
=
9800.
304
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
[uraf-registry]
stanza
[uraf-registry]
stanza
bind-id
=
server_id
Server
administrator
or
user
login
identity
that
is
used
to
bind
(sign
on)
to
the
registry
server.
If
the
ID
belongs
to
a
user
rather
than
an
administrator,
the
user
must
have
privileges
to
update
and
modify
data
in
the
user
registry.
For
IBM
Lotus
Domino
registry,
a
Lotus
Notes
ID
file
provides
the
bind
ID
equivalent.
Note:
Only
the
server
uses
this
ID.
The
server_id
is
an
alphanumeric,
case-insensitive
string.
String
values
are
expected
to
be
characters
that
are
part
of
the
local
code
set.
The
minimum
and
maximum
lengths
of
the
ID,
if
there
are
limits,
are
imposed
by
the
underlying
registry.
For
Active
Directory
the
maximum
length
is
256
alphanumeric
characters.
This
stanza
entry
is
required
when
the
configured
registry
type
is
not
LDAP.
The
default
value
is
generated;
do
not
change
it.
Example:
bind-id
=
MySvrAdminID
bind-pwd
=
admin_password
Encoded
administrator
log-in
password
that
is
used
to
bind
(or
sign
on)
to
the
registry
server.
Additional
password
requirements
can
be
specified
for
Tivoli
Access
Manager
after
the
product
is
installed.
However,
the
initial
password
does
not
necessarily
conform
to
those
requirements.
The
admin_password
value
is
filled
in
automatically,
based
on
information
that
is
supplied
during
server
configuration.
The
password
is
an
encrypted
string.
This
stanza
entry
is
required
when
your
user
registry
is
not
LDAP.
The
default
value
is
generated;
do
not
change
it.
Example:
bind-pwd
=
MyADbindPwd
cache-lifetime
=
number_seconds
Number
of
seconds
that
the
objects
are
allowed
to
stay
in
the
cache.
Valid
values
include:
number_seconds
The
timeout
specified
in
number
of
seconds.
Use
a
number
within
the
range
of
1
to
86400.
If
cache-mode
=
enabled
and
this
stanza
entry
is
not
used,
the
default
value
of
86400
seconds
(number
of
seconds
in
one
day)
will
be
used.
For
performance
tuning,
the
longer
the
time
specified,
the
longer
the
repetitive
Read
advantage
is
held.
A
smaller
number
of
seconds
negates
the
cache
advantage
for
user-initiated
Reads.
This
stanza
entry
is
optional.
Default
value:
86400
Example:
cache-lifetime
=63200
cache-mode
={enabled|disabled}
Appendix
D.
Authorization
API
client
configuration
file
305
Mode
for
caching
that
represents
the
cache
being
either
turned
on
or
turned
off.
Valid
values
include:
enabled
Turns
the
cache
on.
You
would
enable
the
cache
mode
to
improve
the
performance
of
repetitive
Read
actions
on
a
specified
object,
such
as:
login
performance
that
is
done
more
than
once
a
day.
Performance
for
Write
actions
would
not
be
improved.
disabled
Turns
the
cache
off.
You
would
disable
the
cache
mode
for
better
security.
Caching
opens
a
small
window
for
users
to
go
from
server
to
server
in
order
to
bypass
the
maximum
number
of
failed
login
attempts.
This
value
is
the
default
value.
This
stanza
entry
is
optional.
Default
value:
enabled
Example:
cache-mode
=
enabled
cache-size
=
number_objects
object_type:cache_count
value
306
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
Maximum
number
of
objects
for
a
particular
type
of
object
that
can
be
in
the
cache
at
one
time.
Or,
if
it
is
not
numeric,
it
is
a
list
of
one
or
more
object
types
and
their
cache
count
values.
If
cache-mode
=
enabled
and
this
stanza
entry
is
not
used,
the
cache
size
default
value
will
be
used.
Valid
values
include:
number_objects
Maximum
number
of
objects
must
be
a
prime
number
for
the
cache
count
values.
Range
value
is
from
3
to
a
maximum
number
that
is
logical
for
the
task
and
that
does
not
affect
performance.
Non-prime
numbers
are
automatically
rounded
up
to
the
next
higher
prime
number.
If
the
number
fails,
the
default
value
will
be
used.
object
type:cache
count
value
List
of
one
or
more
object
types
and
their
cache
count
values.
Examples:
cache-size
=user:251;group:251;resgroup:251;resource:251;
rescreds:251;
or:
cache-size
=user:251;group:251;
The
second
example
sets
the
user
and
group
cache
sizes
to
251
and
does
not
use
any
cache
for
the
others.
Performance
tuning
depends
on
how
much
memory
space
is
dedicated
to
a
cache
or
how
many
objects
you
typically
have
repetitive
Read
actions
on
(such
as
how
many
users
you
have
logging
in
a
day).
For
example,
a
setting
of
251
might
not
be
good
if
you
have
1000
users
logging
in
and
out
several
times
a
day.
However,
if
only
200
of
those
users
log
in
and
out
repetitively
during
the
day,
251
might
work
well.
This
stanza
entry
is
optional.
Default
value:
251
Example:
cache-size
=305
uraf-server-config
=
fully_qualified_path
Appendix
D.
Authorization
API
client
configuration
file
307
File
name
and
location
of
the
URAF
registry
configuration
file
for
Tivoli
Access
Manager.
The
fully_qualified_path
value
represents
an
alphanumeric,
case-insensitive
string.
String
values
are
expected
to
be
characters
that
are
part
of
the
local
code
set.
The
set
of
characters
permitted
in
a
file
name
can
be
determined
by
the
file
system
and
by
the
local
code
set.
For
Windows,
file
names
cannot
have
these
characters:
a
backward
slash
(\),
a
colon(:),
a
question
mark
(?),
or
double
quotation
marks
(″).
This
stanza
entry
is
required
when
the
configured
registry
type
is
not
LDAP.
UNIX
example
using
IBM
Lotus
Domino
server
and
user
registry:
Default
value
for
UNIX:
uraf-registry-config
=/opt/PolicyDirector/etc/domino.conf
Windows
example
using
Microsoft
Active
Directory
server
and
user
registry:
uraf-registry-config
=c:\Program
files
\tivoli
\Policy
Director
\etc
\activedir.conf
Windows
example
for
using
Microsoft
Active
Directory
user
registry
for
platforms
other
than
Windows
2000:
uraf-registry-config
=c:\Program
files
\tivoli
\Policy
Director
\etc\activedir_ldap.conf
308
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
[xmladi-attribute-definitions]
stanza
[xmladi-attribute-definitions]
stanza
attribute_name
=
″attribute_value″
XMLADI
attribute
definitions.
These
attribute
definitions
are
inserted
into
the
XMLADI
element
start
tag
to
enable
attributes
to
be
defined
for
the
entire
XMLADI
document
and
all
ADI
defined
therein.
The
programmatic
initialization
attribute
can
contain
multiple
attribute
values,
one
for
each
attribute
definition
to
be
added
to
the
XMLADI
element
start
tag.
The
attribute
definitions
are
in
the
format:
attribute_name
=
″attribute_value″
For
example:
xmlns:myNS
=
"http://myURI.mycompany.com"
appID
=
’"Jupiter"
-
Account
Management
Web
\
Portal
Server
#1.’
The
attribute
value
must
be
enclosed
in
either
single
or
double
quotation
marks.
The
XMLADI
element
start
tag
built
from
these
definitions
is:
<XMLADI
xmlns:myNS="http://myURI.mycompany.com"
\
appID=’"Jupiter"
-
Account
Management
Web
Portal
\
Server
#1.’>
This
stanza
entry
is
optional.
There
is
no
default
value.
Appendix
D.
Authorization
API
client
configuration
file
309
310
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
Appendix
E.
User
registry
differences
The
following
user
registry
differences
are
known
to
exist
in
this
version
of
IBM
Tivoli
Access
Manager
(Tivoli
Access
Manager.)
1.
When
Tivoli
Access
Manager
is
using
either
Microsoft
Active
Directory
or
a
Lotus
Domino
server
as
its
user
registry,
only
a
single
domain
is
supported.
Use
an
LDAP
user
registry
if
you
wish
to
take
advantage
of
the
multi-domain
support
in
Tivoli
Access
Manager.
2.
Tivoli
Access
Manager
does
not
support
cross
domain
group
membership
or
universal
groups
when
using
Microsoft
Active
Directory
as
its
user
registry.
Importing
such
groups
into
Tivoli
Access
Manager
is
not
supported.
3.
When
the
Tivoli
Access
Manager
policy
server
is
using
either
Microsoft
Active
Directory
or
a
Lotus
Domino
server
as
its
user
registry,
existing
Tivoli
SecureWay
Policy
Director,
Version
3.8
clients
are
not
able
to
connect
to
the
policy
server.
Either
use
a
different
user
registry
or
upgrade
the
clients
to
Tivoli
Access
Manager.
4.
Users
created
in
a
Lotus
Domino
server
or
Microsoft
Active
Directory
user
registry
are
automatically
given
the
capability
to
own
single
signon
credentials
and
this
capability
can
not
be
removed.
When
using
an
LDAP
user
registry,
this
capability
must
be
explicitly
granted
to
a
user
and
subsequently
can
be
removed.
5.
Leading
and
trailing
blanks
in
user
names
and
group
names
are
ignored
when
using
LDAP
or
Microsoft
Active
Directory
as
the
user
registry
in
an
Tivoli
Access
Manager
secure
domain.
However,
when
using
a
Lotus
Domino
server
as
a
user
registry,
leading
and
trailing
blanks
are
significant.
To
ensure
that
processing
is
consistent
regardless
of
what
user
registry
is
being
used,
define
users
and
groups
in
the
user
registry
without
leading
or
trailing
blanks
in
their
names.
6.
The
forward
slash
character
(/)
should
be
avoided
in
user
and
group
names
defined
using
distinguished
name
strings.
The
forward
slash
character
is
treated
differently
in
different
user
registries:
Lotus
Domino
server
Users
and
groups
can
not
be
created
with
names
using
a
distinguished
name
string
containing
a
forward
slash
character.
To
avoid
the
problem,
either
do
not
use
a
forward
slash
character
or
define
the
user
without
using
the
distinguished
name
designation:
pdadmin
user
create
myuser
username/locinfo
test
test
testpwd
instead
of
using
this
one:
pdadmin
user
create
myuser
cn=username/o=locinfo
test
test
testpwd
Microsoft
Active
Directory
Users
and
groups
can
be
created
with
names
using
a
distinguished
name
string
containing
a
forward
slash
character.
However,
subsequent
operations
on
the
object
might
fail
as
some
Active
Directory
functions
interpret
the
forward
slash
character
as
a
separator
between
the
object
name
and
the
host
name.
To
avoid
the
problem,
do
not
use
a
forward
slash
character
to
define
the
user.
7.
When
using
a
multi-domain
Microsoft
Active
Directory
user
registry,
multiple
users
and
groups
can
be
defined
with
the
same
short
name
as
long
as
they
©
Copyright
IBM
Corp.
2000,2003
311
reside
in
different
domains.
However,
the
full
name
of
the
user
or
group,
including
the
domain
suffix,
must
always
be
specified
to
Tivoli
Access
Manager.
8.
When
using
iPlanet
Version
5.0
as
the
user
registry,
a
user
that
is
created,
added
to
a
group,
and
then
deleted
from
the
user
registry
retains
its
group
membership.
If
a
user
with
the
same
name
is
created
at
some
later
time,
the
new
user
automatically
inherits
the
old
group
membership
and
might
be
given
inappropriate
permissions.
It
is
strongly
recommended
that
the
user
be
removed
from
all
groups
before
the
user
is
deleted.
This
problem
does
not
occur
when
using
the
other
supported
user
registries.
9.
Attempting
to
add
a
single
duplicate
user
to
a
group
does
not
produce
an
error
when
an
LDAP
user
registry
is
being
used.
However,
an
error
is
properly
reflected
when
using
Lotus
Domino
server
or
Microsoft
Active
Directory.
10.
The
Tivoli
Access
Manager
authorization
API
provides
a
credentials
attribute
entitlements
service.
This
service
is
used
to
retrieve
user
attributes
from
a
user
registry.
When
this
service
is
used
with
an
LDAP
user
registry,
the
retrieved
attributes
can
be
either
string
or
binary
data.
However,
when
this
service
is
used
with
a
Microsoft
Active
Directory
or
Lotus
Domino
user
registry,
the
retrieved
attributes
can
be
either
string,
binary
or
integer
data.
11.
The
maximum
lengths
of
various
names
associated
with
Tivoli
Access
Manager
vary
depending
on
the
user
registry
being
used.
See
Table
7
for
a
comparison
of
the
maximum
lengths
allowed
and
the
recommended
maximum
length
to
use
to
ensure
compatibility
with
all
the
user
registries
supported
by
Tivoli
Access
Manager.
Table
7.
Maximum
lengths
for
names
based
on
user
registry
Maximum
length
of:
LDAP
Microsoft
Active
Directory
Lotus
Domino
server
Recommended
maximum
value
First
name
(LDAP
CN)
256
64
960
64
Middle
name
128
64
65535
64
Last
name
(surname)
128
64
960
64
Registry
UID
(LDAP
DN)
1024
2048
255
This
value
is
user
registry-specific
and
must
be
changed
when
changing
user
registries.
Tivoli
Access
Manager
user
identity
256
2048
-
1
-
length_of_
domain_name
200
-
4
-
length_of_
domain_name
This
value
is
user
registry-specific
and
must
be
changed
when
changing
user
registries.
User
password
unlimited
256
unlimited
256
User
description
1024
1024
1024
1024
Group
name
256
256
Group
description
1024
1024
1024
1024
312
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
Table
7.
Maximum
lengths
for
names
based
on
user
registry
(continued)
Maximum
length
of:
LDAP
Microsoft
Active
Directory
Lotus
Domino
server
Recommended
maximum
value
Single
signon
resource
name
240
256
256
240
Single
signon
resource
description
1024
1024
1024
1024
Single
signon
user
ID
240
256
256
240
Single
signon
password
unlimited
256
unlimited
256
Single
signon
group
name
240
256
256
240
Single
signon
group
description
1024
1024
1024
1024
Action
name
1
1
1
1
Action
description,
action
type
unlimited
unlimited
unlimited
Object
name,
object
space
name,
ACL
name,
POP
name
unlimited
unlimited
unlimited
Object
description,
object
space
description,
ACL
description,
POP
description
unlimited
unlimited
unlimited
Even
though
some
names
can
be
of
unlimited
length,
excessive
lengths
can
result
in
policy
that
is
difficult
to
manage
and
might
result
in
poor
system
performance.
Choose
maximum
values
that
are
logical
for
your
environment.
Appendix
E.
User
registry
differences
313
314
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
Appendix
F.
Notices
This
information
was
developed
for
products
and
services
offered
in
the
U.S.A.
IBM
may
not
offer
the
products,
services,
or
features
discussed
in
this
document
in
other
countries.
Consult
your
local
IBM
representative
for
information
on
the
products
and
services
currently
available
in
your
area.
Any
reference
to
an
IBM
product,
program,
or
service
is
not
intended
to
state
or
imply
that
only
that
IBM
product,
program,
or
service
may
be
used.
Any
functionally
equivalent
product,
program,
or
service
that
does
not
infringe
any
IBM
intellectual
property
right
may
be
used
instead.
However,
it
is
the
user’s
responsibility
to
evaluate
and
verify
the
operation
of
any
non-IBM
product,
program,
or
service.
IBM
may
have
patents
or
pending
patent
applications
covering
subject
matter
described
in
this
document.
The
furnishing
of
this
document
does
not
give
you
any
license
to
these
patents.
You
can
send
license
inquiries,
in
writing,
to:
IBM
Director
of
Licensing
IBM
Corporation
500
Columbus
Avenue
Thornwood,
NY
10594
U.S.A
For
license
inquiries
regarding
double-byte
(DBCS)
information,
contact
the
IBM
Intellectual
Property
Department
in
your
country
or
send
inquiries,
in
writing,
to:
IBM
World
Trade
Asia
Corporation
Licensing
2-31
Roppongi
3-chome,
Minato-ku
Tokyo
106,
Japan
The
following
paragraph
does
not
apply
to
the
United
Kingdom
or
any
other
country
where
such
provisions
are
inconsistent
with
local
law:
INTERNATIONAL
BUSINESS
MACHINES
CORPORATION
PROVIDES
THIS
PUBLICATION
“AS
IS”
WITHOUT
WARRANTY
OF
ANY
KIND,
EITHER
EXPRESS
OR
IMPLIED,
INCLUDING,
BUT
NOT
LIMITED
TO,
THE
IMPLIED
WARRANTIES
OF
NON-INFRINGEMENT,
MERCHANTABILITY
OR
FITNESS
FOR
A
PARTICULAR
PURPOSE.
Some
states
do
not
allow
disclaimer
of
express
or
implied
warranties
in
certain
transactions,
therefore,
this
statement
may
not
apply
to
you.
This
information
could
include
technical
inaccuracies
or
typographical
errors.
Changes
are
periodically
made
to
the
information
herein;
these
changes
will
be
incorporated
in
new
editions
of
the
publication.
IBM
may
make
improvements
and/or
changes
in
the
product(s)
and/or
the
program(s)
described
in
this
publication
at
any
time
without
notice.
Any
references
in
this
information
to
non-IBM
Web
sites
are
provided
for
convenience
only
and
do
not
in
any
manner
serve
as
an
endorsement
of
those
Web
sites.
The
materials
at
those
Web
sites
are
not
part
of
the
materials
for
this
IBM
product
and
use
of
those
Web
sites
is
at
your
own
risk.
IBM
may
use
or
distribute
any
of
the
information
you
supply
in
any
way
it
believes
appropriate
without
incurring
any
obligation
to
you.
©
Copyright
IBM
Corp.
2000,2003
315
Licensees
of
this
program
who
wish
to
have
information
about
it
for
the
purpose
of
enabling:
(i)
the
exchange
of
information
between
independently
created
programs
and
other
programs
(including
this
one)
and
(ii)
the
mutual
use
of
the
information
which
has
been
exchanged,
should
contact:
IBM
Corporation
2Z4A/101
11400
Burnet
Road
Austin,
TX
78758
USA
Such
information
may
be
available,
subject
to
appropriate
terms
and
conditions,
including
in
some
cases,
payment
of
a
fee.
The
licensed
program
described
in
this
information
and
all
licensed
material
available
for
it
are
provided
by
IBM
under
terms
of
the
IBM
Customer
Agreement,
IBM
International
Program
License
Agreement,
or
any
equivalent
agreement
between
us.
Any
performance
data
contained
herein
was
determined
in
a
controlled
environment.
Therefore,
the
results
obtained
in
other
operating
environments
may
vary
significantly.
Some
measurements
may
have
been
made
on
development-level
systems
and
there
is
no
guarantee
that
these
measurements
will
be
the
same
on
generally
available
systems.
Furthermore,
some
measurement
may
have
been
estimated
through
extrapolation.
Actual
results
may
vary.
Users
of
this
document
should
verify
the
applicable
data
for
their
specific
environment.
Information
concerning
non-IBM
products
was
obtained
from
the
suppliers
of
those
products,
their
published
announcements
or
other
publicly
available
sources.
IBM
has
not
tested
those
products
and
cannot
confirm
the
accuracy
of
performance,
compatibility
or
any
other
claims
related
to
non-IBM
products.
Questions
on
the
capabilities
of
non-IBM
products
should
be
addressed
to
the
suppliers
of
those
products.
All
statements
regarding
IBM’s
future
direction
or
intent
are
subject
to
change
or
withdrawal
without
notice,
and
represent
goals
and
objectives
only.
This
information
contains
examples
of
data
and
reports
used
in
daily
business
operations.
To
illustrate
them
as
completely
as
possible,
the
examples
include
the
names
of
individuals,
companies,
brands,
and
products.
All
of
these
names
are
fictitious
and
any
similarity
to
the
names
and
addresses
used
by
an
actual
business
enterprise
is
entirely
coincidental.
COPYRIGHT
LICENSE:
This
information
contains
sample
application
programs
in
source
language,
which
illustrates
programming
techniques
on
various
operating
platforms.
You
may
copy,
modify,
and
distribute
these
sample
programs
in
any
form
without
payment
to
IBM,
for
the
purposes
of
developing,
using,
marketing
or
distributing
application
programs
conforming
to
the
application
programming
interface
for
the
operating
platform
for
which
the
sample
programs
are
written.
These
examples
have
not
been
thoroughly
tested
under
all
conditions.
IBM,
therefore,
cannot
guarantee
or
imply
reliability,
serviceability,
or
function
of
these
programs.
You
may
copy,
modify,
and
distribute
these
sample
programs
in
any
form
without
payment
to
IBM
for
the
purposes
of
developing,
using,
marketing,
or
distributing
application
programs
conforming
to
IBM’s
application
programming
interfaces.
316
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
Each
copy
or
any
portion
of
these
sample
programs
or
any
derivative
work,
must
include
a
copyright
notice
as
follows:
©
(your
company
name)
(year).
Portions
of
this
code
are
derived
from
IBM
Corp.
Sample
Programs.
©
Copyright
IBM
Corp.
_enter
the
year
or
years_.
All
rights
reserved.
If
you
are
viewing
this
information
softcopy,
the
photographs
and
color
illustrations
may
not
appear.
Trademarks
The
following
terms
are
trademarks
or
registered
trademarks
of
International
Business
Machines
Corporation
in
the
United
States,
other
countries,
or
both:
AIX
DB2
IBM
IBM
logo
SecureWay
Tivoli
Tivoli
logo
WebSphere
Microsoft,
Windows,
Windows
NT,
and
the
Windows
logo
are
trademarks
of
Microsoft
Corporation
in
the
United
States,
other
countries,
or
both.
Java
and
all
Java-based
trademarks
and
logos
are
trademarks
or
registered
trademarks
of
Sun
Microsystems,
Inc.
in
the
United
States
and
other
countries.
UNIX
is
a
registered
trademark
of
The
Open
Group
in
the
United
States
and
other
countries.
Other
company,
product,
and
service
names
may
be
trademarks
or
service
marks
of
others.
Appendix
F.
Notices
317
318
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
Glossary
A
access
control.
In
computer
security,
the
process
of
ensuring
that
the
resources
of
a
computer
system
can
be
accessed
only
by
authorized
users
in
authorized
ways.
access
control
list
(ACL).
In
computer
security,
a
list
that
is
associated
with
an
object
that
identifies
all
the
subjects
that
can
access
the
object
and
their
access
rights.
For
example,
an
access
control
list
is
a
list
that
is
associated
with
a
file
that
identifies
the
users
who
can
access
the
file
and
identifies
the
users’
access
rights
to
that
file.
access
permission.
The
access
privilege
that
applies
to
the
entire
object.
action.
An
access
control
list
(ACL)
permission
attribute.
See
also
access
control
list.
ACL.
See
access
control
list.
administration
service.
An
authorization
API
runtime
plug-in
that
can
be
used
to
perform
administration
requests
on
a
Tivoli
Access
Manager
resource
manager
application.
The
administration
service
will
respond
to
remote
requests
from
the
pdadmin
command
to
perform
tasks,
such
as
listing
the
objects
under
a
particular
node
in
the
protected
object
tree.
Customers
may
develop
these
services
using
the
authorization
ADK.
attribute
list.
A
linked
list
that
contains
extended
information
that
is
used
to
make
authorization
decisions.
Attribute
lists
consist
of
a
set
of
name
=
value
pairs.
authentication.
(1)
In
computer
security,
verification
of
the
identity
of
a
user
or
the
user’s
eligibility
to
access
an
object.
(2)
In
computer
security,
verification
that
a
message
has
not
been
altered
or
corrupted.
(3)
In
computer
security,
a
process
that
is
used
to
verify
the
user
of
an
information
system
or
of
protected
resources.
See
also
multi-factor
authentication,
network-based
authentication,
and
step-up
authentication.
authorization.
(1)
In
computer
security,
the
right
granted
to
a
user
to
communicate
with
or
make
use
of
a
computer
system.
(2)
The
process
of
granting
a
user
either
complete
or
restricted
access
to
an
object,
resource,
or
function.
authorization
rule.
See
rule.
authorization
service
plug-in.
A
dynamically
loadable
library
(DLL
or
shared
library)
that
can
be
loaded
by
the
Tivoli
Access
Manager
authorization
API
runtime
client
at
initialization
time
in
order
to
perform
operations
that
extend
a
service
interface
within
the
Authorization
API.
The
service
interfaces
that
are
currently
available
include
Administration,
External
Authorization,
Credentials
modification,
Entitlements
and
PAC
manipulation
interfaces.
Customers
may
develop
these
services
using
the
authorization
ADK.
B
BA.
See
basic
authentication.
basic
authentication.
A
method
of
authentication
that
requires
the
user
to
enter
a
valid
user
name
and
password
before
access
to
a
secure
online
resource
is
granted.
bind.
To
relate
an
identifier
to
another
object
in
a
program;
for
example,
to
relate
an
identifier
to
a
value,
an
address
or
another
identifier,
or
to
associate
formal
parameters
and
actual
parameters.
blade.
A
component
that
provides
application-specific
services
and
components.
business
entitlement.
The
supplemental
attribute
of
a
user
credential
that
describes
the
fine-grained
conditions
that
can
be
used
in
the
authorization
of
requests
for
resources.
C
CA.
See
certificate
authority.
CDAS.
See
Cross
Domain
Authentication
Service.
CDMF.
See
Cross
Domain
Mapping
Framework.
certificate.
In
computer
security,
a
digital
document
that
binds
a
public
key
to
the
identity
of
the
certificate
owner,
thereby
enabling
the
certificate
owner
to
be
authenticated.
A
certificate
is
issued
by
a
certificate
authority.
certificate
authority
(CA).
An
organization
that
issues
certificates.
The
certificate
authority
authenticates
the
certificate
owner’s
identity
and
the
services
that
the
owner
is
authorized
to
use,
issues
new
certificates,
renews
existing
certificates,
and
revokes
certificates
belonging
to
users
who
are
no
longer
authorized
to
use
them.
CGI.
See
common
gateway
interface.
©
Copyright
IBM
Corp.
2000,2003
319
cipher.
Encrypted
data
that
is
unreadable
until
it
has
been
converted
into
plain
data
(decrypted)
with
a
key.
common
gateway
interface
(CGI).
An
Internet
standard
for
defining
scripts
that
pass
information
from
a
Web
server
to
an
application
program,
through
an
HTTP
request,
and
vice
versa.
A
CGI
script
is
a
CGI
program
that
is
written
in
a
scripting
language,
such
as
Perl.
configuration.
(1)
The
manner
in
which
the
hardware
and
software
of
an
information
processing
system
are
organized
and
interconnected.
(2)
The
machines,
devices,
and
programs
that
make
up
a
system,
subsystem,
or
network.
connection.
(1)
In
data
communication,
an
association
established
between
functional
units
for
conveying
information.
(2)
In
TCP/IP,
the
path
between
two
protocol
applications
that
provides
reliable
data
stream
delivery
service.
In
the
Internet,
a
connection
extends
from
a
TCP
application
on
one
system
to
a
TCP
application
on
another
system.
(3)
In
system
communications,
a
line
over
which
data
can
be
passed
between
two
systems
or
between
a
system
and
a
device.
container
object.
A
structural
designation
that
organizes
the
object
space
into
distinct
functional
regions.
cookie.
Information
that
a
server
stores
on
a
client
machine
and
accesses
during
subsequent
sessions.
Cookies
allow
servers
to
remember
specific
information
about
clients.
credentials.
Detailed
information,
acquired
during
authentication,
that
describes
the
user,
any
group
associations,
and
other
security-related
identity
attributes.
Credentials
can
be
used
to
perform
a
multitude
of
services,
such
as
authorization,
auditing,
and
delegation.
credentials
modification
service.
An
authorization
API
runtime
plug-in
which
can
be
used
to
modify
a
Tivoli
Access
Manager
credential.
Credentials
modification
services
developed
externally
by
customers
are
limited
to
performing
operation
to
add
and
remove
from
the
credentials
attribute
list
and
only
to
those
attributes
that
are
considered
modifiable.
cross
domain
authentication
service
(CDAS).
A
WebSEAL
service
that
provides
a
shared
library
mechanism
that
allows
you
to
substitute
the
default
WebSEAL
authentication
mechanisms
with
a
custom
process
that
returns
a
Tivoli
Access
Manager
identity
to
WebSEAL.
See
also
WebSEAL.
cross
domain
mapping
framework
(CDMF).
A
programming
interface
that
allows
a
developer
to
customize
the
mapping
of
user
identities
and
the
handling
of
user
attributes
when
WebSEAL
e-Community
SSO
function
are
used.
D
daemon.
A
program
that
runs
unattended
to
perform
continuous
or
periodic
systemwide
functions,
such
as
network
control.
Some
daemons
are
triggered
automatically
to
perform
their
task;
others
operate
periodically.
directory
schema.
The
valid
attribute
types
and
object
classes
that
can
appear
in
a
directory.
The
attribute
types
and
object
classes
define
the
syntax
of
the
attribute
values,
which
attributes
must
be
present,
and
which
attributes
may
be
present
for
the
directory.
distinguished
name
(DN).
The
name
that
uniquely
identifies
an
entry
in
a
directory.
A
distinguished
name
is
made
up
of
attribute:value
pairs,
separated
by
commas.
digital
signature.
In
e-commerce,
data
that
is
appended
to,
or
is
a
cryptographic
transformation
of,
a
data
unit
and
that
enables
the
recipient
of
the
data
unit
to
verify
the
source
and
integrity
of
the
unit
and
to
recognize
potential
forgery.
DN.
See
distinguished
name.
domain.
(1)
A
logical
grouping
of
users,
systems,
and
resources
that
share
common
services
and
usually
function
with
a
common
purpose.
(2)
That
part
of
a
computer
network
in
which
the
data
processing
resources
are
under
common
control.
See
also
domain
name.
domain
name.
In
the
Internet
suite
of
protocols,
a
name
of
a
host
system.
A
domain
name
consists
of
a
sequence
of
subnames
that
are
separated
by
a
delimiter
character.
For
example,
if
the
fully
qualified
domain
name
(FQDN)
of
a
host
system
is
as400.rchland.vnet.ibm.com,
each
of
the
following
is
a
domain
name:
as400.rchland.vnet.ibm.com,
vnet.ibm.com,
ibm.com.
E
EAS.
See
External
Authorization
Service.
encryption.
In
computer
security,
the
process
of
transforming
data
into
an
unintelligible
form
in
such
a
way
that
the
original
data
either
cannot
be
obtained
or
can
be
obtained
only
by
using
a
decryption
process.
entitlement.
A
data
structure
that
contains
externalized
security
policy
information.
Entitlements
contain
policy
data
or
capabilities
that
are
formatted
in
a
way
that
is
understandable
to
a
specific
application.
entitlement
service.
An
authorization
API
runtime
plug-in
which
can
be
used
to
return
entitlements
from
an
external
source
for
a
principal
or
set
of
conditions.
Entitlements
are
normally
application
specific
data
that
will
be
consumed
by
the
resource
manager
application
320
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
in
some
way
or
added
to
the
principal’s
credentials
for
use
further
on
in
the
authorization
process.
Customers
may
develop
these
services
using
the
authorization
ADK.
external
authorization
service.
An
authorization
API
runtime
plug-in
that
can
be
used
to
make
application
or
environment
specific
authorization
decisions
as
part
of
the
Tivoli
Access
Manager
authorization
decision
chain.
Customers
may
develop
these
services
using
the
authorization
ADK.
F
file
transfer
protocol
(FTP).
In
the
Internet
suite
of
protocols,
an
application
layer
protocol
that
uses
Transmission
Control
Protocol
(TCP)
and
Telnet
services
to
transfer
bulk-data
files
between
machines
or
hosts.
G
global
signon
(GSO).
A
flexible
single
sign-on
solution
that
enables
the
user
to
provide
alternative
user
names
and
passwords
to
the
back-end
Web
application
server.
Global
signon
grants
users
access
to
the
computing
resources
they
are
authorized
to
use
—
through
a
single
login.
Designed
for
large
enterprises
consisting
of
multiple
systems
and
applications
within
heterogeneous,
distributed
computing
environments,
GSO
eliminates
the
need
for
users
to
manage
multiple
user
names
and
passwords.
See
also
single
signon.
GSO.
See
global
signon.
H
host.
A
computer
that
is
connected
to
a
network
(such
as
the
Internet
or
an
SNA
network)
and
provides
an
access
point
to
that
network.
Also,
depending
on
the
environment,
the
host
may
provide
centralized
control
of
the
network.
The
host
can
be
a
client,
a
server,
or
both
a
client
and
a
server
simultaneously.
HTTP.
See
Hypertext
Transfer
Protocol.
hypertext
transfer
protocol
(HTTP).
In
the
Internet
suite
of
protocols,
the
protocol
that
is
used
to
transfer
and
display
hypertext
documents.
I
Internet
protocol
(IP).
In
the
Internet
suite
of
protocols,
a
connectionless
protocol
that
routes
data
through
a
network
or
interconnected
networks
and
acts
as
an
intermediary
between
the
higher
protocol
layers
and
the
physical
network.
Internet
suite
of
protocols.
A
set
of
protocols
developed
for
use
on
the
Internet
and
published
as
Requests
for
Comments
(RFCs)
through
the
Internet
Engineering
Task
Force
(IETF).
interprocess
communication
(IPC).
(1)
The
process
by
which
programs
communicate
data
to
each
other
and
synchronize
their
activities.
Semaphores,
signals,
and
internal
message
queues
are
common
methods
of
interprocess
communication.
(2)
A
mechanism
of
an
operating
system
that
allows
processes
to
communicate
with
each
other
within
the
same
computer
or
over
a
network.
IP.
See
Internet
Protocol.
IPC.
See
Interprocess
Communication.
J
junction.
An
HTTP
or
HTTPS
connection
between
a
front-end
WebSEAL
server
and
a
back-end
Web
application
server.
WebSEAL
uses
a
junction
to
provide
protective
services
on
behalf
of
the
back-end
server.
K
key.
In
computer
security,
a
sequence
of
symbols
that
is
used
with
a
cryptographic
algorithm
for
encrypting
or
decrypting
data.
See
private
key
and
public
key.
key
database
file.
See
key
ring.
key
file.
See
key
ring.
key
pair.
In
computer
security,
a
public
key
and
a
private
key.
When
the
key
pair
is
used
for
encryption,
the
sender
uses
the
public
key
to
encrypt
the
message,
and
the
recipient
uses
the
private
key
to
decrypt
the
message.
When
the
key
pair
is
used
for
signing,
the
signer
uses
the
private
key
to
encrypt
a
representation
of
the
message,
and
the
recipient
uses
the
public
key
to
decrypt
the
representation
of
the
message
for
signature
verification.
key
ring.
In
computer
security,
a
file
that
contains
public
keys,
private
keys,
trusted
roots,
and
certificates.
L
LDAP.
See
Lightweight
Directory
Access
Protocol.
lightweight
directory
access
protocol
(LDAP).
An
open
protocol
that
(a)
uses
TCP/IP
to
provide
access
to
directories
that
support
an
X.500
model
and
(b)
does
not
incur
the
resource
requirements
of
the
more
complex
X.500
Directory
Access
Protocol
(DAP).
Applications
that
use
LDAP
(known
as
directory-enabled
applications)
can
use
the
directory
as
a
common
data
store
and
for
retrieving
information
about
people
or
services,
such
as
addresses,
public
keys,
or
service-specific
configuration
parameters.
LDAP
was
originally
specified
in
RFC
Glossary
321
1777.
LDAP
version
3
is
specified
in
RFC
2251,
and
the
IETF
continues
work
on
additional
standard
functions.
Some
of
the
IETF-defined
standard
schemas
for
LDAP
are
found
in
RFC
2256.
lightweight
third
party
authentication
(LTPA).
An
authentication
framework
that
allows
single
sign-on
across
a
set
of
Web
servers
that
fall
within
an
Internet
domain.
LTPA.
See
lightweight
third
party
authentication.
M
management
domain.
The
default
domain
in
which
Tivoli
Access
Manager
enforces
security
policies
for
authentication,
authorization,
and
access
control.
This
domain
is
created
when
the
policy
server
is
configured.
See
also
domain.
management
server.
Obsolete.
See
policy
server.
metadata.
Data
that
describes
the
characteristics
of
stored
data.
migration.
The
installation
of
a
new
version
or
release
of
a
program
to
replace
an
earlier
version
or
release.
multi-factor
authentication.
A
protected
object
policy
(POP)
that
forces
a
user
to
authenticate
using
two
or
more
levels
of
authentication.
For
example,
the
access
control
on
a
protected
resource
can
require
that
the
users
authenticate
with
both
user
name/password
and
user
name/token
passcode.
See
also
protected
object
policy.
multiplexing
proxy
agent
(MPA).
A
gateway
that
accommodates
multiple
client
access.
These
gateways
are
sometimes
known
as
Wireless
Access
Protocol
(WAP)
gateways
when
clients
access
a
secure
domain
using
a
WAP.
Gateways
establish
a
single
authenticated
channel
to
the
originating
server
and
tunnel
all
client
requests
and
responses
through
this
channel.
N
network-based
authentication.
A
protected
object
policy
(POP)
that
controls
access
to
objects
based
on
the
internet
protocol
(IP)
address
of
the
user.
See
also
protected
object
policy.
P
PAC.
See
privilege
attribute
certificate.
permission.
The
ability
to
access
a
protected
object,
such
as
a
file
or
directory.
The
number
and
meaning
of
permissions
for
an
object
are
defined
by
the
access
control
list
(ACL).
See
also
access
control
list.
policy.
A
set
of
rules
that
are
applied
to
managed
resources.
policy
server.
The
Tivoli
Access
Manager
server
that
maintains
the
location
information
about
other
servers
in
the
secure
domain.
polling.
The
process
by
which
databases
are
interrogated
at
regular
intervals
to
determine
if
data
needs
to
be
transmitted.
POP.
See
protected
object
policy.
portal.
An
integrated
Web
site
that
dynamically
produces
a
customized
list
of
Web
resources,
such
as
links,
content,
or
services,
available
to
a
specific
user,
based
on
the
access
permissions
for
the
particular
user.
privilege
attribute
certificate.
A
digital
document
that
contains
a
principal’s
authentication
and
authorization
attributes
and
a
principal’s
capabilities.
privilege
attribute
certificate
service.
An
authorization
API
runtime
client
plug-in
which
translates
a
PAC
of
a
predetermined
format
in
to
a
Tivoli
Access
Manager
credential,
and
vice-versa.
These
services
could
also
be
used
to
package
or
marshall
a
Tivoli
Access
Manager
credential
for
transmission
to
other
members
of
the
secure
domain.
Customers
may
develop
these
services
using
the
authorization
ADK.
See
also
privilege
attribute
certificate.
protected
object.
The
logical
representation
of
an
actual
system
resource
that
is
used
for
applying
ACLs
and
POPs
and
for
authorizing
user
access.
See
also
protected
object
policy
and
protected
object
space.
protected
object
policy
(POP).
A
type
of
security
policy
that
imposes
additional
conditions
on
the
operation
permitted
by
the
ACL
policy
to
access
a
protected
object.
It
is
the
responsibility
of
the
resource
manager
to
enforce
the
POP
conditions.
See
also
access
control
list,
protected
object,
and
protected
object
space.
protected
object
space.
The
virtual
object
representation
of
actual
system
resources
that
is
used
for
applying
ACLs
and
POPs
and
for
authorizing
user
access.
See
also
protected
object
and
protected
object
policy.
private
key.
In
computer
security,
a
key
that
is
known
only
to
its
owner.
Contrast
with
public
key.
public
key.
In
computer
security,
a
key
that
is
made
available
to
everyone.
Contrast
with
private
key.
Q
quality
of
protection.
The
level
of
data
security,
determined
by
a
combination
of
authentication,
integrity,
and
privacy
conditions.
322
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
R
registry.
The
datastore
that
contains
access
and
configuration
information
for
users,
systems,
and
software.
replica.
A
server
that
contains
a
copy
of
the
directory
or
directories
of
another
server.
Replicas
back
up
servers
in
order
to
enhance
performance
or
response
times
and
to
ensure
data
integrity.
resource
object.
The
representation
of
an
actual
network
resource,
such
as
a
service,
file,
and
program.
response
file.
A
file
that
contains
a
set
of
predefined
answers
to
questions
asked
by
a
program
and
that
is
used
instead
of
entering
those
values
one
at
a
time.
role
activation.
The
process
of
applying
the
access
permissions
to
a
role.
role
assignment.
The
process
of
assigning
a
role
to
a
user,
such
that
the
user
has
the
appropriate
access
permissions
for
the
object
defined
for
that
role.
routing
file.
An
ASCII
file
that
contains
commands
that
control
the
configuration
of
messages.
RSA
encryption.
A
system
for
public-key
cryptography
used
for
encryption
and
authentication.
It
was
invented
in
1977
by
Ron
Rivest,
Adi
Shamir,
and
Leonard
Adleman.
The
system’s
security
depends
on
the
difficulty
of
factoring
the
product
of
two
large
prime
numbers.
rule.
One
or
more
logical
statements
that
enable
the
event
server
to
recognize
relationships
among
events
(event
correlation)
and
to
execute
automated
responses
accordingly.
run
time.
The
time
period
during
which
a
computer
program
is
executing.
A
runtime
environment
is
an
execution
environment.
S
scalability.
The
ability
of
a
network
system
to
respond
to
increasing
numbers
of
users
who
access
resources.
schema.
The
set
of
statements,
expressed
in
a
data
definition
language,
that
completely
describe
the
structure
of
a
database.
In
a
relational
database,
the
schema
defines
the
tables,
the
fields
in
each
table,
and
the
relationships
between
fields
and
tables.
secure
sockets
layer
(SSL).
A
security
protocol
that
provides
communication
privacy.
SSL
enables
client/server
applications
to
communicate
in
a
way
that
is
designed
to
prevent
eavesdropping,
tampering,
and
message
forgery.
SSL
was
developed
by
Netscape
Communications
Corp.
and
RSA
Data
Security,
Inc.
security
management.
The
management
discipline
that
addresses
an
organization’s
ability
to
control
access
to
applications
and
data
that
are
critical
to
its
success.
self-registration.
The
process
by
which
a
user
can
enter
required
data
and
become
a
registered
Tivoli
Access
Manager
user,
without
the
involvement
of
an
administrator.
service.
Work
performed
by
a
server.
A
service
can
be
a
simple
request
for
data
to
be
sent
or
stored
(as
with
file
servers,
HTTP
servers,
servers,
and
finger
servers),
or
it
can
be
more
complex
work
such
as
that
of
servers
or
process
servers.
silent
installation.
An
installation
that
does
not
send
messages
to
the
console
but
instead
stores
messages
and
errors
in
log
files.
Also,
a
silent
installation
can
use
response
files
for
data
input.
See
also
response
file.
single
signon
(SSO).
The
ability
of
a
user
to
logon
once
and
access
multiple
applications
without
having
to
logon
to
each
application
separately.
See
also
global
signon.
SSL.
See
Secure
Sockets
Layer.
SSO.
See
Single
Signon.
step-up
authentication.
A
protected
object
policy
(POP)
that
relies
on
a
preconfigured
hierarchy
of
authentication
levels
and
enforces
a
specific
level
of
authentication
according
to
the
policy
set
on
a
resource.
The
step-up
authentication
POP
does
not
force
the
user
to
authenticate
using
multiple
levels
of
authentication
to
access
any
given
resource
but
requires
the
user
to
authenticate
at
a
level
at
least
as
high
as
that
required
by
the
policy
protecting
a
resource.
suffix.
A
distinguished
name
that
identifies
the
top
entry
in
a
locally
held
directory
hierarchy.
Because
of
the
relative
naming
scheme
used
in
Lightweight
Directory
Access
Protocol
(LDAP),
this
suffix
applies
to
every
other
entry
within
that
directory
hierarchy.
A
directory
server
can
have
multiple
suffixes,
each
identifying
a
locally
held
directory
hierarchy.
T
token.
(1)
In
a
local
area
network,
the
symbol
of
authority
passed
successively
from
one
data
station
to
another
to
indicate
the
station
temporarily
in
control
of
the
transmission
medium.
Each
data
station
has
an
opportunity
to
acquire
and
use
the
token
to
control
the
medium.
A
token
is
a
particular
message
or
bit
pattern
that
signifies
permission
to
transmit.
(2)
In
local
area
networks
(LANs),
a
sequence
of
bits
passed
from
one
device
to
another
along
the
transmission
medium.
When
the
token
has
data
appended
to
it,
it
becomes
a
frame.
Glossary
323
trusted
root.
In
the
Secure
Sockets
Layer
(SSL),
the
public
key
and
associated
distinguished
name
of
a
certificate
authority
(CA).
U
uniform
resource
identifier
(URI).
The
character
string
used
to
identify
content
on
the
Internet,
including
the
name
of
the
resource
(a
directory
and
file
name),
the
location
of
the
resource
(the
computer
where
the
directory
and
file
name
exist),
and
how
the
resource
can
be
accessed
(the
protocol,
such
as
HTTP).
An
example
of
a
URI
is
a
uniform
resource
locator,
or
URL.
uniform
resource
locator
(URL).
A
sequence
of
characters
that
represent
information
resources
on
a
computer
or
in
a
network
such
as
the
Internet.
This
sequence
of
characters
includes
(a)
the
abbreviated
name
of
the
protocol
used
to
access
the
information
resource
and
(b)
the
information
used
by
the
protocol
to
locate
the
information
resource.
For
example,
in
the
context
of
the
Internet,
these
are
abbreviated
names
of
some
protocols
used
to
access
various
information
resources:
http,
ftp,
gopher,
telnet,
and
news;
and
this
is
the
URL
for
the
IBM
home
page:
http://www.ibm.com.
URI.
See
uniform
resource
identifier.
URL.
See
uniform
resource
locator.
user.
Any
person,
organization,
process,
device,
program,
protocol,
or
system
that
uses
a
service
provided
by
others.
user
registry.
See
registry.
V
virtual
hosting.
The
capability
of
a
Web
server
that
allows
it
to
appear
as
more
than
one
host
to
the
Internet.
W
Web
Portal
Manager
(WPM).
A
Web-based
graphical
application
used
to
manage
Tivoli
Access
Manager
Base
and
WebSEAL
security
policy
in
a
secure
domain.
An
alternative
to
the
pdadmin
command
line
interface,
this
GUI
enables
remote
administrator
access
and
enables
administrators
to
create
delegated
user
domains
and
assign
delegate
administrators
to
these
domains.
WebSEAL.
A
Tivoli
Access
Manager
blade.
WebSEAL
is
a
high
performance,
multi-threaded
Web
server
that
applies
a
security
policy
to
a
protected
object
space.
WebSEAL
can
provide
single
sign-on
solutions
and
incorporate
back-end
Web
application
server
resources
into
its
security
policy.
WPM.
See
Web
Portal
Manager.
324
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
Index
Aaccess
control
decisionsmaking
192
making
and
extending
194,
239
access
decision
function
(ADF)
2
access
enforcement
function
(AEF)
2
addingadditional
application-specific
context
60
attributes
for
LDAP
access
37
authorization
to
an
application
3
credentials
and
handle
172
name
or
buffer
value
to
attribute
list
154
name
or
value
to
attribute
list
153
additional
user
information
57
address
of
data
structure
57
ADF
(access
decision
function)
2
ADIdynamic
ADI
retrieval
46
ADI
prefix
list
45
ADK
2
administration
serviceconfiguring
127
error
codes
132
implementing
124
initializing
129
shutdown
129
supported
functions
130
administrator’s
distinguished
name
38
AEF
(access
enforcement
function)
2
AIXlibivauthzn.a
library
file
5
allocated
memory
62
AMWebARS
99
APIattribute
lists
12
authorization
decisions
13
credentials
12
error
handling
13
extensions
14
functions
12
API
functionsazn_attrlist_add_entry_buffer()
154
azn_attrlist_add_entry()
153
azn_attrlist_create()
157,
158
azn_attrlist_delete_entry_value()
161
azn_attrlist_delete_entry()
160
azn_attrlist_delete()
159
azn_attrlist_get_entry_buffer_value()
169
azn_attrlist_get_entry_string_value()
165
azn_attrlist_get_entry_type()
167
azn_attrlist_get_names()
170
azn_attrlist_name_get_num()
171
azn_creds_combine()
172
azn_creds_create()
175
azn_creds_delete()
176
azn_creds_for_subject()
178
azn_creds_get_attrlist_for_subject()
181
azn_creds_get_pac()
183,
234
azn_creds_modify()
185,
236
azn_creds_num_of_subjects()
188
azn_decision_access_allowed_ext()
194
API
functions
(continued)azn_decision_access_allowed()
192
azn_error_major()
200
azn_error_minor_get_string()
202
azn_error_minor()
201
azn_id_get_creds()
203
azn_initialize()
207
azn_pac_get_creds()
210,
247
azn_release_buffer()
212
azn_release_strings()
215
azn_shutdown()
216
azn_svc_decision_access_allowed_ext()
239
azn_util_password_authenticate()
219
Application
Development
Kit
(ADK)
2
applicationsbuilding
7
building
an
attribute
list
60
deploying
with
the
authorization
API
9
determining
user’s
authorization
credentials
56
array
of
stringsmemory,
releasing
62
storage,
freeing
215
assigninghandle
for
an
empty
attribute
list
157,
158
handle
to
empty
credentials
structure
175
user
credentials
to
a
credentials
handle
60
attribute
definitionsXMLADI
46
attribute
list
functions
12
attribute
listsadding
name
or
buffer
value
154
adding
name
or
value
153
building
for
additional
application
information
60
creating
18
creating
and
assigning
a
handle
157,
158
deleting
19,
159,
160,
161
getting
an
attribute
entry
value
type
19
getting
an
attribute
name
19
getting
the
number
of
values
19
getting
values
19
obtaining
a
credential
64
releasing
memory
62
setting
an
entry
18
Attribute
Retrieval
Service
99
attribute
type
167
auditidentifier
182
user
information
user_info
57
auditingconfiguring
49
authenticated
user
identity
55
authenticationidentity,
user
56
information
57,
219
mechanism
55
authentication-mechanisms
stanza
278
authority,
authorization
56
authorizationauthority
56
credentials
56,
57,
58
decisions
13,
59,
61
©
Copyright
IBM
Corp.
2000,2003
325
authorization
APIbuffer
57
building
applications
7
changing
the
credential’s
contents
64
character
strings
14
converting
credentials
to
a
transportable
format
63
converting
credentials
to
the
native
format
63
creating
a
chain
of
credentials
63
deploying
applications
9
determining
the
number
of
credentials
in
a
chain
64
handling
credentials
63
initializing
207
introducing
2
obtaining
a
credential
from
a
chain
64
obtaining
credential
from
a
chain
64
setting
code
set
206
shutting
down
62
specifying
cache
mode
type
26
tasks
9
authorization
rulesADI
prefix
45
initializing
44
XMLADI
input
document
44
XSL
rule
document
44
authorization
serverspecifying
cache
mode
type
26
authorization
servicecode
set
206
initializing
207
minor
error
codes
6
minor
errors
21
starting
51
submitting
requests
to
2
authorization
service
dispatcher
77
azn_admin_get_object()
224
azn_admin_get_objectlist()
226
azn_admin_get_tasklist()
228
azn_admin_perform_task()
231
azn_attrlist_add_entry_buffer()
60
azn_attrlist_add_entry()
60
azn_attrlist_create()
60,
66
azn_attrlist_delete()
159
azn_attrlist_get_entry_buffer_value()
162,
169
azn_attrlist_get_entry_string_value()
165
azn_attrlist_get_names()
170
azn_attrlist_get_type()
167
azn_attrlist_h_t
18,
61
azn_attrlist_name_get_num()
171
azn_buffer_desc
14
azn_buffer_t
14
AZN_C_AUDIT_ID
182
AZN_C_EMPTY_BUFFER
14
AZN_C_INITIATOR_INDEX
64,
66,
178,
181
AZN_C_NO_BUFFER
14
AZN_C_NOT_PERMITTED
61,
192,
194,
240
AZN_C_PERMITTED
61,
192,
194,
239
AZN_C_VERSION
51
azn_creds_combine()
64,
172
azn_creds_create()
62,
64,
175
azn_creds_delete()
176
azn_creds_for_subject()
64,
178
azn_creds_get_attrlist_for_subject()
66,
181
azn_creds_get_pac()
63,
183
azn_creds_h_t
20,
62,
63
azn_creds_modify()
65,
185
azn_creds_num_of_subjects()
64,
188
azn_decision_access_allowed_ext()
61,
194
azn_decision_access_allowed()
59,
61,
192
azn_error_get_string()
21
azn_error_major()
200
azn_error_minor_get_string()
202
azn_error_minor()
201
azn_id_get_creds()
57,
60,
63,
203
azn_init_set_code_set()
206
azn_init_ssl_local_domain
28
azn_initialize()
207
azn_operation_read
59
azn_operation_traverse
59
azn_pac_get_creds()
210
azn_release_buffer()
212
azn_release_pobj()
62
azn_release_string()
14,
214
azn_release_strings()
14,
215
AZN_S_
INVALID_MOD_FUNCTION
186,
238
AZN_S_ATTR_INVALID_INDEX
163
AZN_S_ATTR_INVALID_INTEGER_REF
188
AZN_S_ATTR_VALUE_NOT_BUFFER_TYPE
163,
169
AZN_S_ATTR_VALUE_NOT_STRING_TYPE
166
AZN_S_COMPLETE
21
AZN_S_DOMAIN_CONFLICT
204
AZN_S_FAILURE
21
AZN_S_INVALID_ADDED_CREDS_HDL
173
AZN_S_INVALID_APP_CONTEXT_HDL
196,
241
AZN_S_INVALID_ATTR_NAME
153,
162,
169
AZN_S_INVALID_ATTRLIST_HDL
153,
162,
169
AZN_S_INVALID_AUTHORITY
204
AZN_S_INVALID_BUFFER
154
AZN_S_INVALID_BUFFER_REF
162,
169,
212
AZN_S_INVALID_COMB_CREDS_HDL
173
AZN_S_INVALID_CREDS_HDL
173,
176,
177,
179,
184,
193,
235
AZN_S_INVALID_INTEGER_REF
171
AZN_S_INVALID_MECHANISM
204
AZN_S_INVALID_MECHANISM_INFO
204
AZN_S_INVALID_NEW_CREDS_HDL
179,
204,
211,
248
AZN_S_INVALID_OPERATION
193
AZN_S_INVALID_PAC
211,
248
AZN_S_INVALID_PAC_SVC
184,
211,
235,
248
AZN_S_INVALID_PERMISSION_REF
193
AZN_S_INVALID_PROTECTED_RESOURCE
193
AZN_S_INVALID_STRING_REF
214,
215
AZN_S_INVALID_STRING_VALUE
153
AZN_S_INVALID_SUBJECT_INDEX
179
AZN_S_U_PASSWORD_ACCT_DISABLED
220
AZN_S_UNIMPLEMENTED_FUNCTION
179,
211,
248
azn_service_initialize()
244
azn_service_shutdown()
249
azn_shutdown()
51,
216
azn_status_t
21
azn_string_t
14,
18,
56
azn_svc_creds_get_pac()
234
azn_svc_creds_modify()
236
azn_svc_decision_access_allowed_ext()
239
azn_svc_pac_get_creds()
247
azn_util_password_authenticate()
55,
219
aznapi.conf
configuration
file
291
aznutils.h
5,
21
Bbackwards
compatibility
70
deprecated
API
elements
70
Version
3.9
69
Version
4.1
69
326
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
binary
compatibility
70
browser
information
57
buffer
14
declaration
14
empty
14
buffer
attribute
value
162
buffersdeclaration
57
introduction
to
14
none
14
release
of
memory
62
storage,
freeing
212
buildingapplications
7
attribute
lists
60
Ccache
modes
26
chain
of
credentials
63,
188
changingcontents
of
a
credential
64
existing
credential
185,
236
character
strings
14
cleaning
up
62,
216
combining
credentials
and
handle
172
components
ofADK
5
Tivoli
Access
Manager
5
configuration
file
83
aznapi.conf
291
configuringauthorization
API
26
secure
domain
4
contents
of
the
credential
64
convertingcredentials
to
a
transportable
format
63
creatingattribute
lists
18
chain
of
credentials
63
empty
credentials
structure
175
new
attribute
lists
25,
60
privilege
attribute
certificates
183
valid
empty
attribute
list
157,
158
credential
attributes
entitlement
service
100
credentials
12
changing
185,
236
changing
the
credential’s
contents
64
combining
with
a
handle
172
converting
to
a
transportable
format
63
converting
to
the
native
format
63
creating
a
chain
of
credentials
63
creating
and
assigning
a
handle
175
deleting
176
determining
number
of
credentials
64
extracting
individual
credentials
178
handle
60
invoking
a
privilege
attribute
certificate
service
183
making
access
control
decisions
192
making
extended
access
control
decisions
194,
239
obtaining
attribute
list
from
a
credential
65
obtaining
for
user
authorization
56,
57
obtaining
from
a
chain
of
credentials
64
returning
handle
to
new
PAC
credentials
210,
247
returning
in
a
chain
188
returning
information
from
181
user
authorization
57
creds_attrlist
66
custom-protected
object
60
Ddata
type
structureazn_attrlist_h_t
18
azn_buffer_t
14
azn_status_t
21
azn_string_t
14
decisionauthorization
61
decision,
authorization
61
decisionsaccess
control
192,
194,
239
authorization
13
definingsecurity
policy
3
deletingattribute
list
19,
159
attribute
list
entry
160
attribute
list
value
161
credentials
176
deployingapplications
9
applications
into
secure
domain
4
deprecated
API
elements
70
deprecated
DCE
authentication
72
determiningauthorization
credentials
for
a
user
57
identity
for
a
user
56
number
of
credentials
in
a
credentials
chain
64
disablingnotification
listener
28
refreshes
of
local
authorization
policy
database
27
distinguished
name
38
dynADI
retrieval
110
dynamic
ADI
retrieval
46
dynamic
ADI
retrieval
entitlement
services
110
Eempty
credentials
chain
175
enablingnotification
listener
28
entitlement
serviceauthorizing
a
caller
108
configuring
106
dynamic
ADI
retrieval
46
error
codes
109
implementing
103
initializing
106
shut
down
106
entitlement
service
plug-insample
code
93
error
codesaznutils.h
6,
21
ogauthzn.h
6,
21
pdb*msg.h
6,
21
error
handling
13,
21
example
ofassigning
user
identity
information
58
attribute
list
initialization
data
30
declaring
a
buffer
57
extendingAPI
function
standard
14
Index
327
extending
(continued)function
for
obtaining
an
access
decision
61
extensions,
API
14
external
authorization
servicearchitecture
139
authorization
decision
146
configuring
143
error
codes
147
implementing
138
initializing
145
policy
triggers
140
shutdown
145
weightings
142
extracting
individual
credentials
178
Ffiles
aznutils.h
5,
21
ogauthzn.h
6,
21
pdb*msg.h
21
formatcredentials,
transportable
63
freeingarray
of
strings
storage
215
buffer
storage
212
string
storage
214
Ggetting
attribute
list
name
19
attribute
type
167
entry
string
value
165
entry
value
type
19
handle
for
a
specified
identity
203
name
attributes
170
number
of
attribute
entries
171
number
of
values
for
attribute
list
name
19
value
attributes
19
Hhandle
172,
175,
176,
203
credentials
20,
60
handling
credentials
63
header
filesaznutils.h
5
ogauthzn.h
5
host
interfaceslistening
on
50
host
name,
LDAP
server
37
IIBM
Directory
user
registrySee
LDAP
server
identities,
user
56
implementation
modes
2
initialization
13
initializingauthorization
rules
44
authorization
service
207
code
set
206
data
207
initializing
(continued)invalid
data
208
initiator
3
interfacesauthorization
API
manual
pages
151
International
Organization
for
Standardization
(ISO)
2
IP
address
57
ISO
(International
Organization
for
Standardization)
2
ivacld-servers
54
Kkey
file,
SSL
38
key
label,
SSL
39
LLDAP
administrator’s
distinguished
name
38
administrator’s
password
38
key
file
password
39
port
number
37
server
host
name
37
server
key
label
39
SSL
key
file
38
ldap
stanza
280,
291
lengthdata
structure
57
local
cache
mode
2,
26
local
domain
28
logging
inusing
username
and
password
pair
219
Mmajor
errors
6,
21,
200
makingaccess
control
decisions
192
extended
access
control
decisions
194,
239
manager
stanza
297
manual
pagessummary
151
mappingrequested
resource
to
protected
object
60
user
operation
to
a
permission
59
memorycredential
structure
20
release
62
minor
errors
6,
21,
201
mod_info
64
mod_svc_id
65
modelocal
cache
2
remote
cache
2
modes,
specifying
26
modifyingcontents
of
a
credential
64
existing
credential
185,
236
multiple
domains
28
Nname
value
170
notification
listener
26
328
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
number
ofbytes
in
the
data
14
individual
credentials
in
a
chain
188
seconds
before
refreshing
27
value
attributes
in
the
entry
171
values
for
an
attribute
name
19
number
of
port,
LDAP
server
37
Oobtaining
authorization
decision
61
credential
from
a
chain
of
credentials
64
user
authorization
credentials
56,
57
ogauthzn.h
5,
21
Open
Group
2
output
parametersauthorization
decision
61
extended
authorization
decision
61
PPAC
(privilege
attribute
certificate)
56,
63,
183,
210,
247
pac_svc_id
63
passwordaccessing
the
SSL
key
file
39
authenticating
219
LDAP
administrator
38
pdb*msg.h
21
permission
informationenabling
return
of
47
permissions
59
persistent
authorization
policy
database
27
placing
the
data
structure
into
a
buffer
57
policy
database
replica
27
policy
triggers
140
port
numberfor
a
TCP
port
28,
37
privilege
attribute
certificate
(PAC)
56,
63,
183,
210,
247
protected
object
60
protected
object
namespace
60
providingadditional
parameters
60
Rrefreshing
local
authorization
database
27
registry,
user
7,
55
related
publications
xiii
releasingallocated
memory
20,
62
remote
cache
mode
2,
26
remote-acl-users
54
removingattribute
list
159,
160,
161
credentials
176
requested
resource
60
returningaccess
control
decision
information
195,
240
attribute
type
167
entry
string
value
165
handle
185,
236
handle
for
a
specified
identity
203
handle
to
credentials
structure
178
handle
to
new
PAC
credentials
210,
247
returning
(continued)individual
credentials
in
a
chain
188
information
from
a
credentials
structure
181
major
error
code
200
minor
error
code
201
name
attributes
170
number
of
buffer
attribute
entries
171
number
of
value
attributes
171
privilege
attribute
certificate
183
Ssecure
domain
7
Secure
Socket
Layer
(SSL)
38
security
policy
3
serverhost
name,
LDAP
37
service
definition
82
service
plug-in
82,
83
administration
service
80
architecture
76
configuring
82
credentials
modification
service
79,
101
entitlement
service
79,
97
error
codes
88
external
authorization
service
80,
102
implementing
81
initializing
82
privilege
attribute
certificate
service
79,
102
shut
down
92
supplied
implementations
96
service
plug-in
interfacesimplementing
86
setting
an
attribute
list
entry
18
shutdown
13,
62
shutting
down
13,
62,
216
Solaris
Operating
Environmentlibivauthzn.so
library
file
5
specifyingadditional
user
information
57
authorization
authority
56
type
of
cache
mode
26
user
authentication
identity
56
SSLcommunications
38
key
file
password
39
key
label
39
ssl
stanza
300
ssl-local-domain
28
standard,
The
Open
Group
2
stanzasauthentication-mechanisms
278
ldap
280,
291
manager
297
ssl
300
uraf-registry
305
startingauthorization
service
51
status
codes
21,
200,
201
storagearray
of
strings,
freeing
215
buffer,
freeing
212
string,
freeing
214
stringsfreeing
of
storage
214
release
of
memory
62
value
165
Index
329
successful
login
219
summary
ofAPI
extensions
14
API
functions
12
attribute
list
functions
12
attribute
list
tasks
18
authentication
parameters
58
authorization
API
manual
pages
151
authorization
API
tasks
9
authorization
decision
functions
13
authorization
decision
output
parameters
61
buffer
names
and
values
14
cache
modes
26
credentials
functions
12
error
code
files
21
initialization,
shutdown,
and
error
handling
functions
13
local
cache
mode
attributes
and
values
27
SSL
attributes
for
LDAP
access
38
user
identity
types
55
Ttasks,
authorization
API
9
TCP
port
number
28
types
ofadditional
user
information
57
authentication
parameters
58
cache
modes
26
user
identities
55
Uunauthenticated
user
17,
55
uraf-registry
stanza
305
useradditional
auditing
information
57
assigning
credentials
to
a
credentials
handle
60
authentication
identity
56
authorization
credentials
56,
57
mapping
the
user
operation
59
obtaining
an
identity
55
specifying
additional
information
57
unauthenticated
57
user
registrydifferences
311
LDAP
291
maximum
values
312,
313
specifying
LDAP
7
specifying
the
user
authentication
identity
56
User
Registry
Adapter
Framework
(URAF)
305
username
and
password
219
usingusername
and
password
to
log
in
219
utility
function
error
codesmajor
errors
6
minor
errors
6
Vvalue
attributesbuffer
162,
169
entry
number
171
name
170
string
165
type
167
values
14
version
number
51
Wweightings
142
Windows
NTivauthzn.dll
library
file
5
XXMLADI
44,
46
XSL
rule
document
44
330
IBM
Tivoli
Access
Manager
for
e-business:
Authorization
C
API
Developer
Reference
����
Printed
in
USA
SC32-1355-00
![[MS-RAA]: Remote Authorization API Protocol · 2017-09-06 · This document specifies the Remote Authorization API Protocol. The Remote Authorization API Protocol is a Remote Procedure](https://img.pdfslide.us/doc/110x75/5ecc8fe6feb19b7bbf00b5d8/ms-raa-remote-authorization-api-protocol-2017-09-06-this-document-specifies.jpg)
![[MS-RAA]: Remote Authorization API Protocol](https://img.pdfslide.us/doc/110x75/6195a9fdb3927b7fbc54fa19/ms-raa-remote-authorization-api-protocol.jpg)
