为知笔记私有部署单点登录开发帮助

2/23/2021

为知笔记私有部署服务支持单点登录,您只需要进行简单的开发,就可以在您自己的OA系统里面,加入为知笔记链接,并可以让您的OA用户自动登录,而无需输入密码。

开启SSO功能

请使用管理员身份登录为知笔记,并点击头像,进入系统设置,在OAuth里面,开启单点登录功能。 开启单点登录功能后,您将会看到clientId和clientSecret。注意,clientSecret必须保密,只能在您的服务器上面使用,而不能泄漏出来,或者在客户端/浏览器使用。

您还可以设置是否允许自动创建账号。如果不允许,用户必须先以OA里面的email创建账号,然后才可以使用。如果允许自动创建账号,在用户第一次使用的时候,会自动创建账号。

利用这个功能,同时在系统管理里面,禁止账号注册,就可以避免用户自行创建账号,而必须从您的OA里面进行登录。

获取Access Token

下面是nodejs例子:


const API_URL = 'http://192.168.1.100'; //为知笔记服务器地址

// TODO: 替换成自己服务器的设置
const OAUTH_SETTINGS = {
  clientId: 'xxx',
  clientSecret: 'xxx',
};

async function getAccessToken() {
  //
  const {clientId, clientSecret} = OAUTH_SETTINGS;
  const url = `${API_URL}/as/oauth/token?clientId=${clientId}&clientSecret=${clientSecret}`;
  const response = await axios.get(url);
  const {data} = response;
  if (!data || data.returnCode != 200) {
    console.error(response);
    throw new Error('failed to get token');
  }
  return data.result.accessToken;
}

获取用户的登录Url

通过userId (email)获取用户登录的Url,通过该Url,用户可以直接登录到为知笔记。 如果当前用户不存在,并且设置了自动创建账户,则为知笔记将会自动根据当前用户email,创建一个新的用户,并引导用户登录到网页版。如果没有设置设置自动创建账户,则会报告错误。

注意:通过这种方式获取的链接,仅在1分钟内有效,并且只能使用一次。因此,您应该在您的页面内,使用AJAX方式,动态获取Url,然后通过window.open等方式,在浏览器内打开这个链接。

同时,您的服务器程序应该在获取Url的时候,检测当前用户身份。


async function getLoginUrl(userId) { //userId must be email
  const accessToken = await getAccessToken();
  const url = `${API_URL}/as/oauth/service/login_url?accessToken=${accessToken}&userId=${userId}`;
  //
  const response = await axios.get(url);
  const {data} = response;
  if (!data || data.returnCode != 200) {
    console.error(response);
    throw new Error('failed to get login url');
  }
  const loginUrl = data.result;  
  return loginUrl;
}

注意

在生成用户登录Url的时候,您必须先验证当前您的OA系统的用户身份。如果没有验证身份,就随意生成用户登录Url,可能会造成数据安全问题,用户的数据可能会被恶意访问。

在获取到登录Url之后,可以将Url传递给前端,用户点击该Url之后,将会自动进入为知笔记网页版。

如果您的clientSecret不慎泄漏,您可以在设置里面进行重置。

版本要求

要使用该功能,您的为知笔记服务版本需要等于或高于1.0.7

客户端登录

如果您需要在客户端里面使用单点登录功能,请联系我们的客服。(该功能需要定制开发)。

如果您开启了自动创建账号功能,对于自动创建的账号,密码都是随机生成的。因此自动创建的客户端,如果需要使用客户端,则必须重置密码。

管理员首先在系统管理里面设置smtp服务器

要重置用户密码,管理员必须先在系统管理里面设置smtp服务信息,以便为知笔记可以发送重置密码验证邮件给用户。

  1. 管理员登录为知笔记管理后台
  2. 设置smtp服务器信息。(设置信息后,为知笔记服务会重新启动)

普通用户重置密码并登录为知笔记客户端

  1. 从OA里面自动登录到为知笔记网页版
  2. 点击左上角头像,选择账户
  3. 在账户里面,选择更改密码
  4. 在出现的对话框里面,选择通过email重置密码。
  5. 进入自己的邮箱,选择重置密码,然后自行设置密码,就可以使用客户端登录为知笔记了。

例子

我们提供可一个node.js例子,包含服务端和一个简单的demo网页。

点击这里下载 为知笔记 OAuth 例子