Table of contents
TOC
Collapse the table of content
Expand the table of content

Connecting to R Server with mrsdeploy

j-martens|Last Updated: 2/24/2017

The mrsdeploy package, delivered with Microsoft R Client and R Server, provides functions for:

  • Establishing a remote session in a console application for the purposes of executing code on that server
  • Publishing and managing a web service that is backed by the R code block or script you provided.

Each feature can be used independently, but the greatest value is achieved when you can leverage both.

This article explains the authentication functions, the arguments they accept, and how to switch between remote and local sessions.

Authentication

This section describes how you authenticate to R Server, either on-premises or in the cloud, by using the functions in mrsdeploy.

In R Server, every API call between the Web server and client must be authenticated. The mrsdeploy functions, which place API calls on your behalf, are no different. Authentication of user identity is handled via Active Directory. R Server will never store or manage usernames and passwords.

By default, all mrsdeploy operations are available to authenticated users. Destructive tasks, such as deleting a web service from a remote execution command line, are available only to the user who initially created the service.

mrsdeploy provides two functions for authentication against R Server: remoteLogin() and remoteLoginAAD(). These functions support not just authentication, but creation of a remote R session on the R Server. By default, the remoteLogin() and remoteLoginAAD() functions log you in, create a remote R session on the R Server instance, and open a remote command prompt. The function you use depends on the type of authentication and deployment in your organization.

On premises authentication

Use the remoteLogin function in these scenarios:

  • you are authenticating using Active Directory server on your network
  • you are using the default administrator account for an on-premises instance of R Server

This function calls /user/login API, which requires a username and password. For example:

> remoteLogin(
          https://YourHostEndpoint, 
          session = TRUE, 
          diff = TRUE,
          commandline = TRUE
          username = NULL,
          password = NULL,
  )

For example, here is an AD authentication that creates a remote R session, but prompts for a username and password. That username can be the Active DIrectory/LDAP username and password, or the local admin account and its password.

>  remoteLogin("http://localhost:12800", 
            session = FALSE)

Or this example where we authenticate with the local admin account and password, create a remote R session, go to the remote session's command prompt upon login, and returns a report of the differences between local and remote environments.

>  remoteLogin("http://localhost:12800", 
            username = "admin", 
            password = "{{YOUR_PASSWORD}}",
            diff = TRUE,
            session = TRUE
            commandline = TRUE)
Note

Unless you specify otherwise using the arguments below, this function not only logs you in, but also creates a remote R session the R Server instance and put you on the remote command line. If you don't want to be in a remote session, either set session = FALSE or switch back to the local session after login and logout.

remoteLogin ArgumentDescription
endpointThe Microsoft R Server HTTP/HTTPS endpoint, including the port number. You can find this on the first screen when you launch the administration utility.
sessionIf TRUE, create a remote session. If omitted, creates a remote session.
diffIf TRUE, creates a 'diff' report showing differences between the local and remote sessions. Parameter is only valid if session parameter is TRUE.
commandlineIf TRUE, creates a "REMOTE' command line in the R console. Parameter is only valid if session parameter is TRUE. If omitted, it is the same as = TRUE.
promptThe command prompt to be used for the remote session. By default, REMOTE> is used.
usernameIf NULL, user is prompted to enter your AD or local R Server username
passwordIf NULL, user is prompted to enter password

If you do not specify a username and password as arguments to the login function, you'll be prompted for your AD or local R Server username and password.

Cloud authentication

If you are authenticating using Azure Active Directory in the cloud, use the remoteLoginAAD function. For example:

> remoteLoginAAD(
          endpoint, 
          authuri = https://login.windows.net,
          tenantid = "<AAD_DOMAIN>", 
          clientid = "<NATIVE_APP_CLIENT_ID>", 
          resource = "<WEB_APP_CLIENT_ID>", 
          session = TRUE,
          diff = TRUE,
          commandline = TRUE
  )

For example, here is an AAD authentication that will not create a remote R session, but will prompt for a username and password.

>  remoteLoginAAD(
       "https://rserver.contoso.com:12800", 
       authuri = "https://login.windows.net", 
       tenantid = "microsoft.com", 
       clientid = "00000000-0000-0000-0000-000000000000", 
       resource = "00000000-0000-0000-0000-000000000000", 
       session = FALSE 
)
Note

Unless you specify otherwise using the arguments below, this function will not only log you in, but also create a remote R session on the R Server instance and put you on the remote command line. If you don't want to be in a remote session, either set session = FALSE or switch back to the local session after login and logout.

If you do not know your tenantid, clientid, or other details, please contact your administrator. Or, if you have access to the Azure portal for the relevant Azure subscription, you can find these authentication details. For example:

remoteLoginAAD ArgumentDescription
endpointThe Microsoft R Server HTTP/HTTPS endpoint, including the port number. This is the SIGN-ON URL value from the web application
authuriThe URI of the authentication service for Azure Active Directory.
tenantidThe tenant ID of the Azure Active Directory account being used to authenticate is the domain of AAD account such as: myMRServer.contoso.com
clientidThe client ID of the AAD "native" application for the Azure Active Directory account such as 00000000-0000-0000-0000-000000000000.
resourceThe resource ID is the clientID from the AAD "Web" application for the Azure Active Directory account such as 00000000-0000-0000-0000-000000000000.
sessionIf TRUE, create a remote session. If omitted, creates a remote session.
diffIf TRUE, creates a 'diff' report showing differences between the local and remote sessions. Parameter is only valid if session parameter is TRUE.
commandlineIf TRUE, creates a "REMOTE' command line in the R console. Parameter is only valid if session parameter is TRUE.
promptThe command prompt to be used for the remote session. By default, REMOTE> is used. If omitted, it is the same as = TRUE.
usernameIf NULL, user is prompted to enter username <username>@<AAD-account-domain>
passwordIf NULL, user is prompted to enter password


Arguments for remote execution

If you plan to use mrsdeploy to start a remote session on R Server and execute code remotely, there are two key parts to the command:

  1. Create that remote session
  2. Indicate whether you'd like to open a local or remote command prompt upon login.

Take special note of the arguments session and commandline as these influence the state of your command line.

ArgumentDescription
sessionIf TRUE, create a remote session in R Server.
If omitted, it will still create a remote session.
If FALSE, do not create any remote R sessions.
commandlineIf TRUE, creates a REMOTE command line in the R console. REMOTE command line is used to interact with the remote R session. This means that after the authenticated connection is made, the user will be executing R commands remotely until they switch back to the local command line or logout. Parameter is only valid if session parameter is TRUE.

For more details on remote execution, see this article.

Access tokens

After you authenticate with Active Directory or Azure Active Directory, an access token is returned. This access token is then passed in the request header of every subsequent mrsdeploy request.

Keep in mind that every API call and every mrsdeploy function requires authentication with R Server. If the user does not provide a valid login, an Unauthorized HTTP 401 status code is returned.

Remote connection states

Depending on how you configure the session and commandline login parameters are subtle, your execution context can switch between local and remote contexts.

Create remote R session and go to remote command line (1)

In this state, we'll authenticate using one of the two aforementioned login functions with the default argument session = TRUE to create a remote R session, and the default argument commandline = TRUE to transition to the remote R command line.

Note

Unless you specify session = FALSE, this function not only logs you in, but also creates a remote R session on the R Server instance. And, unless you specify commandline = FALSE, you are on the remote command line upon login. If you don't want to be in a remote session, either set session = FALSE or switch back to the local session after login and logout.

CommandState
> remoteLogin(
         "http://localhost:12800"
    )

REMOTE>
state 1
 

When you see the default prompt REMOTE> in the command pane, you'll know that you are now interacting with your remote R session and are no longer in your local R environment:

In this example, we define an interactive authentication workflow that spans both our local and remote environments.

> # EXAMPLE: LOGIN, CREATE REMOTE R SESSION, GO TO REMOTE PROMPT

> remoteLogin("http://localhost:12800") 

REMOTE> x <- 10   # Assign 10 to "x" in remote session

REMOTE> ls()   # List objects in remote session 
[1] "x"

REMOTE> pause()  # Pause remote interaction. Switch to local 

> y <- 10      # Assign 10 to "y" in local session 

> ls()   # List objects in local session 
[1] "y"

> putLocalObject(c("y"))   # Loads local "y" into remote R session's workspace 

> resume()   # Resume remote interaction and move to remote command line 

REMOTE> ls()   # List the objects now in the remote session 
[1] "x" "y"

REMOTE> exit  # Destroy remote session and logout 

>
Important

You can only manage web services from your local session. Attempting to use the service APIs during a remote interaction will result in a error.

Create remote R session and remain with local command line (2)

In this state, you can authenticate using remoteLogin, which is one of the two aforementioned login functions with the argument session = TRUE to create a remote R session, and the argument commandline = FALSE to remain in your local R environment and command line.

CommandState
> remoteLogin(
         "http://localhost:12800",
         session = TRUE,
         commandline = FALSE
    )

>
state 2
 

In this example, we define an interactive authentication workflow that spans both our local and remote environments (just like state 1), but starts out in the local R session, and only then moves to the remote R session.


> # EXAMPLE: LOGIN, CREATE REMOTE R SESSION, STAY LOCAL

> remoteLogin("http://localhost:12800", session = TRUE, commandline = FALSE)

> y <- 10   # Assign 10 to "y" in local session 

> ls()   # List the objects in the local session 
[1] "y"

> putLocalObject(c("y"))   # Loads local "y" into remote R session's workspace 

> resume()   # Switch to remote command line for remote interaction 

REMOTE> x <- 10    # Assign 10 to "x" in remote session 

REMOTE> ls()   # List the objects now in the remote session 
[1] "x" "y"

REMOTE> exit     # Destroy remote session and logout 

>

Remain local without creating a remote R session (3)

In this state, you can authenticate with remoteLogin() and its argument session = FALSE so that no remote R session is started. Without a remote R session, you'll only have the local R environment and command line.

CommandState
> remoteLogin(
         "http://localhost:12800",
         session = FALSE
    )

>
state 3
 

In this example, we define an interactive authentication workflow without a remote R session (session = FALSE). This is useful when working only with the web service functionality of the mrsdeploy package. After authentication, we remain confined within the local R session in order to publish and consume a service.

> # EXAMPLE OF LOGIN WITHOUT REMOTE R SESSION

> remoteLogin("http://localhost:12800", session = FALSE)

> addOne <- function(x) x + 1

> api <- publishService(
            "add-one",
            code = addOne,
            inputs = list(x = "numeric"),
            outputs = list(answer = "numeric") 
         )

> res <- api$addOne(100)

> print(res$output("answer"))
[1] 101
Important

You can only manage web services from your local session. Attempting to use the service APIs during a remote interaction will result in a error.

Switch between remote and local sessions

After you log into the remote R server with the argument session = TRUE, a remote R session is created. You can switch between the remote R session and the local R session directly from the command line. The remote command line allows you to directly interact with an R Server 9.0.1 instance on another machine.

When the REMOTE> command line is displayed in the R console, any R commands entered will be executed on the remote R session.

Switch

Switching between the local command line and the remote command line is done using these functions: pause() and resume(). To switch back to the local R session, type pause(). If you have switched to the local R session, you can go back to the remote R session by typing resume().

To terminate the remote R session, type exit at the REMOTE> prompt. Also, to terminate the remote session from the local R session, type remote_logout().

Convenience FunctionsDescription
pause()When executed from the remote R session, returns the user to the local > command prompt.
resume()When executed from the local R session, returns the user to the REMOTE> command prompt, and sets a remote execution context.

Example

#execute some R commands on the remote session
REMOTE>x<-rnorm(1000)
REMOTE>hist(x)

REMOTE>pause()  #switches the user to the local R session
>resume()  

REMOTE>exit  #logout and terminate the remote R session
>

Logout of a remote session

To terminate the remote R session while you are on the remote command line, type exit at the REMOTE> prompt.

To terminate the remote session from the local R session, type remoteLogout().

See also

© 2017 Microsoft