6 Adding RESTful Anonymous Customer Reference Support

This chapter describes how you can add RESTful Anonymous Customer References (ACRs) to provide secure access for Web applications in Oracle Communications Services Gatekeeper.

About Anonymous Customer References

An Anonymous Customer Reference (ACR) represents a unique identifier that replaces a subscriber's secure information, such as MSISDN or phone number, ensuring privacy when the subscriber interacts with Web applications.

According to GSM Association, an ACR is a string issued by the operator, which maps to a customer (or customers). The operator can pass the ACR in request headers, so you can create an ACR per application per user, and personalize your application based on the user's previous behavior.

Information about ACR API is available at the GSM webs site:

http://technical.openmobilealliance.org/Technical/technical-information/release-program/current-releases/rest-netapi-acr-v1-0

See the discussion on anonymous customer reference specifications in Services Gatekeeper Statement of Compliance for supported specification.

A Web application requiring an ACR for a subscriber requests one from Services Gatekeeper using the RESTful interface. Services Gatekeeper generates and manages one or more ACRs for the subscriber when requested by the Web application.

Configuring ACR Support in Services Gatekeeper

Services Gatekeeper supports ACR operations by default. After you create an ACR plug-in instance, applications can create, query and refresh ACRs using the RESTful interface on a Services Gatekeeper system.

Creating an ACR Plug-in Instance

Services Gatekeeper and the Platform Test Environment MBean interface can be used to create and manage ACR plug-ins. For information on using the Platform Test Environment, see Services Gatekeeper Platform Test Environment User's Guide.

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

  1. Log in to the Administration Console.

  2. Expand the OCSG node under Domain Structure.

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

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

  5. Select PluginManager.

  6. Click Operations.

  7. In the Select An Option 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.

Setting ACR Plug-in Parameters

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

  1. Log in to 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 want to change.

  8. Enter the new values for the attributes.

  9. Click Update Attributes.

Table 6-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.

AcrExpiredLifeTime

Integer

The number of seconds that ACR is kept in Expired state before being deleted. Default Value: 60

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 setup to route application requests containing ACR identifiers to the correct service provider group.

RESTful APIs for ACR Support

You can generate and manage ACRs in Services Gatekeeper using the RESTful API described below.

Create ACR

The Create ACR operation creates a new ACR for a subscriber based on the 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 system on which Services Gatekeeper is installed.

  • version is the supported version of the RESTful Network API for Roaming Provisioning.

  • address is the subscriber identifier MSISDN. Services Gatekeeper supports an address entry of acr:authorization, where authorization is an OAuth accessToken.

Note:

address must be URL-escaped in accordance with RFC 1738.

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 whether the ACR was successfully created. 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: Valid or Expired.

  • expiry: String. The expiration time of the ACR.

Examples

Example 6-1 shows a sample Create ACR request.

Example 6-1 Create ACR Request Example

POST http://example.com/customerReference/v1/tel%3A%2B7990123456
HTTP/1.1
Host: example.com:80
Accept: application/json
 
{"acr":{"status":"Valid"}}

Example 6-2 shows a sample Create ACR response.

Example 6-2 Create ACR Response Example

HTTP/1.1 201 Created

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 2009 02:51:59 GMT"}

Query ACR

The Query ACR operation queries for the ACR status of the referenced subscriber. The status of the ACR indicates whether the reference is valid or expired.

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 system on which Services Gatekeeper is installed.

  • version is the supported version of the RESTful Network API for Roaming Provisioning.

  • address is the subscriber MSISDN.

  • acr is the ACR for which the status query is being made, including the network-code (ncc).

Note:

address and acr must be URL-escaped in accordance with RFC 1738.

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: Valid or Expired.

Examples

Example 6-3 shows a sample Query ACR request.

Example 6-3 Query ACR Request Example

GET 
http://example.com/customerReference/v1/tel%3A%2B7990123456/acr%3A0123456890123456789%3Bncc=23415

Example 6-4 shows a sample Query ACR response.

Example 6-4 Query ACR Response Example

{"acr":{"status":"Valid"}}

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 system on which Services Gatekeeper is installed.

  • version is the supported version of the RESTful Network API for Roaming Provisioning.

  • address is the subscriber MSISDN.

  • acr is the ACR for which the status query is being made, including the network-code (ncc).

Note:

address and acr must be URL-escaped in accordance with RFC 1738.

Request Header

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

Request Body

The request body for Change ACR Status accepts the following parameters:

  • acr: String.

  • status: String.

  • expiry: String.

  • developerId: String. Required. The RESTful developer ID.

  • applicationId: String. Optional. The Services Gatekeeper application ID.

Response Header

The response header indicates whether the ACR status was successfully changed. 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 6-5 shows a sample Change ACR request.

Example 6-5 Change ACR Status Request Example

POST
http://example.com/customerReference/v1/tel%3A%2B7990123456/acr%3A0123456890123456789%3Bncc=23415 
HTTP/1.1
Host: example.com:80
Accept: application/json
 
{"acr":{"status":"Valid"}}

Example 6-6 shows a sample Change ACR response.

Example 6-6 Change ACR Status Response Example

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

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 6-2 lists the possible error codes for failed requests.

Table 6-2 ACR Operations Error Codes

Error Code Cause

303

The request to create the ACR failed, because the ACR for the MSISDN exists.

400

Bad request. Check the error message and correct the request syntax.

For example, a request with {address} whose value is "MSISDN B" is attempting to query/change acr of an {address} whose value is "MSISDN A"

401

The request from network-code A is attempting to change/query acr of network-code B

404

The request is attempting to query an invalid or expired ACR

503

Server busy and service unavailable. Retry the request.

EDRs

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

Table 6-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