Learn how to allow confidential clients to connect to mobile
services in a secure way. For example, you 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. You 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 your 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):
- Select Runtime Settings in the console navigation
sidebar, and then select the Confidential Clients
tab.
- Select Create New to register a new confidential
client.
- 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.
- Select Save. You can now see your new registered
client in the confidential-clients table.
You 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:
- 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.
- Encode the result string to Base64 format.
- 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:
- grant_type - this value must be set to "client_credentials".
- scope - the requested scope, as a space-separated list
of zero or more scope elements. See OAuth scopes.
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