Lab 2.5: Authorisation Policy
The purpose of this module is to understand how to configure which user and organisation attributes are sent to applications.
SSO installed
Overview
An authorisation policy is used to define what data is delivered to the applications. This is sometimes known as an attribute release policy.
The same authorisation policy can be reused and assigned to many different web agents. A web agent can only have one authorisation policy assigned to it at one time.
It is strongly recommended to use an authorisation policy for all web agents and send only the minimum amount of information required.
An example authorisation Policy is shown below. This policy is used by the CustomerID Administration application itself. When a user logs in, role information, the unique ID of the user and an attribute called group are sent to the application. In order to access the CustomerID Administration application, the user must be in the group eIDMUser (it is defined in the application's Allowed To tab)
Access Control with Authorisation Policies
In addition to controlling what attributes are sent and in what format, authorisation policies can be used for Attribute Based Access Control (ABAC) by checking for the presence or absence of a user or method attribute.
Single-Value Attribute constraint fails for the defined attribute if more than one distinct value is assigned
Required Attribute constraint fails for the defined attribute if no value is assigned
Example:
This policy requires that the user has the following attributes:
at least one role (but may have many)
one and only one email address
if present, the user must have only a mobile phone number
Why is this important? If an application cannot operate without a certain attribute, or cannot handle multiple attributes, the user can be prevented access before they reach the application.
Attributes tab
An authorisation policy adds attributes with name and value to the response message for applications.
The following fields can be configured:
Group: The user must belong to the selected group for the attribute release to be processed. eIDMUser is a special group containing all CustomerID users.
Name: Name of the authorisation attribute as the recipient receives it
Value: Source of the attribute value to be sent.
Scope: Applications using OAuth or OIDC can utilise scope to request the exact data they need from the identity provider (claims such as email, phone, and address). The usage is optional.
Name Format: Machine-readable indication of the format of the attribute (rarely used; define only if required by the integrating application)
Friendly Name: Human-readable description of the attribute value (rarely used; define only if required by the integrating application)
The rule pictured above is processed like an if statement - if the user belongs to the group "eIDMUser" in the site "eIDM Groups", send the target application an attribute named "role" with the value containing the output of the macro eidm:roles, which is a dynamic list of all CustomerID roles that the user has.
Other possible values in the Value field are:
Attribute Values | Definition |
|---|---|
user:<name> | the value is evaluated by reading the attribute <name> from the user's directory object. For example, user:uid would return the value of the uid attribute. Typical LDAP User Attributes for Ubisecure Directory users: dn: Distinguished name (full path to LDAP object) cn: Full Name name: Full Name uid: Use ID used typically for login mobile: Mobile Phone number givenName: First Name sn: Surname mail: Email o: Organisation ubiloginEnabled: Account status TRUE or FALSE ubiloginNotBefore: YYYY-MM-DD HH:MM ubiloginNotOnOrAfter: YYYY-MM-DD HH:MM |
method:<name> | the value is evaluated by reading the attribute <name> assigned by the authentication method component. The availability of method attributes depends on the authentication method implementation. For example, the CUSTID attribute is available with the Tupas 2 authentication method. method:CUSTID would then return the value of the CUSTID attribute from the Tupas 2 authentication process. |
text:<string> | the value is literal value <string> e.g. text:GOLDMEMBER |
eidm:roles | The user’s roles in Ubisecure CustomerID. This parameter supports different authorisation role filtering and mappings. The desired policy can be given to the operation as a parameter separated by colon, i.e., eidm:roles:<policy name>. For more information see authorisation configuration - CustomerID |
eidm:orgclaims | Organisation memberships from Ubisecure CustomerID. This macro provides structured information about the user's roles' respective organisations in a JSON format. This data can be included in the authorisation policy by invoking the authoriser with orgclaims parameter, i.e., using 'eidm:orgclaims' as the value in an authorisation policy's attribute. The parameter supports different authorisation role filtering and mappings similar to the eidm:roles operation (see the examples above). The desired policy should can be given to the operation as a parameter separated by a colon, i.e., eidm:orgclaims:<policy name>. Assuming a user has two roles Customers/1234/Representative and Organizations/OrganizationUser. The following is an example of a JSON response for the user.
For more information see authorisation configuration - CustomerID |
user:<name>;binary | The attribute <name> is returned to Web Agents as Base64 coded string. For example, user:objectGuid;binary would return a value such as sFy0xj0cXU6QpjsQRCzG5Q== Encoding is based on LDAP binary option mechanism (http://www.rfc-editor.org/rfc/rfc2251.txt , Chapter 4.1.5.1). |
Applications tab
To be used, the authorisation policy must be attached to an application using the Applications tab. The same authorisation policy can be reused and assigned to many different applications. An application can only have one authorisation policy assigned to it at one time.