For up-to-date product documentation, see the IBM MobileFirst Foundation Developer Center.


Confidential clients

Learn how to allow confidential clients to connect to mobile services in a secure way. For example, we can grant a back-end service access to the Push service.


Overview

Confidential clients are clients that are capable of maintaining the confidentiality of their authentication credentials. We can use the MobileFirst authorization server to grant confidential clients access to protected resources, in accordance with the OAuth specification. This feature allows you to grant access to our resources to non-mobile clients, such as performance-testing applications. You begin by registering a confidential client with MobileFirst Server. As part of the registration, you provide the credentials of the confidential client, which consist of an ID and a secret. In addition, you set the client's allowed scope, which determines the scopes that can be granted to this client. When a registered confidential client requests an access token from the authorization server, the server authenticates the client by using the registered credentials, and verifies that the requested scope matches the client’s allowed scope.


Registering confidential clients

Register and manage confidential clients by using IBM MobileFirstâ„¢ Platform Operations Console (the console):

  1. Select Runtime Settings in the console navigation sidebar, and then select the Confidential Clients tab.
  2. Select Create New to register a new confidential client.
  3. In the Create Confidential Client dialog window, provide the requested configuration parameters:

    • Display Name - an optional display name that is used to refer to the confidential client. The default display name is the value of the ID parameter.
    • ID - a unique identifier of the confidential client.
    • Secret - the secret that is used to authenticate the identity of the client.
    • Allowed Scope - the client's allowed scope. The scope is a space-separated list of scope elements. See OAuth scopes.
      An element of an allowed scope can also include the special asterisk wildcard character (*), which signifies any sequence of zero or more characters. For example, if the scope element is "send*", the confidential client can be granted access to scopes that contain any scope element that starts with "send", such as "sendMessage". The asterisk wildcard can be placed at any position within the scope element, and can also appear more than once.
      An allowed-scope parameter that consists of a single asterisk character (*) indicates that the confidential client can be granted a token for any scope.
  4. Select Save. We can now see your new registered client in the confidential-clients table.
    We can delete clients or edit their registration information, at any time, by selecting the relevant action icon for the client entry in the table.

You might also see in the console's confidential-clients table the following preregistered MobileFirst confidential clients:


Acquiring access tokens

To obtain an access token, the confidential client sends an access-token request with the "client_credentials" grant type, as described in the OAuth specification. The token request is an HTTP POST request that is sent to the URL of the token endpoint. The URL pattern for accessing the token endpoint is as follows (replace the <...> placeholders with your custom data):

http(s)://<server_ip>:<server_port>/<project_name>/api/az/v1/token In the request, include the HTTP authorization header. The authorization server uses this header to authenticate the confidential client. Follow these steps to construct the authorization header:

  1. Create a string that consists of the client ID and secret, separated by a colon (:). For example, for a testClient ID and a testSecret secret, use the string testClient:testSecret.
  2. Encode the result string to Base64 format.
  3. Add the string "Basic " before the encoded Base64 string.
For example, the authorization header for the client ID testClient and the client secret testSecret is formed in the following manner:

Authorization: Basic dGVzdENsaWVudDp0ZXN0U2VjcmV0 In addition to the authorization header, add the following two parameters to the request, using the application/x-www-form-urlencoded format:

When the authorization server receives the request, it authenticates the confidential client, and verifies that the requested scope is included in the client's allowed scope (as defined during registration). Each scope element in the requested scope must match one of the elements in the allowed scope (including wildcard expressions). If the request is accepted, the server issues an access token with the requested scope, and passes it to the client as a JSON object within the response. Following is an example of a response JSON object; (actual access tokens are longer than shown in the example):

{ "access_token": "eyJhbGciOiJSUzI1NiIsImp3ay", "token_type": "Bearer", "expires_in": 3600, "scope": "sendMessage" } For more information about access tokens, see Access tokens. For information about the access-token response, see Access-token response.


Accessing protected resources

After the confidential client acquires an access token, it can use this token to access protected resources, such as adapter resources or MobileFirst Server endpoints. The client provides the access token by adding an HTTP authorization header to the HTTP request. The value of the header is constructed by inserting the string "Bearer " before the access token. Following is an example of a resource-request header:

Authorization: Bearer eyJhbGciOiJSUzI1NiIsImp3ay

Parent topic: MobileFirst security framework