IAS Authorization via AMS beta

CAP applications using Identity Authentication Service (IAS) for authentication must manage authorization via Authorization Management Service (AMS), which is also part of SAP Cloud Identity Services (SCI).

• Streamlined AMS Integration
• Setup
• Generate Policies
  • Role-based authorization
  • Instance-based authorization
• Build
• Prepare for Deployment

Streamlined AMS Integration

CAP is tightly integrated with Authorization Management Service (AMS). Applications that run with IAS-based authentication can benefit from AMS, which allows central access policy management at the business level. The integration with AMS comes as an easy-to-consume plugin for CAP applications.

The interaction between the CAP application and AMS (via plugin) is as follows:

1. IAS-Authentication is performed independently as a pre-step.
2. The plugin injects user roles and filters according to AMS policies assigned to the current request user.
3. CAP performs the authorization on the basis of the CDS authorization model and the injected user claims.

AMS is transparent to CAP application code and can be easily consumed via plugin dependency.

To enhance your project with IAS and AMS, you can make use of new CDS CLI tooling:

cds add ias
cds add ams

This automatically adds required configuration for IAS/AMS, taking into account the concrete application context (tenant mode and runtime environment etc.).

The CDS model and technical authorization rules in the application domain are fully decoupled from AMS business policies which are defined on top:

Define your CDS model along with technical authorization rules

aspect fromSystem {
  systemType : String enum { DEV; QS; PROD; };
}

entity Issues : fromSystem {
  key ID: UUID;
      description: String;
      resolved: Boolean;
}

annotate Issues with @(restrict: [
    { grant: ['READ'], to: 'ReviewIssues' },
    { grant: ['READ', 'WRITE'], to: 'ManageIssues' }
]);

Optionally, link your CDS model to AMS attributes by @ams annotation

annotate fromSystem with @ams.attributes: {
  SystemType: (systemType)
};

Define AMS policies that combine roles and attribute filters at business level

SCHEMA {
 SystemType : String
}

POLICY QualityAuditor {
 ASSIGN ROLE ReviewIssues WHERE SystemType IS NOT RESTRICTED;
}

POLICY SupportEngineer {
 USE QualityAuditor RESTRICT SystemType = 'PROD';
}

Assign users to AMS policies

WARNING

Make sure to use at least version 3 of @sap/ams or at least version 2 of com.sap.cloud.security.ams.client:cap-ams-support.

Setup

Since @sap/cds-dk 8.6.0, the cds add ams command has been available to configure the project for authorization via AMS. Implicitly, it also runs the new cds add ias command to configure the project for authentication via SAP Identity Service.

cds add ams

This adds the following...

Runtime plugins

See the dependencies to the AMS client library and the AMS CAP integration library:

srv/pom.xml

<properties>
  <sap.cloud.security.ams.version>3.8.0</sap.cloud.security.ams.version> 
</properties>
<dependencies>
  <dependency>  
    <groupId>com.sap.cloud.security.ams.client</groupId>
    <artifactId>jakarta-ams</artifactId>
    <version>${sap.cloud.security.ams.version}</version>
  </dependency>
  <dependency>
    <groupId>com.sap.cloud.security.ams.client</groupId>
    <artifactId>cap-ams-support</artifactId>
    <version>${sap.cloud.security.ams.version}</version>
  </dependency>
</dependencies>

These libraries integrate into the CAP framework to handle incoming requests. Based on the user's assigned policies, the user's roles are determined and written to the UserInfo object. The framework then authorizes the request as usual based on the user's roles.

Development plugins

It also adds a build step using a CDS plugin as a Node.js devDependency:

package.json

{
  "devDependencies": {
    "@sap/ams": "^3"
  }
}

This plugin provides three features:

• Validate ams.attributes annotations for type coherence against the AMS schema.
• Generate policies from the CDS model during the build using a custom build task.
• Generate a deployer application during the build to upload the Data Control Language (DCL) base policies.

Generate Policies

In AMS, authorization policies are used to define concepts such as roles in a language called Data Control Language (DCL).

Using the official AMS plugins (cds add ams), you can generate policies from the CDS model and get out-of-the-box enforcement of CAP role restrictions based on AMS policies during runtime.

Role-based authorization

You define the role Reader as required to access the Books entity in your CDS model:

entity Books @(requires: 'Reader') {...}

The following policy is generated from the CDS source and defines the Reader role:

POLICY Reader {
    ASSIGN ROLE Reader;
}

Instance-based authorization

Given the expressiveness of DCL, the Authorization Management Service (AMS) is the natural choice when your application requires instance-based authorization that exceeds the capabilities of the standard instance-based CDS conditions. AMS supports exclusively role-based authorization, as well as a mix of instance-based and role-based authorization.

The AMS integration for defining advanced instance-based authorization rules has recently received a redesign in close collaboration with CAP. There will be detailed documentation soon.

Build

mvn clean install

After the application is built, check the srv/src/main/resources/ams folder to see the generated AMS schema and a basePolicies DCL file in a DCL package called cap:

srv/src/main/resources

└─ ams
   ├─ cap
   │  └─ basePolicies.dcl
   └─ schema.dcl

Prepare for Deployment

Policies are typically deployed to the AMS server whenever the application is deployed. Afterwards, those policies can be assigned to users in the Administration Console of the IAS tenant, for example, to grant a role to a user. Using the AMS plugins (cds add ams), the configuration of the deployment artifacts is done automatically.

Prerequisites on SAP BTP

• Get your SAP Cloud Identity Service tenant.
• Establish Trust towards your SAP Cloud Identity Service tenant to use it as identity provider for applications in your subaccount.

Follow the Deploy to Cloud Foundry guide, to prepare your project for deployment. Here's a shortcut:

cds add hana,approuter,mta,ams

After successful deployment, you need to Assign Authorization Policies.

Kyma configuration

Using cds add helm to deploy to Kyma is fully supported and automatically configured, too. Follow the Deploy to Kyma guide to prepare your project.

XSUAA-specific configuration

If not required, make sure to manually remove the XSUAA-specific configuration.