auth(): Authenticates a user name and password for a database on the z/TPF system

Authenticates a user name and password for a database on the z/TPF system.

Last updated

Added for PUT13.

Format

Use the following format to authenticate a user name and password for a database on the z/TPF system by using the default MONGODB-CR protocol: 
  db.auth(<username>, <password>)
Use the following format to authenticate a user name and password for a database on the z/TPF system by using the authentication mechanism that you specify: 
  db.auth( 
	  {
     user: <username>,
     pwd: <password>,
     mechanism: <authenticationMechanism>,
     digestPassword: <boolean>
    }
 )
user: username
Specifies the user name that you want to authenticate, where username is a string that contains the user name. The maximum length of this string is 32 bytes.
pwd: password
Specifies the password for the user name that you want to authenticate, where password is a string that contains the password.
mechanism: authenticationMechanism
Specifies the authentication mechanism that you want to use, where authenticationMechanism is a string that contains the authentication mechanism. Specify one of the following values:
MONGODB-CR
The MongoDB Challenge Response (MONGODB-CR) protocol that creates an MD5 hash of the password and passes the hash to the server for authentication. Authentication by using this mechanism calls the UATH_mongodb_cr entry point in the MongoDB authentication user exit (UATH).

This is the default mechanism for the z/TPF system.

PLAIN
The PLAIN Simple Authentication and Security Layer (SASL) mechanism that passes the user name and password in plain text. Authentication by using this mechanism calls the UATH_mongodb_cr entry point in the MongoDB authentication user exit (UATH). If you use this mechanism, you must specify the digestPassword parameter and set the value to false.
digestPassword: boolean
Indicates whether you want to create a digest for the password or to pass the password in plain text, where boolean is a value of true or false. If you use the PLAIN SASL mechanism, you must specify this parameter and set the value to false. If you use the MONGODB-CR protocol, set the value to true or do not specify the parameter so that the default value of true is used.

Return conditions

A value of 0 indicates that the authentication was not successful. A value of 1 indicates that authentication was successful.

Programming considerations

  • When z/TPF support for MongoDB is started in secure mode, the remote client must be authenticated before you can access the z/TPF data by using this interface.
  • You can use the logout MongoDB command to log out an authenticated remote client.
  • If you use the auth() method on a session that was already authenticated, the previous authentication information is overwritten.
  • By default, authentication is accomplished by using the MongoDB authentication user exit (UATH). For more information about the interfaces and examples of the MongoDB authentication user exit (UATH), see the code comments in the user exit (uath.cpp).
  • To use the PLAIN SASL mechanism, ensure that your MongoDB remote client includes Secure Sockets Layer (SSL).
  • The authenticated user name is used as the ECB owner name when the request is being processed. User names that are greater than 8 bytes might be truncated when they are used as the ECB owner names.

Examples

The following example uses a MongoDB shell to authenticate the remote client with the monguser user name and the mongpwd password by using the default MONGODB-CR protocol.
db.auth("monguser", "mongpwd");
The following example uses a MongoDB shell to authenticate the remote client with the monguser user name and the mongpwd password by using the PLAIN SASL mechanism.
db.auth(
   {
    user: "monguser",
    pwd: "mongpwd",
    mechanism: "PLAIN",
    digestPassword: false
   }
);
The following example uses a MongoDB Java™ client driver to connect and authenticate the remote client with the monguser user name and the mongpwd password against the database with the name of tpfdf by using the MONGODB-CR protocol. If you use the MongoDB Java client driver, credentials are associated with each MongoClient object. 
MongoCredential credential = MongoCredential.createMongoCRCredential("monguser", 
                             "tpfdf", "mongpwd".toCharArray());
ServerAddress checkIn=new ServerAddress("ztpf.mydomain.com", 27017);
MongoClient mongoClient = new MongoClient(checkIn, Arrays.asList(credential));
The following example uses a MongoDB Java client driver to connect and authenticate the remote client with the monguser user name and the mongpwd password against the database with the name of tpfdf by using the PLAIN SASL mechanism. If you use the MongoDB Java client driver, credentials are associated with each MongoClient object. 
MongoCredential credential = MongoCredential.createPlainCredential("monguser", 
                             "tpfdf", "mongpwd".toCharArray());
ServerAddress checkIn=new ServerAddress("ztpf.mydomain.com", 27017);
MongoClient mongoClient = new MongoClient(checkIn, Arrays.asList(credential));