ory/kratos-01-快速入門
快速入門官方英文文檔: Quickstart | ORY Kratos
ORY Kratos 有幾個正在經歷改動的組件,因此從一開始就使所有問題都變得困難。
本入門指南將幫助你安裝 ORY Kratos 和一些其他依賴項,以便你瞭解 ORY Kratos 的工作方式。
請注意,本指南不能代替研究文檔。你必須瞭解核心概念和 API 纔能有效地使用 ORY Kratos。這篇文章僅是入門指導。
用例:你想要登錄並註冊你的應用程序
本節爲你提供了一些有關我們要實現的目標以及爲此所需的工具的背景信息。你還將瞭解我們爲本指南選擇的網絡設置。
本快速入門指南的前提是假設我們正在編寫一個稱爲 SecureApp 的 NodeJS 應用程序。 這個程序沒有花哨的東西僅有一些 ExpressJS 和一些使用 Handlebars 的 HTML 模板。 我們使用 TypeScript,但這只是因爲它更具可讀性,並不是因爲我們在做任何與衆不同的事情!
在 UI 層,你當然可以選擇任何技術。 它可以與 Swift,ReactJS 或 Angular(客戶端)以及 PHP,Ruby,Python,Java(服務器端)或一起使用,總之隨便你怎麼組合。我們之所以選擇 NodeJS + TypeScript,是因爲我們認爲它最容易理解,並且因爲JavaScript 和 NodeJS 被普遍理解並且易於安裝。
我們真的不知道 SecureApp 有一天它會被擴展成什麼樣子。 但是我們確切知道它將具有某種類型的儀表板並且需要用戶,因此我們需要:
- 登錄
- 登出
- 註冊
- 個人資料管理(“更新名字”,“更新頭像…”)
- 憑據管理(“添加新的輔助郵箱”,“更改密碼”,“ …”)
- 帳戶恢復(“密碼重置”)
- 使用Google Authenticator進行兩因素身份驗證
- “使用Google登錄”和“使用GitHub登錄”
當然還有在儀表盤顯示一些信息
- 比如用戶信息:“
你好 {{firstName}} {{lastName}},你的生日在{{Birthday}}!
”。 僅在用戶登錄時可見!
設置
你可能已經知道,ORY Kratos 僅限於 API。 它沒有 UI 或 HTML 模板引擎。 我們將在 NodeJS SecureApp 中實現所有面向用戶的 UI(儀表盤,登錄,註冊…)。
爲了確保沒有未經身份驗證(登錄)的人都無法訪問儀表板,我們可以使用一小段代碼(此處爲 ExpressJS)來執行此操作:
// Import the ORY Kratos SDK. SDKs are available for all popular programming
// languages!
//
// We will add examples for other programming languages here soon!
import { KratosPublicSDK } from '@oryd/kratos-client';
// You can use protect as a middleware for expressJS:
//
// import express from 'express'
// const app = express()
// app.get("/dashboard", needsLogin, dashboard)
//
const needsLogin = (req, res, next) => {
new KratosPublicSDK('https://public.ory-kratos')
.whoami(req)
.then(({ body }) => {
req.user = { session: body };
next();
})
.catch(() => {
res.redirect('/login');
});
};
ORY Kratos不僅是一個API,它還使用Cookie,HTTP重定向,Anti-CSRF令牌等等,因此這些你都不用煩心了!
由於我們的 SecureApp 和 ORY Kratos 需要共享 cookie,爲了使 Anti-CSRF 令牌和登錄會話正常工作,我們將設置轉發請求到 ORY Krato 的 Public API 的路徑。
如果發出了對 https://my-secureap/.ory/kratos/public/self-service/browser/flows/login
的 HTTP 請求,我們會將請求轉發給 https://public.ory-kratos/self-service/browser/flows/login
(像代理一樣) 並將響應通過管道傳遞迴初始 HTTP 請求:
import express from 'express';
import request from 'request';
const app = express();
const pathPrefix = '/.ory/kratos/public';
app.use(pathPrefix + '/', (req, res) => {
const url = 'https://public.ory-kratos' + req.url.replace(pathPrefix, '');
// Uses the request library to forward the request to **ORY Kratos**
req.pipe(request(url, { followRedirect: false })).pipe(res);
});
// ...
// app.get("/dashboard", needsLogin, dashboard)
// ...
ORY Kratos 不附帶管理用戶界面。 你必須自己實現,或選擇 ORY Cloud 產品(待發行)。
在本快速入門中,我們將使用 ORY Kratos CLI(命令行界面)與 ORY Kratos 的管理 API 進行交互。
快速入門還隨附 MailSlurper,這是演示程序用來演示如何進行演示的模擬 SMTP 服務器。 電子郵件驗證有效。
克隆ORY Kratos並運行docker
爲了使該示例正常工作,你將需要在系統上安裝 Git 和 Docker,以及 Docker Compose。 不需要其他依賴項。 在開始之前,請確保 Docker 具有足夠的磁盤空間。
Tips: 本教程使用 Docker-Compose 卷,這些卷據報道已用完磁盤空間。 使用
docker system df
檢查剩餘磁盤空間。 如果卷高於85%的閾值,請在開始之前修剪舊的 Docker 對象!
Tips: 如果遇到構建錯誤(例如,網絡超時),請確保網絡運行正常並再次運行
macke docker
。 如果問題仍然存在,請隨時打開問題。
讓我們克隆 ORY Kratos 並運行 docker-compose:
git clone https://github.com/ory/kratos.git
# or if you have git+ssh set up:
# git clone [email protected]:ory/kratos.git
cd kratos
git checkout v0.3.0-alpha.1
make quickstart
# or if you don't have make installed:
docker pull oryd/kratos:latest-sqlite
docker pull oryd/kratos-selfservice-ui-node:latest
docker-compose -f quickstart.yml -f quickstart-standalone.yml up --build --force-recreate
這可能需要一兩分鐘。
一旦輸出變慢並且日誌表明系統運行正常,就可以開始運行了!
狀況良好的系統將顯示以下內容(消息的順序可能相反):
kratos_1 | time="2020-01-20T14:52:13Z" level=info msg="Starting the admin httpd on: 0.0.0.0:4434"
kratos_1 | time="2020-01-20T14:52:13Z" level=info msg="Starting the public httpd on: 0.0.0.0:4433"
獲得完整功能的系統有兩個重要因素:
- 需要確保端口
4455
、4433
、4434
和4436
空閒。- 確保始終使用
127.0.0.1
作爲主機名,切勿使用localhost
!這很重要,因爲瀏覽器將這兩個視爲單獨的域,因此在設置和使用正確的cookie
時會遇到問題。
你可能會注意到在此示例中未使用任何數據庫。 ORY Kratos 支持 SQLite,PostgreSQL,MySQL 和 CockroachDB 作爲數據庫後端。
爲了快速入門,我們安裝了一個永久捲來存儲 SQLite 數據庫。
以後的指南將解釋如何設置生產系統!
網絡架構
該演示利用了多種服務 Docker 鏡像:
- ORY Kratos
- SecureApp-用 NodeJS 編寫的示例應用程序,用於實現登錄,註冊,註銷,…和儀表板屏幕。
- ORY Kratos可以通過其發送電子郵件的SMTP服務器。我們將使用 MailHog,這是具有簡單 UI 的簡約 SMTP 穿越服務器。
爲了更好地理解所有內容的連接方式,讓我們看一下網絡配置。假設你至少對Docker(組合)網絡的工作方式有一定的瞭解:
如前所述,我們正在將請求代理到 ORY Kratos 的 Public API。
我們這樣做是因爲這樣所有請求都將來自同一主機名。這樣可以避免 Cookie 常見的跨域問題。
用戶執行註冊,註銷,登錄
已經有足夠的理論支持了,是時候讓我們開始下一步了!
讓我們首先嚐試打開儀表板-轉到 http://127.0.0.1:4455/dashboard
。你可能會注意到,你最終將登錄到端點:
SecureApp 的登錄屏幕
查看網絡堆棧,你會看到兩個重定向發生:
SecureApp 的網絡 trace。
因爲在一開始瀏覽器還沒有有效的身份驗證(登錄)會話建立,所以纔有了從 http://127.0.0.1:4445/dashboard
到 http://127.0.0.1:4455/.ory/kratos/public/self-service/browser/flows/login
的首次重定向。
重定向到 某個ORY Kratos API ,記錄瀏覽器應用程序的身份 ID,這裏就是 request 後面的參數 。
ORY Kratos 會進行一些安全檢查,並準備表單數據,然後將瀏覽器重定向到 http://127.0.0.1:4445/auth/login
,並附加一個 ?request =
查詢參數。
然後,/auth/login
(屬於SecureApp)從 ORY Kratos 的 Admin API 中獲取對呈現表單至關重要的數據:
$ curl http://127.0.0.1:4434/self-service/browser/flows/requests/login?request=<request-id>
{
"id": "27aa98bc-a074-418f-96fa-8b8146050209",
"expires_at": "2020-01-20T21:10:12.7365393Z",
"issued_at": "2020-01-20T21:00:12.7365532Z",
"request_url": "http://127.0.0.1:4455/self-service/browser/flows/login",
"methods": {
"password": {
"method": "password",
"config": {
"action": "http://127.0.0.1:4455/.ory/kratos/public/auth/browser/methods/password/login?request=27aa98bc-a074-418f-96fa-8b8146050209",
"method": "POST",
"fields": [
{
"name": "csrf_token",
"type": "hidden",
"required": true,
"value": "Ii8iIEdnn12vVQ2vyz2YaHjmXMUK5eSQgw9pgENGxPjXi1PHC9gOG51x61o2GT9LGvC81ddvmNXYeLvlPxA04g=="
},
{
"name": "identifier",
"type": "text",
"required": true
},
{
"name": "password",
"type": "password",
"required": true
}
]
}
}
}
}
然後將此數據呈現爲 HTML 表單。 此流程也可用於**單頁應用程序(SPA)**和 Angular 或 ReactJS 之類的框架。 有關特定流程(登錄,註冊,註銷等)的更多詳細信息,請轉至概念章節。
讓我們繼續下一個流程-註冊! 單擊“創建帳戶”,這將啓動類似於我們剛剛使用的流程:
到目前爲止,網絡重定向看起來很熟悉:
如果我們嘗試使用 123456
這樣的密碼進行註冊,那麼 ORY Kratos 的密碼策略將會拒絕:
錯誤消息直接來自ORY Kratos 的 API:
$ curl http://127.0.0.1:4434/self-service/browser/flows/requests/registration?request=<request-id>
{
"id": "79349cbd-c785-476a-8db8-d0d71c5b003c",
"expires_at": "2020-01-20T21:17:00.5077381Z",
"issued_at": "2020-01-20T21:07:00.5077527Z",
"request_url": "http://127.0.0.1:4455/self-service/browser/flows/registration",
"methods": {
"password": {
"method": "password",
"config": {
"action": "http://127.0.0.1:4455/.ory/kratos/public/auth/browser/methods/password/registration?request=79349cbd-c785-476a-8db8-d0d71c5b003c",
"method": "POST",
"fields": [
{
"name": "csrf_token",
"type": "hidden",
"required": true,
"value": "+ZQ8x5cVgdtt4xtPIRJXQPKMVU5c/S2Mj2MuudP32vsMME0g26oQnV/H/brcNvBjkJq1XoF3UcnUFPzcr6Eq4Q=="
},
{
"name": "password",
"type": "password",
"required": true
},
{
"name": "traits.email",
"type": "text",
"value": "[email protected]"
},
{
"name": "traits.full_name",
"type": "text"
}
]
}
}
}
}
設置不違反這些策略的密碼,我們將立即重定向到儀表板:
通過使用“註銷”,你將再次被重定向到登錄屏幕,並且將能夠使用剛剛設置的登錄憑據!
瞭解登錄和註冊的工作方式
請轉到自助服務流程一章,深入瞭解各個流程的工作原理。
電子郵件驗證
在你註冊後,一封電子郵件已發送到你使用的電子郵件地址。 因爲快速入門使用了僞造的 SMTP 服務器,所以電子郵件沒有到達你的收件箱。 但是,你可以通過在 127.0.0.1:4436
打開 MailSlurper UI 來檢索電子郵件。
你應該會看到以下內容:
如果不是,請硬刷新選項卡或單擊菜單欄中的主頁圖標。
接下來,點擊驗證鏈接。
你最終將在儀表板中獲得一個經過驗證的電子郵件地址(請檢查 JSON Payload 中的 authenticated
和 authenticated_at
字段):
要重新請求驗證電子郵件,請填寫表格 127.0.0.1:4455/verify
。
使用的配置
你可以在 ./contrib/quickstart
和 ./quickstart.yml
中找到此快速入門指南的所有配置文件。 要了解每個單獨的配置文件的功能,必須查閱本文檔的其他章節。
要運行 ORY Kratos 的最低版本,你需要設置配置項
identity.traits.default_schema_url
和dsn
。 你還應該配置urls.*_ui
,因爲否則你的用戶將以回退狀態結束。
將來,本指南將支持更多用例,例如:
- 使用 GitHub 登錄並註冊
清理Docker
最後,要清理所有內容,需要關閉 Docker Compose 環境並刪除所有已安裝的卷。
docker-compose -f quickstart.yml down -v
docker-compose -f quickstart.yml rm -f -s -v