diff --git a/.vitepress/config.ts b/.vitepress/config.ts index 64ade3331..5e5ad5f80 100644 --- a/.vitepress/config.ts +++ b/.vitepress/config.ts @@ -21,7 +21,7 @@ const redirectLinks: Record = {} const latestVersions = { java_services: '2.1.0', - java_cds4j: '2.1.0' + java_cds4j: '2.1.1' } const localSearchOptions = { diff --git a/.vitepress/theme/custom.scss b/.vitepress/theme/custom.scss index 0fd9cbc66..44559b3b0 100644 --- a/.vitepress/theme/custom.scss +++ b/.vitepress/theme/custom.scss @@ -252,7 +252,6 @@ kbd { .learn-more { color: var(--vp-c-gray); - font-style: italic; margin-top: -5px; margin-bottom: 5px; display: block; diff --git a/node.js/authentication.md b/node.js/authentication.md index 7cd14a132..3aaf2d341 100644 --- a/node.js/authentication.md +++ b/node.js/authentication.md @@ -133,21 +133,22 @@ cds.serve ('CustomerService') .with (function(){ ## Authentication Strategies {#strategies} -CAP ships with a few prebuilt authentication strategies, used by default: [`mocked`](#mocked) during development and [`jwt`](#jwt) in production. +CAP ships with a few prebuilt authentication strategies, used by default: [`mocked`](#mocked) during development and [`xsuaa`](#xsuaa) in production. You can override these defaults and configure the authentication strategy to be used through the `cds.requires.auth` [config option in `cds.env`](./cds-env), for example: -```jsonc -"cds": { // in package.json +::: code-group +```json [package.json] +"cds": { "requires": { - "auth": { "kind": "jwt" } + "auth": "xsuaa" } } ``` - -::: tip -Run `cds env get requires.auth` in your project root to find out the effective authentication config for your current environment. ::: +::: tip Inspect effective configuration +Run `cds env get requires.auth` in your project root to find out the effective config for your current environment. +::: ### Dummy Authentication {.h2 #dummy } @@ -156,37 +157,39 @@ This strategy creates a user that passes all authorization checks. It’s meant **Configuration:** Choose this strategy as follows: -```json -"cds": { // in package.json +::: code-group +```json [package.json] +"cds": { "requires": { - "auth": { "kind": "dummy" } + "auth": "dummy" } } ``` - +::: ### Mocked Authentication {.h2 #mocked } This authentication strategy uses basic authentication with pre-defined mock users during development. -::: tip -**Note:** When testing different users in the browser, it's best to use an incognito window, because logon information might otherwise be reused. -::: +> **Note:** When testing different users in the browser, it's best to use an incognito window, because logon information might otherwise be reused. **Configuration:** Choose this strategy as follows: -```jsonc -"cds": { // in package.json +::: code-group +```json [package.json] +"cds": { "requires": { - "auth": { "kind": "mocked" } + "auth": "mocked" } } ``` +::: You can optionally configure users as follows: -```jsonc -"cds": { // in package.json +::: code-group +```json [package.json] +"cds": { "requires": { "auth": { "kind": "mocked", @@ -201,6 +204,7 @@ You can optionally configure users as follows: } } ``` +::: #### Pre-defined Mock Users {#mock-users} @@ -220,9 +224,7 @@ The default configuration shipped with `@sap/cds` specifies these users: } ``` -::: tip This default configuration is merged with your custom configuration such that, by default, logins by alice, bob, ... and others (`*`) are allowed. -::: If you want to restrict these additional logins, you need to overwrite the defaults: @@ -239,24 +241,25 @@ If you want to restrict these additional logins, you need to overwrite the defau This authentication strategy uses basic authentication to use mock users during development. -::: tip -**Note:** When testing different users in the browser, it's best to use an incognito window, because logon information might otherwise be reused. -::: +> **Note:** When testing different users in the browser, it's best to use an incognito window, because logon information might otherwise be reused. **Configuration:** Choose this strategy as follows: -```jsonc -"cds": { // in package.json +::: code-group +```json [package.json] +"cds": { "requires": { - "auth": { "kind": "basic" } + "auth": "basic" } } ``` +::: You can optionally configure users as follows: -```jsonc -"cds": { // in package.json +::: code-group +```json [package.json] +"cds": { "requires": { "auth": { "kind": "basic", @@ -271,13 +274,14 @@ You can optionally configure users as follows: } } ``` +::: In contrast to [mocked authentication](#mocked), no default users are automatically added to the configuration. ### JWT-based Authentication { #jwt } -This is the default strategy used in production. User identity, as well as assigned roles and user attributes, are provided at runtime, by a bound instance of the ['user account and authentication'](https://help.sap.com/products/BTP/65de2977205c403bbc107264b8eccf4b/419ae2ef1ddd49dca9eb65af2d67c6ec.html) service (UAA). This is done in form of a JWT token in the `Authorization` header of incoming HTTP requests. +This is the default strategy used in production. User identity, as well as assigned roles and user attributes, are provided at runtime, by a bound instance of the ['User Account and Authentication'](https://help.sap.com/products/BTP/65de2977205c403bbc107264b8eccf4b/419ae2ef1ddd49dca9eb65af2d67c6ec.html) service (UAA). This is done in form of a JWT token in the `Authorization` header of incoming HTTP requests. **Prerequisites:** You need to add [passport](https://www.passportjs.org/) to your project: ```sh @@ -291,20 +295,22 @@ npm add @sap/xssec **Configuration:** Choose this strategy as follows: -```jsonc -"cds": { // in package.json +::: code-group +```json [package.json] +"cds": { "requires": { - "auth": { "kind": "jwt" } + "auth": "jwt" } } ``` +::: [Learn more about testing JWT-based authentication in **XSUAA in Hybrid Setup**.](#xsuaa-setup){.learn-more} ### XSUAA-based Authentication { #xsuaa } -Authentication kind *xsuaa* is a logical extension of kind [*jwt*](#jwt) that additionally offers access to SAML attributes through `req.user.attr` (for example, `req.user.attr.familyName`). +Authentication kind `xsuaa` is a logical extension of kind [`jwt`](#jwt) that additionally offers access to SAML attributes through `req.user.attr` (for example, `req.user.attr.familyName`). **Prerequisites:** You need to add [@sap/xssec](https://help.sap.com/docs/HANA_CLOUD_DATABASE/b9902c314aef4afb8f7a29bf8c5b37b3/54513272339246049bf438a03a8095e4.html#loio54513272339246049bf438a03a8095e4__section_atx_2vt_vt) to your project: @@ -314,13 +320,15 @@ npm add @sap/xssec **Configuration:** Choose this strategy as follows: -```jsonc -"cds": { // in package.json +::: code-group +```json [package.json] +"cds": { "requires": { - "auth": { "kind": "xsuaa" } + "auth": "xsuaa" } } ``` +::: [See **XSUAA in Hybrid Setup** below for additional information of how to test this](#xsuaa-setup){.learn-more} @@ -347,13 +355,15 @@ npm add @sap/xssec **Configuration:** Choose this strategy as follows: -```jsonc -"cds": { // in package.json +::: code-group +```json [package.json] +"cds": { "requires": { - "auth": { "kind": "ias" } + "auth": "ias" } } ``` +::: ### Custom Authentication {#custom } @@ -391,7 +401,7 @@ module.exports = function custom_auth (req, res, next) { ## XSUAA in Hybrid Setup {#xsuaa-setup} -### Prepare Local Environment +### Prepare Local Environment The following steps assume you've set up the [**Cloud Foundry Command Line Interface**](https://help.sap.com/products/BTP/65de2977205c403bbc107264b8eccf4b/856119883b8c4c97b6a766cc6a09b48c.html). @@ -442,7 +452,7 @@ If you don’t know the API endpoint, have a look at section [Regions and API En This step is necessary for locally running apps and for apps deployed on Cloud Foundry. ::: -### Configure the Application +### Configure the Application 1. Create a service key: @@ -485,7 +495,7 @@ cds env list requires.uaa --resolve-bindings --profile hybrid This prints the full `uaa` configuration including the credentials. -### Set Up the Roles for the Application { #auth-in-cockpit} +### Set Up the Roles for the Application { #auth-in-cockpit} By creating a service instance of the `xsuaa` service, all the roles from the _xs-security.json_ file are added to your subaccount. Next, you create a role collection that assigns these roles to your users. @@ -504,7 +514,7 @@ By creating a service instance of the `xsuaa` service, all the roles from the _x 7. Add the email addresses for your users to the *Users* list. 8. Choose *Save* -### Running Approuter +### Running Approuter The approuter component implements the necessary authentication flow with XSUAA to let the user log in interactively. The resulting JWT token is sent to the application where it’s used to enforce authorization and check the user's roles. diff --git a/node.js/core-services.md b/node.js/core-services.md index 0f020b1ee..ef88b2d81 100644 --- a/node.js/core-services.md +++ b/node.js/core-services.md @@ -506,7 +506,7 @@ class BooksService extends cds.ApplicationService { - **`.on`** handlers actually fulfill requests, e.g. by reading/writing data from/to databases - **`.before`** handlers run before the `.on` handlers, frequently for validating inbound data -- **`.after`** handlers run before the `.on` handlers, frequently to enrich outbound data +- **`.after`** handlers run after the `.on` handlers, frequently to enrich outbound data **Argument `event`** can be one of: