Logo Help Center

Elvis 4 REST API - login

Elvis 4 REST API - login

GET/POST

http://yourserver.com/services/login
    ?cred=<base64 credentials>
    &username=<username>
    &password=<password>
    &nextUrl=<URL for next page>
    &failUrl=<URL for fail page>
    &locale=<language_COUNTRY_variant>
    &timezoneOffset=<timecode>
    &clientType=api_...
    &returnProfile=true

What does it do?

Authenticates your browser session.

All other REST calls require an authenticated session, otherwise they will respond with a "401 Unauthorized" status.

The login service can be used in two flavors:

  1. Handle an AJAX login request

Use this if you want maximum control on the client side over what happens. It returns a JSON response with details about the result of your authenticate request. This mechanism is also used by the auto login function of the Elvis JavaScript library.

  1. Handle form based login

Forwards to a 'success' or 'failure' URL after the authentication attempt. Use this to build a simple login page, see the following sample at GitHub. You can also tell the JavaScript library to use your login page whenever authentication is required.

Parameters

cred

Base 64 encoded credentials.

cred=<base64Encode( username + ":" + password )>

Base64 encoding is not secure. Use https to make login secure.

Optional. Either cred or username and password must be specified.

username

The username to be used to login. This should match a valid username from the LDAP or ActiveDirectory server or from the internal Elvis users. Sometimes an LDAP configuration supports various usernames for one user.

Optional. Either cred or username and password must be specified.

password

The password for the user. Since this is passed to the server as plain text, use https to make login secure.

Optional. Either cred or username and password must be specified.

nextUrl

When specified, the service will send a 301 redirect to this URL after a successful login.

Optional. When not specified, a JSON response with login details will be returned.

failUrl

When specified, the service will send a 301 redirect to this URL if login fails.

Optional. When not specified, a JSON response with login failure details will be returned.

locale

The locale to be used for this user to format locale sensitive information like dates and numbers.

A locale has one of the following formats:

<language code>

<language code>_<country code>

The language argument is a valid ISO Language Code. These codes are the lower-case, two-letter codes as defined by ISO-639.

The country argument is a valid ISO Country Code. These codes are the upper-case, two-letter codes as defined by ISO-3166.

Examples:

  • locale=de
  • locale=fr
  • locale=nl_BE

Optional. When not specified, the locale configured on the server will be used.

timezoneOffset

The timezone for this user, used to format dates. Must be specified as base timezone offset in milliseconds to GMT. For example:

America/Los_Angeles

Base GMT offset: -8:00

= -28800000 milliseconds

timezoneOffset=-28800000

Europe/Paris,

Base GMT offset: +1:00

= 3600000 milliseconds

timezoneOffset=3600000

Optional. When not specified, the timezone configured on the server will be used. If specified, the locale MUST also be specified, otherwise the timezoneOffset is ignored.

clientType

Custom client type that will be displayed in the usage history of the asset. Used to track which interface was used to perform the operation. The client type must be prefixed with "api_", for example: "api_MyPublicWebsite".

Optional. When not specified, operations will be tracked without a client type.

returnProfile

Specify 'true' to return profile with login response.

Optional. When not specified, profile details are not returned.

Return value

When nextUrl and failUrl are set, the service will respond with a 302 redirect. This will change the URL of the browser and navigate to the 'next' URL.

When nextUrl and failUrl are not set, the service returns a JSON response with the following information:

loginSuccess

true | false

Indicates if login was successful.

sessionId

The session ID.

Useful if you are doing cross-domain calls to an Elvis Server, since session cookies are not accepted when received through a cross-domain AJAX call. You will have to store the sessionId yourself and add ;jsessionid=<received id> to the URL of each subsequent call made to the Elvis Server. When you use the JavaScript library to perform the login, this will be done for you automatically.

serverVersion

The version of the server. This can be used to check if the Elvis Server you are connecting to meets your minimum server version requirements.

loginFaultMessage

A message indicating why login failed.

Only returned when loginSuccess is false.

userProfile

An object with details about the user.

Only returned when loginSuccess is true and the returnProfile parameter is set to true.

For details about the properties in the object, see REST profile.

Examples

AJAX login with success

The following shows the response of a successful authentication attempt.

login

http://demo.elvisdam.com/services/login    
    ?username=guest
    &password=guest
{
  "sessionId" : "d7nkuyltv5z81tilxftfcu6ob",
  "serverVersion" : "3.0.3.622",
  "loginSuccess" : true
}

AJAX login with profile

The following shows the response of a successful authentication attempt.

login
http://demo.elvisdam.com/services/login    
    ?username=demo
    &password=demo
    &returnProfile=true
{
  "sessionId" : "rkz4i6kajppg1cdsqff1xdui5",
  "serverVersion" : "3.0.3.622",
  "userProfile" : {
    "authorities" : [ "ROLE_USER", ... ],
    "username" : "demo",
    "fullName" : "Demo User",
    "userZone" : "/Users/demouser",
    "groups" : [ "department1" ],
    "email" : "user@example.com"
  },
  "loginSuccess" : true
}

AJAX login failure

The following shows the response of a failed authentication attempt.

login
http://demo.elvisdam.com/services/login    
    ?username=guest
    &password=wrongpassword
{
      "loginSuccess" : false,
      "loginFaultMessage" : "Invalid username or password"
    }
Was this article helpful?
0 out of 0 found this helpful / Created: / Updated:
Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.