The syntax required to set the properties and values defined in the xs-security.json application security descriptor file.
{
"xsappname" : "node-hello-world",
"scopes" : [ {
"name" : "$XSAPPNAME.Display",
"description" : "display" },
{
"name" : "$XSAPPNAME.Edit",
"description" : "edit" },
{
"name" : "$XSAPPNAME.Delete",
"description": "delete",
"granted-apps": ["$XSAPPNAME(application,business-partner)"]
}
],
"attributes" : [ {
"name" : "Country",
"description" : "Country",
"valueType" : "string" },
{
"name" : "CostCenter",
"description" : "CostCenter",
"valueType" : "string" }
],
"role-templates": [ {
"name" : "Viewer",
"description" : "View all books",
"default-role-name": "Viewer: Authorized to Read All Books",
"scope-references" : [
"$XSAPPNAME.Display" ],
"attribute-references": [
{
"name" : "Country",
"default-values" : [
"USA", "Germany"
]
}
]
},
{
"name" : "Editor",
"description" : "Edit, delete books",
"scope-references" : [
"$XSAPPNAME.Edit",
"$XSAPPNAME.Delete" ],
"attribute-references" : [
"Country",
"CostCenter"]
}
],
"role-collections": [
{
"name": "UserViewerRC",
"description": "User Viewer Role Collection",
"role-template-references": ["$XSAPPNAME.Viewer"]
}
],
"authorities":["$ACCEPT_GRANTED_AUTHORITIES"],
"oauth2-configuration": {
"token-validity": 900,
"redirect-uris": ["https://myapp.cfapps.eu10.hana.ondemand.com","https://myapp.mydomain.com/my/logout"],
"credential-types": ["binding-secret","x509"]
},
"xsenableasyncservice":"true"
}
Try out the tutorials for the SAP Authorization and Trust Management service to get familiar with using the application security descriptor in the Cloud Foundry environment of SAP BTP.
See Tutorials for the SAP Authorization and Trust Management Service.
Use the xsappname property to specify the name of the application that the security description applies to.
"xsappname" : "<app-name>",
Naming Conventions
Bear in mind the following restrictions regarding the length and content of an application name in the xs-security.json file:
-
The following characters can be used in an application name of the Cloud Foundry environment at SAP BTP:
aA–zZ,0–9,-(hyphen),_(underscore),/(forward slash), and\(backslash). -
The maximum length of an application name is 100 characters.
Use the custom tenant-mode property to define the way the tenant's OAuth clients get their client secrets.
During the binding of the xsuaa service, the UAA service broker writes the tenant mode into the credential section. The application router uses the tenant mode information for the implementation of multitenancy with the application service plan.
{ "xsappname" : "<application_name>", "tenant-mode" : "shared", "scopes" : [ { "name" : "$XSAPPNAME.Display", "description" : "display"
Syntax
"tenant-mode" : "shared"
The following tenant modes are available:
Tenant Modes
|
Value |
Description |
|---|---|
|
|
Default value. An OAuth client gets a separate client secret for each subaccount. |
|
|
An OAuth client always gets the same client secret. It’s valid in all subaccounts. The application service plan uses this tenant mode. |
|
|
A tenant has multiple subscriptions to applications. For each subscription to an application, the tenant gets an OAuth client with a client secret. |
In the application security file (xs-security.json), the scopes property defines an array of one or more security scopes that apply for an application. You can define multiple scopes; each scope has a name and a short description. The list of scopes defined in the xs-security.json file is used to authorize the OAuth client of the application with the correct set of local and foreign scopes; that is, the permissions the application requires to be able to respond to all requests.
"scopes": [
{
"name" : "$XSAPPNAME.Display",
"description" : "display"
},
{
"name" : "$XSAPPNAME.Edit",
"description" : "edit"
},
{
"name" : "$XSAPPNAME.Delete",
"description" : "delete",
"granted-apps" : [ "$XSAPPNAME(application,business-partner)"]
}
]
All scopes in the scopes file is used to authorize the OAuth client of the application with the correct set section are local, that is, application specific. Local scopes are checked by the application's own application router or checked programmatically within the application's runtime container. In the event that an application needs access to other services of the Cloud Foundry environment on behalf of the current user, the provided access token must contain the required foreign scopes. Foreign scopes are not provided by the application itself; they're checked by other sources outside the context of the application.
In the xs-security.json file, “local”scopes must be prefixed with the variable <$XSAPPNAME> at run time. The variable is replaced with the name of the corresponding local application name.
The variable <$XSAPPNAME> is defined in the application's deployment manifest description (
manifest.yml).
Usually, “foreign” scopes include the service plan and the name of the application to which the scope belongs. For more information, see Referencing the Application Use the following syntax:
$XSAPPNAME(<service_plan>,<xsappname>).<local_scope_name>
"$XSAPPNAME(application,business-partner).Create"
If you want to grant a scope from this application to another application for a user scenario, this application needs to grant access to the scope for the application that wants to use this scope. Using the granted-apps property in the scopes section, you can specify the application you want to grant your scope to. The other application (referenced as <service_plan>,<foreign_xsappname>) receives the scope as a “foreign”scope. For more information, see the related link.
Here is the syntax in the security descriptor of the application that grants the scope. For more information, see Referencing the Application.
"granted-apps" : [ "$XSAPPNAME(<service_plan>,<foreign_xsappname>)"]
"granted-apps" : [ "$XSAPPNAME(application,business-partner)"]
If you want to grant a scope from this application to another application for a client credentials scenario, use the grant-as-authority-to-apps property in the scopes section. In this case, the scopes are granted as authorities. Specify the other application by name. For more information, see the related link.
Here is the syntax in the security descriptor of the application that grants the scope:
"grant-as-authority-to-apps" : [ "$XSAPPNAME(<service_plan>,<foreign_xsappname>)"]
"grant-as-authority-to-apps" : [ "$XSAPPNAME(application,business-partner)"]
Bear in mind the following restrictions regarding the length and content of a scope name:
-
The following characters can be used in a scope name:
aA–zZ,0–9,-(hyphen),_(underscore),/(forward slash),\(backslash), and:(colon). -
Scope names can't start with a leading
.(period). For example,.myScopeName1. -
The maximum length of a scope name, including the fully qualified application name, is 193 characters.
For other limits when using the properties, see Limits for the Application Security Descriptor.
In the application security descriptor (xs-security.json), the attributes property enables you to define an array, listing one or more attributes that are applied to the role templates also defined in the xs-security.json element is only relevant for user scenarios file. You can define multiple attributes.
"attributes" : [
{
"name" : "Country",
"description" : "Country",
"valueType" : "s" },
{
"name" : "CostCenter",
"description" : "CostCenter",
"valueType" : "string" }
],
The attributes element is only relevant for a user scenario. Each element of the attributes array defines an attribute. These attributes can be referenced by role templates. There are multiple sources of attributes:
-
Static attributes
Use the SAP BTP cockpit to assign the value of the attributes. You can use the static value.
-
Attributes from an identity provider
You can reference the attributes provided by an identity provider. The token is issued by the configured identity provider during authentication. You find the attribute value in the configuration of your identity provider. The attributes provided by the identity provider, appear as an attribute in the JSON web token, if the user has assigned the corresponding roles. You can use the attributes to achieve instance-based authorization checks.
-
Unrestricted attributes
In this case, you want to express that it's not necessary to set a specific value for this attribute. The behavior is the same as if the attribute would not exist for this role.
For more information, see the related link about attributes.
The attributes definition can take the following properties:
attributes Properties
|
Key |
Description |
Example |
|---|---|---|
|
|
The name of the attribute with a value to apply when building the role template |
|
|
|
A short summary of the attribute defined |
|
|
|
The type of value expected for the defined attribute; possible values are: |
|
|
|
By default, every attribute needs dedicated attribute values. The default value is For more information, see Relationship Between |
|
Naming Conventions
Bear in mind the following restrictions regarding the length and content of attribute names in the xs-security.json file:
-
The following characters can be used to declare an xs-security attribute name in the Cloud Foundry environment: “aA”-“zZ”, “0”-“9”, “_” (underscore)
-
The maximum length of a security attribute name is 64 characters.
For other limits when using the properties, see Limits for the Application Security Descriptor.
In the application-security file (xs-security.json), the role-templates property enables you to define an array listing one or more roles (with corresponding scopes and any required attributes), which are required to access a particular application module. You can define multiple role-templates, each with its own scopes and attributes.
Role templates can be delivered with default values for each attribute reference. When you deploy role templates with default values for each attribute reference, you create default roles.
attribute-references can contain a JSON array of multiple objects.
"role-templates": [
{
"name" : "Viewer",
"description" : "View all books",
"default-role-name" : "Viewer: Authorized to Read All Books",
"scope-references" : [
"$XSAPPNAME.Display"
],
"attribute-references": [
{
"name" : "Country",
"default-values" : [
"USA", "Germany"
]
}
]
attribute-references can contain a JSON array of string.
A role template must be instantiated. This is especially true with regard to any attributes defined in the role template and the specific attribute values, which are subject to customization and, as a result, can't be provided automatically. Role templates that only contain "role-templates": [ { "name" : "Viewer", "description" : "View all books", "default-role-name" : "Viewer: Authorized to Read All Books", "scope-references" : [ "$XSAPPNAME.Display" ], "attribute-references": [ "Country" ] }, ] “local”"role-templates": [ scopes can be instantiated without user interaction. The same is also true for “foreign”scopes where the scope owner has declared consent in a kind of allowlist (for example, either for “public” use or for known “friends”).
The resulting (application-specific) role instances need to be assigned to the appropriate user groups.
role-template Properties
|
Key |
Description |
Example |
|---|---|---|
|
|
The name of the role to build from the role template |
|
|
|
A short summary of the role to build |
|
|
|
The name of the role in Unicode The name can be up to 255 characters long. The naming conventions of |
|
|
|
The security scope to apply to the application-related role |
|
|
|
One or more attributes to apply to the built role. You can use a JSON array of objects or of string. If you use an array of objects,
For more information, see Relationship between default-values of attribute-references and valueRequired.
|
(an array of objects)
|
Naming Conventions
Bear in mind the following restrictions regarding the length and content of role-template names in the xs-security.json file:
-
The following characters can be used to declare an xs-security role-template name: “aA”-“zZ”, “0”-“9”, “.” (period), “-” (hyphen), “_” (underscore).
-
The maximum length of a role-template name is 64 characters.
For other limits when using the properties, see Limits for the Application Security Descriptor.
The optional role-collections property enables you to define role collections with predefined roles. Administrators use these predefined role collections. They can assign them to users during the initial setup of SAP BTP.
The role-collections property only makes sense if application developers reference role templates that can create default roles at deployment time.
The
role-collectionselement can only reference role templates of the same subaccount.
"role-collections": [ { "name": "Employee", "description": "Employee roles", "role-template-references": [ "$XSAPPNAME.Employee" ] } ]
role-collections Properties
|
Key |
Description |
Example |
|---|---|---|
|
|
The name of the role collection to build
|
|
|
|
A short summary of the role collection to build |
|
|
|
The role templates referenced by the |
Syntax
|
Naming Conventions
Bear in mind the following restrictions regarding the length and content of role-collections names in the xs-security.json file:
-
The maximum length of a role-collection name is 64 characters.
-
The maximum length of a role-collection description is 1000 characters.
-
The
role-template-references(mandatory) element is an array with references to role template definitions from the Cloud Foundry application or from other Cloud Foundry applications.We recommend that you reference all role templates using either the
$XSAPPNAMEor$XSAPPNAME(<service_plan>,<XSAPPNAME>)prefix to link to the correct application where the role template is defined (see Referencing the Application).
Conditions
The role templates must fulfill one of the following conditions regarding attributes:
-
Either they don't have attribute references.
-
Or default attribute values are defined. It’s also possible to add the
"valueRequired" : falseproperty to an attribute.
This makes sure that a default role is automatically created for the role-templates after developers have deployed the application. The role collections use the predefined roles, which have been created automatically.
For other limits when using the properties, see Limits for the Application Security Descriptor.
To enable one (sending) application to accept and use the authorization scopes granted by another application, each application must be bound to its own instance of the xsuaa service. This is required to ensure that the applications are registered as OAuth 2.0 clients at the UAA. You must also add an authorities property to the security descriptor file of the sending application that is requesting an authorization scope. In the authorities property of the sending application's security descriptor, you can either specify that all scope authorities configured as grantable in the receiving application should be accepted by the application requesting the scopes, or alternatively, only individual, named, scope authorities:
-
Request and accept all authorities flagged as "grantable" in the receiving application's security descriptor:
Specifying Scope Authorities in the Sending Application's Security Descriptor
"authorities":["$ACCEPT_GRANTED_AUTHORITIES"]
-
Request and accept only the "specified" scope authority that is flagged as grantable in the specified receiving application's security descriptor. For more information, see Referencing the Application.
Specifying Scope Authorities in the Sending Application's Security Descriptor
"authorities":["<ReceivingApp>.ForeignCall", "<ReceivingApp2>.ForeignCall",]
Since both the sending application and the receiving application are bound to UAA services using the information specified in the respective application's security descriptor, the sending application can accept and use the specified authority from the receiving application. The sending application is now authorized to access the receiving application and perform some tasks.
The granted authority always includes the prefixed name of the application that granted it. This information tells the sending application, which receiving application has granted which set of authorities.
The scope authorities listed in the sending application's security descriptor must be specified as "grantable" in the receiving application's security descriptor.
To flag a scope authority as "grantable", add the
grant-as-authority-to-appsproperty to the respective scope in the receiving application's security descriptor.
For more information, see the related link.
Use the custom oauth2-configuration property to define custom values for the OAuth 2.0 clients, such as the token validity and redirect URIs.
The xsuaa service broker registers and uses these values for the configuration of the OAuth 2.0 clients.
"oauth2-configuration": { "token-validity": 43200, "redirect-uris": [ "https://myapp.cfapps.eu10-004.hana.ondemand.com", "https://myapp.mydomain.com/my/content"], "refresh-token-validity": 1800, "credential-types": ["binding-secret","x509"], "system-attributes": ["groups","rolecollections"], "allowedproviders ": ["orgin_key1","origin_key2"] }
The following configuration keys are available:
oauth2-configuration Properties
|
Key |
Description |
Example |
|---|---|---|
|
|
Sets the token lifetime in seconds for access tokens issued by SAP Authorization and Trust Management service. The value ranges from 60 seconds to 86400 seconds, in other words, from 1 minute to 24 hours. Default: 43200 seconds (12 hours)
|
|
|
|
Sets the token lifetime in seconds for refresh tokens issued by SAP Authorization and Trust Management service. The value ranges from 60 seconds to 31536000 seconds, in other words, from 1 minute to 1 year. Default: 604800 seconds (7 days) |
|
|
|
This key contains a list of the redirect URIs that SAP BTP checks for when redirecting. If your landscape domain or custom domain aren't on this list, including wildcards, the Authorization and Trust Management Service won't redirect users there. We support explicit wildcards, namely domain relaxing and arbitrary paths. For example:
For more information, see Listing Allowed Redirect URIs. |
|
|
|
Specifies the types of secrets available for binding applications to the service instance. The first type listed is the default type of secret. Otherwise, specify the type of secret when you create the binding or service key. For more information, see Service Instance Secrets. With The default value is
|
|
|
|
Includes the system attributes in the JWT. If you don't define a value, the system includes the attributes for groups and role collections by default. If the size of the JWT becomes an issue for you, you can explicitly remove them. For example: You can also have the service include a refresh token of a trusted identity provider. For more information, see Include Tokens from Corporate Identity Providers or SAP Cloud Identity Services in Tokens of the SAP Authorization and Trust Management Service. Values:
|
|
|
|
Includes an array of allowed identity providers. The default is that all identity providers are allowed. As an option, developers can configure on application level which identity providers can be used for business users to log on to a certain application. The value of
|
|
The xsenableasyncservice element controls whether the cf create-service and cf update-service commands of the Cloud Foundry command line interface (cf CLI) are executed synchronously (false) or asynchronously (true).
The Cloud Controller of Cloud Foundry times out after 60 seconds for the synchronous execution of the commands. For this reason, we recommend that you use asynchronous execution for multitenant applications or reuse services.
You usually need to wait for the completion of
cf create-serviceandcf update-serviceeven if you use asynchronous mode. Otherwise you might run into conflicts due to parallel update operations on the OAuth 2.0 clients.
"xsenableasyncservice":"true"
Syntax
"xsenableasyncservice":"false"
|
Value |
Description |
|---|---|
|
|
Cloud Foundry command line interface commands are executed synchronously. |
|
|
Cloud Foundry command line interface commands are executed asynchronously. |
If you want to grant scopes to an application for example, you must reference this application. Depending on where the application is located, you can reference an application in multiple ways:
-
Referencing the application of the current
xs-security.jsonfile -
Referencing a foreign application that is located in the same subaccount
Application References
|
Description |
Syntax |
|---|---|
|
Application in the current |
|
|
Application in the same subaccount |
|
|
Reference to any service instance in the same subaccount and space |
This is the service instance name you used when you created it. |
You can use these references with the following properties:
Properties
|
Property |
Description |
Example |
|---|---|---|
|
|
Granting scopes to other applications. |
|
|
|
Use this property if you want to grant a scope to other applications for a client credential scenario. |
|
|
|
Granting authorities (for a client credentials scenario) |
|
|
|
Referencing scopes in role templates |
|
|
|
Using this property, you can reference scopes in foreign applications (for a user scenario). |
|
When you define role templates and attributes in the xs-security.json file, you need to know that there's a relationship between default-values of attribute-references in the role template and valueRequired in the attribute. What is important to know is that you configure valueRequired in the current attribute definition independently from any role template. The attributes are later referenced in the role templates using the attribute-references element.
This means that an attribute can be referenced in multiple role templates. You can set default-values for the first role template and not for the second one. If you define an attribute with "valueRequired": true" (see rows 1 and 3), a default role can be generated automatically for the first role template only, but not for the second one.
Configuration Examples
|
Use Case |
Role Template |
Attribute |
|---|---|---|
|
A default role with default values is generated automatically. Administrators must set attribute values for their roles. |
|
or no |
|
A default role with default values is generated automatically. Administrators don't have to set attribute values for their role. A role that isn't restricted by attributes (unrestricted) is created. |
|
|
|
A default role is generated automatically. Administrators don't have to set attribute values for their roles. A role that isn't restricted by attributes (unrestricted) is created. |
No |
|
When you define role templates and attributes, observe the following configuration restriction:
- Do not add
attribute-referenceswithoutdefault-values, whereattributeis defined with"valueRequired" : true.When you update role templates and attributes, observe the following configuration restrictions:
Do not change
default-valuesofattribute-references.Do not change the
"valueRequired"property fromfalsetotrue.
Related Information
Tutorials for the SAP Authorization and Trust Management Service
Security Considerations for the SAP Authorization and Trust Management Service
Configuration Options for the SAP Authorization and Trust Management Service