Janrain 使用文档
来源:互联网 发布:剑灵力士女捏脸数据图 编辑:程序博客网 时间:2024/05/19 12:40
Documentation
Additional Documentation:
- Engage for Android - Library for Android app support
- Engage for iOS - Library for native iOS app support
- Provider Guide - Features supported by each provider
- Social Sharing API - Allows users to post acitivty updates to popular social networks
In This Document:
Introduction to Janrain Engage
- Overview
- User Interaction Flow
Integrating The Sign-In Interface
- The Sign-In Interface
- Setting the default provider
- Localization
- Your token_url
Authentication and Profile Data: Using the API
- Profile Data
- Mappings
- API Documentation
- API request format
- API response format
- API error responses
- auth_info API call
- get_contacts API call
- get_user_data API call
- set_status API call
- map API call
- unmap API call
- mappings API call
- all_mappings API call
- activity API call
- analytics_access API call
- set_auth_providers API call
- providers API call
Overview
Janrain makes it easy to add OpenID and other authentication APIs to your website. We help you add authentication from providers like Google, Facebook, Twitter, Yahoo! and Windows Live ID, making it extremely simple for users to get in and start using your web application. It runs on our servers in the cloud and is accessed via simple, restful API calls. Janrain Engage is a proxy between your website and the OpenID provider, and is completely transparent to the end user. Adding Janrain Engage to your website doesn't require any changes to your database, and its only requirements are the ability for your servers to make outbound HTTPS calls and to parse JSON or XML.
Janrain Engage Flow
Below is a step-by-step diagram that shows how a user will sign in to your website using Janrain Engage, including the appropriate integration points.
The Sign-in Interface
Janrain Engage uses javascript to add a user friendly sign-in box to your website. Below is a sample of the sign-in widget. We'll supply you with javascript customized to show it on your web site:
Additionally, you may embed the interface directly into a page on your site without using the javascript popup. If you would like to disable the pre-existing "Select one of these third-party accounts" at the top of the embedded display, include the parameterflags=hide_sign_in_with in your embedded iframe's src URL.
Sign-In Interface Default Provider
By default, users that have never signed in to your site will see the Janrain Engage sign-in interface as pictured above, with all your providers shown. To set a default provider in this case, you can set RPXNOW.default_provider
in your JavaScript to one of the following values, depending on which providers you have enabled for your relying party:
"aol""facebook""google""live_id""myspace""openid""yahoo""flickr""livejournal""myopenid""verisign""wordpress""blogger""hyves""netlog""twitter""linkedin""paypal""salesforce""orkut""vzn""foursquare"
For example:
RPXNOW.default_provider = "openid";
To cause the widget to display the provider list even if they have logged in before, setRPXNOW.flags="show_provider_list".
Sign-In Interface Localization
You can set the language for the sign-in interface to one of the following:
ar bg cs da de el en es fi foo fr he hr hu id it ja lt nb-NO nl nl-BE nl-NL no pl pt pt-BR pt-PT ro ru sk sl sr sv sv-SE th uk zh zh-CHT
If you'd like to use a language that is missing from this list or if you would like to improve our existing translations, please let us know.
Setting the language for the popup
Set RPXNOW.language_preference
in the javascript in your page.
For example:
RPXNOW.language_preference = 'es';
Setting the language for the embedded widget
Add the parameter "language_preference=lang" to your embedded iframe's src URL, where lang is any of the language codes listed above.
Your token_url
When configuring the sign-in interface, you supply a token_url
parameter. This is where the user will POST
their token
after completing the authentication process. You must extract the token
and pass into the auth_info
API call.
If the user cancels the OpenID sign-in transaction, they will make a POST
to your token_url
without the token parameter.
Note: You can pass state through the Janrain Engage authentication transaction by adding query parameters to your token_url.
Profile Data
Janrain Engage can request profile and registration data from the user using the Simple Registration OpenID extension, the HCard microformat, and soon via the new Portable Contacts protocol. This information may be used to aid in new user registration, and profile/contact information syncing.
Source: Simple Registration OpenID Extension
The Simple Registration (SREG) OpenID extension provides a mechanism for providers to send a small set of registration data the relying party during the OpenID transaction. SREG is currently supported by many of the major independent OpenID providers, and will likely soon be supported by the major consumer providers as well. Nine fields are defined in the Simple Registration schema: nickname, email, fullname, dob, gender, postcode, country, language, and timezone. Data fields are sent with the user's consent, and their presence is purely for user convenience.
Source: Attribute Exchange
OpenID Attribute Exchange (AX) is an OpenID service extension for exchanging identity information between endpoints. Janrain Engage currently support AX for fetching verified email addresses from Google's OpenID provider.
Source: hCard
hCard is a simple, open, distributed format for representing people, companies, organizations, and places, using a 1:1 representation of vCard properties and values in semantic HTML or XHTML. hCard is commonly embedded in OpenID pages to provide machine readable public identity data. Many OpenID providers automatically mark their users' profile pages up with hCard data, which can be useful to you in user registration and/or profile syncing.
Source: Facebook
If you have enabled Facebook (FB) login for your Janrain Engage sites, we'll provide you with some standard profile fields that the Facebook platform makes available through their API.
Normalizing Sources
For your convenience, Janrain Engage normalizes profile data from our sources into a standardized format. This makes it easy for you to parse and use the profile data without having to learn about the different sources and their individual schemas.
Personal Data Fields
Outlined below are the fields that are available in the normalized profile
structure.
true
if Janrain Engage was able to retrieve only limited public data from the user's profile (e.g., because the login session has expired or the user logged out from their account). If Janrain Engage succeeded in retrieving complete set of data, this field will be missing or set to false
.Used only with Facebook.The name field
The components of the person's real name. Providers MAY return just the full name as a single string in the formatted sub-field, or they MAY return just the individual component fields using the other sub-fields, or they MAY return both. If both variants are returned, they SHOULD be describing the same name, with the formatted name indicating how the component fields should be combined.
The address field
Provider Specific Fields
Some providers return fields specific only to them. These fields will be present in the 'provider' dictionary keyed by the provider name.
Mappings
Janrain Engage allows customers to associate a user account record in the customer’s database with one or more user identities in Janrain Engage. We call these associations Mappings.
Mappings can connect a user who has just authenticated with a social network to his or her legacy local account. Mappings may also be used to link multiple social networking accounts to a single user, either through a front-end login process or as a feature associated with a user profile. The Janrain Engage mapping API permits multiple methods of user account mapping. Mappings help you add social sign-in to your existing user accounts without changing your database schema. The Mapping API also helps you implement the best practice of allowing multiple social identities per user, which gives the end user total control of their identity by letting them switch their identity provider as their needs change.
You probably have a "users" or "accounts" table in your database. The mapping API lets you associate the primary key of an existing user with an identity provider’s identifier, and store that mapping on the Janrain Engage server. When a mapping exists for a user, Janrain Engage returns both the primary key for the user and the associated provider’s indentifier in the auth_info call. You then use the primary key to figure out which account to sign the user into on your site.
New mappings are created with the map
API call. Before using the map API call to save a primary key to identifier mapping, you must first know who the user is on your site, and have a record for them in your users or accounts table. This means that the user is either already logged in with a legacy account, or they have been verified using Janrain Engage and you have created a new record for them in the database but haven't yet stored that mapping anywhere. Either way, new mappings are generally created right after a user has verified their identity with Janrain Engage and you have extracted their identifier via the auth_info
API call.
The image below represents a website using Janrain Engage with a Users table that has a primary key called "id". A user has bound three different provider identities to his account, and because the website is using the mapping API he may use any one of his mapped accounts to sign in as the BrianMan692 user.
After the mapping is made, when the user signs in with his brian.myopenid.com OpenID, an auth_info response including the primaryKey will be returned. Use the value of the primaryKey field to sign the user in as BrianMan692.
{ "profile": { "identifier": "http:\/\/brian.myopenid.com\/", "primaryKey": "17" }, "stat": "ok"}
Janrain Engage API
The following sections describe in detail the back-channel API calls you will make to the Janrain Engage servers. The next section discusses the general request and response formats, and error cases that each API call adheres to.
Request Format
Each API call into Janrain Engage is made as an HTTP POST to the base URL list below. Additionally, each call has a method name, and a set of required and/or optional parameters.
Response Format
Janrain Engage formats API responses in either XML or JSON. It is required that you include the format query parameter in your request URL.
Error Responses
If an irrecoverable error occurs during the API call, Janrain Engage will return an error response with a code and a message.
Here's a sample error response:
{ "err": { "msg": "Data not found", "code": 2 }, "stat": "fail"}
<?xml version='1.0' encoding='UTF-8'?><rsp stat='fail'> <err msg='Data not found' code='2'/></rsp>
auth_info
The auth_info call is used in your token_url code, and is called after extracting the token. Use the auth_info call to get information about the user currently signing in to your web application.
auth_info - Request
'true' or 'false'(default). Return the extended Simple Registration and HCard data in addition to the normalized Portable Contacts format.
tokenUrlnoValidate the specified token URL value against the token URL that was originally sent. See 'Token URL mismatch' below for more details.auth_info - Response
The auth info contains all the information Janrain Engage knows about the user logging into your website.
If the user logged in with a provider that allows account access after authentication, this will be present and contain the user's authorization credentials. A field named 'type' will describe the type of access available, and be one of 'OAuth', 'Facebook', or 'WindowsLive'.
- For OAuth, the provided fields are named 'oauthToken' and 'oauthTokenSecret', representing the OAuth access token.
- For Facebook, the provided fields are named 'uid', 'sessionKey', and 'expires'.
- For WindowsLive, the provided field is named 'eact', which contains the user's delegated authentication consent token.
{ "profile": { "displayName": "brian", "preferredUsername": "brian", "url": "http:\/\/brian.myopenid.com\/", "providerName": "Other", "identifier": "http:\/\/brian.myopenid.com\/" }, "stat": "ok"}
<?xml version='1.0' encoding='UTF-8'?><rsp stat='ok'> <profile> <displayName> brian </displayName> <identifier> http://brian.myopenid.com/ </identifier> <preferredUsername> brian </preferredUsername> <providerName> Other </providerName> <url> http://brian.myopenid.com/ </url> </profile></rsp>
auth_info - Token URL mismatch
If the tokenUrl parameter you specified does not match the token URL to which the token was originally sent, you will receive this error response:
{ "err": { "msg": "Token URL mismatch: (your tokenUrl parameter) (original token URL)", "code": 3 }, "stat": "fail"}
<?xml version='1.0' encoding='UTF-8'?><rsp stat='fail'> <err msg='Token URL mismatch: (your tokenUrl parameter) (original token URL)' code='3'/></rsp>
get_contacts
Retrieve a list of contacts for an identifier in the Portable Contacts format.
The get_contacts
call is made using the identifier returned in the auth_info
call.
get_contacts - Request
Note: Only identifiers from Google, Yahoo, Windows Live, Facebook, MySpace, Twitter and LinkedIn are currently supported. Only Google and Windows Live provide a contact's email address. Google and Yahoo require additional setup from your Janrain Engage developer console.
get_contacts - Response
The get_contacts response contains a portable contacts response node with an entry for contact.
{ "response": { "entry": [ { "emails": [ { "type": "other", "value": "bob@example.com" } ], "displayName": "Bob Johnson" }, { "emails": [ { "type": "other", "value": "cindy.smith@example.com" } ], "displayName": "Cindy Smith" }, { "emails": [ { "type": "other", "value": "fred.williams@example.com" } ], "displayName": "Fred Williams" }, { "emails": [ { "type": "other", "value": "j.lewis@example.com" } ] }, { "emails": [ { "type": "other", "value": "mary.jones@example.com" } ], "displayName": "Mary Jones" }, { "emails": [ { "type": "other", "value": "p.green@example.com" } ], "displayName": "Patricia Green" } ], "startIndex": 1, "itemsPerPage": 5, "totalResults": 5 }, "stat": "ok"}
<?xml version='1.0' encoding='UTF-8'?><rsp stat='ok'> <response> <startIndex> 1 </startIndex> <itemsPerPage> 5 </itemsPerPage> <totalResults> 5 </totalResults> <entry> <displayName> Bob Johnson </displayName> <emails> <email> <type> other </type> <value> bob@example.com </value> </email> </emails> </entry> <entry> <displayName> Cindy Smith </displayName> <emails> <email> <type> other </type> <value> cindy.smith@example.com </value> </email> </emails> </entry> <entry> <displayName> Fred Williams </displayName> <emails> <email> <type> other </type> <value> fred.williams@example.com </value> </email> </emails> </entry> <entry> <emails> <email> <type> other </type> <value> j.lewis@example.com </value> </email> </emails> </entry> <entry> <displayName> Mary Jones </displayName> <emails> <email> <type> other </type> <value> mary.jones@example.com </value> </email> </emails> </entry> <entry> <displayName> Patricia Green </displayName> <emails> <email> <type> other </type> <value> p.green@example.com </value> </email> </emails> </entry> </response></rsp>
set_status
Set the status message for the account corresponding to an identifier.
The set_status
call is made using the identifier returned in the auth_info
call. The status message will be set using the appropriate API for the specified identifier; for example, if the specified identifier is a Facebook identifier, Janrain Engage will make an API call to Facebook to set the status on the Facebook account.
set_status - Request
This is a string containing location data associated with the content being published. The string is latitude, followed by longitude, for example "37.4220 -122.0843". Valid values for latitude are -90.0 to +90.0, with North being positive. Valid values for longitude are -180.0 to +180.0 with East being positive.
In the cases of invalid values in the location parameter, an invalid parameter exception is returned by the API. In the case of unsupported providers or users who have disabled location on their account with the provider, the location value will be silently ignored.
truncateno'true' (default) or 'false'. If 'true', truncate status when posting to providers which impose status length restrictions (currently Twitter, Yahoo, and LinkedIn).set_status - Response
This method has no specific response - It returns an empty success response if it completes without error.
{ "stat": "ok"}
<?xml version='1.0' encoding='UTF-8'?><rsp stat='ok'/>
set_status - Provider support
set_status
is currently supported for the following providers:
- MySpace
- Yahoo!
If the provider does not provide a user status or does not provide an API to update it, this error response will be sent by Janrain Engage:
{ "err": { "msg": "The provider or identifier does not support this feature", "code": 11 }, "stat": "fail"}
<?xml version='1.0' encoding='UTF-8'?><rsp stat='fail'> <err msg='The provider or identifier does not support this feature' code='11'/></rsp>
map
Map an OpenID to a primary key. Future logins by this owner of this OpenID will return the mapped primaryKey in theauth_info
API response, which you may use to sign the user in.
The map
call is usually made right after a call to auth_info
, when you already know who the user is because they are signed in to your website with their legacy (or existing) account.
map - Request
map - Response
This method has no specific response - It returns an empty success response if it completes without error.
{ "stat": "ok"}
<?xml version='1.0' encoding='UTF-8'?><rsp stat='ok'/>
unmap
Remove (unmap) an OpenID from a primary key, and optionally unlink your application from the user's account with the provider.
unmap - Request
unmap - Response
This method has no specific response - It returns an empty success response if it completes without error.
{ "stat": "ok"}
<?xml version='1.0' encoding='UTF-8'?><rsp stat='ok'/>
mappings
Get all stored mappings for a particular primary key
mappings - Request
mappings - Response
{ "stat": "ok", "identifiers": [ "http:\/\/brian.myopenid.com\/", "http:\/\/brianellin.com\/" ]}
<?xml version='1.0' encoding='UTF-8'?><rsp stat='ok'> <identifiers> <identifier> http://brian.myopenid.com/ </identifier> <identifier> http://brianellin.com/ </identifier> </identifiers></rsp>
all_mappings
Get all stored mappings for a particular application
all_mappings - Request
all_mappings - Response
{ "mappings": { "1": [ "http:\/\/cygnus.myopenid.com\/" ], "2": [ "http:\/\/brianellin.com\/", "http:\/\/brian.myopenid.com\/" ] }, "stat": "ok"}
<?xml version='1.0' encoding='UTF-8'?><rsp stat='ok'> <mappings> <mapping> <primaryKey> 1 </primaryKey> <identifiers> <identifier> http://cygnus.myopenid.com/ </identifier> </identifiers> </mapping> <mapping> <primaryKey> 2 </primaryKey> <identifiers> <identifier> http://brianellin.com/ </identifier> <identifier> http://brian.myopenid.com/ </identifier> </identifiers> </mapping> </mappings></rsp>
activity
Post an activity update to the user's activity stream. Currently supported providers are:
- MySpace
- Yahoo!
Janrain Engage will make a best effort to use all of the fields submitted in the activity request, but note that how they get presented (and which ones are used) ultimately depends on the provider.
This API will work if and only if:
- Your Janrain Engage application has been configured to authenticate using the user's provider
- The user has already authenticated and has given consent to publish activity
Otherwise, you will be given an error response indicating what was wrong. Detailed error responses will also be given if theactivity parameter does not meet the formatting requirements described below.
activity - Request
This is a string containing location data associated with the content being published. The string is latitude, followed by longitude, for example "37.4220 -122.0843". Valid values for latitude are -90.0 to +90.0, with North being positive. Valid values for longitude are -180.0 to +180.0 with East being positive.
In the cases of invalid values in the location parameter, an invalid parameter exception is returned by the API. In the case of unsupported providers or users who have disabled location on their account with the provider, the location value will be silently ignored.
activity JSON structure
An activity request is a JSON object with the following attributes:
KeyRequired?TypeDescriptionurlyesstringThe URL of the resource being mentioned in the activity updateactionyesstringA string describing what the user did, written in the third person. Examples:- "wrote a restaurant review"
- "posted a comment"
- "took a quiz"
action_links: [ {"text": "Rate this quiz result", "href": "http://example.com/quiz/12345/result/6789/rate"}, {"text": "Take this quiz", "href": "http://example.com/quiz/12345/take"} ]medianoarrayAn array of media objects. Media object format and rules are identical to those described on the Facebook Developer page on Attachments.propertiesnoobjectAn object with attributes describing properties of the update. An attribute value can be a string or an object with two attributes, text and href. Example:
properties: { "Time": "05:00", "Location": { "text": "Portland", "href": "http://en.wikipedia.org/wiki/Portland,_Oregon" } }
activity - Complete example "activity" value
{ "user_generated_content": "I thought you would appreciate my review.", "title": "A Critique of Atomic Pizza", "action_links": [ { "href": "http:\/\/example.com\/review\/write", "text": "Write a review" } ], "action": "wrote a review of Atomic Pizza", "url": "http:\/\/example.com\/reviews\/12345\/", "media": [ { "href": "http:\/\/bit.ly\/3fkBwe", "src": "http:\/\/bit.ly\/1nmIX9", "type": "image" } ], "description": "Atomic Pizza has a great atmosphere and great prices.", "properties": { "Location": { "href": "http:\/\/bit.ly\/3fkBwe", "text": "North Portland" }, "Rating": "5 Stars" }}
analytics_access
Get statistics for your application in a zip file. Goes great with cron jobs. The process consists of two API calls. The first call is to establish a one time use token to access the analytics server. The second is to use that token to receive a .zip file containing your statistics.
analytics_access - Response
The first call returns a URL to access the analytics file
{ "url": "http:\/\/rpxnow.com\/export?access_token=19e936b707e7862269c...&end=02\/10\/2010&api=true"}
<?xml version='1.0' encoding='UTF-8'?><rsp stat='ok'/>
The report will list total, unique, new, and returning sign-ins per day.
If your application runs on more than one domain the download will include a report for each domain that has data for the given date range, plus a report with totals for all of your domains.
set_auth_providers
Set the providers that will be displayed in the sign-In Interface.
set_auth_providers - Request
set_auth_providers - Response
This method has no specific response - It returns an empty success response if it completes without error.
{ "stat": "ok"}
<?xml version='1.0' encoding='UTF-8'?><rsp stat='ok'/>
Currently supported provider names are:
- aol
- live_id
- myspace
- openid
- yahoo
- flickr
- livejournal
- myopenid
- verisign
- wordpress
- blogger
- hyves
- netlog
- paypal
- salesforce
- orkut
- vzn
- foursquare
Otherwise, you will be given an error response indicating what was wrong.
providers
Get a list of configured signin and social providers. Note that this API call does not use apiKey to identify the application, but rather, must be called on the application's domain. In this example, results would be returned for the 'my_app' application.
providers - Request
providers - Response
Returns configured providers or error.
{ "social": [ "aol", "facebook", "google" ], "signin": [ "aol", "facebook", "twitter" ], "stat": "ok"}
<?xml version='1.0' encoding='UTF-8'?><rsp stat='ok'> <signin> <provider> aol </provider> <provider> facebook </provider> <provider> twitter </provider> </signin> <social> <provider> aol </provider> <provider> facebook </provider> <provider> google </provider> </social></rsp>
- Janrain 使用文档
- Janrain Engage Social Login and Social Sharing
- Janrain: Facebook与Google占据76%社交登陆验证入口
- log4j简明使用文档
- log4j 简明使用文档
- ROSE使用文档
- cvs使用文档
- TestTrack Pro使用文档
- 使用实例文档
- log4j使用文档
- log4j使用文档
- Gentle.NET 使用文档
- nv文档使用VBOs
- Vss2005使用文档
- Log4net 使用文档(概念)
- Log4net 使用文档(概念)
- 使用 perldoc 找文档
- Log4net 使用文档(概念)
- 什么是源型 漏型?什么是上拉电阻?下拉电阻?什么是 线驱动输出 集电极开路输出,推挽式输出?
- 使用eclipse编写Hadoop应用程序
- hdu 1331||1579 Function Run Fun(记忆化)
- VS2010安装包制作
- Linux 性能监测工具
- Janrain 使用文档
- 将图片嵌入程序文件的一点研究
- Error: Ran out of space in ROM for simsun.ac3
- 游戏引擎开发之路
- 直接在手机桌面上建立应用的快捷方式
- 提高网站性能
- Java多线程之线程返回值
- 用牛顿方法解一元非线性方程的根(Matlab实现)
- IIS设置ISAPI筛选器Rewrite组件防盗链(防盗链可以节省流量,提高性能)