应用服务器端集成

对于移动身份管理服务,第三方应用需要和EMM移动身份管理服务进行集成,集成的主要目的是第三方服务接到ST Token后,需要向移动身份管理服务进行验证Token的有效性,如果采用OAuth和OIDC的方案。

firewall-cmd --add-rich-rule="rule family=ipv4 source address=${rp_srv_ip} service name=https accept" --permanent
firewall-cmd --reload

EMM服务器首先应该配置准许第三方应用服务访问443端口,登录EMM服务器执行:

EM版本提供的标准插件适用于使用 JAVA 语言开发的应用服务端,若应用服务的版本与EMM身份管理的要求不一致, 请联系NQSky 并提供相关集成服务。

1. OAuth集成

此章节用于说明 OAuth RP-Server 如何与NQSky EMM移动身份管理服务集成及相关事项. 此文档 适用于使用 JAVA 语言开发的 RP-Server。

1.1 环境说明

NQSky EMM 移动身份管理服务以及提供的 RP-Server SDK jar 文件使用 Java 1.8 版本开发, 需要已有的 RP- Server 支持 Java 1.8; 若 RP-Server 的版本与EMM身份管理的要求不一致, 请联系NQSky 并提供相关集成服务。

SDK 使用的字符编码为 UTF-8, 包括所有请求(request), 响应(response)中 使用的字符编码也是 UTF-8; 请在使用中确保字符编码一致。

对于与 RP-Server 的集成, EMM移动身份管理服务尽量减少对已有的项目的改造. 具体来说, 身份管理使用 Servlet Filter 来实现具体的业务逻辑.

OAuth RP Client 在请求时会在 request 的 Header 中传递 token 到 RP-Server, 通过配置的 OAuthRSFilter 拦截并与 身份管理 通信完成校验 并获取用户信息供 RP- Server 使用.
传递的 token 的 key 为: Authorization.

注意 使用 NQSky EMM 移动身份管理服务解决方案不需要从 RP-Client 端传递任何与用户相关的信息到 RP- Server, 使用  需要的 token 即可.

1.2 RR-Server配置

本节用于说明 RP-Server 的配置及如何使用从 EMM 身份管理服务中 获取的当前用户信息.

在项目中添加 SDK jar 文件 ids-oauth-0.1.jar 及依赖的 lib 文件(oauth- lib 文件夹中); 若项目为 Maven 项目, 则在 pom.xml 文件中添加以下 dependency 即可.

<dependency>
	<groupId>commons-io</groupId>
	<artifactId>commons-io</artifactId> 
</dependency>
<dependency>
	<groupId>com.fasterxml.jackson.core</groupId>
	<artifactId>jackson-databind</artifactId> 
	<version>2.5.4</version>
</dependency>

若项目中已经有相应的 lib,则忽略.

在项目的 web.xml 中添加 OAuthRSFilter 配置, 如下:

<filter>
<filter-name>OAuthRSFilter</filter-name> 
<filter-class>com.idsmanager.as.sdk.rps.oauth.OAuthRSFilter</filt er-class> 
<init-param> 
<param-name>ids.access-token.uri</param-name> 
<param-value>{EMMHost}/public/oauth/token_validation</param-value> 
</init-param>
<filter-mapping>
 <filter-name>OAuthRSFilter</filter-name> 
<url-pattern>/public/oauth_test</url-pattern>
</filter-mapping>

注意, 在配置时需要将{EMMHost} 替换为真实的 URL 地址, 如: http://localhost:8080/IDS, 并确保完整的 URL 地址正确.

配置为项目中需要 移动身份管理服务 拦截处理的 URL 地址, 可配置多个 拦截多个 URL 地址.

通过 OAuthRSFilter 拦截的 URL 请求会自动去 移动身份管理服务校验传递的 token 是否 正确, 若正确则获取用户信息(如:username, tenantId); 若不正确则会响应错 误信息,如 401, 具体请参考 SDK 错误码 部分.

验证正确后可在请求(request)中获取用户信息, 具体代码为: ,

一段 DEMO 代码如下:

@RequestMapping(value = {"/public/oauth/login"},method = RequestMetho d.GET) 
@ResponseBody
public ProcessResult oauthLogin(HttpServletRequest request){ 
OAuthRSFilter.Username user = (OAuthRSFilter.Username) request.g etAttribute(OAuthRSFilter.USERNAME_KEY); 
String username = user.getUsername(); 
if(null==username){ 
return new ProcessResult<>(null, ErrorNumber.USER_NOT_EXIT); } 
//username = formatUsername(username);
if(isExitsUserDto(username)){
return new ProcessResult<>(updateDtoLoginTimes(username)); }else{ 
return new ProcessResult<>(createOauthUser(username)); 
} 
} 

可在提供的 OAuth RPServer DEMO 项目中查看具体的使用示例.

注意 若在 EMM移动身份管理服务中添加的 OAuth RP 的 grant_type 选择client_credentials
, 则获取的用户信息(username)为 null; 因为在 OAuth2 协议中, client_credentials是不关心用户信息的.

通过以上配置, 即可完成RPServer 与EMM移动身份管理服务的集成.

 1.3 扩展

本节说明可扩展的功能以及如何应用, 可根据实际需要扩展 。

OAuth 集成中提供的OAuthRSFilter能满足正常的集成,但如果RP-Server 需要扩展现有的功能或满足一些特殊的需求, 可扩展 OAuthRSFilter 现有的 功能.

创建一个新的 Java Class 继承 OAuthRSFilter 并覆盖(override)对应的方法 即可对默认的实现功能进行扩展.

一些常用的应用场景及需要覆盖(override)的方法如下:

场景1:

扩展出现错误时的响应(response)处理(默 认为 response.sendError(error,description))

Override Method:

protected void responseError(int error, String description, HttpSe rvletResponse response) throws IO Exception{ 
    //your codes
}

 场景2:

在 OAuthRSFilter 销毁(destroy)时添加操 作(默认为不做任何事情)

Override Method:

public void destroy() { //your codes }

 1.4 相关文件

包括的文件及说明如下 :

ids-oauth-0.1.jar: OAuth RP-Server SDK jar 文件, 需要在项目中引入

oauth-lib(目录):该目录下有 OAuth RP-Server 中需要使用的 jar 文件, 需要 在项目中引入(若为 Maven 项目添加 dependency 即可)

web.xml.demo: web.xml 中配置 OAuthRSFilter 的示例.

2. OIDC集成

此章节用于说明 OAuth RP-Server 如何开发, 与NQSky EMM移动身份管理服务集成及相关事项. 此文档 适用于使用 JAVA 语言开发的 RP-Server。

2.1 环境说明

SDK 使用的字符编码为 UTF-8, 包括所有请求(request), 响应(response)中 使用的字符编码也是 UTF-8; 请在使用中确保字符编码一致.

对于与 RP-Server 的集成, EMM 身份管理服务中尽量减少对已有的项目的改造. 具体来说, EMM 身份管理服务中使用 Servlet Filter 来实现具体的业务逻辑.

OIDC RP Client 在请求时会在 request 的 Header 中传递两个 token 到 RP- Server, 通过配置的 OIDCRSFilter 拦截并与  通信完成校验 并获取用户信息供 RP-Server 使用.
传递的两个 token 的 key 分别为: Authorization, IdToken.

2.2 RP-Server 配置及使用

本节用于说明 RP-Server 的配置及如何使用从 IDS 获取的当前用户信息。

在项目中添加 SDK jar 文件 ids-oidc-0.1.jar 及依赖的 lib 文件(oidc-lib 文件夹中); 若项目为 Maven 项目, 则在 pom.xml 文件中添加以下 dependency 即可。

<dependency>
<groupId>commons-io</groupId> 
<artifactId>commons-io</artifactId> 
<version>2.4</version>
</dependency>
<dependency>
<groupId>org.bitbucket.b_c</groupId> 
<artifactId>jose4j</artifactId>
<version>0.4.3</version>
<exclusions> 
	<exclusion> 
    	<groupId>commons-logging</groupId>
	<artifactId>commons-logging</artifactId> 
	</exclusion> 
    </exclusions>
</dependency>
<dependency>
	 <groupId>com.fasterxml.jackson.core</groupId> 
	<artifactId>jackson-databind</artifactId> 
<version>2.5.4</version> 
</dependency>

若项目中已经有相应的 lib,则忽略.

在项目的 web.xml 中添加 OIDCRSFilter 配置, 如下:

<filter>
	
<filter-name>OIDCRSFilter</filter-name> 
<filter-class>com.idsmanager.as.sdk.rps.oidc.OIDCRSFilter</filter -class> 
<init-param> 
<param-name>ids.publickey.uri</param-name> 
	<param-value>{EMMHost}/api/rp/oidc/</param-value> 
    </init-param>
</filter>
<filter-mapping>
	<filter-name>OIDCRSFilter</filter-name> 
	<url-pattern>/public/oidc_test</url-pattern> 

</filter-mapping>

注意, 在配置时需要将{EMMHost} 替换为 EMM 真实的 URL 地址, 如: http://localhost:8080/IDS, 并确保完整的 URL 地址正确。

配置为项目中需要 EMM身份管理服务拦截处理的 URL 地址, 可配置多个 拦截多个 URL 地址。通过 OIDCRSFilter 拦截的 URL 请求会自动去 IDS 校验传递的 token 是否正确, 若正确则获取用户信息(如: username, tenantId); 若不正确则会响应错 误信息,如 401, 具体请参考 SDK 错误码部分。

验证正确后可在请求(request)中获取用户信息, 具体代码为: ,

一段 DEMO 代码如下:

@RequestMapping(value="/public/oidc/login",method= RequestMethod.GET)
@ResponseBody
public ProcessResult oidcLogin(HttpServletRequest request){
	OIDCRSFilter.PayLoad payLoad = (OIDCRSFilter.PayLoad)	request.getAttribute(OIDCRSFilter.PAYLOAD_KEY); 
String username =payLoad.getRPUsername();
if(null==username){
return new ProcessResult<>(null, ErrorNumber. USER_NOT_EXIT);
}
if(isExitsUserDto(username)){
return new ProcessResult<>(updateDtoLoginTimes(username));
}else{

return new ProcessResult<>(createOIDCUser(username));
} 
}

可在提供的 OIDC RPServer DEMO 项目中查看具体的使用示例.通过以上配置, 即可集成 IDS 到 RPServer 中.

2.3 相关文件

包括的文件及说明如下 :

ids-oidc-0.1.jar : OIDC RP-Server SDK jar 文件, 需要在项目中引入

oidc-lib(目录) :该目录下有 OIDC RP-Server 中需要使用的 jar 文件, 需要 在项目中引入

web.xml.demo : web.xml 中配置 OIDCRSFilter 的示例