Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

req.user vs req.user #1493

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open

req.user vs req.user #1493

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
17e1cd1
req.user vs req.user
sjvans Dec 3, 2024
8b16820
Update node.js/authentication.md
sjvans Dec 3, 2024
0e70b01
Merge branch 'main' into req.user-vs-req.user
sjvans Dec 20, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 13 additions & 13 deletions node.js/authentication.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,24 +9,24 @@ uacp: This page is linked from the Help Portal at https://help.sap.com/products/

# Authentication

{{$frontmatter?.synopsis}} This is done by [authentication middlewares](#strategies) setting the [`req.user` property](#cds-user) which is then used in [authorization enforcement](#enforcement) decisions.
{{$frontmatter?.synopsis}} This is done by [authentication middlewares](#strategies) setting the [`cds.context.user` property](#cds-user) which is then used in [authorization enforcement](#enforcement) decisions.

[[toc]]


## cds. User { #cds-user .class }
[user]: #cds-user
[`req.user`]: #cds-user
[`cds.context.user`]: #cds-user

Represents the currently logged-in user as filled into [`req.user`](events#user) by authentication middlewares.
Represents the currently logged-in user as filled into [`cds.context.user`](events#user) by authentication middlewares.
Simply create instances of `cds.User` or of subclasses thereof in custom middlewares.
For example:

```js
const cds = require('@sap/cds')
const DummyUser = new class extends cds.User { is:()=>true }
module.exports = (req,res,next) => {
req.user = new DummyUser('dummy')
cds.context.user = new DummyUser('dummy')
next()
}
```
Expand Down Expand Up @@ -112,7 +112,7 @@ By default, `cds.User.default` points to `cds.User.Anonymous`. However, you can

## Authorization Enforcement {#enforcement}

Applications can use the `req.user` APIs to do programmatic enforcement.
Applications can use the `cds.context.user` APIs to do programmatic enforcement.
For example, the authorization of the following CDS service:

```cds
Expand All @@ -132,7 +132,7 @@ can be programmatically enforced by means of the API as follows:
const cds = require('@sap/cds')
cds.serve ('CustomerService') .with (function(){
this.before ('*', req =>
req.user.is('authenticated') || req.reject(403)
req.user.is('authenticated') || req.reject(403)
)
this.before (['READ', 'CREATE'], 'Orders', req =>
req.user.is('admin') || req.reject(403)
Expand Down Expand Up @@ -298,7 +298,7 @@ In contrast to [mocked authentication](#mocked), no default users are automatica

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 authentication strategy also adds [`req.user.tokenInfo`](#user-token-info).
This authentication strategy also adds [`cds.context.user.tokenInfo`](#user-token-info).

**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:
```sh
Expand All @@ -322,7 +322,7 @@ npm add @sap/xssec

### 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 `cds.context.user.attr` (for example, `cds.context.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:
```sh
Expand All @@ -348,7 +348,7 @@ npm add @sap/xssec

This is an additional authentication strategy using the [Identity Authentication Service](https://help.sap.com/docs/IDENTITY_AUTHENTICATION) (IAS) that can be used in production. User identity and user attributes are provided at runtime, by a bound instance of the IAS service. This is done in form of a JWT token in the `Authorization` header of incoming HTTP requests.

This authentication strategy also adds [`req.user.tokenInfo`](#user-token-info).
This authentication strategy also adds [`cds.context.user.tokenInfo`](#user-token-info).

To allow forwarding to remote services, JWT tokens issued by IAS service don't contain authorization information. In particular, no scopes are included. Closing this gap is up to you as application developer.

Expand Down Expand Up @@ -384,22 +384,22 @@ You can configure an own implementation by specifying an own `impl` as follows:

Essentially, custom authentication middlewares must do two things:

First, they _must_ [fulfill the `req.user` contract](#cds-user) by assigning an instance of `cds.User` or a look-alike to the incoming request at `req.user`.
First, they _must_ [fulfill the `cds.context.user` contract](#cds-user) by assigning an instance of `cds.User` or a look-alike to the continuation of the incoming request at `cds.context.user`.

Second, if running in a multitenant environment, `req.tenant` must be set to a string identifying the tenant that is addressed by the incoming request.
Second, if running in a multitenant environment, `cds.context.tenant` must be set to a string identifying the tenant that is addressed by the incoming request.

```js
module.exports = function custom_auth (req, res, next) {
// do your custom authentication
req.user = new cds.User({
cds.context.user = new cds.User({
id: '<user-id>',
roles: ['<role-a>', '<role-b>'],
attr: {
<user-attribute-a>: '<value>',
<user-attribute-b>: '<value>'
}
})
req.tenant = '<tenant>'
cds.context.tenant = '<tenant>'
}
```

Expand Down
4 changes: 2 additions & 2 deletions node.js/cds-serve.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -296,9 +296,9 @@ Be aware that overriding requires constant updates as new middlewares by the fra

[Learn more about the middlewares default order.](#cds-middlewares){.learn-more}

#### Customization of `req.user`
#### Customization of `cds.context.user`

You can register middlewares to customize `req.user`.
You can register middlewares to customize `cds.context.user`.
It must be done after authentication.
If `cds.context.tenant` is manipulated as well, it must also be done before `cds.context.model` is set for the current request.

Expand Down
5 changes: 5 additions & 0 deletions node.js/events.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -137,6 +137,11 @@ The current user, an instance of `cds.User` as identified and verified by the au

[See reference docs for `cds.User`.](authentication#cds-user){.learn-more .indent}

::: tip
Please note the difference between `req` in a service handler (instance of `cds.EventContext`) and `req` in an express middleware (instance of `http.IncomingMessage`).
Case in point, `req.user` in a service handler is an official API and, if not explicitely set, points to `cds.context.user`.
On the other hand, setting `req.user` in a custom authentication middleware is deprecated.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

do you generally discourage the use use of req.user in middleware or only for setting properties?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We do recommend the usage of <cds.Request>.user or cds.context.user.

Our authentication middlewares only set cds.context.user which later on is also used when constructing a cds.Request.

<express.Request>.user is not set by us but if custom authentication middlewares set it, it's still working but deprecated. Custom authentication middlewares should also set cds.context.user instead.

:::



Expand Down
Loading