Configuring Managed Authentication

CDAP provides several ways via Managed authentication mode to authenticate a client's identity:

Basic Authentication
LDAP Authentication
JASPI Authentication
Custom Authentication

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

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:

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

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

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

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

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

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).

Configuring Exemptions from Authentication

Sometimes, you need to exempt certain URLs from authentication. For example, you might want to secure your entire application, except that you want to allow management of artifacts 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

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 calls to the artifact endpoints in the default namespace:

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

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