Login Service

Introduction

With the UKG Pro Web Services, you can leverage your UKG Pro data for solving business application and integration needs.

This document describes how to authenticate with the UKG Pro web services and is intended for individuals who are familiar with software development and web service technologies.

Login Service API

The UKG Pro Login Service API enables the user to authenticate their UKG Pro credentials in order to retrieve an authentication token. The authentication token is used to consume the UKG Pro web services to retrieve or update UKG Pro data.

Overview

This document describes the methods of the service and provides code examples using Microsoft’s Visual Studio 2008 using C# and XML (.NET Framework 3.0 or higher).

The following information describes the service requirements.


Service Specifications

Protocol	Simple Object Access Protocol (SOAP) 1.2
SSL Support	Required


Sign Up and Licensing

Account Required	UKG Pro Service Account or UKG Pro Web User with Web Services Permissions

Using an UKG Pro Service Account is recommended. For information regarding establishing and maintaining an UKG Pro Service Account, please refer to the document Maintaining Service Accounts located in the UKG Pro Technical Content section of the Ultimate Library under UKG Pro Web Services and APIs.

Quick Start

This section provides steps for creating a sample application in your development environment to retrieve the authentication token.

Prerequisites

In order to use the service, you will need the following items:

An UKG Pro Service Account username and password OR an UKG Pro Web User username and password
The Customer API key from the UKG Pro Web Service administrative page
If you use an UKG Pro Service Account:
You will need the User API key from the Service Account administrative page.
- You must have appropriate permissions granted to the Service Account on the Service Account administrative page for the services you plan to use.
If you use an UKG Pro Web User account:
- You will need the User API key from the Web Service administrative page.

C# Example

Generate the Service Reference

Once you have a user and API keys, you need to create a service reference to the Login Service. In your development environment, add the service reference to the Login Service.

In Visual Studio, select the Add Service Reference menu item from the Project menu. Once you enter the service information you should have the reference display in the solution explorer.

Created service reference

Created service reference

Example C# Code

The following code is an example of authenticating to your UKG Pro data in a console application. You can copy the entire contents to a C# console application and update the following values and have an operable application.

UserName = "YOUR SERVICE ACCOUNT OR WEB USER NAME ",
Password = "YOUR PASSWORD",
UserAPIkey = "YOUR USER API KEY",
CustomerAPIkey = "YOUR CUSTOMER API KEY"

namespace ConsoleSample
{
    using System;
    using System.ServiceModel;
    using System.ServiceModel.Channels;

    using ConsoleSample.LoginService;

    public class Program
    {
        internal static void Main(string[] args)
        {
            // Setup your user credentials:
            const string UserName = "";
            const string Password = "";
            const string UserApiKey = "";
            const string CustomerApiKey = "";

            // Create a proxy to the login service:
            var loginClient = new LoginServiceClient("WSHttpBinding_ILoginService");

            try
            {
                // Submit the login request to authenticate the user:
                string message;
                string authenticationToken;

                AuthenticationStatus loginRequest =
                    loginClient
                        .Authenticate(
                            CustomerApiKey,
                            Password,
                            UserApiKey,
                            UserName,
                            out message,
                            out authenticationToken);

                if (loginRequest == AuthenticationStatus.Ok)
                {
                    // User is authenticated and the authentication token is provided.
                    Console.WriteLine("User authentication successful.");
                }
                else
                {
                    // User authentication has failed. Review the message for details.
                    Console.WriteLine("User authentication failed: " + message);
                }

                loginClient.Close();

                Console.WriteLine("Press a key to exit...");
                Console.ReadKey(true);
            }
            catch (Exception ex)
            {
                Console.WriteLine("Exception: " + ex);
                loginClient.Abort();
                throw;
            }
        }

XML Examples

Authentication Service (http://<address>/services/LoginService)
The Authentication Service is required to get the Token needed for all Core Web Service Calls.

The following code is an XML example of authenticating to your UKG Pro data. You can copy the entire contents and update the values in the request. The response example shows how a successful response will be formatted.

Login Method Request

<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope" xmlns:a="http://www.w3.org/2005/08/addressing">
  <s:Header>
<a:Action   s:mustUnderstand="1">http://www.ultimatesoftware.com/services/loginservice/ILoginService/Authenticate</a:Action> 
  	    <h:ClientAccessKey xmlns:h="http://www.ultimatesoftware.com/services/loginservice">CAK</h:ClientAccessKey> 
  	    <h:Password xmlns:h="http://www.ultimatesoftware.com/services/loginservice">PASSWORD</h:Password> 
  	    <h:UserAccessKey xmlns:h="http://www.ultimatesoftware.com/services/loginservice">USER API KEY</h:UserAccessKey> 
  	    <h:UserName xmlns:h="http://www.ultimatesoftware.com/services/loginservice">USERNAME</h:UserName> 
 	  </s:Header>
  <s:Body>
 	    <TokenRequest xmlns="http://www.ultimatesoftware.com/contracts" /> 
  </s:Body>
</s:Envelope>

Login Method Response


<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope" xmlns:a="http://www.w3.org/2005/08/addressing">
  <s:Header>
    <a:Action s:mustUnderstand="1">http://www.ultimatesoftware.com/services/loginservice/ILoginService/AuthenticateResponse</a:Action>
  </s:Header>
  <s:Body>
    <TokenResponse xmlns="http://www.ultimatesoftware.com/contracts">
    <Status xmlns="http://www.ultimatesoftware.com/services/loginservice">Ok</Status> 
    <StatusMessage i:nil="true" xmlns="http://www.ultimatesoftware.com/services/loginservice"  xmlns:i="http://www.w3.org/2001/XMLSchema-instance" /> 
    <Token xmlns="http://www.ultimatesoftware.com/services/loginservice">LOGIN TOKEN</Token> 
  </TokenResponse>
</s:Body>
</s:Envelope>