1.1   Configuring Moab Web Services

This section describes the location of the MWS configuration files. It also shows some examples of how to configure logging.

To see a full reference to all configuration and logging parameters available in MWS, see 8.2  MWS Configuration.

MWS does not support LDAP and PAM authentication at the same time.

1.1.1 Home Directory

The MWS home directory contains configuration files, log files, and files that serve features of MWS such as hooks and plugins. You should set the location of the MWS home directory using the MWS_HOME property. If you do not set MWS_HOME as a Java property or as an environment variable, then MWS will use /opt/mws as the default MWS_HOME.

For documentation clarity, the default '/opt/mws/' is used in the file names for the MWS_HOME property.

1.1.2 Configuration Files

The primary configuration file is /opt/mws/etc/mws-config.groovy. If this file is missing or contains errors, MWS will not start.

Configuration files can also be placed in the /opt/mws/etc/mws.d directory. Any configuration files here get merged with /opt/mws/etc/mws-config.groovy. In case of conflict, the configuration in /opt/mws/etc/mws.d takes precedence.

MWS logging is configured in /opt/mws/etc/logback.groovy. For details on logging configuration, see 1.3  Configuring Logging.

1.1.3 LDAP Configuration Using /opt/mws/etc/mws-config.groovy

The LDAP configuration provided below is for MWS to authenticate against a single LDAP server. If you want to use LDAP to authenticate multiple servers, you must create and use a custom PAM module.

1.1.3.A  Using a Supported LDAP Directory Type

To configure an MWS connection to an LDAP server, add the following parameters to /opt/mws/etc/mws-config.groovy:

Throughout the following examples in this topic, you will see dc=acme,dc=com. 'acme' is only used as an example to illustrate what you would use as your own domain controller if your domain name was 'acme.com.' You should replace any references to 'acme' with your own organization's domain name.

Sample configuration for OpenLDAP:

Sample OpenLDAP configuration
-----------------------------

ldap.server  = "192.168.0.5"
ldap.port = 389
ldap.baseDNs = ["dc=acme,dc=com"]
ldap.bindUser = "cn=Manager,dc=acme,dc=com"
ldap.password = "*****"
ldap.directory.type = "OpenLDAP Using InetOrgPerson Schema"

Sample configuration for Microsoft Active Directory:

Sample Active Directory configuration
-------------------------------------

ldap.server  = "192.168.0.5"
ldap.port = 389
ldap.baseDNs = ["CN=Users,DC=acme,DC=com","OU=Europe,DC=acme,DC=com"]
ldap.bindUser = "cn=Administrator,cn=Users,DC=acme,DC=com"
ldap.password = "*****"
ldap.directory.type = "Microsoft Active Directory"

To configure a secure connection to the LDAP server, see 1.2.4 Securing the LDAP Connection.

1.1.3.B  Using an Unsupported LDAP Directory Type

If you are not using one of the supported directory types, you can explicitly configure MWS to work with your LDAP schema by using the following parameters:

For example:

Advanced Active Directory configuration
-----------------------------

ldap.server  = "myldaphostname"
ldap.port = 389
ldap.baseDNs = ["CN=Users,DC=acme,DC=com","OU=Europe,DC=acme,DC=com"]
ldap.bindUser = "cn=Administrator,cn=Users,DC=acme,DC=com"
ldap.password = "*****"
ldap.user.objectClass = "person"
ldap.group.objectClass = "group"
ldap.ou.objectClass = "organizationalUnit"
ldap.user.membership.attribute = "memberof"
ldap.group.membership.attribute = "member"
ldap.user.name.attribute = "sAMAccountName"

Here is a similar example for OpenLDAP. Note there is no user membership attribute in the OpenLDAP InetOrgPerson schema and therefore ldap.user.membership.attribute is set to null. This is allowable because the ldap.group.membership.attribute is set.

Advanced OpenLDAP configuration
-----------------------------

ldap.server  = "myldaphostname"
ldap.port = 389
ldap.baseDNs = ["dc=acme,dc=com"]
ldap.bindUser = "cn=Manager,dc=acme,dc=com"
ldap.password = "*****"
ldap.user.objectClass = "inetOrgPerson"
ldap.group.objectClass = "groupOfNames"
ldap.ou.objectClass = "organizationalUnit"
ldap.user.membership.attribute = null
ldap.group.membership.attribute = "memberUid"
ldap.user.name.attribute = "uid"

1.1.3.C  Overriding Attributes in a Supported LDAP Directory Type

You can also override attributes in supported directory types. For example, say you are using OpenLDAP with an NIS Schema. The group objectClass for NIS defaults to 'groupOfNames', but you want to use 'groupOfUniqueNames' instead while retaining all other defaults for NIS. You can do this by setting ldap.directory.type to 'OpenLDAP Using NIS Schema' and overriding the ldap.group.objectClass attribute as follows:

Advanced OpenLDAP configuration
-----------------------------

ldap.directory.type = "OpenLDAP Using NIS Schema"
ldap.group.objectClass = "groupOfUniqueNames"

The user class in your LDAP schema must have an attribute that uniquely identifies a user (for example: 'uid' or 'sAMAccountName').

1.1.4 PAM (Pluggable Authentication Module) Configuration Using /opt/mws/etc/mws-config.groovy

“PAM provides a way to develop programs that are independent of authentication scheme. These programs need ‘authentication modules’ to be attached to them at run-time in order to work. Which authentication module is to be attached is dependent upon the local system setup and is at the discretion of the local system administrator.” The Linux Kernel Archives (Linux-PAM) accessed October 26, 2016.

1.1.4.A  Requirements for PAM

To use PAM with MWS, the following are required:

• The PAM package must be installed, for example:

yum install pam

• The /etc/pam.d directory must contain at least one PAM configuration file. For example, here is the login configuration file from SLES:

#%PAM-1.0
auth	 requisite	pam_nologin.so
auth	 [user_unknown=ignore success=ok ignore=ignore auth_err=die default=bad]	pam_securetty.so
auth	 include	common-auth
account  include 	common-account
password include	common-password
session  required	pam_loginuid.so
session	 include	common-session
#session  optional       pam_lastlog.so nowtmp showfailed
session  optional       pam_mail.so standard

1.1.4.B  Configuring MWS to Use PAM

To configure an MWS connection to PAM, add the following parameter to /opt/mws/etc/mws-config.groovy:

For example:

pam.configuration.service = "login"

You can configure only one authentication method in /opt/mws/etc/mws-config.groovy: LDAP or PAM, but not both. If you have configured both LDAP and PAM, MWS defaults to using LDAP.

If you need multiple authentication methods, you must add them to your local PAM configuration. See your distribution documentation for details.

If you configure MWS to authenticate via PAM using local files or NIS, you need to run Tomcat as root. This configuration is highly discouraged and is not supported by Adaptive Computing. The recommended approach is to configure PAM and NSS to authenticate against LDAP.

For more information about PAM, see the SUSE and Red Hat documentation.

1.1.5 OAuth Configuration Using /opt/mws/etc/mws-config.groovy

OAuth is a security framework designed to simplify authentication in web technologies. In the case of MWS, OAuth allows trusted client applications to securely delegate authentication to MWS. Once MWS has authenticated a user by verifying the username and password in LDAP, PAM, or NIS, MWS returns an access token to the client. The client then presents this access token to MWS to access resources. OAuth is very flexible and allows MWS to work in many different scenarios by use of grant types. For more information on OAuth and grant types, see the OAuth documentation.

1.1.5.A  OAuth Client Terminology

Resource Owner: The person accessing and manipulating data. For MWS, this would be the person who logs into the client (the user).

Client: The application that wants to access a resource. For MWS, this is Viewpoint.

Protected Resource: The data for which protection is desired. For MWS, this would be Moab itself, and interaction with Moab.

Access Token: Instead of user credentials, OAuth uses tokens to issue requests, and the tokens get signed to indicate authorization.

1.1.5.B  Register Viewpoint as a Client in MWS

Oauth is used with Viewpoint and requires client registration. Its client credentials are used to validate that the client (viewpoint) is allowed to authenticate on behalf of a resource owner. It involves giving the client its own credentials (username and password). MWS will first authenticate the client using a client id (viewpoint) and client secret (password), then will authenticate the resource owner.

If using Viewpoint, configure the following line in /opt/mws/etc/mws-config.groovy:

viewpoint.clientSecret = "<ENTER-CLIENTSECRET-HERE>"

Replace <ENTER-CLIENTSECRET-HERE> with your client secret (password) for Viewpoint.

1.1.5.C  Obtaining an Access Token from MWS for Viewpoint (Logging In)

Before the viewpoint client can access private data in MWS, it must obtain an access token that grants access to the API. The token endpoint URL is only used to gain an access token and log in a user.

Getting a viewpoint access token:

POST https://localhost:8080/mws/rest/oauth/token?api-version=3
Adding header: 
     "Content-Type: application/x-www-form-urlencoded"
Request body (String):
grant_type=password&client_id=viewpoint&client_secret=THE_CLIENT_SECRET&username=RESOURCE_OWNER_USERNAME&password=RESOURCE_OWNER_PASSWORD

Example using curl:

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -v -d 'grant_type=password&client_id=viewpoint&client_secret=pkyiW5JYQFN/jf95kuqH3LKtWtI/qJCD&username=moab-admin&password=changeme!' 'https://localhost:8080/mws/oauth/token'

Produces the following sample response:

* About to connect() to localhost port 8080 (#0)
*   Trying 127.0.0.1... connected
* Connected to localhost (127.0.0.1) port 8080 (#0)
> POST /mws/oauth/token HTTP/1.1
> User-Agent: curl/7.19.7 (x86_64-redhat-linux-gnu) libcurl/7.19.7 NSS/3.14.0.0 zlib/1.2.3 libidn/1.18 libssh2/1.4.2
> Host: localhost:8080
> Accept: */*
> Content-Type: application/x-www-form-urlencoded
> Content-Length: 126
> 
< HTTP/1.1 200 OK
< Server: Apache-Coyote/1.1
< Cache-Control: no-store
< Pragma: no-cache
< Set-Cookie: JSESSIONID=6CE8F9E7C454575FABCF3D156B153CFD; Path=/mws
< Content-Type: application/json;charset=UTF-8
< Transfer-Encoding: chunked
< Date: Fri, 13 May 2024 18:16:42 GMT
< 
* Connection #0 to host localhost left intact
* Closing connection #0
{"access_token":"b693eec0-6c93-4540-8b2f-1e170be08046","token_type":"bearer","expires_in":43096,"scope":"read write"}

1.1.5.D  Sending the Access Token to MWS When Requesting Protected Resource

After the client obtains an access token, it will send the access token to MWS in an HTTP authorization header for each rest call.

The client is responsible for handling user sessions with each access token, meaning the client has to request a new access token when a new user logs in.

Requesting an MWS resource (getting list of all nodes for example):

GET https://localhost:8080/mws/rest/nodes?api-version=3&fields=name
Adding authorization header: 
     "Authorization: Bearer ACCESS_TOKEN"

Example using curl:

curl -X GET -H "Authorization: Bearer b693eec0-6c93-4540-8b2f-1e170be08046" -v 'https://localhost:8080/mws/rest/nodes?api-version=3&fields=name'

Produces the following sample response:

* About to connect() to localhost port 8080 (#0)
*   Trying 127.0.0.1... connected
* Connected to localhost (127.0.0.1) port 8080 (#0)
> GET /mws/rest/nodes?api-version=3&fields=name HTTP/1.1
> User-Agent: curl/7.19.7 (x86_64-redhat-linux-gnu) libcurl/7.19.7 NSS/3.14.0.0 zlib/1.2.3 libidn/1.18 libssh2/1.4.2
> Host: localhost:8080
> Accept: */*
> Authorization: Bearer b693eec0-6c93-4540-8b2f-1e170be08046
> 
< HTTP/1.1 200 OK
< Server: Apache-Coyote/1.1
< Content-Type: application/json;charset=UTF-8
< Pragma: no-cache
< Set-Cookie: JSESSIONID=6CE8F9E7C454575FABCF3D156B153CFD; Path=/mws
< Content-Type: application/json;charset=UTF-8
< Content-Language: en-US
< Transfer-Encoding: chunked
< Date: Fri, 13 May 2024 18:39:07 GMT
< 
{"totalCount":3,"resultCount":3,"results":[{"name":"node1"},{"name":"node2"},{"name":"node3"}]}

Related Topics 

• 1.2  Setting up MWS Security
• 1.4  Version and Build Information