The AuthService.svc authentication service

Glossary Item Box

To pass the authentication, call the Login() method of the AuthService.svc service. The service request string is as follows:

http(s)://[bpm'online application address]/ServiceModel/AuthService.svc/Login

Example:

https://mycompany.bpmonline.com/ServiceModel/AuthService.svc/Login

Service request parameters:

Method: POST
ContentType: application/json

The request must pass bpm’online user credentials. The credentials are passed in the form of a JSON object with the following properties.

UserName: Bpm’online user name
UserPassword: Bpm’online user password

The titles of the reply to the POST request contain authentication cookies that must be saved on the client side or a client PC and used for future requests to bpm’online web services.

The reply also contains a JSON object of the authentication status. The primary properties of the returned JSON object are available in table 1.

Table 1. General properties of the authentication status JSON object

Property	Description
Code	Authentication status code. The authentication is successful if the value is “0”. Otherwise the authentication has failed.
Message	The message that contains the reason for failing the authentication.
Exception	The object that contains a detailed description of an exception that caused the authentication to fail.

An example of calling the AuthService.svc

This example contains an implementation of a C# console application that creates a request to the AuthService.svc for user authentication. User credentials are passed to the TryLogin() method as incoming parameters “userName” and “userPassword”. The method returns true upon successful authentication and false if the authentication has failed. A message with the reason for failed authentication will be sent to console.

To implement this example, create a simple console C# application in the Visual Studio: “RequestAuthentification” Add the System.Web.Extensions.dll system library (Fig. 1) to the dependencies (References) of the Visual Studio project. This library is needed for conversion of the authentication status JSON object from a string to a C# object (de-serialization).

Fig. 1. Visual Studio project dependencies

Add the following program code to the Program.cs file of the created application:

using System;
using System.IO;
using System.Net;

namespace RequestAuthentification
{
    // Auxiliary class for de-serialization of the JSON object from the HTTP reply.
    class ResponseStatus
    {
        public int Code { get; set; }
        public string Message { get; set; }
        public object Exception { get; set; }
        public object PasswordChangeUrl { get; set; }
        public object RedirectUrl { get; set; }
    }

    // Primary class of the application.
    class Program
    {
        // HTTP address of the application.
        private const string baseUri = "http://mybpmonlineapp.com";
        // Container for Cookie authentication in bpm'online. Must be used in subsequent requests.
        // This is the most important resulting object.
        // The rest of the functions in this example are developed for implementation of its properties.
        public static CookieContainer AuthCookie = new CookieContainer();
        // A request string to the "Login" method of the "AuthService.svc" service.
        private const string authServiceUri = baseUri + @"/ServiceModel/AuthService.svc/Login";

        // Performs user authentication request.
        public static bool TryLogin(string userName, string userPassword)
        {
            // Creating an instance of the authentication service request.
            var authRequest = HttpWebRequest.Create(authServiceUri) as HttpWebRequest;
            // Defining the request's method.
            authRequest.Method = "POST";
            // Defining the request's content type.
            authRequest.ContentType = "application/json";
            // Enabling the use of cookie in the request.
            authRequest.CookieContainer = AuthCookie;

            // Placing user credentials to the request.
            using (var requestStream = authRequest.GetRequestStream())
            {
                using (var writer = new StreamWriter(requestStream))
                {
                    writer.Write(@"{
                    ""UserName"":""" + userName + @""",
                    ""UserPassword"":""" + userPassword + @"""
                    }");
                }
            }

            // Auxiliary object where the HTTP reply data will be de-serialized.
            ResponseStatus status = null;
            // Getting a reply from the server. If the authentication is successful, cookie will be placed to the AuthCookie property.
            // These cookies can be used for subsequent requests.
            using (var response = (HttpWebResponse)authRequest.GetResponse())
            {
                using (var reader = new StreamReader(response.GetResponseStream()))
                {
                    // De-serialization of the HTTP reply to an auxiliary object.
                    string responseText = reader.ReadToEnd();
                    status = new System.Web.Script.Serialization.JavaScriptSerializer().Deserialize<ResponseStatus>(responseText);
                }

            }
            
            // Checking authentication status.
            if (status != null)
            {
                // Authentication is successful.
                if (status.Code == 0)
                {
                    return true;
                }
                // Authentication is unsuccessful.
                Console.WriteLine(status.Message);
            }
            return false;
        }

        // Application login method.
        static void Main(string[] args)
        {
            // Calling authentication method.
            Console.WriteLine("Is authentication successful?: {0}", TryLogin("User 1", "User 1"));
            Console.WriteLine("Press ENTER to close...");
            Console.ReadLine();
        }
    }
}

The authentication will be successful of correct user credentials were entered on calling the TryLogin() method (Fig. 2). If the credentials were invalid, an error message will be displayed (Fig. 2).

Fig. 2. Successful authentication