The application programming interface (API) for the back-end application server (App Server) consists of the following service.
The access point for services in this API is the enterprise BlackBerry Proxy, or legacy Good Proxy. The access point forms the part of the BlackBerry Dynamics proxy infrastructure that is installed on the enterprise network.
Requests can be addressed to an access point by specifying its server address and port number directly. Requests could also be addressed indirectly, through a load balancer, virtual IP address, or other component of the enterprise network. The server address would be provided by the enterprise's IT or network administration. By default, a BlackBerry Dynamics enterprise access point will accept:
It is recommended that production App Servers connect over a secure connection, and that plain HTTP is only used during the development phase. See under Certificates for Service Requests, below, for details of the electronic certificates that could be required when addressing service requests on a secure connection. Any certificates that are required should be obtained from the enterprise IT or network administration.
BlackBerry Dynamics supports clustering of access point servers. If clustering is in use, then there will be a number of servers that can used as the access point for this API. A list of these servers' addresses can be obtained by utilizing the getGPSservers
service, which is documented on the enterprise access point servers list API page. Note that this API is itself hosted on an enterprise access point, so at least one server address must still be provided by the enterprise's IT or network administration, at some point. That page also describes how the App Server should select a single server from the returned list.
Service requests in this API can be sent over a secure HTTP connection, the establishment of which requires the usual presentation and trusting of electronic certificates.
When service requests are addressed to an enterprise access point over a secure connection, its certificate must be trusted by the App Server. The certificate presented will be one of the following:
The first of these is the default, applying unless action has been taken to install a different root CA on the management console.
If the certificate is signed by a management console or Enterprise CA, then a corresponding CA certificate must also be installed on the App Server as a trusted CA. If no such certificate is installed, the App Server will not be able to establish a secure HTTP connection to the access point, and hence won't be able to send service requests.
Call this service when the App Server is sent a BlackBerry Dynamics authentication token by the fron-end application. The service will verify the token, and respond accordingly.
If the token is valid then this confirms the identity of the end user of the front-end application that sent the token.
GET
/verifyGDAuthToken
HTTP/1.1
See under Addressing Service Requests, above, for details. This is a standard HTTP field.
X-Good-GD-AuthToken:
received_token Mandatory header containing the authentication token. This will have been sent to the App Server by the front-end application.
Content-Length
will be zero. The following response headers will be included.X-Good-GD-AuthResponseCode:
code description Code | Text | Description |
---|---|---|
100 | OK | The token is valid. |
200 | Unsupported version | The protocol version is unsupported (reserved for future use.) |
201 | Format not recognized | There appears to be an error in the format of the token. |
401 | Expired, or digest does not match content | The token is expired or its digest does not match its content. The App Server should communicate to the front-end application that a new token is required. Tokens are expired by the system at 24-hour intervals. The expiry interval is initially timed from when the front-end application connects to the BlackBerry Dynamics infrastructure for the first time. Subsequently, the timer restarts whenever the application connects and the token is expired. Note that token expiry time is not based on the time that the token was requested. |
500 | General error | A general error occurred. |
X-Good-GD-AuthTokenVersion:
protocol_version X-Good-GD-UserID:
user_id GDAppConfigKeyUserID
element of the getApplicationConfig (GDMac) return value.X-Good-GD-ContainerID:
container_id X-Good-GD-AuthTokenCreationTime:
timestamp X-Good-GD-AuthChallenge:
challenge challenge
parameter in the original call to the getGDAuthToken:serverName function. If there was no challenge string then the header might be omitted.X-Good-GD-Server:
server_name serverName
parameter in the original call to the getGDAuthToken:serverName function. If an empty string was passed then the header might be omitted.X-Good-GD-AppID:
gd_app_id GET /verifyGDAuthToken HTTP/1.1 Host: GoodProxyServer.corp.example.com:17433 X-Good-GD-AuthToken: Mnx1c2VyQHh5emNvcnAuY29tfDY4MzE2MzExLUJBN0MtNDU0NC05Rjl BLThEQUE3Njc3RDg1QXxjb20uZ29vZC5nZC5zYW1wbGVBcHB8MTM0NDgxMzY5NnwlfHNhbXB sZWFwcFNlcnZlci54eXouY29tfE5UWXhPRUU1UTBKQk56WkdPVE5ETlRSQlFrTTNNemxCUmp NMmFzYlRRZ1kNCg==
(Long lines have been wrapped for ease of reading, and indented.)
HTTP/1.1 200 OK Content-Length: 0 X-Good-GD-AuthResponseCode: 100 OK X-Good-GD-AuthTokenVersion: 2 X-Good-GD-UserID: ANOther@example.com X-Good-GD-ContainerID: 68316311-BA7C-4544-9F9A-8DAA7677D85A X-Good-GD-AuthTokenCreationTime: 1344813696 X-Good-GD-AuthChallenge: Resource15137487964165 X-Good-GD-Server: myappserver.corp.example.com X-Good-GD-AppID: com.example.gd.mygdappid
In this case, the challenge string was "Resource15137487964165".
HTTP/1.1 200 OK Content-Length: 0 X-Good-GD-AuthResponseCode: 401 Expired, or digest does not match content