4 Anonymous Customer Reference

This chapter describes the use of OneAPI Anonymous Customer Reference (ACR) in Oracle Communications Services Gatekeeper.

About Anonymous Customer References

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.

Support for ACRs Using OAuth Authentication

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.

Configuring ACR Support in Services Gatekeeper

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.

Creating an ACR Plug-in Instance

To create an instance of the ACR plug-in in the Services Gatekeeper:

1. Log into the Administration Console.

2. Expand the OCSG node under Domain Structure.

3. Click on the name of the administration or managed server you want to create the ACR plug-in instance on.

4. Expand the Container Services node under Oracle Communications Services Gatekeeper.

5. Select PluginManager.

6. Click Operations.

7. In the Select An Option pull down menu select createPluginInstsance.

8. Enter Plugin_acr in the PluginServiceId field.

9. Enter a unique name in the PluginInstanceId field.

10. Click Invoke.

11. 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.

Setting ACR Plug-in Parameters

To configure the ACR plug-in attributes in Table 4-1:

1. Log into the Administration Console.

2. Expand the OCSG node under Domain Structure.

3. Select the administration or managed server where you created the ACR plug-in.

4. Expand the Communication Services node under Oracle Communications Services Gatekeeper.

5. Select the ACR plug-in instance to configure.

6. Click Attributes.

7. Select the checkboxes of the attributes you wish to change.

8. Enter the new values for the attribute(s).

9. 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

Creating Multiple ACRs for a Single Subscriber

You can create multiple ACRs for the same subscriber or MSISDN. Services Gatekeeper creates a unique ACR for each application. Use this configuration to route application requests containing ACR identifiers to the correct service provider group.

Using ACRs with Services Gatekeeper

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.

---

Create ACR

The Create ACR operation creates a new ACR for a subscriber based on MSISDN.

Authorization

Basic or OAuth

HTTP Method

POST

URI

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.

Request Header

The MIME-type for the Content-Type header field is application/json.

Request Body

The request body for Create ACR accepts the following parameters:

• acr. String.

• status. String.

• expiry. String.

Response Header

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.

Response Body

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.

Examples

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.

Example 4-2 Create ACR Response Example

HTTP/1.1 201 CreatedContent-Type: application/jsonContent-Length: 1234Date: Thu, 04 Jun 2009 02:51:59 GMT{"acr": "acr:0123456890123456789;ncc=23415","status":"Valid","expiry":"Thu 11 Jun 2009 02:51:59 GMT"}

---

Query ACR

The Query ACR operation queries the ACR status of the referenced subscriber.

Authorization

Basic or OAuth

HTTP Method

GET

URI

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).

Request Header

The MIME-type for the Content-Type header field is application/json.

Request Body

There is no request body.

Response Header

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".

Response Body

The response body contains the following parameters:

• acr. String. The Services Gatekeeper generated ACR.

• status. String. The current status of the ACR.

Examples

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.

Example 4-4 Query ACR Response Example

{"acr":{"status":"Expired"}}

---

Change ACR Status

The Change ACR Status operation refreshes an expired ACR to a valid status.

Authorization

Sessionless:Basic, Sessionful: Basic and Session ID, or OAuth

HTTP Method

POST

URI

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).

Request Header

The MIME-type for the Content-Type header field is application/json.

Request Body

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.

Response Header

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.

Response Body

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.

Examples

Example 4-5 shows a sample Change ACR request.

Example 4-5

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.

Example 4-6

Content-Type: application/json
Content-Length: 1234
Date: Thu, 04 Jun 2009 02:51:59 GMT
 
{"acr": "acr:0123456890123456789;ncc=23415",
"status":"Valid",
"expiry":"Thu 11 Jun 2014 02:51:59 GMT"

---

Errors and Exceptions and EDRs

Errors and Exceptions

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

EDRs

Table 4-3 lists the EDRs generated by ACR operations.

Table 4-3 ACR Operations EDRs

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