Authorization Rules

An authorization rule is used to perform access checks for authenticated user IDs against lists of services defined within the rule. This feature is available on z/OS, Linux and Windows using EntireX Security on these platforms. Authorization rules can be stored in the Broker attribute file or in an LDAP repository. This document covers the following topics:

Introduction
Rules Stored in Broker Attribute File
Rules Stored in LDAP Repository

Note:
Authorization Rules stored in an LDAP Repository are deprecated and support will be dropped in the next version.

Introduction

The value of SECURITY-SYSTEM in the DEFAULTS=SECURITY section of the Broker attribute file determines the location of the authorization rules:

Broker Attribute File
Set SECURITY-SYSTEM=OS.
Rules are defined under DEFAULTS=AUTHORIZATION-RULES of the broker attribute file.

On z/OS, if section DEFAULTS=AUTHORIZATION-RULES is defined in the broker attribute file, it takes precedence over RACF and any authorization rules in RACF are ignored.
LDAP Repository
Set SECURITY-SYSTEM=LDAP.

Rules are stored in an LDAP repository. Security-specific attributes LDAP-AUTHENTICATION-URL and LDAP-AUTHORIZATION-URL define the parameters for the access of the LDAP client side, and LDAP-AUTHORIZATION-RULE defines applicable rule names.

If section DEFAULTS=AUTHORIZATION-RULES is defined in the broker attribute file, it takes precedence over LDAP and any authorization rules in the LDAP repository are ignored.

Whenever an authorization call occurs, the Broker security exit performs checks based on the value of the security-specific attribute AUTHORIZATION-DEFAULT. Examples of these two approaches are provided below.

Rules Stored in Broker Attribute File

Set SECURITY-SYSTEM=OS in the SECURITY-SYSTEM section of the broker attribute file and define the individual rules under DEFAULTS=AUTHORIZATION-RULES. A rule is a container for a list of services and a list of client and server user IDs. All users defined in a rule are authorized to use all services defined in this rule.

Sample Attribute File Settings

DEFAULTS=SECURITY
   SECURITY-SYSTEM = OS
   SECURITY-LEVEL = AUTHORIZATION
   AUTHORIZATION-DEFAULT = NO

DEFAULTS = AUTHORIZATION-RULES
   RULE-NAME = rule1
      CLASS = class1, SERVER = server1, SERVICE = service1
      CLIENT-USER-ID = user1
      CLIENT-USER-ID = user2
      SERVER-USER-ID = user3
      SERVER-USER-ID = user4
   RULE-NAME = rule2
      CLASS = class2, SERVER = server2, SERVICE = service2
      CLASS = class3, SERVER = server3, SERVICE = service3
      CLIENT-USER-ID = user1
      CLIENT-USER-ID = user5
      CLIENT-USER-ID = user6
      SERVER-USER-ID = user7

This example results in the following permissions:

user1 may send requests to all three services.
user2 may send requests to service1 only.
user5 and user6 may send requests to service2 and service3, but not service1.
user3 and user4 may run as servers of service1.
user7 may run as server of service2 and service3.

Attributes are described in more detail under Security-specific Attributes and Authorization Rule-specific Attributes.

Rules Stored in LDAP Repository

This section covers the following topics:

Sample Attribute File Settings
Configuring your LDAP Repository
Authorization Rule Data
Hints for Microsoft Active Directory

Sample Attribute File Settings

Specify the URL of your LDAP server under LDAP-AUTHENTICATION-URL and LDAP-AUTHORIZATION-URL in the DEFAULTS=SECURITY section of the broker attribute file, and specify up to 16 rules with LDAP-AUTHORIZATION-RULE as shown in the example below:

DEFAULTS=SECURITY
   SECURITY-SYSTEM = LDAP
   SECURITY-LEVEL = AUTHORIZATION
   LDAP-AUTHENTICATION-URL = "ldap://myhost.mydomain.com"
   LDAP-AUTHORIZATION-URL  = "ldap://myhost.mydomain.com"
   LDAP-AUTHORIZATION-RULE = rule1
   LDAP-AUTHORIZATION-RULE = rule2
   ...
   LDAP-AUTHORIZATION-RULE = rule16
   LDAP-PERSON-BASE-BINDDN   = "cn=users,dc=software-ag,dc=de"
   LDAP-SASL-AUTHENTICATION  = YES

Note:
We assume you can change authorization rules (add/modify/delete) in LDAP directly. Add/delete authorization rule names in Broker attribute file accordingly.

Attributes are described in more detail under Security-specific Attributes.

Configuring your LDAP Repository

An LDAP server is a prerequisite (based on LDAPv3); it is not installed with EntireX.

For the installation of the LDAP server, see the respective product documentation. All servers have to support the attribute types sag-key, sag-value and the objectClass sag-xds. They are defined in the following schema.

attributetypes:
      ( 1.2.276.0.12.2.1.1
      NAME 'sag-key'
      DESC 'User Defined Attribute'
      SYNTAX '1.3.6.1.4.1.1466.115.121.1.26')
attributetypes:
      ( 1.2.276.0.12.2.1.2
      NAME 'sag-value'
      DESC 'User Defined Attribute'
      SYNTAX '1.3.6.1.4.1.1466.115.121.1.5')
objectclasses:
      ( 1.2.276.0.12.2.3.1
      NAME 'sag-xds'
      DESC 'User Defined ObjectClass'
      SUP 'top'
      MUST ( objectclass $ sag-key )
      MAY ( aci $ sag-value ) )

We recommend setting up a separate branch in the directory for authorization rules. The distinguished name of this branch is the value of the configuration setting specified with attribute LDAP-BASE-DN in section Security-specific Attributes in the platform-independent Administration documentation.

Authorization Rule Data

The following example describes the required data in LDAP to define the authorization rule RULE1 restricting service SC1:SN1:SV1 (CLASS=SC1, SERVER=SN1,SERVICE=SV1) to authorized client CLIENT1 and authorized server SERVER1. It assumes attribute LDAP-BASE-DN was set to "dc=software-ag,dc=de".

Define the authorization rule:

sag-key=RULE1,sag-key=100,sag-key=AuthRules,sag-key=EntireX,sag-key=Software AG,dc=software-ag,dc=de

Define the service for the authorization rule:

sag-key=SC1:SN1:SV1,sag-key=RULE1,sag-key=100,sag-key=AuthRules,sag-key=EntireX,sag-key=Software AG,dc=software-ag,dc=de

Define a client user ID for the service:

sag-key=CLIENT1 [C,sag-key=SC1:SN1:SV1,sag-key=RULE1,sag-key=100,sag-key=AuthRules,sag-key=EntireX,sag-key=Software AG,dc=software-ag,dc=de

Define a server user ID for the service:

sag-key=SERVER1 [S,sag-key=SC1:SN1:SV1,sag-key=RULE1,sag-key=100,sag-key=AuthRules,sag-key=EntireX,sag-key=Software AG,dc=software-ag,dc=de

The part "sag-key=100,sag-key=AuthRules,sag-key=EntireX,sag-key=Software AG" identifies authorization rules in general. All values are fixed and must not be changed. Preceeding "sag-key=RULE1" defines the name of an authorization rule. This rule name must have been defined with attribute LDAP-AUTHORIZATION-RULE in the Broker attribute file.

The definition of services requires "sag-key=SC1:SN1:SV1" in front of the complete rule data.

User ID values contain the user ID plus blank, open square bracket and uppercase C for clients or S for servers.

Following table lists attribute type and value. All entries belong to objectClass sag-xds.

Attribute Type	Value
`sag-key`	`Software AG`
`sag-key`	`EntireX`
`sag-key`	`AuthRules`
`sag-key`	`100`
`sag-key`	`RULE1`
`sag-key`	`SC1:SN1:SV1`
`sag-key`	`CLIENT [C`
`sag-key`	`SERVER [S`

Hints for Microsoft Active Directory

Note:
To deploy the sagxds schema on Microsoft Active Directory, do not use the Microsoft Active Directory tools for editing the schema. Use the following step-by-step instructions:

Start of instruction set To deploy the sagxds schema

Make a backup of the system state. Changes to the schema of Microsoft Active Directory are irreversible without a backup of the system state.
You must enable UPDATE schema.
1. To make the Schema Master available, enter the following at a command prompt:
```
regsvr32.exe schmmgmt.dll
```
2. Enter MMC.
3. From Console menu item, select: Add/remove snap-in.
4. Choose Add.
5. Choose Active Directory Schema from Action menu item of Active Directory Schema, select Operations Master.
6. Choose "The schema may be modified on this domain controller".

Copy the following text to the file sagxds.ldif

# Add sag-value attribute

dn: CN=sag-value,CN=Schema,CN=Configuration,DC=<your domains name>
changetype: add
adminDisplayName: sag-value
attributeID: 1.2.276.0.12.2.1.2
attributeSyntax: 2.5.5.10
cn: sag-value
isSingleValued: FALSE
lDAPDisplayName: sag-value
distinguishedName: CN=sag-value,CN=Schema,CN=Configuration,DC=<your domains name>
objectCategory:
 CN=Attribute-Schema,CN=Schema,CN=Configuration,DC=<your domains name>
objectClass: attributeSchema
oMSyntax: 4
name: sag-value

# Add sag-key attribute
# Active Directory requires the naming attribute(RDN) to be a syntax of DirectoryString

dn: CN=sag-key,CN=Schema,CN=Configuration,DC=<your domains name>
changetype: add
adminDisplayName: sag-key
attributeID: 1.2.276.0.12.2.1.1
attributeSyntax: 2.5.5.12
cn: sag-key
isMemberOfPartialAttributeSet: TRUE
isSingleValued: TRUE
lDAPDisplayName: sag-key
distinguishedName: CN=sag-key,CN=Schema,CN=Configuration,DC=<your domains name>
objectCategory:
 CN=Attribute-Schema,CN=Schema,CN=Configuration,DC=<your domains name>
objectClass: attributeSchema
oMSyntax: 64
name: sag-key
searchFlags: 1

# Update the schema

DN:
changetype: modify
add: schemaUpdateNow
schemaUpdateNow: 1
-

# Add sag-xds class

dn: CN=sag-xds,CN=Schema,CN=Configuration,DC=<your domains name>
changetype: add
adminDescription: sag-xds
adminDisplayName: sag-xds
cn: sag-xds
defaultObjectCategory:
 CN=sag-xds,CN=Schema,CN=Configuration,DC=<your domains name>
governsID: 1.2.276.0.12.2.3.1
lDAPDisplayName: sag-xds
mayContain: sag-value
mustContain: sag-key
distinguishedName: CN=sag-xds,CN=Schema,CN=Configuration,DC=<your domains name>
objectCategory: CN=Class-Schema,CN=Schema,CN=Configuration,DC=<your domains name>
objectClass: classSchema
objectClassCategory: 1
possSuperiors: container
name: sag-xds
rDNAttID: sag-key
subClassOf: top

# Update the schema

DN:
changetype: modify
add: schemaUpdateNow
schemaUpdateNow: 1
-

# Modify sag-xds class
# make sag-xds a possSuperior. This means a sag-xds class can contain other sag-xds classes.

dn: CN=sag-xds,CN=Schema,CN=Configuration,DC=<your domains name>
changetype: modify
add: possSuperiors
possSuperiors: sag-xds
-

# Update the schema

DN:
changetype: modify
add: schemaUpdateNow
schemaUpdateNow: 1
-

Replace all instances of dc= <your domain name> with your domain name, for example dc=myunit,dc=mycompany,dc=com.

Run it with the command:

ldifde -s <your server> -b <account> <domain> <password> -i -f sagxds.ldif

Add containers that represent the base DN of the authorization rules. These containers determine the value of attribute LDAP-BASE-DN under Security-specific Broker Attributes. Example (for two containers):
```
dn: CN=<your container 1>,DC=<your domain name>
changetype: add
cn: <your container 1>
objectclass: container

dn: CN=<your container2>,<your container 1>,DC=  <your domain name>
changetype: add
cn: <your container 2>
objectclass: container
```
With the utilities for Microsoft Active Directory, set the permissions to read and to modify the containers.