Confidential Clients

Overview

Mobile applications can utilize the PMF client SDKs to request access to protected resources.
Other entities which are not mobile applications can do so as well. Such entities are considered as Confidential Clients.

Confidential clients are clients that are capable of maintaining the confidentiality of their authentication credentials. You can use the PMF authorization server to grant confidential clients access to protected resources, in accordance with the OAuth specification. This feature allows you to grant access to your resources to non-mobile clients, such as performance-testing applications, and any other kind of back-end that might need to request a protected resource, or use one of the PMF REST APIs, such as the REST API for push notifications.

You begin by registering a confidential client with PMF. 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.

Registered confidential clients can obtain a token to be used in all requests to the PMF. This flow is based on the client credentials flow of the OAuth specification. Note that an access token for a confidential client is valid for one hour. If you’re using a confidential client for a task that lasts more than an hour, renew the token every hour by sending a new token request.

Registering the confidential client

In the navigation sidebar of the PMF Operations Console, click Runtime Settings → Confidential Clients. Click New to add a new entry.
You must provide the following information:

  • 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. For example: Back-end Node server.
  • ID: A unique identifier for the confidential client (can be considered as a “user name”). The ID can contain only ASCII characters.
  • Secret: A private passphrase to authorize access from the confidential client (can be considered as an API key). The secret can contain only ASCII characters.
  • Allowed Scope: A confidential client that uses such ID and Secret combination is automatically granted the scope that is defined here. For more information about scopes, see 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.

Examples of scopes:

  • Protecting external resources uses the scope authorization.introspect.
  • Sending a Push Notification via the REST API uses the space-separated scope elements messages.write and push.application.<applicationId>.
  • Adapters can be protected by a custom scope element, such as accessRestricted.
  • The scope * is a catch-all scope, granting access to any requested scope.

Configurting a confidential client

Predefined confidential clients

The PMF comes with some predefined confidential clients:

test

The test client is available only in development mode. It allows you to test your resources easily.

  • ID: test
  • Secret: test
  • Allowed Scope: * (any scope)

admin

The admin client is used internally by the PMF administration service.

push

The push client is used internally by the PMF push service.

Obtaining an access token

A token can be obtained from the PMF token endpoint.

For testing purposes, you can use Postman as described below.
In a real situation, implement Postman in your back-end logic, with the technology of your choice.

  1. Make a POST request to http(s)://[ipaddress-or-hostname]:[port]/[runtime]/api/az/v1/token.
    For example: http://localhost:9080/mfp/api/az/v1/token
    • In a development environment, the PMF uses a pre-existing mfp runtime.
    • In a production environment, replace the runtime value with your runtime name.
  2. Set the request with a content-type of application/x-www-form-urlencoded.
  3. Set the following two form parameters:
    • grant_type - Set the value to client_credentials.

    • scope - Set the value to the protecting scope of your resource. If your resource is not assigned a protecting scope, omit this parameter to apply the default scope (RegisteredClient). For more information, see Scopes.

      Image of postman configuration

  4. To authenticate the request, use Basic Authentication. Use your confidential client’s ID and Secret.

    Image of postman configuration

    Outside of Postman, if you use the test confidential client, set the HTTP header to Authorization: Basic dGVzdDp0ZXN0 (test:test encoded using base64).

The response for this request will contain a JSON object, including the access token and its expiration time (1 hour).

{
  "access_token": "eyJhbGciOiJSUzI1NiIsImp ...",
  "token_type": "Bearer",
  "expires_in": 3599,
  "scope": "sendMessage accessRestricted"
}

Creating a confidential client

Using the access token

From here on, you can make requests to the desired resources by adding the HTTP header: Authorization: Bearer eyJhbGciOiJSUzI1NiIsImp ..., replacing the access token by the one you extracted from the previous JSON object.

Possible responses

In addition to the normal responses that your resource may generate, look out for a few responses that are generated by PMF.

Bearer

An HTTP 401 response status with the HTTP header WWW-Authenticate : Bearer means that no token was found on the Authorization header of the original request.

invalid_token

An HTTP 401 response status with the HTTP header WWW-Authenticate: Bearer error="invalid_token" means that the token that was sent is invalid or expired.

insufficient_scope

An HTTP 403 response status with the HTTP header WWW-Authenticate : Bearer error="insufficient_scope", scope="RegisteredClient scopeA scopeB" means that the token found in the original request did not match the scope that is required by this resource. The header also includes the expected scope.

When you issue a request, if you do not know which scope is required by the resource, use insufficient_scope to determine the required scope. For example, request a token without specifying a scope, and make a request to the resource. Then, you can extract the required scope from the 403 response and request a new token for this scope.

▲
Last modified on