mirror of
https://github.com/lowdefy/lowdefy.git
synced 2025-03-31 15:20:32 +08:00
fix(docs): Add user authorization docs.
This commit is contained in:
SamTolmay
parent
5a2e0cdffb
commit
9f259fdb90
@ -160,3 +160,10 @@ _ref:
|
||||
The easiest way to host your custom block is the deploy the custom block to [npm](https://www.npmjs.com/) and [Unpkg](https://unpkg.com/) will automatically host your block for you on their CDN. Although this option is easy, the cache settings for Unpkg can result in longer load times in some cases which can result in a unreliable user experience. It is thus best to deploy you blocks to your own static file servers.
|
||||
|
||||
We are working on a Lowdefy blocks CDN to improve this developer experience in the future.
|
||||
- _ref:
|
||||
path: templates/navigation_buttons.yaml
|
||||
vars:
|
||||
previous_page_title: Lists
|
||||
previous_page_id: lists
|
||||
next_page_title: User authentication
|
||||
next_page_id: users-introduction
|
||||
|
||||
@ -81,7 +81,7 @@ _ref:
|
||||
The `AwsS3PresignedGetObject` request is used to get a download link for an object in AWS S3. The link provided by this request can be opened using the `Link` action.
|
||||
|
||||
#### Properties
|
||||
- `versionId: string`: _String_ - VersionId used to reference a specific version of the object.
|
||||
- `versionId: string`: VersionId used to reference a specific version of the object.
|
||||
- `expires: number`: Number of seconds for which the policy should be valid.
|
||||
- `key: string`: __Required__ - Key (or filename) under which object will be stored. If another file is saved with the same key, that file will be overwritten, so a random string in this field is probably needed.
|
||||
- `responseContentType: string`: Sets the Content-Type header of the response.
|
||||
|
||||
@ -119,6 +119,28 @@
|
||||
properties:
|
||||
title: Custom Blocks
|
||||
|
||||
- id: users_group
|
||||
type: MenuGroup
|
||||
properties:
|
||||
title: User Authentication
|
||||
icon: TeamOutlined
|
||||
links:
|
||||
- id: users
|
||||
type: MenuLink
|
||||
pageId: users-introduction
|
||||
properties:
|
||||
title: Introduction
|
||||
- id: openid-connect
|
||||
type: MenuLink
|
||||
pageId: openid-connect
|
||||
properties:
|
||||
title: OpenID Connect
|
||||
- id: login-and-logout
|
||||
type: MenuLink
|
||||
pageId: login-and-logout
|
||||
properties:
|
||||
title: Login and Logout
|
||||
|
||||
- id: blocks_input
|
||||
type: MenuGroup
|
||||
properties:
|
||||
|
||||
@ -25,6 +25,10 @@
|
||||
- _ref: concepts/lists.yaml
|
||||
- _ref: concepts/custom-blocks.yaml
|
||||
|
||||
- _ref: users/users-introduction.yaml
|
||||
- _ref: users/openid-connect.yaml
|
||||
- _ref: users/login-and-logout.yaml
|
||||
|
||||
- _ref: blocks/input/AutoComplete.yaml
|
||||
- _ref: blocks/input/ButtonSelector.yaml
|
||||
- _ref: blocks/input/CheckboxSelector.yaml
|
||||
|
||||
158
packages/docs/users/login-and-logout.yaml
Normal file
158
packages/docs/users/login-and-logout.yaml
Normal file
@ -0,0 +1,158 @@
|
||||
# Copyright 2020-2021 Lowdefy, Inc
|
||||
|
||||
# Licensed under the Apache License, Version 2.0 (the "License");
|
||||
# you may not use this file except in compliance with the License.
|
||||
# You may obtain a copy of the License at
|
||||
|
||||
# http://www.apache.org/licenses/LICENSE-2.0
|
||||
|
||||
# Unless required by applicable law or agreed to in writing, software
|
||||
# distributed under the License is distributed on an "AS IS" BASIS,
|
||||
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
# See the License for the specific language governing permissions and
|
||||
# limitations under the License.
|
||||
|
||||
_ref:
|
||||
path: templates/general.yaml.njk
|
||||
vars:
|
||||
pageId: login-and-logout
|
||||
pageTitle: Login and Logout
|
||||
section: User Authentication
|
||||
filePath: concepts/login-and-logout.yaml
|
||||
content:
|
||||
- id: introduction
|
||||
type: MarkdownWithCode
|
||||
properties:
|
||||
content: |
|
||||
The [`Login`](/Login) and [`Logout`](/Logout) actions can be used to log users in and out.
|
||||
|
||||
## Login
|
||||
|
||||
The `Login` action requests the OpenID provider's authorization URL from the Lowdefy server. The user is redirected to this URL, which normally hosts a login page. After the user has logged in successfully, the user is redirected to the `auth/openid-callback` route in the Lowdefy app, where the rest of the OpenID authorization code flow is completed.
|
||||
|
||||
The parameters of the Login action specify where the user is redirected after login is complete. If the pageId is not set, the user is redirected to the homepage. The parameters are:
|
||||
- `authUrlQueryParams: object`: Query parameters to set for the authorization URL.
|
||||
- `pageId: string`: The pageId of the page to redirect to after the login flow is complete
|
||||
- `input: object`: The input to set for the page the user is redirected to after login.
|
||||
- `urlQuery: object`: The urlQuery to set for the page the user is redirected to after login.
|
||||
|
||||
#### Examples
|
||||
|
||||
###### A login page that redirects users in the onEnter event:
|
||||
```yaml
|
||||
id: login
|
||||
type: Context
|
||||
events:
|
||||
onEnter:
|
||||
# Redirect to "page1" if user is already logged in.
|
||||
- id: logged_in_redirect
|
||||
type: Link
|
||||
skip:
|
||||
_eq:
|
||||
- _user: sub
|
||||
- null
|
||||
params: page1
|
||||
# Call the Login action to log the user in.
|
||||
- id: login
|
||||
type: Login
|
||||
skip:
|
||||
_ne:
|
||||
- _user: sub
|
||||
- null
|
||||
params:
|
||||
# Redirect to "page1" after login is complete.
|
||||
pageId: page1
|
||||
```
|
||||
|
||||
###### A set of login and logout buttons:
|
||||
```yaml
|
||||
id: login_logout
|
||||
type: Box
|
||||
blocks:
|
||||
- id: Login
|
||||
type: Button
|
||||
visible:
|
||||
_eq:
|
||||
- _user: sub
|
||||
- null
|
||||
events:
|
||||
onClick:
|
||||
- id: login
|
||||
type: Login
|
||||
- id: Logout
|
||||
type: Button
|
||||
visible:
|
||||
_ne:
|
||||
- _user: sub
|
||||
- null
|
||||
events:
|
||||
onClick:
|
||||
- id: logout
|
||||
type: Logout
|
||||
```
|
||||
|
||||
###### A signup button that uses authUrlQueryParams to request the signup screen:
|
||||
```yaml
|
||||
id: Signup
|
||||
type: Button
|
||||
events:
|
||||
onClick:
|
||||
- id: login
|
||||
type: Login
|
||||
params:
|
||||
authUrlQueryParams:
|
||||
screen_hint: signup
|
||||
```
|
||||
|
||||
## Logout
|
||||
|
||||
When the `Logout` action is called, the user data and authorization cookie are cleared by the app. The `Logout` action does not take any parameters. The user is then redirected to the URL configured in `logoutRedirectUri`, or the app homepage if this is not configured.
|
||||
|
||||
Some OpenID Connect providers provide a URL that the user can be directed to to logout the user from the the provider. These urls normally have a query parameter that specifies where the provider should redirect the user after they have logged out the user. These redirect URLs are normally configured with the provider.
|
||||
|
||||
The logoutRedirectUri can be a [Nunjucks](https://mozilla.github.io/nunjucks/) template string, with the following template variables:
|
||||
- `client_id`: The OpenID Connect client ID in `LOWDEFY_SECRET_OPENID_CLIENT_ID`
|
||||
- `host`: The app host URL. This url includes the URL prefix (`https://` or `http://` if running a development server), and is URI encoded. It is intended to be used as a query parameter.
|
||||
- `id_token_hint`: The user idToken.
|
||||
- `openid_domain`: The OpenID Connect client ID in `LOWDEFY_SECRET_OPENID_DOMAIN`.
|
||||
|
||||
#### Examples
|
||||
|
||||
###### Redirect to the `logged-out` page in the app after logout:
|
||||
```yaml
|
||||
config:
|
||||
auth:
|
||||
openId:
|
||||
logoutRedirectUri: '/logged-out'
|
||||
```
|
||||
|
||||
###### Redirect to the Auth0 logout URL and return to the `logged-out` page in the app after logout:
|
||||
```yaml
|
||||
config:
|
||||
auth:
|
||||
openId:
|
||||
# Line breaks added for clarity
|
||||
logoutRedirectUri: "{{ openid_domain }}/v2/logout?\
|
||||
returnTo={{ host }}/logged-out&\
|
||||
client_id={{ client_id }}"
|
||||
```
|
||||
|
||||
###### Redirect to the Keycloak logout URL and return to the `logged-out` page in the app after logout:
|
||||
```yaml
|
||||
config:
|
||||
auth:
|
||||
openId:
|
||||
# Line breaks added for clarity
|
||||
logoutRedirectUri: "{{ openid_domain }}/protocol/openid-connect/logout?\
|
||||
post_logout_redirect_uri={{ host }}/logged-out&\
|
||||
client_id={{ client_id }}&\
|
||||
id_token_hint={{ id_token_hint }}"
|
||||
```
|
||||
|
||||
- _ref:
|
||||
path: templates/navigation_buttons.yaml
|
||||
vars:
|
||||
previous_page_title: OpenID Connect
|
||||
previous_page_id: openid-connect
|
||||
next_page_title: Protected pages
|
||||
next_page_id: protected-pages
|
||||
83
packages/docs/users/openid-connect.yaml
Normal file
83
packages/docs/users/openid-connect.yaml
Normal file
@ -0,0 +1,83 @@
|
||||
# Copyright 2020-2021 Lowdefy, Inc
|
||||
|
||||
# Licensed under the Apache License, Version 2.0 (the "License");
|
||||
# you may not use this file except in compliance with the License.
|
||||
# You may obtain a copy of the License at
|
||||
|
||||
# http://www.apache.org/licenses/LICENSE-2.0
|
||||
|
||||
# Unless required by applicable law or agreed to in writing, software
|
||||
# distributed under the License is distributed on an "AS IS" BASIS,
|
||||
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
# See the License for the specific language governing permissions and
|
||||
# limitations under the License.
|
||||
|
||||
_ref:
|
||||
path: templates/general.yaml.njk
|
||||
vars:
|
||||
pageId: openid-connect
|
||||
pageTitle: OpenID Connect
|
||||
section: User Authentication
|
||||
filePath: users/openid-connect.yaml
|
||||
content:
|
||||
- id: open_id_connect_content
|
||||
type: MarkdownWithCode
|
||||
properties:
|
||||
content: |
|
||||
Lowdefy supports the OpenID Connect standard as a user authorization mechanism. This means to add users to your app, you should setup a OpenID Connect provider. Some popular providers are:
|
||||
|
||||
- [Auth0](https://auth0.com)
|
||||
- [Gluu](https://gluu.org)
|
||||
- [Keycloak](https://www.keycloak.org)
|
||||
- [Microsoft identity platform](https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-overview) (Active Directory)
|
||||
- [Okta](https://www.okta.com)
|
||||
- [Ory Hydra](https://www.ory.sh)
|
||||
- [Ping Identity](https://www.pingidentity.com)
|
||||
- [Sign In With Google](https://developers.google.com/identity)
|
||||
|
||||
A full list of OpenID Connect providers can be found [here](https://openid.net/developers/certified/).
|
||||
|
||||
## Configuring an OpenID Connect provider
|
||||
|
||||
To configure an OpenID Connect provider, you need to set the following lowdefy [secrets](/secrets): `OPENID_CLIENT_ID`, `OPENID_CLIENT_SECRET`, `OPENID_DOMAIN`, and `JWT_SECRET`. The can be set by setting the following environment variables:
|
||||
```
|
||||
LOWDEFY_SECRET_OPENID_CLIENT_ID = YOUR_CLIENT_ID
|
||||
LOWDEFY_SECRET_OPENID_CLIENT_SECRET = YOUR_CLIENT_SECRET
|
||||
LOWDEFY_SECRET_OPENID_DOMAIN = YOUR_OPENID_DOMAIN
|
||||
LOWDEFY_SECRET_JWT_SECRET = YOUR_SECRET_KEY
|
||||
```
|
||||
|
||||
See the section on JSON Web Tokens below for information about the `JWT_SECRET`.
|
||||
|
||||
If these are not set, the `Login` and `Logout` actions won't work, so users won't be able to log in. However, protected pages will not be served to public users.
|
||||
|
||||
Optional configuration can also be set in the Lowdefy configuration, at the path `config.auth.openId`. The following fields can be set:
|
||||
|
||||
- `scope: string`: _Optional_ - The OpenID Connect scope to request. The default is `openid profile email`. Should contain at least `openid`.
|
||||
- `logoutRedirectUri: string`: _Optional_ - The URL to redirect to after logout. See more [here](/login-and-logout).
|
||||
|
||||
|
||||
Details to configure specific OpenID Connect providers are given [here](/openid-example-configurations).
|
||||
|
||||
# JSON Web Tokens
|
||||
|
||||
The app will use the `JWT_SECRET` to sign the JSON web tokens (with HS256) used to authorize users. This secret should be a long randomly generated string.
|
||||
|
||||
You can run the following command in the command console to generate the key:
|
||||
```bash
|
||||
node -e "console.log(require('crypto').randomBytes(256).toString('base64'));"
|
||||
```
|
||||
|
||||
We recommend using a different key in your development and production environments.
|
||||
|
||||
Optional configuration can also be set in the Lowdefy configuration, at the path `config.auth.jwt`. The following fields can be set:
|
||||
|
||||
- `expiresIn: string | number`: The length of time a user token should be valid. The default is 4 hours. Can be expressed as a number in seconds, or a [vercel/ms string](https://github.com/vercel/ms).
|
||||
|
||||
- _ref:
|
||||
path: templates/navigation_buttons.yaml
|
||||
vars:
|
||||
previous_page_title: Introduction
|
||||
previous_page_id: introduction
|
||||
next_page_title: Login and Logout
|
||||
next_page_id: login-and-logout
|
||||
51
packages/docs/users/users-introduction.yaml
Normal file
51
packages/docs/users/users-introduction.yaml
Normal file
@ -0,0 +1,51 @@
|
||||
# Copyright 2020-2021 Lowdefy, Inc
|
||||
|
||||
# Licensed under the Apache License, Version 2.0 (the "License");
|
||||
# you may not use this file except in compliance with the License.
|
||||
# You may obtain a copy of the License at
|
||||
|
||||
# http://www.apache.org/licenses/LICENSE-2.0
|
||||
|
||||
# Unless required by applicable law or agreed to in writing, software
|
||||
# distributed under the License is distributed on an "AS IS" BASIS,
|
||||
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
# See the License for the specific language governing permissions and
|
||||
# limitations under the License.
|
||||
|
||||
_ref:
|
||||
path: templates/general.yaml.njk
|
||||
vars:
|
||||
pageId: users-introduction
|
||||
pageTitle: Introduction
|
||||
section: User Authentication
|
||||
filePath: concepts/users-introduction.yaml
|
||||
content:
|
||||
- id: introduction
|
||||
type: Markdown
|
||||
properties:
|
||||
content: |
|
||||
To add users to a Lowdefy app, you need to do the following:
|
||||
- Configure an OpenID Connect provider
|
||||
- Configure which pages should be public and protected (only available to logged in users).
|
||||
- Add the `Login` and `Logout` actions to your app, to allow users to log in and out.
|
||||
|
||||
Optionally, you can also:
|
||||
- Use role based authorization to make certain pages available only to users with the correct roles.
|
||||
|
||||
An example app implementing OpenID Connect can be found [here](https://github.com/lowdefy/lowdefy-example-openid-connect).
|
||||
|
||||
- id: jwt_session_warning
|
||||
type: Alert
|
||||
properties:
|
||||
type: warning
|
||||
icon: WarningFilled
|
||||
message: Stateful JSON Web Tokens are used for authentication
|
||||
description: Lowdefy uses stateful JSON Web Tokens for user authentication, since the Lowdefy server is stateless and does not maintain a database of user sessions. This means that once a token is issued, it is valid until the token expires. Any changes to the user's access will only reflect after the token has expired, and the user obtains (or fails to obtain) a new token from the OpenID Connect provider. We recommend making sure tokens have a relatively short expiry time (the default is 4 hours), and evaluating if the security provided by this system is appropriate for your use case.
|
||||
|
||||
- _ref:
|
||||
path: templates/navigation_buttons.yaml
|
||||
vars:
|
||||
previous_page_title: Overview
|
||||
previous_page_id: overview
|
||||
next_page_title: OpenID Connect
|
||||
next_page_id: openid-connect
|
||||
Loading…
x
Reference in New Issue
Block a user