Client Authentication

Client authentication in CDAP consists of two components:

  • Authentication Server: Clients must first authenticate with the authentication server using valid credentials. The authentication server integrates with different authentication backends (LDAP, JASPI plugins) using a plugin API. Once authenticated, clients are issued an access token representing their identity.

  • CDAP Router: The CDAP router serves as the secured host in the perimeter security model. All client calls to the cluster go through the router, and must present a valid access token when security is enabled.

CDAP Authentication Process

CDAP provides support for authenticating clients using OAuth 2 Bearer tokens, which are issued by the CDAP authentication server. The authentication server provides the integration point for all external authentication systems. Clients authenticate with the authentication server as follows:

  1. Client initiates authentication, supplying credentials.

  2. Authentication server validates supplied credentials against an external identity service, according to configuration (LDAP, Active Directory, custom).

    1. If validation succeeds, the authentication server returns an Access Token to the client.

    2. If validation fails, the authentication server returns a failure message, at which point the client can retry.

  3. The client stores the resulting Access Token and supplies it in subsequent requests.

  4. CDAP processes validate the supplied Access Token on each request.

    1. If validation succeeds, processing continues to authorization.

    2. If the submitted token is invalid, an "invalid token" error is returned.

    3. If the submitted token is expired, an "expired token" error is returned. In this case, the client should restart authorization from step #1.

Supported Authentication Mechanisms

CDAP provides several ways to authenticate a client's identity:

  • Basic Authentication

  • LDAP Authentication

  • JASPI Authentication

  • Custom Authentication

To configure security, see Security.

Obtaining an Access Token

Obtain a new access token by calling:

GET <base-auth-url>/token

The <base-auth-url> can be found either by making a request and retrieving the authentication URI (auth_uri) in the response body or by knowing the configuration of the CDAP server for the security.auth.server.announce.address and port, as described in Security.

The required header and request parameters may vary according to the external authentication mechanism that has been configured. For username and password based mechanisms, the Authorization header may be used:

Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW

HTTP Responses

Status Codes

Description

Status Codes

Description

200 OK

Authentication was successful and an access token will be returned

401 Unauthorized

Authentication failed

Success Response Fields

Response Fields

Description

Response Fields

Description

access_token

The Access Token issued for the client. The serialized token contents are base-64 encoded for safe transport over HTTP.

token_type

In order to conform with the OAuth 2.0 Bearer Token Usage specification (RFC 6750), this value must be "Bearer".

expires_in

Token validity lifetime in seconds.

Example

Sample request:

GET <base-auth-url>/token HTTP/1.1 Host: server.example.com Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW

Sample response:

Comments

  • Only Bearer tokens (RFC 6750) are currently supported

Authentication with Microservices Endpoints

When security is enabled on a CDAP cluster, only requests with a valid access token will be allowed by CDAP. Clients accessing CDAP Microservices endpoints will first need to obtain an access token from the authentication server, as described above, which will be passed to the router daemon on subsequent HTTP requests.

The following request and response descriptions apply to all CDAP Microservices endpoints:

The <base-url> is typically http://<host>:11015 or https://<host>:10443, as described in the Microservices Conventions.

In order to authenticate, all client requests must supply the Authorization header:

For CDAP-issued access tokens, the authentication scheme must always be Bearer.

HTTP Responses

Status Codes

Description

Status Codes

Description

200 OK

Authentication was successful and an access token will be returned

401 Unauthorized

Authentication failed

403 Forbidden

Authentication succeeded, but access to the requested resource was denied

Error Response Fields

Response Fields

Description

Response Fields

Description

error

An error code describing the type of failure (see Error Code Values)

error_description

A human readable description of the error that occurred

auth_uri

List of URIs for running authentication servers. If a client receives a 401 Unauthorized response, it can use one of the values from this list to request a new access token.

Error Code Values

Response Fields

Description

Response Fields

Description

invalid_request

The request is missing a required parameter or is otherwise malformed

invalid_token

The supplied access token is expired, malformed, or otherwise invalid. The client may request a new access token from the authorization server and try the call again.

insufficient_scope

The supplied access token was valid, but the authenticated identity failed authorization for the requested resource

Example

A sample request and responses for different error conditions are shown below. Header values are wrapped for display purposes.

Request:

Missing token:

Invalid or expired token:

Comments

  • The auth_uri value in the error responses indicates where the authentication server(s) are running, allowing clients to discover instances from which they can obtain access tokens.

Created in 2020 by Google Inc.