Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Configuring Authentication Mechanisms

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

Basic Authentication

The simplest way to identity a client is to authenticate against a realm file. To configure basic authentication add these properties to cdap-site.xml:

Property

Value

Description

security.authentication.handlerClassName

io.cdap.cdap.security.server. BasicAuthenticationHandler

Name of the class handling authentication

security.authentication.basic.realmfile

<filepath>

An absolute or relative path to the realm file

The realm file is of the following format:

Code Block
username: password[,rolename ...]

In CDAP Sandbox, the realm file can be specified as conf/realmfile and placed with the cdap-site.xml file. Note that it is not advisable to use this method of authentication. In production, we recommend using any of the other methods described below.

LDAP Authentication

You can configure CDAP to authenticate against an LDAP instance by adding these properties to cdap-site.xml:

Property

Value

Description

security.authentication.handlerClassName

io.cdap.cdap.security.server. LDAPAuthenticationHandler

Name of the class handling authentication

security.authentication.loginmodule.className

io.cdap.cdap.security.server. LDAPLoginModule

Name of a class used as a custom login module for authentication

security.authentication.handler.debug

false

Set to true to enable debugging

security.authentication.handler.hostname

<hostname>

LDAP server host

security.authentication.handler.port

<port>

LDAP server port

security.authentication.handler.userBaseDn

<userBaseDn>

Distinguished Name of the root for user account entries in the LDAP directory

security.authentication.handler.userRdnAttribute

<userRdnAttribute>

LDAP Object attribute for username when search by role DN

security.authentication.handler.userObjectClass

<userObjectClass>

LDAP Object class used to store user entries

In addition, you may configure these optional properties in cdap-site.xml:

Property

Value

Description

security.authentication.handler.userIdAttribute

<userIdAttribute>

LDAP Object attribute containing the username

security.authentication.handler.userPasswordAttribute

<userPasswordAttribute>

LDAP Object attribute containing the user password

security.authentication.handler.roleBaseDn

<roleBaseDn>

Distinguished Name of the root of the LDAP tree to search for group memberships

security.authentication.handler.roleNameAttribute

<roleNameAttribute>

LDAP Object attribute specifying the group name

security.authentication.handler.roleMemberAttribute

<roleMemberAttribute>

LDAP Object attribute specifying the group members

security.authentication.handler.roleObjectClass

<roleObjectClass>

LDAP Object class used to store group entries

If the LDAP instance requires binding as a specific user, you may configure these optional properties in cdap-security.xml:

Property

Value

Description

security.authentication.handler.bindDn

<bindDn>

The Distinguished Name used to bind to the LDAP server and search the directory

security.authentication.handler.bindPassword

<bindPassword>

The password used to bind to the LDAP server

To enable SSL between the authentication server and the LDAP instance, configure these properties in cdap-site.xml:

Property

Default Value

Value

Description

security.authentication.handler.useLdaps

false

true

Set to true to enable use of LDAPS

security.authentication.handler.ldapsVerifyCertificate

true

true

Set to true to enable verification of the SSL certificate used by the LDAP server

LDAP with Active Directory

The following properties are listed as "optional" for LDAP but are required if you are using LDAP with Active Directory.

  • security.authentication.handler.userIdAttribute

  • security.authentication.handler.bindDn

  • security.authentication.handler.bindPassword

When using group based authentication, you will need the following properties to further filter the access.

  • security.authentication.handler.roleBaseDn

  • security.authentication.handler.roleMemberAttribute

  • security.authentication.handler.roleNameAttribute

  • security.authentication.handler.roleObjectClass

For Active Directory, the property security.authentication.handler.userBaseDn should NOT include the group information. It should return the full list of users in the organization or domain. The group information should be included in the property security.authentication.handler.roleBaseDn and will only allow access to these users.

JASPI Authentication

To authenticate a user using JASPI (Java Authentication Service Provider Interface) add these properties to cdap-site.xml:

Property

Value

Description

security.authentication.handlerClassName

io.cdap.cdap.security.server. JASPIAuthenticationHandler

Name of the class handling authentication

security.authentication.loginmodule.className

<custom-login-module>

Name of the class of the login module handling authentication

In addition, any properties with the prefix security.authentication.handler., such as security.authentication.handler.hostname, will be provided to the handler. These properties, stripped of the prefix, will be used to instantiate the javax.security.auth.login.Configuration used by the LoginModule.

Custom Authentication

To use a Custom Authentication mechanism, set the security.authentication.handlerClassName in cdap-site.xml with the custom handler's classname. Any properties set in either cdap-site.xml or cdap-security.xml and that are prefixed with security.authentication.handler. are available through a Map<String, String> object and can be used to configure the handler.

To make your custom handler class available to the authentication service, copy your packaged jar file (and any additional dependency jars) to the security/lib/ directory within your CDAP installation (typically under /opt/cdap).

The Developer Manual Custom Authentication section shows how to create a Custom Authentication Mechanism.

Configuring Exemptions from Authentication

Sometimes you need to exempt certain URLs from authentication. For example, you may want to secure your entire application, except that you want to allow sending data to a stream by unauthenticated clients. For this, you can configure the CDAP Router to bypass the authentication for URLs that match a given regular expression, by adding this property in cdap-site.xml:

Property

Value

Description

router.bypass.auth.regex

<reg-exp>

Regular expression to match URLs that are exempt from authentication.

For example, the following configuration in cdap-site.xml will allow unauthenticated posting to all streams in the default namespace:

Code Block
<property>
  <name>router.bypass.auth.regex</name>
  <value>/v3/namespaces/default/streams/[^/]+</value>
</property>

This must be configured on every node that runs the CDAP Router.

Testing Perimeter Security

To ensure that you've configured security correctly, run these simple tests to verify that the security components are working as expected. See the CDAP Reference Manual: HTTP RESTful API for information on the conventions used for these examples. Note that if SSL is enabled for CDAP Servers, then the base URL used in these examples will use https instead of http.

  • After configuring CDAP as described above, start (or restart) CDAP and attempt to make a request:

    Code Block
    GET /v3/apps

    such as:

Expand
titleLinux
Code Block
$ curl -v -w"\n" -X GET "http://localhost:11015/v3/namespaces/default/apps"
Expand
titleWindows
Code Block
> curl -v -X GET "http://localhost:11015/v3/namespaces/default/apps"

This should return a 401 Unauthorized response with a list of authentication URIs in the response body. For example:

Code Block
{"auth_uri":["http://localhost:10009/token"]}
  • Submit a username and password to one of the authentication URIs (<auth-uri>) to obtain an AccessToken by submitting a Basic Authorization header with the username and password:

    Code Block
    GET <auth-uri> "Authorization: Basic <encoded_username_password_string>"

    Using curl, assuming a CDAP authentication server at the URI localhost:10009 and that you have defined a username:password pair such as cdap:bigdata in the realm file, you can use curl's -u option to create the header:

Expand
titleLinux
Code Block
$ curl -v -w"\n" -X GET "http://localhost:10009/token" -u cdap:bigdata
Expand
titleWindows
Code Block
> curl -v -X GET "http://localhost:10009/token" -u cdap:bigdata
  • This should return a 200 OK response with the AccessToken string in the response body (formatted to fit):

    Code Block
    {"access_token":"AghjZGFwAI7e8p65Uo7OpfG5UrD87psGQE0u0sFDoqxtacdRR5GxEb6bkTypP7mXdqvqqnLmfxOS",
      "token_type":"Bearer","expires_in":86400}
  • Reattempt the first command, but this time include the access_token as a header in the request:

    Code Block
    GET /v3/apps "Authorization: Bearer <access_token>"

    such as (formatted to fit):

Expand
titleLinux
Code Block
$ curl -v -w"\n" -X GET "http://localhost:11015/v3/namespaces/default/apps" \ -H "Authorization: Bearer AghjZGFwAI7e8p65Uo7OpfG5UrD87psGQE0u0sFDoqxtacdRR5GxEb6bkTypP7mXdqvqqnLmfxOS"
Expand
titleWindows
Code Block
> curl -v -X GET "http://localhost:11015/v3/namespaces/default/apps" ^ -H "Authorization: Bearer AghjZGFwAI7e8p65Uo7OpfG5UrD87psGQE0u0sFDoqxtacdRR5GxEb6bkTypP7mXdqvqqnLmfxOS"

This should return a 200 OK response.

  • Visiting the CDAP UI should redirect you to a login page that prompts for credentials. Entering the credentials that you have configured should let you work with the CDAP UI as normal.

...