blackberry.com
BlackBerry Dynamics
Runtime library for iOS applications
from the application developer portal

Authentication Token Back-End API

The BlackBerry Dynamics authentication token mechanism has both front-end and back-end parts. This page covers the back-end part, which is used by the application server.

See also:
GDUtility for the front-end part, which is used by the application on the mobile device or computer, and for an overall description of the feature.

Services

The application programming interface (API) for the back-end application server (App Server) consists of the following service.

verifyGDAuthToken Verify a BlackBerry Dynamics authentication token and confirm the identity of the end user.

Addressing Service Requests

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:

  • Plain HTTP connections on port 17080.
  • Secure HTTP connections on port 17433.

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.

Certificates for Service Requests

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:

  • Certificate signed by the Certificate Authority (CA) generated for the management console during installation.
  • Certificate signed by an Enterprise CA.
  • Certificate signed by a trusted third party CA.

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.

verifyGDAuthToken Service

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.

Method
GET
Path
/verifyGDAuthToken
Protocol
HTTP/1.1
Host
Enterprise access point address and port number

See under Addressing Service Requests, above, for details. This is a standard HTTP field.

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

See also:
GDUtility
Response
The service returns a standard HTTP/1.1 response. The status will be 200, if the service received the request. The Content-Length will be zero. The following response headers will be included.
X-Good-GD-AuthResponseCode: code description
This header will contain a numeric status code, possibly followed by a status text. The codes used are as follows:
CodeTextDescription
100OKThe token is valid.
200Unsupported versionThe protocol version is unsupported (reserved for future use.)
201Format not recognizedThere appears to be an error in the format of the token.
401Expired, 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.

500General errorA general error occurred.
X-Good-GD-AuthTokenVersion: protocol_version
This header will contain the version number of BlackBerry Dynamics protocol that was used to generate the token.
X-Good-GD-UserID: user_id
This header will contain the user identifier of the end user that activated the front-end application that sent the token. Typically, this is the enterprise email address of the user. The same value would be found in the GDAppConfigKeyUserID element of the getApplicationConfig (GDiOS) return value.
X-Good-GD-ContainerID: container_id
This header will contain a unique container identifier, assigned to the front-end application by the enterprise management console at activation time.
X-Good-GD-AuthTokenCreationTime: timestamp
This header will contain the UTC time at which the token was created, represented as a numeric time stamp.
X-Good-GD-AuthChallenge: challenge
This header will contain the challenge string provided by the front-end application when the token was created. This will be the value of the 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
This header will contain the server name provided by the front-end application when the token was created. This will be the value of the 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
This header will contain the BlackBerry Dynamics entitlement identifier of the front-end application that sent the token. The App Server should check that the value corresponds to an application with which it expects to communicate.
Examples

Verify authentication token

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

Token verified response

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

Token expired response

 HTTP/1.1 200 OK
 Content-Length: 0
 X-Good-GD-AuthResponseCode: 401 Expired, or digest does not match content