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 2 flavors:
- Handle a log-in 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.
- 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. Note: For Elvis 5.9 and higher, this must be a relative URL on the same domain as the Elvis server. If you do specify an absolute URL with a domain, only the part of the URL after the domain will be used to redirect to. |
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. Note: For Elvis 5.9 and higher, this must be a relative URL on the same domain as the Elvis server. If you do specify an absolute URL with a domain, only the part of the URL after the domain will be used to redirect to. |
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:
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. |
clientId |
Used for tracking a check-out action to a specific client. The client that has checked-out the file will be the only client that is able to the file back in. Typically a client will generate a UUID once, store it locally and then pass it with every log-in. Optional. When not specified, client check-outs will not be tracked with a client ID. It is only required to specify this when your client performs check-outs and check-in actions. |
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. This option has been deprecated in Elvis 5. Do not use the sessionId return value, it will be removed in a future version of Elvis 5. In Elvis 5, session handling must be done using standard cookie handling of the browser (see 'Cookies' below). An Elvis 5 cluster potentially consists of multiple servers behind a load balancer. Such situations can require additional cookies to successfully remain authenticated. In Elvis 4, this parameter could be used by clients to allow cross-domain logins on an Elvis Server. The sessionId could then be added as ;jsessionid=... postfix in subsequent urls. Passing the jsessionid in the URL is not advised. Especially in load-balanced environments the jsessionid in the URL is not sufficient to remain authenticated. |
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. |
Cookies
The log-in request will set a number of session cookies which all need to be passed along with any subsequent requests made to the Elvis server to handle authentication of those requests. This is both for API calls and for URLs of thumbnails, previews and originals that are made.
In Web browser environments, the Web browser will typically handle this for you.
When API calls are made from other environments such as node.js, a Java http client, .NET, or PHP, make sure to turn on cookie handling in the HTTP(s) library that you are using. In the node.js request library for example, this is handled using the cookie 'jar' options: https://github.com/request/request.
The following table shows the cookies are currently being used by the Elvis server (depending on situation).
Note: Do not rely on these explicitly, as the names of the cookies might change at any time in the future. Simply pass all cookies received during login with subsequent requests.
JSESSIONID |
Primary Elvis session cookie. |
AWSELB | Only in AWS environments. The AWS load balancer cookie that ensures subsequent requests are sent to the same cluster node. This results in sticky sessions which provide best performance by optimizing cache usage in each of the nodes in the Elvis cluster. |
Examples
Successful login
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
}
Login with profile
The following shows the response of a successful authentication attempt.
loginhttp://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
}
Login failure
The following shows the response of a failed authentication attempt.
loginhttp://demo.elvisdam.com/services/login ?username=guest &password=wrongpassword |
{
"loginSuccess" : false,
"loginFaultMessage" : "Invalid username or password"
}
Document history
- 1 November 2018: Updated section 'Parameters' by adding clientId.
Comment
Do you have corrections or additional information about this article? Leave a comment! Do you have a question about what is described in this article? Please contact Support.
0 comments
Please sign in to leave a comment.