Child pages
  • Guide to API Authentication - Secure Remote Logins
Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

Version 1 Next »

 

Introduction

cPanel & WHM supports secure remote logins via the Cpanel::LogMeIn module.

Important:

  • API calls that use a method that includes a URL must use the correct port:
    • 2082 — Unsecure calls to cPanel's APIs.
    • 2083 — Secure calls to cPanel's APIs.
    • 2086 — Unsecure calls to WHM's APIs, or to cPanel's APIs via the WHM API.
    • 2087 — Secure calls to WHM's APIs, or to cPanel's APIs via the WHM API.
    • 2095 — Unsecure calls to cPanel's APIs via a Webmail session.
    • 2096 — Secure calls to cPanel's APIs via a Webmail session.
    Otherwise-correct calls will return Permission denied or Function not found errors if they use an incorrect port number. 
  • This document only includes cPanel & WHM authentication methods. For Manage2 authentication information, read our Guide to the Manage2 API documentation.

Secure remote logins

To allow users to log in to cPanel & WHM remotely, write a script that calls the Cpanel::LogMeIn module's get_loggedin_url() subroutine. This subroutine returns a URL for remote logins to cPanel, WHM, or Webmail.

  • In cPanel & WHM version 11.38.0 and earlier, the URL is a single-use URL.
  • cPanel & WHM version 11.38.1 introduced reusable remote login URLs. These URLs expire when the user logs out, or after a normal session timeout.

Parameters

When you call the get_loggedin_url() subroutine, you must pass in the following parameters:

ParameterTypeDescriptionPossible valuesExample
userstring

Required

The cPanel, WHM, or Webmail username.

A valid username.

In most scripts, retrieve this value from user input.

username
passstring

Required

The account's password.

A secure password.

In most scripts, retrieve this value from user input.

12345luggage
hostnamestring

Required

The cPanel, WHM, or Webmail account's main domain.

A valid domain on the server.example.com
servicestring

Required

The account's service type.

  • cpanel
  • whm
  • webmail
cpanel
goto_uristring

Required

The location to which the script will redirect the user. The get_loggedin_url() subroutine uses this value to create the URL.

A valid path, relative to the /usr/local/cpanel/base/ directory./frontend/paper_lantern/park/index.html

Returns

The get_loggedin_url() subroutine returns the following values:

ReturnTypeDescriptionPossible valuesExample
login_okbooleanWhether the function authenticated the user successfully.
  • 1 — Success.
  • 0 — Failure.
1
login_messagestringA status message from the subroutine.
  • Login OK
  • An error message.
Login OK
login_urlstringThe secure remote login URL.A valid URL that includes a valid session token and directs the user to the goto_uri path.https://example.com:2083/cpsess##########/frontend/paper_lantern/park/index.html

Example Perl script

 Click to view...

Note:

This script reuses the session URL. For cPanel & WHM version 11.38.0 and earlier, you must call the get_loggedin_url() subroutine each time that you generate a URL. 

#!/usr/bin/perl 
 
use lib '/usr/local/cpanel';
use Cpanel::LogMeIn ();
  
# The cPanel, WHM, or Webmail username entered at login.
my $user    = 'YYYYYY'; 
 
# The cPanel, WHM, or Webmail password entered at login. 
my $pass    = 'XXXXXX';
 
# The cPanel, WHM, or Webmail account's main domain.
my $host    = 'localhost';
 
# The service to log in to (cpanel, whm, or webmail).
my $service = 'cpanel';
 
# Call the get_loggedin_url subroutine.
my ( $login_ok, $login_message, $login_url, $security_token ) = Cpanel::LogMeIn::get_loggedin_url(
    'user'     => $user,
    'pass'     => $pass,
    'hostname' => $host,
    'service'  => $service,
    'goto_uri' => '/'
);
  
# Set up HTTP headers with the returned values.
if ($login_ok) {
    print "Location: $login_url\r\n\r\n";
}
else {
    print "Content-type: text/plain\r\n\r\n";
    print "LOGIN FAILED: $login_message\n";
}
  
# Call the get_loggedin_url subroutine for a different URL.
( $login_ok, $login_message, $login_url, $security_token ) = Cpanel::LogMeIn::get_loggedin_url(
    'active_token_for_reuse'    => $security_token,                                                                                                                                                   
    'user'     => $user,
    'pass'     => $pass,
    'hostname' => $host,
    'service'  => $service,
    'goto_uri' => '/frontend/paper_lantern/park/index.html'
);
  
# Set up HTTP headers with the returned values.
if ($login_ok) {
    print "Location: $login_url\r\n\r\n";
}
else {
    print "Content-type: text/plain\r\n\r\n";
    print "LOGIN FAILED: $login_message\n";
}
  • No labels