@0xgw/passport-forcedotcom 中文文档教程
passport-forcedotcom
这是与 PassportJS 一起使用的策略 Force.com 平台(意味着您可以将它与 Saleforce CRM 一起使用,您的 Force.com 应用程序和 Database.com)。
请注意,从 0.1.0 版开始,现在会产生成功的身份验证 在标准的 PassportJS 用户配置文件中 目的。
Usage
- Download this npm module
npm install --save passport-forcedotcom
- Import it into your app
var passport = require("passport");
var ForceDotComStrategy = require("passport-forcedotcom").Strategy;
- Define the strategy with your application credentials and information
passport.use(
new ForceDotComStrategy(
{
clientID: "{client_id}",
clientSecret: "{client_secret}",
scope: ["id", "chatter_api"],
callbackURL: "https://my.example.com/auth/forcedotcom/callback",
},
function verify(token, refreshToken, profile, done) {
console.log(profile);
return done(null, profile);
}
)
);
- And then setup some routes to hande the flow
app.get("/auth/forcedotcom", passport.authenticate("forcedotcom"), {
display: "page", // valid values are: "page", "popup", "touch", "mobile"
prompt: "", // valid values are: "login", "consent", or "login consent"
login_hint: "", // optional: the user's SalesForce email address or username
state: "", // optional: an aribrary URL encoded string that will get passed back to you
});
// this should match the callbackURL parameter above:
app.get(
"/auth/forcedotcom/callback",
passport.authenticate("forcedotcom", { failureRedirect: "/error" }),
function (req, res) {
res.render("index", checkSession(req));
}
);
和护照一样,您可以更新用户序列化/反序列化。
SalesForce 可以使用 login_hint
参数来预填充登录表单上的用户名字段。 不过,这似乎不是很可靠。 有关详细信息,请参阅 SalesForce OAuth 文档。
如果您需要在使用 SalesForce 启动登录和用户被重定向回您的应用程序之间维护有关用户的信息,则 state
参数很有用。 这避免了依赖 cookie 来维护任何状态信息的需要。 例如,您可以使用它来跟踪用户在开始登录过程之前尝试访问的页面。 如果您传递一个 state
字符串,那么它应该是 URL 编码。
Creating a Connected App
为了使用此策略,您需要有一个 已连接 应用 在 Salesforce 内部。 请参阅此 文章 有关详细和最新的连接应用程序创建说明。
提示:
- Please note that the
client_id
is referred to as "Consumer Key" and theclient_secret
is referred to as the "Consumer Secret" in some of the UI and documentation. - Be sure to set the Connected App's callback URL to the same setting you provided in the
new ForceDotComStrategy
constructor. If you're usingexpress
, then the route you attach must also correspond to this URL (e.g.app.get('/auth/forcedotcom/callback', ...)
- to get a
photos
section in the User Profile you need to set up theapi
orchatter_api
scope when creating the Connected App. - the URL to the photo lasts for ~30 days
- if you do not need the photos, supply a
skipPhoto: true
option to theForceDotComStrategy
constructor and only enable theid
scope.
Example
examples/
文件夹中有一个名为 simple-example
的示例应用程序。 这显示了如何使用带有大量注释的 ForceDotCom-Passport。 在本地运行:
- Open
app.js
inexamples/simple-example
- Set
CF_CLIENT_ID
,CF_CLIENT_SECRET
,CF_CALLBACK_URL
and optionally,SF_AUTHORIZE_URL
,SF_TOKEN_URL
to match your connected app's settings. - Install npm modules by running
npm install
- Run:
node app.js
- Open
localhost:3000
in the browser and try to login using OAuth.
Maintainers
Authors
- Joshua Birk
- Raja Rao DV
- Jared Hanson - whose help resolved a previous issue with handling the incoming OAuth information so that things like the
instance_url
can be readily available. - The team at GoInstant (now Salesforce) who made sure it was production worthy.
- Updates, quality of life additions, enhancements from Jason Ghent and Fabian Jakobs.
passport-forcedotcom
This is a Strategy for use with PassportJS with the Force.com platform (meaning you can use it with Saleforce CRM, your Force.com applications and Database.com).
Please Note that as of version 0.1.0, successful authentication now results in a standard PassportJS User Profile object.
Usage
- Download this npm module
npm install --save passport-forcedotcom
- Import it into your app
var passport = require("passport");
var ForceDotComStrategy = require("passport-forcedotcom").Strategy;
- Define the strategy with your application credentials and information
passport.use(
new ForceDotComStrategy(
{
clientID: "{client_id}",
clientSecret: "{client_secret}",
scope: ["id", "chatter_api"],
callbackURL: "https://my.example.com/auth/forcedotcom/callback",
},
function verify(token, refreshToken, profile, done) {
console.log(profile);
return done(null, profile);
}
)
);
- And then setup some routes to hande the flow
app.get("/auth/forcedotcom", passport.authenticate("forcedotcom"), {
display: "page", // valid values are: "page", "popup", "touch", "mobile"
prompt: "", // valid values are: "login", "consent", or "login consent"
login_hint: "", // optional: the user's SalesForce email address or username
state: "", // optional: an aribrary URL encoded string that will get passed back to you
});
// this should match the callbackURL parameter above:
app.get(
"/auth/forcedotcom/callback",
passport.authenticate("forcedotcom", { failureRedirect: "/error" }),
function (req, res) {
res.render("index", checkSession(req));
}
);
And as usual with passport, you can update the user serialization/de-serialization.
The login_hint
parameter may be used by SalesForce to pre-populate the username field on the login form. This don't seem to be very reliable though. See the SalesForce OAuth documentation for more details.
The state
parameter is useful if you need to maintain information about the user between initiating the login with SalesForce and the user being redirected back to your application. This avoids the need to rely on a cookie to maintain any state information. For example, you could use this to track the page that the user was trying to access before they started the login process. If you pass a state
string then it should be URL encoded.
Creating a Connected App
In order to use this Strategy, you'll need to have a Connected App inside of Salesforce. See this article for detailed and up-to-date Connected App creation instructions.
Tips:
- Please note that the
client_id
is referred to as "Consumer Key" and theclient_secret
is referred to as the "Consumer Secret" in some of the UI and documentation. - Be sure to set the Connected App's callback URL to the same setting you provided in the
new ForceDotComStrategy
constructor. If you're usingexpress
, then the route you attach must also correspond to this URL (e.g.app.get('/auth/forcedotcom/callback', ...)
- to get a
photos
section in the User Profile you need to set up theapi
orchatter_api
scope when creating the Connected App. - the URL to the photo lasts for ~30 days
- if you do not need the photos, supply a
skipPhoto: true
option to theForceDotComStrategy
constructor and only enable theid
scope.
Example
There is an example app called simple-example
in: examples/
folder. This shows how to use ForceDotCom-Passport with lots of comments. To run locally:
- Open
app.js
inexamples/simple-example
- Set
CF_CLIENT_ID
,CF_CLIENT_SECRET
,CF_CALLBACK_URL
and optionally,SF_AUTHORIZE_URL
,SF_TOKEN_URL
to match your connected app's settings. - Install npm modules by running
npm install
- Run:
node app.js
- Open
localhost:3000
in the browser and try to login using OAuth.
Maintainers
Authors
- Joshua Birk
- Raja Rao DV
- Jared Hanson - whose help resolved a previous issue with handling the incoming OAuth information so that things like the
instance_url
can be readily available. - The team at GoInstant (now Salesforce) who made sure it was production worthy.
- Updates, quality of life additions, enhancements from Jason Ghent and Fabian Jakobs.