GitHub - wuyunhua1987/koa2-oauth2-server-demo: oauth2-server demo with koa2

本文是一篇新手教程，目的是提供一个有效的指引，让初次接触OAuth2的同学快速掌握关键信息，快速实现功能，本文不会涉及原理、源码

什么是OAuth2

关于OAuth2的解释，网络上相关文章100%会写，有详细的，有简短的，但是很多新手不明白什么是协议，协议意味着什么？

OAuth2协议强制要求你怎么做，你不能有自己的想法。请求必须是xxx，返回必须是xxx，步骤必须是xxx。因为都被强制了，张三的实现和李四的实现，接口必然完全一样。node的实现和php的实现，接口必然完全一样。

要想掌握OAuth2，必须看完这份协议RFC6749，这里有一份中文版的RFC6749

oauth2-server包

oauth2-server是OAuth2协议nodejs的实现

他是OAuth2协议的完整实现，他提供了3个接口供我们使用，同时他要求我们必须告诉他token是怎么存储的。文档里详细描述

他用来辅助你实现授权和认证的具体功能，你可以在任何nodejs框架中使用，也可以选择任意的后端存储

他不是用来做注册登录的，也不是用来替代jwt的

使用Koa和oauth2-server实现授权码流程

我们完全按照RFC6749规定的流程来做。

 +--------+                               +---------------+
 |        |--(A)- Authorization Request ->|   Resource    |
 |        |                               |     Owner     |
 |        |<-(B)-- Authorization Grant ---|               |
 |        |                               +---------------+
 |        |
 |        |                               +---------------+
 |        |--(C)-- Authorization Grant -->| Authorization |
 | Client |                               |     Server    |
 |        |<-(D)----- Access Token -------|               |
 |        |                               +---------------+
 |        |
 |        |                               +---------------+
 |        |--(E)----- Access Token ------>|    Resource   |
 |        |                               |     Server    |
 |        |<-(F)--- Protected Resource ---|               |
 +--------+                               +---------------+

                Figure 1: Abstract Protocol Flow

A是第三方应用询问Resource Owner是否授权，举个例子，第三方app选择微信登录的时候，跳转到微信，询问是否授权登录
B是Resource Owner同意授权，回调第三方应用，同时附上code
C是第三方应用收到回调后，带着code，去找Authorization Server，换取token
D是Authorization Server验证code通过后，返回第三方应用一个token
E是第三方应用拿着token去Resource Server请求资源，举个例子，微信API里获取用户头像昵称，API要求token验证
F是Resource Server验证token通过后，返回给第三方应用程序资源，比如头像昵称

一、搭建三个http服务器，分别作为第三方应用、授权服务器、资源服务器

mkdir koa2-oauth2-server & cd koa2-oauth2-server
yarn init
yarn add koa koa-router koa-bodyparser oauth2-server jsonwebtoken

编辑package.json，加上入口scripts

// ...
"scripts": {
  "auth": "node ./auth",
  "app":  "node ./app",
  "api": "node ./api"
}

// app/index.js the third app http server 3001
const Koa = require('koa')
const bodyParser = require('koa-bodyparser');
const Router = require('koa-router')

const app = new Koa();
app.use(bodyParser());

var router = new Router();

router.get('/hello', async(ctx) => {
    ctx.body = 'hello app'
});

app.use(router.routes()).use(router.allowedMethods());

app.listen('3001');

// auth/index.js the authorize http server 3002
const Koa = require('koa')
const OAuth2 = require('oauth2-server')
const bodyParser = require('koa-bodyparser');
const Router = require('koa-router')

const app = new Koa();
app.use(bodyParser());

var router = new Router();

router.get('/hello', async(ctx) => {
    ctx.body = 'hello auth'
});

app.use(router.routes()).use(router.allowedMethods());

app.listen('3002');

// api/index.js the resource http server 3003
const Koa = require('koa')
const bodyParser = require('koa-bodyparser');
const Router = require('koa-router')

const app = new Koa();
app.use(bodyParser());

var router = new Router();

router.get('/hello', async(ctx) => {
    ctx.body = 'hello api'
});

app.use(router.routes()).use(router.allowedMethods());

app.listen('3003');

二、第三方app应用请求授权（步骤A）

根据RFC6749协议中的规定，第三方请求授权必须满足以下条件

请求授权服务器授权uri的规定，需要提供以下参数

response_type 必需我们这里是code
client_id 必需客户端标识
redirect_uri 可选的成功后重定向uri
scope 可选的申请范围
state 必需客户端用于维护请求和回调之间状态的值

如果resource owner允许授权，要求返回302重定向，重定向到redirect_uri，并带上以下数据:

code 必需授权服务器生成的授权码
state 必需请求中携带的状态值

如果resource owner不允许访问，或者出现其他错误，要求返回302重定向，并重定向到redirect_uri，并带上以下数据:

error 必需
- invalid_request 请求缺少必需的参数、包含无效的参数值、包含一个参数超过一次或其他不良格式
- unauthorized_client 客户端未被授权使用此方法请求授权码
- access_denied 资源所有者或授权服务器拒绝该请求
- unsupported_response_type 授权服务器不支持使用此方法获得授权码
- invalid_scope 请求的范围无效，未知的或格式不正确
- server_error 授权服务器遇到意外情况导致其无法执行该请求
- temporarily_unavailable 授权服务器由于暂时超载或服务器维护目前无法处理请求
error_description 可选提供额外信息的人类可读的信息
error_uri 可选指向带有有关错误的信息的人类可读网页的URI
state 必需请求中携带的状态值

一个请求授权例子：

GET http://localhost:3002/authorize?response_type=code&client_id=client&state=xyz&redirect_uri=http://localhost:3001/callback HTTP/1.1
Content-Type: application/x-www-form-urlencoded

接下来我们来写代码实现协议，修改auth/index.js。oauth2-server包提供了3个方法给我们使用，这里会用到oauth.authorize()，他的文档在这里

// 省略...
const { Request, Response, UnauthorizedRequestError } = require('oauth2-server')
// 省略...
const oauth = new OAuth2({
    model: require('./model')
})
app.context.oauth = oauth;

router.get('/authorize', async(ctx, next) => {
    // 构造oauth2-server的request、response
    const request = new Request(ctx.request);
    const response = new Response(ctx.response);

    try {
        // 调用oauth2-server的authorize生成code
        ctx.state.oauth = {
            code: await ctx.oauth.authorize(request, response)
        };
        // 使用oauth2-server的response
        ctx.body = response.body;
        ctx.status = response.status;

        ctx.set(response.headers);
    } catch (e) {
        if (e instanceof UnauthorizedRequestError) {
            ctx.status = e.code;
        } else {
            ctx.body = { error: e.name, error_description: e.message };
            ctx.status = e.code;
        }

        return ctx.app.emit('error', e, ctx);
    }
})
// 省略...

oauth2-server要求我们提供存储的具体实现，我们写一个model.js，先什么都不写

// auth/model.js oauth2-server的存储实现
module.exports = {
    // 先什么都不写，看看会发生什么
}

运行以下yarn run auth

接下来我们编写app部分的代码，先编写一个按钮用于发起授权请求，再编写一个callback用于授权回调

// app/index.js
// 省略...
router.get('/login', async(ctx) => {
    // uri必需这么写,client_id先随便写一个，redirect_uri写callback
    ctx.body = '<a href="http://localhost:3002/authorize?response_type=code&client_id=client&state=xyz&redirect_uri=http://localhost:3001/callback">授权</a>'
});

router.get('/callback', async(ctx) => {
    // 输出code
    ctx.body = ctx.query.code
});
// 省略...

运行appyarn run app，打开浏览器，输入http://localhost:3001/login，点击授权链接，观察页面。不出意外将会看到这样的结果：

{
    error: "invalid_argument",
    error_description: "Invalid argument: model does not implement `getClient()`"
}

注意：这里的错误是授权服务器发出的，并不是授权回调后展示的错误

这个错误提示很明显了，auth2-server要求的model，必需要实现getClient()方法，我们先查看文档看看这个方法是干啥的，他的文档在这里

这个方法要求实现如何根据client_id/client_secret得到client object，具体一点就是根据clientId、clientSecret去存储里找到到client对象，参数和返回文档已经给了，我们来实现一下，这里使用内存存储实现

// auth/model.js 实现getClient
module.exports = {
    async getClient(clientId, clientSecret) {
        return {
            id: 'client',
            redirectUris: ['http://localhost:3001/callback'],
            grants: ['authorization_code']
        };
    }
}

为了演示，直接写死了，真实业务中，是会先注册clientId/clientSecret到数据库里，这里检索出来即可

重新运行auth服务yarn run auth，再操作一次点击授权，观察页面。不出意外会看到这样的结果：

{
    error: "invalid_argument",
    error_description: "Invalid argument: model does not implement `saveAuthorizationCode()`"
}

有了之前的经验，很明显这里需要我们实现saveAuthorizationCode()，阅读oauth2-server文档，我们实现一下：

// auth/model.js 实现saveAuthorizationCode()
async saveAuthorizationCode(code, client, user) {
    return {
        authorizationCode: code.authorizationCode,
        expiresAt: code.expiresAt,
        redirectUri: code.redirectUri,
        scope: code.scope,
        client: { id: client.id },
        user: { id: user.id }
    };
}

为了演示，直接写死了，真实业务中，需要把这些数据保存到数据库中，否则后续无法判断是否已使用，无法判断是否已失效

重新运行yarn run auth，重复上一步操作，观察页面，提示缺少getAccessToken()的实现，根据文档实现一下：

// auth/model.js 实现getAccessToken()
async getAccessToken(accessToken) {
    return {
        accessToken: 'dddd',
        accessTokenExpiresAt: new Date(2020, 09, 01, 10, 10, 10),
        scope: '1',
        client: { id: 'client' },
        user: { id: 1 }
    };
}

为了演示，直接写死了，真实业务中，需要根据accessToken去数据库里查寻token对象

重新运行yarn run auth，重复上一步操作，观察页面，这次不再提示缺少xxx方法的实现了，而是提示Unauthorized，并且返回的http状态码是401，说明未登录，怎么回事呢？

因为没有登录授权服务器，授权服务器并不知道resource owner是谁，就无法询问。真实业务中，这里发现401，就需要弹出登录界面，先让用户完成登录。之后再询问用户是否授权，选择授权范围，再带上access_token重新请求授权

我们先绕过这一步，后面再完善，在请求URL后面加上access_token=1，使得请求合规，后续的验证身份环节，需要在auth/model.js的getAccessToken()方法中验证身份，但我们不处理，这样不论access_token是什么总是能通过身份认证

// app/index.js 
// 省略...
router.get('/login', async(ctx) => {
    ctx.body = '<a href="http://localhost:3002/authorize?response_type=code&client_id=client&state=xyz&redirect_uri=http://localhost:3001/callback&access_token=1">授权</a>'
})
// 省略...

为了允许uri query携带access_token参数，我们需要修改一下auth/index.js代码

// auth/index.js allow token in query string
// 省略...
const oauth = new OAuth2({
    model: require('./model'),
    allowBearerTokensInQueryString: true,
    accessTokenLifetime: 4 * 60 * 60
})
// 省略...

重新运行yarn run auth & yarn run app，重复上一步操作，观察页面。不出意外会看到重定向，http://localhost:3001/callback?code=ae4354425c3a3bb75ef5e969a19ebd304a0736ef&state=xyz

步骤B成功了，拿到了code，下一步，我们用code换取通行证token

三、第三方app应用换取token（步骤C）

上一步我们在/callback里拿到了code，接下来要用code去授权服务器换取token，根据RFC6749协议中的规定，第三方请求获取token必须满足以下条件

请求授权服务器获取token uri的规定，需要提供以下参数

grant_type 必需这里必须设置为authorization_code
code 必需从授权服务器拿到的code
redirect_uri 必需上一步中redirect_uri，必须完全一样
client_id 必需客户端id
client_secret 必需客户端secret

请求类型必须是post，content-type必须是application/x-www-form-urlencoded，例如

POST http://localhost:3002/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer 1

grant_type=authorization_code&code=2d6d7da2ed7c405ade522ced89a875bc2b65c8e1&client_id=client&client_secret=secret&redirect_uri=http://localhost:3002/callback

注意：一般情况下，这一步请求需要在服务器里完成，避免在客户端完成，因为涉及client_secret，避免泄露

请求成功的返回必须是这样子的

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
  "access_token":"2YotnFZFEjr1zCsicMWpAA",
  "token_type":"example",
  "expires_in":3600,
  "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
  "example_parameter":"example_value"
}

我们编写一个/token的uri来实现换取token功能

// auth/index.js 
// 省略...
router.post('/token', async(ctx) => {
    const request = new Request(ctx.request);
    const response = new Response(ctx.response);
    try {
        // 调用oauth2-server的token()生成token
        ctx.state.oauth = {
            token: await ctx.oauth.token(request, response)
        };

        // 使用oauth2-server的response
        ctx.body = response.body;
        ctx.status = response.status;

        ctx.set(response.headers);
    } catch (e) {
        if (e instanceof UnauthorizedRequestError) {
            ctx.status = e.code;
        } else {
            ctx.body = { error: e.name, error_description: e.message };
            ctx.status = e.code;
        }

        return ctx.app.emit('error', e, ctx);
    }
})
// 省略...

接下来我们在app里请求授权服务器换取token

// app/index.js
const axios = require('axios');
// 省略...
router.get('/callback', async(ctx) => {
    const code = ctx.query.code;
    const res = await axios({
        url: 'http://localhost:3002/token',
        method: 'POST',
        headers: { 'content-type': 'application/x-www-form-urlencoded' },
        data: `grant_type=authorization_code&code=${code}&client_id=client&client_secret=secret&redirect_uri=http://localhost:3002/callback`
    });
    console.log(res.data);
    ctx.body = "ok"
});
// 省略...

axios是node中httpclient库，记得yarn add axios

现在重启一下，yarn run auth & yarn run app，重复上一步中的授权，页面显示Internal Server Error，看一下终端给出的异常信息：invalid_argument: Invalid argument: model does not implement getAuthorizationCode()

很明显，需要继续实现model.js里的方法，参考文档，补充方法，重复上述步骤，依次实现revokeAuthorizationCode()、saveToken()

// auth/model.js
// 省略...
async getAuthorizationCode(code) {
    return {
        code: code,
        expiresAt: new Date(2020, 9, 1, 0, 0, 0),
        redirectUri: 'http://localhost:3002/callback',
        scope: '1',
        client: { id: 'client' },
        user: { id: 1 }
    };
},
async revokeAuthorizationCode(code) {
    return true
},
async saveToken(token, client, user) {
    return {
        accessToken: token.accessToken,
        accessTokenExpiresAt: token.accessTokenExpiresAt,
        refreshToken: token.accessToken,
        refreshTokenExpiresAt: token.refreshTokenExpiresAt,
        scope: token.scope,
        client: client,
        user: user
    };
},
// 省略...

重新运行yarn run auth，不出意外会看到200 ok，观察终端，会发现授权服务器返回了token给我们：

{
    access_token: "e1062fc1a93d9b86231090a7ca2b221dd0eb7d8a",
    token_type: "Bearer",
    expires_in: 14399,
    refresh_token: "e1062fc1a93d9b86231090a7ca2b221dd0eb7d8a",
    scope: "1"
}

步骤D成功了，拿到了token，下一步，我们用token获取资源

四、从API服务器获取数据（步骤E）

上一步我们拿到了通行证token，我们试一下从API服务器获取用户数据，资源都是受保护的，我们写一个中间件用来做用户身份验证，验证方法使用oauth2-server提供的authenticate方法，这个方法要求必须实现getAccessToken()方法，我们在这个方法里面决定他是否通过身份验证，如果通过返回固定格式，如果没通过，抛出UnauthorizedRequestError异常，具体实现如下：

// api/index.js
const OAuth2 = require('oauth2-server')
const { Request, Response, UnauthorizedRequestError } = require('oauth2-server')
const oauth = new OAuth2({
    model: {
        async getAccessToken(accessToken) {
            // 省略验证过程，如果没通过，取消下面这行的注释
            //throw new UnauthorizedRequestError('token invaild')
            return {
                accessToken: 'dddd',
                accessTokenExpiresAt: new Date(2020, 9, 1, 0, 0, 0),
                scope: '1',
                client: { id: 'client' },
                user: { id: 1 }
            };
        }
    },
    allowBearerTokensInQueryString: true,
    accessTokenLifetime: 4 * 60 * 60
})
app.context.oauth = oauth;

app.use(async(ctx, next) => {
    const request = new Request(ctx.request);
    const response = new Response(ctx.response);
    try {
        ctx.state.oauth = {
            token: await ctx.oauth.authenticate(request, response)
        };
        await next();
    } catch (e) {
        if (e instanceof UnauthorizedRequestError) {
            ctx.status = e.code;
        } else {
            ctx.body = { error: e.name, error_description: e.message };
            ctx.status = e.code;
        }
    }
});

// 获取资源，如果如果通过了中间件的身份验证，这里就能拿到userid
router.get('/user', async(ctx, next) => {
    const { user, client } = ctx.state.oauth.token
    ctx.body = { user, client }
});

为了演示，没有写具体如何验证的，真实业务中可以使用数据库验证，也可以使用jwt验证

加下来就可以在app中请求API了，改一下callback方法

// app/index.js
router.get('/callback', async(ctx) => {
    const code = ctx.query.code;
    const res = await axios({
        url: 'http://localhost:3002/token',
        method: 'POST',
        headers: { 'content-type': 'application/x-www-form-urlencoded' },
        data: `grant_type=authorization_code&code=${code}&client_id=client&client_secret=secret&redirect_uri=http://localhost:3002/callback`
    });
    // 带上token去请求资源
    const access_token = res.data.access_token
    try {
        const user = await axios.get(`http://localhost:3003/user?access_token=${access_token}`)
        ctx.body = user.data
    } catch (e) {
        ctx.body = { error_description: e.message };
        ctx.status = e.response.status;
    }
});

重启app和api服务器，yarn run app & yarn run api，重复第一步的授权，不出意外我们将会看到如下json:

{
    user: {
        id: 1
    },
    client: {
        id: "client"
    }
}

步骤F成功了，拿到了受保护的资源，并且API服务器知道是来自哪个client，哪个user

总结

本文首先阐述实现OAuth2的关键点是RFC6749，很多文章上来就讲什么是OAuth2却不提RFC6749，这会误导新手，即使知道了原理，还是不知道请求的参数应该填什么。

其次，我们使用node的包oauth2-server来实现了一遍授权码验证过程，这个过程要始终围绕RFC6749，否则流程很难走通，自然无法实现model。

最后，写这篇文章的缘由是我发现网络上关于oauth2-server的koa实现非常非常少，即使有，也没有提供代码，所以就有了这篇文章，源码在github/gitee上，希望大家能有所收获。

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
api		api
app		app
auth		auth
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
package.json		package.json
yarn.lock		yarn.lock

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

什么是OAuth2

oauth2-server包

使用Koa和oauth2-server实现授权码流程

一、搭建三个http服务器，分别作为第三方应用、授权服务器、资源服务器

二、第三方app应用请求授权（步骤A）

三、第三方app应用换取token（步骤C）

四、从API服务器获取数据（步骤E）

总结

About

Releases

Packages

Languages

License

wuyunhua1987/koa2-oauth2-server-demo

Folders and files

Latest commit

History

Repository files navigation

什么是OAuth2

oauth2-server包

使用Koa和oauth2-server实现授权码流程

一、搭建三个http服务器，分别作为第三方应用、授权服务器、资源服务器

二、第三方app应用请求授权（步骤A）

三、第三方app应用换取token（步骤C）

四、从API服务器获取数据（步骤E）

总结

About

Resources

License

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages