---
description: >
  How to enable business-level authorization for IAS-authenticated CAP Java applications using SAP Authorization Management Service (AMS).
---

<script setup>
import { useData } from 'vitepress'
const { versions } = useData().theme.value.capire
</script>

# IAS Authorization via AMS  <Badge type="warning" text="beta" /> { #ams-configuration-java }

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)*.

[[toc]]


## 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 graphic is explained in the following text.](./assets/ams.png){width="500px" }

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:

```sh
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:

::: details Define your CDS model along with technical authorization rules

```cds
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' }
]);
```

:::

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

<!-- cds-mode: ignore -->
```cds
annotate fromSystem with @ams.attributes: {
  SystemType: (systemType)
};
```

:::

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

```yaml
SCHEMA {
 SystemType : String
}

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

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

:::

::: details Assign users to AMS policies

![Screenshot showing the AMS Policy Assignment](assets/ams-assignment.png)

:::


::: 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`.
:::

<span id="internallinks"/>


## 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.

```sh
cds add ams
```

::: details This adds the following...

##### Runtime plugins

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

::: code-group
```xml-vue [srv/pom.xml]
<properties>
  <sap.cloud.security.ams.version>{{versions.cloud_sec_ams}}</sap.cloud.security.ams.version> <!-- [!code ++] -->
</properties>
<dependencies>
  <dependency>  <!-- [!code ++:10] -->
    <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](#generate-policies), the user's roles are determined and written to the [UserInfo](/@external/guides/security/cap-users#developing-with-users) object. The framework then authorizes the request as usual based on the user's roles.

<br>

##### Development plugins

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

::: code-group
```json [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](https://help.sap.com/docs/cloud-identity-services/cloud-identity-services/configuring-authorization-policies?locale=en-US) 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:

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

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

```sql
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](/@external/guides/security/authorization#instance-based-auth). 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

```sh
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*:

::: code-group

``` [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.

::: details Prerequisites on SAP BTP

- [Get your SAP Cloud Identity Service tenant.](https://help.sap.com/docs/cloud-identity-services/cloud-identity-services/get-your-tenant)
- [Establish Trust](https://help.sap.com/docs/btp/sap-business-technology-platform/establish-trust-and-federation-between-uaa-and-identity-authentication) 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](/@external/guides/deploy/to-cf), to prepare your project for deployment. Here's a shortcut:

```sh
cds add hana,approuter,mta,ams

```

After successful deployment, you need to [Assign Authorization Policies](https://help.sap.com/docs/cloud-identity-services/cloud-identity-services/assign-authorization-policies).

::: details Kyma configuration

Using `cds add kyma` to deploy to Kyma is fully supported and automatically configured, too. Follow the [Deploy to Kyma guide](/@external/guides/deploy/to-kyma) to prepare your project.

:::

::: warning XSUAA-specific configuration

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

:::