Skip to content

Commit 1871a4b

Browse files
pfvatterottpfvatterott
authored
Update READMEs (#61)
* Update READMEs * Added parent README
1 parent 94c3ae6 commit 1871a4b

File tree

3 files changed

+303
-3
lines changed

3 files changed

+303
-3
lines changed

‎README.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
<p align="center">
2+
<a href="https://www.propelauth.com?ref=github" target="_blank" align="center">
3+
<img src="https://www.propelauth.com/imgs/lockup.svg" width="200">
4+
</a>
5+
</p>
6+
7+
# PropelAuth Node Libraries
8+
9+
Javascript libraries for managing authentication, backed by [PropelAuth](https://www.propelauth.com?ref=github).
10+
11+
[PropelAuth](https://www.propelauth.com?ref=github) makes it easy to add authentication and authorization to your B2B/multi-tenant application.
12+
13+
Your frontend gets a beautiful, safe, and customizable login screen. Your backend gets easy authorization with just a few lines of code. You get an easy-to-use dashboard to config and manage everything.
14+
15+
## [PropelAuth Node Library](https://github.com/PropelAuth/node/tree/main/packages/node)
16+
17+
PropelAuth's Node library provides all the building blocks you need to add authentication to your Node projects. You should prefer the [Cloudflare Workers](https://docs.propelauth.com/reference/backend-apis/cloudflare-workers), [Express](https://docs.propelauth.com/reference/backend-apis/express), or [Next.js libraries](https://docs.propelauth.com/reference/fullstack-apis/nextjsapp/automatic-installation) if you are using those frameworks, as they provide a more first-class experience, however, this library can be used in any Node project.
18+
19+
## [PropelAuth Cloudflare Worker Library](https://github.com/PropelAuth/node/tree/main/packages/cloudflare-worker)
20+
21+
PropelAuth's Cloudflare Workers library makes it easy to add authentication and authorization to your [Cloudflare Workers](https://workers.cloudflare.com).

‎packages/cloudflare-worker/README.md‎

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
<p align="center">
2+
<a href="https://www.propelauth.com?ref=github" target="_blank" align="center">
3+
<img src="https://www.propelauth.com/imgs/lockup.svg" width="200">
4+
</a>
5+
</p>
6+
7+
# PropelAuth Cloudflare Library
8+
9+
A Javascript library for managing authentication, backed by [PropelAuth](https://www.propelauth.com?ref=github). While this library was built specifically with Cloudflare Workers in mind, it can also be used in edge/serverless contexts.
10+
11+
[PropelAuth](https://www.propelauth.com?ref=github) makes it easy to add authentication and authorization to your B2B/multi-tenant application.
12+
13+
Your frontend gets a beautiful, safe, and customizable login screen. Your backend gets easy authorization with just a few lines of code. You get an easy-to-use dashboard to config and manage everything.
14+
15+
## Documentation
16+
17+
- Full reference this library is [here](https://docs.propelauth.com/reference/backend-apis/cloudflare-workers)
18+
- Getting started guides for PropelAuth are [here](https://docs.propelauth.com/)
19+
20+
## Installation
21+
22+
```shell
23+
npm install @propelauth/cloudflare-worker
24+
```
25+
26+
## Initialize
27+
28+
`initAuth` performs a one-time initialization of the library.
29+
It will verify your `apiKey` is correct and fetch the metadata needed to verify access tokens in [validateAccessTokenAndGetUserClass](#protect-api-routes).
30+
31+
You can find the `authUrl`, `apiKey`, and `verifierKey` in the **Backend Integration** section in your PropelAuth dashboard.
32+
33+
```typescript
34+
import { initAuth } from '@propelauth/cloudflare-worker'
35+
36+
const {
37+
validateAccessTokenAndGetUserClass,
38+
// ...
39+
} = initAuth({
40+
authUrl: 'REPLACE_ME',
41+
apiKey: 'REPLACE_ME',
42+
verifierKey: 'REPLACE_ME',
43+
})
44+
```
45+
46+
## Protect API Routes
47+
48+
After initializing auth, you can verify access tokens by passing it in the Authorization header (formatted `Bearer TOKEN`) to `validateAccessTokenAndGetUserClass`.
49+
You can see more information about the User Class [here](https://docs.propelauth.com/reference/backend-apis/cloudflare-workers#user-class).
50+
51+
```ts
52+
const authorizationHeader = // Get the Authorization header from an HTTP request
53+
try {
54+
const user = await validateAccessTokenAndGetUserClass(authorizationHeader)
55+
console.log(`Got request from user ${user.userId}`);
56+
} catch (err) {
57+
// You can return a 401, or continue the request knowing it wasn't sent from a logged-in user
58+
console.log(`Unauthorized request ${err}`);
59+
}
60+
```
61+
62+
## Authorization / Organizations
63+
64+
You can also verify which organizations the user is in, and which roles and permissions they have in each organization all through the [User Class](https://docs.propelauth.com/reference/backend-apis/cloudflare-workers#user-class).
65+
66+
### Check Org Membership
67+
68+
Verify that the request was made by a valid user **and** that the user is a member of the specified organization.
69+
70+
```ts
71+
const authorizationHeader = // Get the Authorization header from an HTTP request
72+
const orgId = // get the orgId from somewhere, such as the request URL
73+
try {
74+
const user = await validateAccessTokenAndGetUserClass(authorizationHeader)
75+
const org = user.getOrg(orgId)
76+
if (!org) {
77+
// return a 403
78+
}
79+
console.log(`Got request from user ${user.userId} for org ${org.orgName}`);
80+
} catch (err) {
81+
// You can return a 401, or continue the request knowing it wasn't sent from a logged-in user
82+
console.log(`Unauthorized request ${err}`);
83+
}
84+
```
85+
86+
### Check Org Membership and Role
87+
88+
Similar to checking org membership, but will also verify that the user has a specific Role in the organization.
89+
90+
A user has a Role within an organization. By default, the available roles are Owner, Admin, or Member, but these can be configured. These roles are also hierarchical, so Owner > Admin > Member.
91+
92+
```ts
93+
const authorizationHeader = // Get the Authorization header from an HTTP request
94+
const orgId = // get the orgId from somewhere, such as the request URL
95+
try {
96+
const user = await validateAccessTokenAndGetUserClass(authorizationHeader)
97+
const org = user.getOrg(orgId)
98+
if (!org || !org.isRole("Admin")) {
99+
// return a 403
100+
}
101+
console.log(`Got request from Admin user ${user.userId} for org ${org.orgName}`);
102+
} catch (err) {
103+
// You can return a 401, or continue the request knowing it wasn't sent from a logged-in user
104+
console.log(`Unauthorized request ${err}`);
105+
}
106+
```
107+
108+
### Check Org Membership and Permission
109+
110+
Similar to checking org membership, but will also verify that the user has the specified permission in the organization.
111+
112+
Permissions are arbitrary strings associated with a role. For example, `can_view_billing`, `ProductA::CanCreate`, and `ReadOnly` are all valid permissions. You can create these permissions in the PropelAuth dashboard.
113+
114+
```ts
115+
const authorizationHeader = // Get the Authorization header from an HTTP request
116+
const orgId = // get the orgId from somewhere, such as the request URL
117+
try {
118+
const user = await validateAccessTokenAndGetUserClass(authorizationHeader)
119+
const org = user.getOrg(orgId)
120+
if (!org || !org.hasPermission("can_view_billing")) {
121+
// return a 403
122+
}
123+
console.log(`User ${user.userId} has 'can_view_billing' permissions for org ${org.orgName}`);
124+
} catch (err) {
125+
// You can return a 401, or continue the request knowing it wasn't sent from a logged-in user
126+
console.log(`Unauthorized request ${err}`);
127+
}
128+
```
129+
130+
## Calling Backend APIs
131+
132+
You can also use the library to call the PropelAuth APIs directly, allowing you to fetch users, create orgs, and a lot more.
133+
134+
```ts
135+
const auth = initAuth({
136+
authUrl: 'REPLACE_ME',
137+
apiKey: 'REPLACE_ME',
138+
verifierKey: 'REPLACE_ME',
139+
})
140+
141+
const magicLink = await auth.createMagicLink({
142+
email: '[email protected]',
143+
})
144+
```
145+
146+
See the [API Reference](https://docs.propelauth.com/reference) for more information.
147+
148+
149+
## Questions?
150+
151+
Feel free to reach out at [email protected]
152+

‎packages/node/README.md‎

Lines changed: 130 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
11
<p align="center">
22
<a href="https://www.propelauth.com?ref=github" target="_blank" align="center">
3-
<img src="https://propelauth-logos.s3.us-west-2.amazonaws.com/logo-only.png" width="100">
3+
<img src="https://www.propelauth.com/imgs/lockup.svg" width="200">
44
</a>
55
</p>
66

7-
# PropelAuth Node Middleware
7+
# PropelAuth Node Library
88

9-
A javascript library for managing authentication, backed by [PropelAuth](https://www.propelauth.com?ref=github).
9+
A Javascript library for managing authentication, backed by [PropelAuth](https://www.propelauth.com?ref=github).
1010

1111
[PropelAuth](https://www.propelauth.com?ref=github) makes it easy to add authentication and authorization to your B2B/multi-tenant application.
1212

@@ -17,6 +17,133 @@ Your frontend gets a beautiful, safe, and customizable login screen. Your backen
1717
- Full reference this library is [here](https://docs.propelauth.com/reference/backend-apis/node)
1818
- Getting started guides for PropelAuth are [here](https://docs.propelauth.com/)
1919

20+
## Installation
21+
22+
```shell
23+
npm install @propelauth/node
24+
```
25+
26+
## Initialize
27+
28+
`initBaseAuth` performs a one-time initialization of the library.
29+
It will verify your `apiKey` is correct and fetch the metadata needed to verify access tokens in [validateAccessTokenAndGetUserClass](#protect-api-routes).
30+
31+
32+
```typescript
33+
import { initBaseAuth } from '@propelauth/node';
34+
35+
const {
36+
validateAccessTokenAndGetUserClass,
37+
fetchUserMetadataByUserId,
38+
// ...
39+
} = initBaseAuth({
40+
authUrl: "REPLACE_ME",
41+
apiKey: "REPLACE_ME",
42+
});
43+
```
44+
45+
## Protect API Routes
46+
47+
After initializing auth, you can verify access tokens by passing it in the Authorization header (formatted `Bearer TOKEN`) to `validateAccessTokenAndGetUserClass`.
48+
You can see more information about the User Class [here](https://docs.propelauth.com/reference/backend-apis/node#user-class).
49+
50+
```ts
51+
const authorizationHeader = // Get the Authorization header from an HTTP request
52+
try {
53+
const user = await validateAccessTokenAndGetUserClass(authorizationHeader)
54+
console.log(`Got request from user ${user.userId}`);
55+
} catch (err) {
56+
// You can return a 401, or continue the request knowing it wasn't sent from a logged-in user
57+
console.log(`Unauthorized request ${err}`);
58+
}
59+
```
60+
61+
## Authorization / Organizations
62+
63+
You can also verify which organizations the user is in, and which roles and permissions they have in each organization all through the [User Class](https://docs.propelauth.com/reference/backend-apis/node#user-class)
64+
65+
### Check Org Membership
66+
67+
Verify that the request was made by a valid user **and** that the user is a member of the specified organization.
68+
69+
```ts
70+
const authorizationHeader = // Get the Authorization header from an HTTP request
71+
const orgId = // get the orgId from somewhere, such as the request URL
72+
try {
73+
const user = await validateAccessTokenAndGetUserClass(authorizationHeader)
74+
const org = user.getOrg(orgId)
75+
if (!org) {
76+
// return a 403
77+
}
78+
console.log(`Got request from user ${user.userId} for org ${org.orgName}`);
79+
} catch (err) {
80+
// You can return a 401, or continue the request knowing it wasn't sent from a logged-in user
81+
console.log(`Unauthorized request ${err}`);
82+
}
83+
```
84+
85+
### Check Org Membership and Role
86+
87+
Similar to checking org membership, but will also verify that the user has a specific Role in the organization.
88+
89+
A user has a Role within an organization. By default, the available roles are Owner, Admin, or Member, but these can be configured. These roles are also hierarchical, so Owner > Admin > Member.
90+
91+
```ts
92+
const authorizationHeader = // Get the Authorization header from an HTTP request
93+
const orgId = // get the orgId from somewhere, such as the request URL
94+
try {
95+
const user = await validateAccessTokenAndGetUserClass(authorizationHeader)
96+
const org = user.getOrg(orgId)
97+
if (!org || !org.isRole("Admin")) {
98+
// return a 403
99+
}
100+
console.log(`Got request from Admin user ${user.userId} for org ${org.orgName}`);
101+
} catch (err) {
102+
// You can return a 401, or continue the request knowing it wasn't sent from a logged-in user
103+
console.log(`Unauthorized request ${err}`);
104+
}
105+
```
106+
107+
### Check Org Membership and Permission
108+
109+
Similar to checking org membership, but will also verify that the user has the specified permission in the organization.
110+
111+
Permissions are arbitrary strings associated with a role. For example, `can_view_billing`, `ProductA::CanCreate`, and `ReadOnly` are all valid permissions. You can create these permissions in the PropelAuth dashboard.
112+
113+
```ts
114+
const authorizationHeader = // Get the Authorization header from an HTTP request
115+
const orgId = // get the orgId from somewhere, such as the request URL
116+
try {
117+
const user = await validateAccessTokenAndGetUserClass(authorizationHeader)
118+
const org = user.getOrg(orgId)
119+
if (!org || !org.hasPermission("can_view_billing")) {
120+
// return a 403
121+
}
122+
console.log(`User ${user.userId} has 'can_view_billing' permissions for org ${org.orgName}`);
123+
} catch (err) {
124+
// You can return a 401, or continue the request knowing it wasn't sent from a logged-in user
125+
console.log(`Unauthorized request ${err}`);
126+
}
127+
```
128+
---
129+
130+
## Calling Backend APIs
131+
132+
You can also use the library to call the PropelAuth APIs directly, allowing you to fetch users, create orgs, and a lot more.
133+
134+
```ts
135+
const auth = initAuth({
136+
authUrl: 'REPLACE_ME',
137+
apiKey: 'REPLACE_ME',
138+
})
139+
140+
const magicLink = await auth.createMagicLink({
141+
email: '[email protected]',
142+
})
143+
```
144+
145+
---
146+
20147
## Questions?
21148

22149
Feel free to reach out at [email protected]

0 commit comments

Comments
 (0)