Skip to content

Latest commit

 

History

History
370 lines (254 loc) · 17.7 KB

03-One-Off-Deployment.md

File metadata and controls

370 lines (254 loc) · 17.7 KB
Raw

One-off Deployment

Deploy the application into a subaccount of the customer BTP global account and integrate the subaccount with the customer identity provider (IDP) for authentication.

Setup the BTP Subaccount

BTP Cockpit (Global account):

Create a subaccount to host the application runtime (in our example we used the data center of Amazon Web Services (AWS) and the region Europe (Frankfurt)). You can reuse the subaccount used for development for convience.

Optional: Assign subaccount to a Directory as parent.

Check if sufficient service assignments are available in your global account:

  • Cloud Foundry Runtime (3 units of Application runtime)
  • SAP HANA Cloud (1 unit)
  • SAP HANA Schemas & HDI Containers
  • Launchpad Service

Open Entity Assignments and assign quotas for the following entities to your subaccount in which you want to deploy the application:

  • Cloud Foundry Runtime (3 units of Application runtime)
  • SAP HANA Cloud (1 unit)
  • SAP HANA Schemas & HDI Containers
  • Launchpad Service (plan: standard (Application))

Note: The value help may not offer an item referring to "Cloud Foundry". In this case select "Application runtime" and save the change, the name of item in the list of entity assignment is changed to "Cloud Foundry Runtime".

Enable Cloud Foundry

BTP Cockpit (subaccount):

Open the subaccount Overview and enable Cloud Foundry:

  • Plan: standard
  • Landscape: cf-eu10
  • Instance Name: authorreadings
  • Org Name: authorreadings

Create Space (runtime)

  • keep standard roles
  • Add CF Org members
  • Add CF space members

Create a HANA database

BTP Cockpit (subaccount):

Open the Cloud Foundry space, navigate to SAP HANA Cloud and create a HANA database:

  • Choose CF Organization + Space
  • Instance Name: authorreadings-db
  • Enter a password
  • Save

Subscribe Lauchpad application

BTP Cockpit (subaccount):

Open the Service Marketplace and select the Launchpad Service. Create a subscription of the Launchpad Service with

  • Service: Launchpad
  • Plan: standard - Subscription

Open Users and add the role collection Launchpad_Admin to your user.

Note: The SAP Launchpad provides the managed application router, which we are using to manage application authentication and tokens. You need to subscribe the Launchpad service before deploying your application to ensure that the Web app can be published as "HTML5 Application".

Prepare project configuration (make adjustments) for Cloud Foundry deployments

Next, let’s make some adjustments so that the app can be deployed to Cloud Foundry as a central Launchpad content.

Configure web app to connect to the app services. Define a route in the web app: Open file ./app/authorreadingmanager/xs-app.json and add the following route at position 1 (the order matters! The most specific one should be in the beginning)

Note: We will define the destination “cap-launchpad” later as part of project configuration mta.yml file

"routes": [
  {
    "authenticationType": "none",
    "csrfProtection": false,
    "source": "^/authorreadingmanager/",
    "destination": "launchpad"
  }
]

Check and adjust/add the service name in webapp configuration file at the end: Open file ./app/authorreadingmanager/webapp/manifest.json.

Note: This service name needs to be unique within your account and will appear in the runtime URL of the application.

"sap.cloud": {
   "public": true,
   "service": "authorreadingmanager"
}

Add to package.json

"engines": {
   "node": "^14"
}

Configure project deployment config files:

Adjust and configure the destination-content module in file ./mta.yaml. Here you define destinations and service keys for the destinations. After the MTA app has been deployed, you will see two destinations html_repo_host and …_uaa_fiori in your subaccount.

Note that the service name authorreadingmanager of the web app matches the service name used in file manifest.json of the web app.

modules:
- name: author-readings-destination-content
  type: com.sap.application.content
  requires:
  - name: author-readings-destination-service
    parameters:
      content-target: true
  - name: author-readings-repo-host
    parameters:
      service-key:
        name: author-readings-repo-host-key
  - name: author-readings-uaa
    parameters:
      service-key:
        name: author-readings-uaa-key
  parameters:
    content:
      instance:
        destinations:
        - Name: authorreadingmanager-repo-host-dest
          ServiceInstanceName: author-readings-html5-srv
          ServiceKeyName: author-readings-repo-host-key
          sap.cloud.service: authorreadingmanager
        - Authentication: OAuth2UserTokenExchange
          Name: authorreadingmanager-uaa-fiori-dest
          ServiceInstanceName: author-readings-uaa
          ServiceKeyName: author-readings-uaa-key
          sap.cloud.service: authorreadingmanager
        existing_destinations_policy: ignore
  build-parameters:
    no-source: true

Add the destination service resource in file mta.yaml. Here you define destination resource for the route as defined in web application configuration file ./app/authorreadingmanager/xs-app.json.

Note that the name launchpad of the route in xs-app.json should match with the destination service resource name in file mta.yaml.

resources:
- name: author-readings-destination-service
  type: org.cloudfoundry.managed-service
  parameters:
    config:
      HTML5Runtime_enabled: true
      init_data:
        instance:
          destinations:
          - Authentication: NoAuthentication
            Name: ui5
            ProxyType: Internet
            Type: HTTP
            URL: https://ui5.sap.com
          - Authentication: NoAuthentication
            Name: launchpad
            ProxyType: Internet
            Type: HTTP
            URL: ~{srv-api/srv-url}
            HTML5.DynamicDestination: true
            HTML5.ForwardAuthToken: true

Add the service api as a required dependency of the destination in file ./mta.yaml:

resources:
- name: author-readings-destination-service
  requires:
  - name: srv-api

After all the above changes are applied in file mta.yml, the file would look like the mta-file of the sample application.

Enable additional request origins (CORS)

In this step we enable citizen users to build AppGyver applications that connect to the OData services of our BTP application as backend. In general Appgyver expects the server to handle Cross Origin Request Sharing (CORS). However, by default CAP services do not allow cross origin requests.

Therefore we enhance the default bootstrapping by some custom logic to allow AppGyver applications to access the OData services (compare https://cap.cloud.sap/docs/node.js/cds-serve).

Create a file server.js in the the root folder of the application to define allowed request origins for CORS checks. In our example we allow all origins for simplicity; for productive use specific origins shall be listed and allowed only.

// Define allowed access origins for CORS checks.
// In our example we allow all origins; for productive use specific origins shall be allowed only.
const cds = require('@sap/cds')
cds.on('bootstrap', (app) => {
    const cors = require('cors')
	app.use(cors())
	app.use((req, res, next) => {
		res.setHeader('Access-Control-Allow-Origin', '*');
		next();
	});
})
cds.on('listening', () => {
	// add more middleware ...
})
module.exports = cds.server // delegate to default server.js

Enhance the file package.json with the dependency:

"dependencies": {
	"cors": "^2.8.5"
}

Deploy to Cloud Foundry

  1. Open a new terminal and login to cloud foundry: Run command cf login, enter the CF API of your environment (for example https://api.cf.eu10.hana.ondemand.com), enter your development user/password, select org of the BTP provider subaccount for the application (authorreadings), and select the CF space (runtime).

  2. Navigate to the sub-folder with the sample application using command cd Applications/author-readings.

  3. Run command npm install to install the messaging npm packages.

  4. Build the project by selecting Build MTA Project in the context menu of file mta.yaml.

  5. Deploy the application by selecting Deploy MTA Archive in the context menu of file ./mta_archives/author-readings_1.0.0.mtar.

You can find details on how to deploy the application to the Cloud Foundry Runtime here.

Configure the Launchpad

Once you have deployed your application successfully, the included Web Application is available as HTML5 Application and ready to be added to a Launchpad site.

  1. Open the Launchpad Site Manager by launching the application Launchpad Service from your section Instance and Subscriptions in your BTP subaccount.

Fetch the latest version of your Web application:

  1. Open the Provider Manager. The HTML5 Apps content provider is created automatically and all Web applications that you deployed to the BTP subaccount are automatically added as content to this content provider.

  2. Select the content provider HTML5 Apps and fetch any updates of your Web application by clicking the fetch updated content icon. The HTML5 Apps content provider should now expose the latest version of the Web application.

Note: You need to update the content provider whenever you changed the Web application.

Add the web application to your content:

  1. Open the Content Manager and navigate to the Content Explorer sheet, select the content provider HTML5 Apps and add your Web application to your content by clicking on Add to my Content.

Create a group and add you app to the group:

  1. Open the Content Manager and navigate to sheet My Content.

  2. Create a new group (button + New >> Group) and enter a title and desciption.

  3. On the Assignments-panel, click into the search box to get the list of available apps. Click on "+"-symbol behind your app to assign your app to the group.

  4. Save the group.

Assign the Web application to the default role:

In this step, you’ll assign your app to the "Everyone" role. This is a default role - the content assigned to this role is visible to all users.

  1. Open the Content Manager and navigate to sheet My Content.

  2. Click the role Everyone to open the role editor.

  3. Edit the role: On the Assignments-panel, click into the search box to get the list of available apps. Click on "+"-symbol behind your app to assign your app to the role.

  4. Save the role.

Create/update a site:

In this step we create and review a launchpad site. If you already have a site, then just add your Web application.

  1. Open the Site Directory. Create a site and enter a site name.

  2. Launch the site with button Go to site and test your Web application.

Note: Take note of the launchpad site URL as BTP Application Launchpad URL. On the launchpad, open the context menu of the tile "Author Readings" and take note of the URL as BTP Application URL. We will use these URLs for later testing and to embedd the BTP application in the launchpads of ByD and S4HANA Cloud.

Note: The URL of the web application as provided in the BTP provider subaccount under HTML5 Applications does not route requests via the managed application router of the SAP Launchpad service and hence user attributes are not propagated to the application. You may encounter this by observing a login user "Default User".

Configure Authentication and Authorization

We use the SAP Identity and Authentication Service (IAS) as corporate identity provider (IDP) and establish a trust relationship between the service provider (our BTP subaccount to which we deployed our application) and the IAS tenant. In result the BTP subaccount and our application delegates user authentications to the IAS tenant incl. single sign-on. Furthermore we use the IAS tenant to assign authorization roles to users via user groups.

Precondition: You have admin access to an SAP Identity and Authentication Service tenant.

Configure Single Sign-on using the SAP Identity and Authentication Service

As preferred approach we configure the trust between the BTP subaccount and the IAS using Open ID Connect (OIDC). As fallback I described a SAML 2.0 trust configuration as well.

Open ID Connect Configuration

Setup the trust relationship between the BTP subaccount to IAS using Open ID Connect (OIDC).

Note: As precondition of this setup the BTP subaccount and the IAS tenant need to be assigned to the same customer ID.

BTP sub-account:

  1. Open menu item Security >> Trust Configuration and click on "Establish Trust" and select the IAS tenant to setup the OIDC trust configuration.

IAS Admin UI:

  1. Login to the IAS admin UI (URL: /admin/)

  2. Open menu item Applications and search the application that refers to your BTP subaccount (the name typically follows the pattern: XSUAA_).

  3. Edit the application and change the following fields:

    • The display name appears on user login screen and the login applies to all applications liked to the IAS tenant (following the SSO principle). Change the "Display Name" to something meaningful from an end-user point of view representing the scope of the IAS, for example "Almika Inc. - User login" or something more general if you have multiple apps running in your subaccount.
    • Enter the "Home URL", e.g. using the link to the Launchpad site or the application.

SAML 2.0 Configuration (fallback)

Setup the trust relationship between the BTP subaccount to IAS using SAML 2.0. This approach is the fallback trust configuration if the OIDC configuration is not possible.

Note: This fallback applies if the BTP subscriber subaccount and the IAS tenant are not assigned to the same customer ID. This setup comes with limitations regarding remote access to the OData services of the BTP app with principal propagation.

BTP subaccount:

  1. Download the Service provider SAML metadata file: Open menu item Security >> Trust Configuration and click on Download SAML Metadata.

IAS Admin UI:

  1. Open menu item Applications and create a new application of type Bundled application.

    • Enter the required information like application display name, application URL, … The display name appears on user login screen and the login applies to all applications liked to the IAS tenant (following the SSO principle). Choose something meaningful from an end-user point of view representing the scope of the IAS, for example "Almika Inc. - User login" or something more general if you have multiple apps running in your subaccount.
    • Open section *SAML 2.0 Configuration" and upload the Service provider SAML metadata file from the BTP subaccount.
    • Open section Subject Name identifier and select "E-Mail" as basic attribute.
    • Open section Default Name ID Format and select "E-Mail".

  2. Download the IDP SAML metadata file: Open menu item Tenant Settings >> SAML 2.0 Configuration and click on Download Metadata File (the button in the lower left corner).

BTP subaccount:

  1. Open menu item Security >> Trust Configuration and click on New Trust Configuration. Upload the IDP SAML metadata file and enter a meaningful name and description for the IDP (for example "Corporate IDP" or "Custom IAS (SAML2.0)").

Setup Users and User Groups

In our example we are using IAS user groups to assign authorizaton roles to users. The user groups will be passed as "assertion attribute" to the BTP subaccount and will be mapped to respective role collections in the BTP subaccount.

IAS Admin UI:

  1. Open menu item User Management and add the users who shall have access to the BTP application. Enter user details like name and e-mail and take into account that the e-mail is used as identifying attribute and hence I would recommend to use the e-mail address as used in the ERP system that we will integrate later.

  2. Open menu item User Groups and add user groups that represent typical user roles and enter a unique (technical) Name and a meaningful "Display Name*, for example:

    Name: Display name:
    Author_Reading_Manager Author Reading Manager
    Author_Reading_Admin Author Reading Administrator

  3. Open menu item Applications, open the application referring to the BTP subaccount with your application, and navigate to Assertion Attributes. Check if the User Attribute "Groups" is already mapped to the Assertion Attribute "groups". If not, then add the attribute mapping.

BTP subaccount:

  1. Open menu item Role Collections and add the user groups (using the unique technical name of the user group) to the role collections that shall be assigned to the respective users with the use group:

    Role Collection: User Groups:
    AuthorReadingManagerRoleCollection Author_Reading_Manager
    AuthorReadingAdminRoleCollection Author_Reading_Admin

Login to the BTP Application and test Single Sign-on

Launch your BTP application and select the IAS tenant as IDP.

Note: The first attempt to open the app may fail with an authorization error message if the user has not yet been replicated from the IAS tenant to the BTP subaccount (latest at this point this replication is triggered and executed atomatically). The second login attempt to open the app should be successful always.

You may deactivate the "Default Identity Provider" (which refers to the SAP ID Service) in the trust center of your BTP subaccount.