# oauth

OAuth模块管理客户端的用户登录授权验证功能，允许应用访问第三方平台的资源。

## 方法：

- getServices: 获取登录授权认证服务列表

## 对象：

- AuthService: 登录授权认证服务对象
- AuthOptions: JSON对象，授权认证参数选项
- AuthInfo: 登录授权认证信息
- UserInfo: 登录授权用户信息

## 回调方法：

- ServicesSuccessCallback: 获取登录授权认证服务成功回调
- AuthorizeSuccessCallback: 授权认证成功回调函数
- LogoutSuccessCallback: 注销登录授权认证操作成功回调函数
- SuccessCallback: 登录授权认证服务操作成功回调函数
- ErrorCallback: 登录授权认证服务操作失败回调函数

## 权限：

permissions

    {
    // ...
    "permissions":{
    	// ...
    	"OAuth": {
    		"description": "登录鉴权"
    	}
    }
    }

# AuthService

登录授权认证服务对象

    interface plus.oauth.AuthService {
    	// Attributes
    	attribute String id;
    	attribute String description;
    	attribute AuthInfo authResult;
    	attribute UserInfo userInfo;
    	attribute JSON extra;

    	// Methods
    	function void author(successCallback, errorCallback, options);
    	function void login(successCallback, errorCallback, options);
    	function void logout(successCallback, errorCallback);
    	function void getUserInfo(successCallback, errorCallback);
    	function void addPhoneNumber(successCallback, errorCallback);
    }

## 说明：

AuthService对象用于表示登录授权认证服务，在JS中为对象，用于向系统进行登录授权认证操作。

## 属性：

- id: 登录授权认证服务标识
- description: 登录授权认证服务描述
- authResult: 授权认证结果数据
- userInfo: 登录授权认证用户信息
- extra: 登录授权认证扩展信息

## 方法：

- authorize: 请求授权认证
- login: 请求登录授权认证操作
- logout: 注销登录授权认证
- getUserInfo: 获取登录授权用户信息
- addPhoneNumber: 添加用户手机号信息

# AuthOptions

JSON对象，授权认证参数选项

    interface plus.oauth.AuthOptions {
    	attribute String scope;
    	attribute String state;
    	attribute String appid;
    	attribute String appkey;
    	attribute String appsecret;
    	attribute String redirect_uri;
    }

## 说明：

此对象支持的属性值由登录授权认证服务定义。 例如“微信”，则可配置以下参数： scope - 应用授权作用域； state - 用于保持请求和回调的状态参数。

## 属性：

- scope: (String 类型 )申请的权限作用范围

  如果存在多个权限，则以","符号分割。

- state: (String 类型 )客户端的当前状态，可以指定任意值，登录认证后原封不动的返回保存到AuthService对象的extra中
- appid: (String 类型 )登录授权认证服务平台申请的appid

  动态设置登录授权服务中需要使用的appid，仅需要此参数的登录授权服务（如“微信登录”、“QQ登录”）支持。 如果未设置则使用运行环境中内置的appid值（如在HBuilder中可在manifest.json的SDK配置项中进行设置）。

- appkey: (String 类型 )登录授权认证服务平台申请的appkey

  动态设置登录授权服务中需要使用的appkey，仅需要此参数的登录授权服务（如“新浪微博登录”、“360登录”）支持。 如果未设置则使用运行环境中内置的appkey值（如在HBuilder中可在manifest.json的SDK配置项中进行设置）。

- appsecret: (String 类型 )登录授权认证服务平台申请的appsecret

  动态设置登录授权服务中需要使用的appsecret，仅需要此参数的登录授权服务（如“微信登录”、“新浪微博登录”）支持。 如果未设置则使用运行环境中内置的appkey值（如在HBuilder中可在manifest.json的SDK配置项中进行设置）；当开放平台申请的appsecret值涉及到安全问题时，可在应用运行时从服务器获取，然后通过此api动态设置。

- redirect_url: (String 类型 )登录授权认证服务平台申请的redirect_url

  动态设置登录授权服务中需要使用的redirect_url，仅需要此参数的登录授权服务（如“新浪微博登录”）支持。 如果未设置则使用运行环境中内置的redirect_url值（如在HBuilder中可在manifest.json的SDK配置项中进行设置）。

# AuthInfo

登录授权认证信息

    interface plus.oauth.AuthInfo {
    	attribute String openid;
    	attribute String access_token;
    	attribute String expires_in:
    	attribute String refresh_token;
    	attribute String scope;
    }

## 说明：

此对象仅定义标准属性，登录授权认证服务可扩展自定义数据。 例如“微信”登录授权服务，则包括以下数据： unionid - 用户统一标识，针对一个微信开放平台帐号下的应用，同一用户的unionid是唯一的。

## 属性：

- access_token: (String 类型 )登录授权的访问令牌

  如果登录授权服务不支持此属性，则返回"undefined"。

- openid: (String 类型 )登录授权用户的唯一标识

  如果登录授权服务不支持此属性，则返回"undefined"。

- expires_in: (String 类型 )登录授权访问令牌过期时间

  单位为秒，如果登录授权服务不支持此属性，则返回"undefined"。

- refresh_token: (String 类型 )登录授权的更新令牌

  用来获取下一次的访问令牌，如果登录授权服务不支持此属性，则返回"undefined"。

- scope: (String 类型 )登录授权的权限范围

  如果存在多个权限，则以","符号分割。

# UserInfo

登录授权用户信息

    interface plus.oauth.UserInfo {
    	attribute String openid;
    	attribute String headimgurl:
    	attribute String nickname;
    	attribute String email;
    	attribute String phonenumber;
    	attribute String sex;
    	attribute String province;
    	attribute String city;
    	attribute String country;
    }

## 说明：

用于保存登录授权用户的信息。 此对象仅定义标准属性，登录授权认证服务可扩展自定义数据。 例如“微信”登录授权服务，可能包括以下自定义数据： privilege - 用户特权信息，json数组，如微信沃卡用户为（chinaunicom）； unionid - 用户统一标识，针对一个微信开放平台帐号下的应用，同一用户的unionid是唯一的。

## 属性：

- openid: (String 类型 )登录授权用户的唯一标识

  如果登录授权服务不支持此属性，则返回"undefined"。

- headimgurl: (String 类型 )登录授权用户的头像图片地址

  要求为"http://"或"https://"开头的地址，如果登录授权服务不支持此属性，则返回"undefined"。

- nickname: (String 类型 )登录授权用户的昵称

  如果登录授权服务不支持此属性，则返回"undefined"。

- email: (String 类型 )登录授权用户的邮箱地址

  如果登录授权服务不支持此属性，则返回"undefined"。

- phonenumber: (String 类型 )登录授权用户的电话号码

  如果登录授权服务不支持此属性，则返回"undefined"。

- sex: (String 类型 )登录授权用户的性别

  1为男性，2为女性。 如果登录授权服务不支持此属性，则返回"undefined"。

- province: (String 类型 )登录授权用户注册的省份信息

  如果登录授权服务不支持此属性，则返回"undefined"。

- city: (String 类型 )登录授权用户注册的城市信息

  如果登录授权服务不支持此属性，则返回"undefined"。

- country: (String 类型 )登录授权用户注册的国家信息

  如果登录授权服务不支持此属性，则返回"undefined"。

# ServicesSuccessCallback

获取登录授权认证服务成功回调

    void ServicesSuccessCallback( services ) {
    	// Get oauth services success code
    }

## 说明：

当获取登录授权认证服务列表成功时触发，并通过services参数返回运行环境支持的登录授权认证服务列表。

## 参数：

- services: ( Array[ AuthService ] ) 必选 运行环境支持的登录授权认证服务列表
  运行环境支持的登录授权认证服务列表数组，可通过services.length获取服务列表的数目。 如果当前运行环境没有支持的登录授权认证服务，则返回空数组。

## 返回值：

void : 无

# AuthorizeSuccessCallback

授权认证成功回调函数

    void onAuthorizeSuccess(event){
    	　　// authorize code
    }

## 说明：

授权认证成功时触发，并返回操作结果。

## 参数：

- event: ( JSON ) 必选 授权认证回调参数
  包括以下字段： event.target - 授权认证服务对象； event.scope - 申请的权限作用范围，调用authorize方法传入的scope值； event.state - 自定义参数，调用authorize方法传入的state值； event.code - 用户换取access_token的code； event.lang - 微信客户端当前语言； event.country - 微信用户当前国家信息。

## 返回值：

void : 无

# LogoutSuccessCallback

注销登录授权认证操作成功回调函数

    void onLogoutSuccess(event){
    	　　// logout code
    }

## 说明：

注销登录授权认证成功时触发，并返回操作结果。

## 参数：

- event: ( JSON ) 必选 注销登录授权认证操作回调事件参数
  包括以下参数： event.target - 表示登录授权认证服务对象； 其它属性可保存注销登录授权的扩展数据。

## 返回值：

void : 无

# SuccessCallback

登录授权认证服务操作成功回调函数

    void onSuccess(event){
    	　　// auth code
    }

## 说明：

登录授权认证服务操作如请求登录授权认证、获取登录授权用户信息成功时触发，并返回操作结果。

## 参数：

- event: ( JSON ) 必选 登录授权认证服务操作回调事件参数
  包括以下参数： event.target - 表示登录授权认证服务对象，可以通过此对象的authResult、userInfo属性来获取操作结果信息。

## 返回值：

void : 无

# ErrorCallback

登录授权认证服务操作失败回调函数

    void onError(error){
    	// Error code
    }

## 说明：

登录授权认证服务操作如请求登录授权认证、注销登录授权认证、获取登录授权用户信息失败时触发，并返回错误信息。

## 参数：

- error: ( Exception ) 必选 操作失败错误信息
  包括以下参数： error.code - 表示错误代码； error.message - 错误描述信息；

## 返回值：

void : 无