Oracle® Communications Services Gatekeeper RESTful Application Developer's Guide Release 5.1 E37533-01 |
|
|
PDF · Mobi · ePub |
This chapter describes the use of OneAPI Anonymous Customer Reference (ACR) in Oracle Communications Services Gatekeeper.
OneAPI supports using Anonymous Customer References (ACRs) as subscriber identifiers. An ACR represents a unique identifier replacing a subscriber's secure information, such as MSISDN or phone number, ensuring privacy when interacting with Web applications.
For information on the OneAPI ACR specification see:
http://www.gsma.com/oneapi/anonymous-customer-reference-beta
Services Gatekeeper supports ACRs by generating and managing one or more ACRs for a subscriber when requested by a Web application. A Web application requiring an ACR for a subscriber requests one from Services Gatekeeper using the RESTful API.
Services Gatekeeper supports the use of ACRs for all of the supported OneAPI services including SMS, MMS, Terminal Location and Payment.
In addition to basic and session ID authentication, Services Gatekeeper also supports OAuth authentication of applications requesting or querying ACR identifiers. Services Gatekeeper can use OAuth to provide subscribers SSO-like access to resources such as photos or Web sites.
Services Gatekeeper supports allowing OAuth access to subscriber resources using ACRs. Requests can use a valid accessToken to retrieve or update ACR information when submitted. The Services Gatekeeper OAuth Interceptor uses the provided accessToken to confirm a subscriber's identity before releasing ACR information.
For information about Services Gatekeeper OAuth support, see Oracle Communications Services Gatekeeper OAuth Guide.
Services Gatekeeper supports ACR operations by default. Applications can create, query and refresh ACRs using the RESTful API on a Services Gatekeeper system after you create an ACR plug-in instance.
To create an instance of the ACR plug-in in the Services Gatekeeper:
Log into the Administration Console.
Expand the OCSG node under Domain Structure.
Click on the name of the administration or managed server you want to create the ACR plug-in instance on.
Expand the Container Services node under Oracle Communications Services Gatekeeper.
Select PluginManager.
Click Operations.
In the Select An Option pull down menu select createPluginInstsance.
Enter Plugin_acr
in the PluginServiceId field.
Enter a unique name in the PluginInstanceId field.
Click Invoke.
Add a route to the ACR plug-in using the pluginManager Mbean.
The Platform Test Environment MBean interface can also be used to create and manage ACR plug-ins. For information on using the Platform Test Environment, see Oracle Communications Services Gatekeeper Platform Test Environment Guide.
To configure the ACR plug-in attributes in Table 4-1:
Log into the Administration Console.
Expand the OCSG node under Domain Structure.
Select the administration or managed server where you created the ACR plug-in.
Expand the Communication Services node under Oracle Communications Services Gatekeeper.
Select the ACR plug-in instance to configure.
Click Attributes.
Select the checkboxes of the attributes you wish to change.
Enter the new values for the attribute(s).
Click Update Attributes.
Table 4-1 ACR Plug-in Attributes
Attribute | Type | Description |
---|---|---|
Ncc |
String |
The network-code of the operator. In Services Gatekeeper, this is the same as a service provider group. |
AcrLifeTime |
Integer |
The number of seconds a generated or refreshed ACR is valid. Default value: 3600 |
TrafficAcrMappingEnabled |
Boolean |
Whether to enable ACR mapping in network traffic. Default value: False |
Services Gatekeeper supports using ACRs by generating and managing one or more ACRs for a subscriber when requested by a Web application. A Web application requiring an ACR for a subscriber requests one from Services Gatekeeper using the RESTful API described below. Services Gatekeeper supports the use of ACRs for all of the supported OneAPI services including SMS, MMS, Terminal Location and Payment.
For more information on OneAPI services support, see Oracle Communications Services Gatekeeper OneAPI Application Developer's Guide.
The Create ACR operation creates a new ACR for a subscriber based on MSISDN.
http://host:port/CustomerReference/version/address
where:
host and port are the host name and port of the machine on which Services Gatekeeper is installed.
address is the subscriber identifier MSISDN. Services Gatekeeper supports an address entry of acr:Authorization, where authorization is an OAuth accessToken.
The request body for Create ACR accepts the following parameters:
acr. String.
status. String.
expiry. String.
The response header indicates successful creation of the ACR. If the request fails, the Status-Line header field will contain the status code and the reason for the failure. See "Errors and Exceptions", for more information.
The response body contains the following parameters:
acr. String. The Services Gatekeeper generated ACR.
status. String. The current status of the ACR.
expiry. String. The expiration time of the ACR.
Example 4-1 shows a sample Create ACR request.
Example 4-1 Create ACR Request Example
POST http://example.com/CustomerReference/v1/tel%2B%3A7990123456HTTP/1.1Host: example.com:80Accept: application/json{"acr":{"status":"Valid"}}
Example 4-2 shows a sample Create ACR response.
The Query ACR operation queries the ACR status of the referenced subscriber.
http://host:port/CustomerReference/version/address/acr
where:
host and port are the host name and port of the machine on which Services Gatekeeper is installed.
address is the subscriber MSISDN.
acr is the ACR for which the status query is being made including the network-code (ncc).
Standard header fields. If the request fails, the Status-Line header field will contain the status code and the reason for the failure. See "Errors and Exceptions".
The response body contains the following parameters:
acr. String. The Services Gatekeeper generated ACR.
status. String. The current status of the ACR.
Example 4-3 shows a sample Query ACR request.
Example 4-3 Query ACR Request Example
GET http://example.com/CustomerReference/v1/tel%2B%3A7990123456/acr%2B0123456890123456789%3Bncc=23415
Example 4-4 shows a sample Query ACR response.
The Change ACR Status operation refreshes an expired ACR to a valid status.
http://host:port/CustomerReference/version/address/acr
where:
host and port are the host name and port of the machine on which Services Gatekeeper is installed.
address is the subscriber MSISDN.
acr is the ACR for which the status query is being made including the network-code (ncc).
The request body for Create ACR accepts the following parameters:
acr. String.
status. String.
expiry. String.
developerId. String. Required. The OneAPI developer ID.
applicationId. String. Optional. The Services Gatekeeper application ID.
The response header indicates successful change of the ACR status. If the request fails, the Status-Line header field will contain the status code and the reason for the failure. See "Errors and Exceptions", for more information.
The response body contains the following parameters:
acr. String. The Services Gatekeeper generated ACR.
status. String. The updated status of the ACR.
expiry. String. The new expiration time of the ACR.
Example 4-5 shows a sample Change ACR request.
POST http://example.com/CustomerReference/v1/tel%2B%3A7990123456/acr%2B0123456890123456789%3Bncc=23415 HTTP/1.1 Host: example.com:80 Accept: application/json {"acr":{"status":"Valid"}}
Example 4-6 shows a sample Change ACR response.
The Status-Line in the response message indicates the protocol version, the three-digit Status Code and the reason for the failure of a request. Table 4-2 lists the possible error codes for failed requests.
Table 4-2 ACR Operations Error Codes
Error Code | Cause |
---|---|
303 |
create ACR failed, because the acr for the MSISDN has existed |
400 |
The request with {address} = "MSISDN B" try to query/change acr of "MSISDN A" |
401 |
The request from ncc A try to change/query acr of ncc B |
404 |
query an un-existed ACR |
503 |
inner server error |
Table 4-3 lists the EDRs generated by ACR operations.
EDR | Service | Method | Description |
---|---|---|---|
408001 |
oracle.ocsg.parlayrest.plugin.AcrPlugin |
CreateAcrResp createAcr |
create acr code for address |
408002 |
oracle.ocsg.parlayrest.plugin.AcrPlugin |
QueryAcrResp queryAcr |
query acr code for address |
408003 |
oracle.ocsg.parlayrest.plugin.AcrPlugin |
ChangeAcrResp ChangeAcr |
change acr code for address |