You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Before you implement the Express integration, ensure you have:
26
+
27
+
-[Node.js](https://nodejs.org/) and [npm](https://docs.npmjs.com/) installed
28
+
- An [Express.js](https://expressjs.com/) application
29
+
- An OpenID Connect (OIDC) identity provider (optional for testing)
30
+
31
+
### Setting up the integration
32
+
33
+
Let's walk through how to secure your application APIs using Cedar with the new package for Express.
34
+
35
+
#### Step 1: Add the Cedar Authorization Middleware package
36
+
37
+
The Cedar Authorization Middleware package will be used to generate a Cedar schema, create sample authorization policies, and perform the authorization in your application.
38
+
39
+
```bash
40
+
npm i --save @cedar-policy/authorization-for-expressjs
41
+
```
42
+
43
+
#### Step 2: Generate Cedar schema from your APIs
44
+
45
+
A Cedar [schema](../overview/terminology.html#term-schema) defines the authorization model for an application, including the entity types in the application and the actions users are allowed to take. We recommend defining a [namespace](../overview/terminology.html#term-namespaces) for your schema. In this example, we use YourNamespace. Your policies are validated against this schema when you run the application.
46
+
47
+
The `authorization-for-expressjs` package can analyze the [OpenAPI specification](https://swagger.io/specification/) of your application and generate a Cedar schema. Specifically, the paths object is required in your specification.
48
+
49
+
If you don't have an OpenAPI specification, you can follow the quick instructions of the [express-openapi-generator](https://github.com/nklisch/express-openapi-generator) package to generate an OpenAPI specification.
50
+
51
+
You can generate a Cedar schema by running, replacing `openapi.json` with the file of your schema and `YourNamespace` with the namespace of our choice:
This will generate a schema file named `v4.cedarschema.json` in the package root.
58
+
59
+
#### Step 3: Define authorization policies
60
+
61
+
If no policies are configured, Cedar denies all authorization requests. We will add policies that grant access to APIs only for authorized user groups.
Note: If you specified an `operationId` in the OpenAPI specification, the action names defined in the Cedar Schema will use that `operationId` instead of the default `<HTTP Method> /<PATH>` format. In this case, ensure the naming of your Actions in your Cedar Policies matches the naming of your Actions in your Cedar Schema.
91
+
92
+
For large applications with complex authorization policies, it can be challenging to analyze and audit the actual permissions provided by the many different policies. Cedar also provides the [Cedar Analysis CLI](https://github.com/cedar-policy/cedar-spec/tree/main/cedar-lean-cli) to help developers perform policy analysis on their policies.
93
+
94
+
#### Step 4: Update the application code to call Cedar and authorize API access
95
+
96
+
The application will use the Cedar middleware to authorize every request against the Cedar policies. First, add the package to the project and define the `CedarInlineAuthorizationEngine` and `ExpressAuthorizationMiddleware`. This block of code can be added to the top of the `app.js` file:
// Map your authenticated user to a Cedar principal
60
-
constuser=req.user;
61
-
return {
62
-
uid: {
63
-
type:'YourApp::User',
64
-
id:user.sub
65
-
},
66
-
attrs: {
67
-
...user,
68
-
},
69
-
parents:user.groups.map(group=> ({
70
-
type:'YourApp::UserGroup',
71
-
id: group
72
-
}))
73
-
};
74
-
}
122
+
getPrincipalEntity: principalEntityFetcher
75
123
},
76
124
skippedEndpoints: [
77
125
{httpVerb:'get', path:'/login'},
78
-
{httpVerb:'get', path:'/health'},
126
+
{httpVerb:'get', path:'/api-spec/v3'},
79
127
],
80
128
logger: {
81
-
debug:console.log,
82
-
log:console.log,
129
+
debug:s=>console.log(s),
130
+
log:s=>console.log(s),
83
131
}
84
132
});
133
+
```
134
+
135
+
Next, add the Express Authorization middleware to the application:
136
+
137
+
```javascript
138
+
constapp=express();
139
+
140
+
app.use(express.json());
141
+
app.use(verifyToken()); // validate user token
142
+
// ... other pre-authz middlewares
85
143
86
-
// Use the middleware after your authentication middleware
87
-
app.use(authMiddleware); // Your authentication middleware
88
144
app.use(expressAuthorization.middleware);
89
145
90
-
// Define your routes
91
-
app.get('/protected-resource', (req, res) => {
92
-
res.json({ message:'Access granted!' });
93
-
});
146
+
// ... other middlewares
147
+
```
148
+
149
+
#### Step 5: Add application code to configure the user
150
+
151
+
The Cedar authorizer requires user groups and attributes to authorize requests. The authorization middleware relies on the function passed to `getPrincipalEntity` in the initial configuration to generate the principal entity. You need to implement this function to generate the user entity:
152
+
153
+
```javascript
154
+
asyncfunctionprincipalEntityFetcher(req) {
155
+
constuser=req.user; // it's common practice for the authn middleware to store the user info from the decoded token here
0 commit comments