Federated Single Sign-on User Service

Federated SSO User Object

The Federated SSO User object includes the following properties.

PropertyRequiredTypeDescription
ActivationKey
GuidA unique key used during manual provisioning. It is automatically generated on create.
ClientUserNameYesStringEmployee’s network identity account used for federation.
EmployeeIdentifierYesReference

ID that represents a person. This is a reference object of the type of identifier you are using. Valid identifiers are:

EmployeeNumberIdentifier

EmailAddressIdentifier

SsnIdentifier

SinIdentifier (For Canada)

NationalIdentifier (Global person identifier)

RetryAttempts
Int

Number of times a user has failed manual provisioning.

Defaults to 0 on create.

Status
Int

Defaults to 0 on create which is not an active user. In most cases you’ll want to use 1 to set the users as active.

0 = Provisional (Used during manual provisioning)
1 = Complete
2 = Failed

UKG ProUserName
StringThe UKG Pro web user account. If not passed in, the service will look up the account based on the employee identifier.

Quick Start

This section provides steps for creating a sample application in your development environment to retrieve and update the Federated SSO User information.

Prerequisites

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

  • UKG Pro web user account and password
  • User API key and Customer API key from the UKG Pro 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 and the Federated SSO User Service. In your development environment, add the service references.

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

Example Code

The following code is an example of retrieving and updating Federated SSO User information from 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 WEB USER NAME ",

Password = "YOUR PASSWORD",

UserAPIkey = "YOUR USER API KEY",

CustomerAPIkey = "YOUR CUSTOMER API KEY"

//Example Quick Start Code Begin

using System;
using System.Linq;
using System.ServiceModel;
using System.ServiceModel.Channels;
using Microsoft.VisualStudio.TestTools.UnitTesting;
using SsoUserServiceClient.LoginService;
using SsoUserServiceClient.SsoUserService;


namespace SsoUserServiceClient
{
    class Program
    {
        // Service addresses:
        private const string LoginServiceAddress = "http://[ENTER URL]/services/LoginService";
        private const string SsoUserServiceAddress = "http://[ENTER URL]/services/EmployeeSsoUser";


        // Noble user credentials:
        private const string CustomerAPIkey = "";
        private const string UserAPIkey = "";
        private const string UserName = "";
        private const string Password = "";


        private const string SsoUserUKG ProUserName = "AllieC";


        // The EmployeeIdentifier identifies the employee user for whom we are creating an SsoUser record.
        private static readonly EmployeeNumberIdentifier SsoUserEmployeeIdentifier =
                                    new EmployeeNumberIdentifier()
                                    {
                                        EmployeeNumber = "735070809"
                                    };


        private static readonly EmployeeSsoUserClient SsoUserClient =
                new EmployeeSsoUserClient("WSHttpBinding_IEmployeeSsoUser", SsoUserServiceAddress);


        private static readonly LoginServiceClient LoginServiceClient =
                new LoginServiceClient("WSHttpBinding_ILoginService", LoginServiceAddress);


        static void Main(string[] args)
        {
            // Acquire an UKG Pro security token for the given user credentials.
            string token = Authenticate();
            Console.WriteLine("Authentication successful.");


            // Here, we create a new, populated instance of an SsoUser.
            // This will be used to demonstrate the EmployeeSsoUser CRUD operations.
            SsoUser user = CreateNewSsoUser();
            Console.WriteLine("New user object populated");


            // The OperationContextScope allows us to set the outgoing SOAP header
            using (var scope = new OperationContextScope((IContextChannel)SsoUserClient.InnerChannel))
            {
                SetHeaders(token);


                // We can not create an existing record, so clear it out if needed for the subsequent demonstration.
                //ResetSsoUserData();


                // Create an SsoUser record:
                SsoUserCreateResponse createResponse = SsoUserClient.CreateSsoUser(new[] { user });
                Assert.IsTrue(createResponse.Success);
                Console.WriteLine("Created Federated SSO User for " + user.ClientUserName);


                // Get the new SsoUser record (here we demostrate GetSsoUserByClientUserName):
                user = SsoUserClient.GetSsoUserByClientUserName("MyClientUserName").Results.First();
                Assert.AreEqual("MyClientUserName", user.ClientUserName);
                Assert.AreEqual(SsoUserUKG ProUserName, user.UKG ProUserName);
                Assert.AreEqual(5, user.RetryAttempts); // We will be updating this field.
                Console.WriteLine("Retrieved Federated SSO for UKG Pro user " + user.UKG ProUserName);


                // Update the RetryAttempts on the new SsoUser record:
                Console.WriteLine("Updating retry attemps. Current value: " + user.RetryAttempts.ToString());
                user.RetryAttempts = 0;
                SsoUserUpdateResponse updateResponse = SsoUserClient.UpdateSsoUser(new[] { user });
                Assert.IsTrue(updateResponse.Success);


                // Get the modified SsoUser record (here we demostrate GetSsoUserByEmployeeIdentifier):
                user = SsoUserClient.GetSsoUserByEmployeeIdentifier(SsoUserEmployeeIdentifier).Results.First();
                Assert.AreEqual(SsoUserEmployeeIdentifier.EmployeeNumber, ((EmployeeNumberIdentifier)user.EmployeeIdentifier).EmployeeNumber);
                Assert.AreEqual(0, user.RetryAttempts);
                Console.WriteLine("Updatd retry attempts to value: " + user.RetryAttempts);


                // Delete the new SsoUser record:
                // Here we leverage the convenience of an already populated SsoUser object; however,
                // the minimum data required for a delete is ClientUserName + EmployeeIdentifier.
                SsoUserDeleteResponse deleteResponse = SsoUserClient.DeleteSsoUser(new[] { user });
                Assert.IsTrue(deleteResponse.Success);


                // Verify that the new SsoUser record was deleted:
                Assert.IsTrue(SsoUserClient.GetSsoUserByClientUserName("MyClientUserName").Results.Count() == 0);
                Console.WriteLine("Deleted user...Press a key to exit.");
                Console.ReadKey();
            }
        }


        private static void ResetSsoUserData()
        {
            var results = SsoUserClient.GetSsoUserByEmployeeIdentifier(SsoUserEmployeeIdentifier).Results;
            
            if (results != null)
            {
                SsoUserDeleteResponse deleteResponse = SsoUserClient.DeleteSsoUser(new[] { results.FirstOrDefault() });
            }
        }


        private static SsoUser CreateNewSsoUser()
        {
            var user =
                new SsoUser()
                {
                    ClientUserName = "MyClientUserName",
                    EmployeeIdentifier = SsoUserEmployeeIdentifier,
                    RetryAttempts = 5,
                    Status = 1 // When Status = 1, the service will lookup and populate the corresponding UKG Pro user name.
                };


            return user;
        }


        /// <summary>
        /// Sets the outgoing SOAP headers.
        /// ultiproToken and CustomerAPIkey are required, with the correct namespaces.
        /// </summary>
        /// <param name="token">A valid UKG Pro security token</param>
        private static void SetHeaders(string token)
        {
            MessageHeaders headers = OperationContext.Current.OutgoingMessageHeaders;


            headers.Add(MessageHeader.CreateHeader("ultiproToken", "http://www.ultimatesoftware.com/foundation/authentication/ultiproToken", token));
            headers.Add(MessageHeader.CreateHeader("ClientAccessKey", "http://www.ultimatesoftware.com/foundation/authentication/clientaccesskey", CustomerAPIkey));
        }


        /// <summary>
        /// Calls the LoginService to provide a token for the given user credentials.
        /// The CustomerAPIkey and UserAPIkey for the given user may be obtained from UKG Pro Web.
        /// </summary>
        /// <returns>A valid UKG Pro security token</returns>
        private static string Authenticate()
        {
            string statusMessage;
            string token;


            LoginServiceClient.Authenticate(CustomerAPIkey, Password, UserAPIkey, UserName, out statusMessage, out token);


            // If authentication succeeded, statusMessage will be null
            Assert.IsNull(statusMessage);


            // If authentication succeeded, the token should be a GUID
            Guid result;
            Assert.IsTrue(Guid.TryParse(token, out result));


            return token;
        }
    }
}
// Example Quick Start Code End

Methods

This section introduces the API methods for the Federated SSO User Web Service.

FindSSOUsers

This method provides a way to query the web service based on one or more filter criteria.

Syntax

Binding.FindSSOUsers(EmployeeQuery)

Code Example

// Find employees
EmployeeQuery query = new EmployeeQuery();
query.LastName = "LIKE (a%)";


SsoUserFindResponse findresponse = SsoUserClient.FindSsoUsers(query);


// Check the results of the find to see if there are any errors.
if (findresponse.OperationResult.HasErrors)
{
    // Review each error.
    foreach (OperationMessage message in findresponse.OperationResult.Messages)
    {
        Console.WriteLine("Error message: " + message.Message);
    }
}
else
{
    // If employee records are returned, loop through the results
    // and write out the data.
    foreach (EmployeeSsoUser employeessouser in findresponse.Results)
    {
        // If null, it's not an employee setup for SSO
        if (employeessouser.SsoUsers != null)
        {
            foreach (SsoUser ssouser in employeessouser.SsoUsers)
            {
                Console.WriteLine("Last name:" + employeessouser.LastName + ", UKG Pro user:" + ssouser.UKG ProUserName);
            }
        }
    }
}

GetSSOUserByEmployeeIdentifier

This method allows you to retrieve an individual SSO user record by providing an employee identifier.
This is helpful when you are designing an application that is aware of the employees to retrieve or when you plan to execute an update of some of the SSO user information.

Syntax

Binding.GetSSOUserByEmployeeIdentifier(employeeIdentifier)

Code Example: See the quick start code for an example.

GetSSOUserByClientUserName

Syntax

Binding.GetSSOUserByClientUserName(clientusername)

Code Example: See the quick start code for an example.

CreateSSOUser

This method allows you to create a new SSO user record.

Syntax

Binding.CreateSSOUser(SSOUser[])

Code Example: See the quick start code for an example.

UpdateSSOUser

This method allows you to update the SSO user information. We recommend executing a find or get to retrieve the SSO user information first then submitting the object to the update method.

Syntax

Binding.UpdateSSOUser(SSOUser[])

Code Example: See the quick start code for an example.

XML Example

Authentication Service http://<address>/services/LoginService
The Authentication Service is required to get the Token needed for all Core Web Service Calls. Please refer to the UKG Pro Login Service API Guide for further information.

NewHire

<s:Envelope xmlns:a="http://www.w3.org/2005/08/addressing" xmlns:s="http://www.w3.org/2003/05/soap-envelope">
  <s:Header>
  <a:Action s:mustUnderstand="1">http://www.ultimatesoftware.com/services/employeenewhire/IEmployeeNewHire/NewHireUsa</a:Action>
  <ultiproToken xmlns="http://www.ultimatesoftware.com/foundation/authentication/ultiproToken">e0ceac80-baf5-4abf-9b87-89628c931c71</ultiproToken>
  <ClientAccessKey xmlns="http://www.ultimatesoftware.com/foundation/authentication/clientaccesskey">CAN12</ClientAccessKey>
  </s:Header>
  <s:Body>
  <NewHireUsa xmlns="http://www.ultimatesoftware.com/services/employeenewhire">
  <entities xmlns:b="http://www.ultimatesoftware.com/contracts" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <b:Employee>
  <b:AddressLine1>123 Maple Lane</b:AddressLine1>
  <b:AddressLine2 />
  <b:AlternateEmailAddress />
  <b:AlternateTitle />
  <b:BenefitSeniorityDate>2012-01-01T00:00:00</b:BenefitSeniorityDate>
  <b:BirthDate>1980-01-01T00:00:00</b:BirthDate>
  <b:City>Piermont</b:City>
  <b:CompanyIdentifier i:nil="true" />
  <b:Country>USA</b:Country>
  <b:County />
  <b:DeductionBenefitGroup>SAL</b:DeductionBenefitGroup>
  <b:DistributionCenterCode i:nil="true" />
  <b:EarningsGroup>SAL</b:EarningsGroup>
  <b:EmailAddress>[email protected]</b:EmailAddress>
  <b:EmployeeNumber />
  <b:EmployeeType>REG</b:EmployeeType>
  <b:EthnicOrigin>White (Not Hispanic or Latino)</b:EthnicOrigin>
  <b:FederalAdditionalAmountWithheld>0</b:FederalAdditionalAmountWithheld>
  <b:FederalEmployeeClaimsExempt>false</b:FederalEmployeeClaimsExempt>
  <b:FederalFilingStatus>M</b:FederalFilingStatus>
  <b:FederalSubjectToBackupWithholding>false</b:FederalSubjectToBackupWithholding>
  <b:FederalTotalAllowancesClaimed>0</b:FederalTotalAllowancesClaimed>
  <b:FederalW2Pension>false</b:FederalW2Pension>
  <b:FirstName>Joe</b:FirstName>
  <b:FormerLastName />
  <b:FullOrPartTime>F</b:FullOrPartTime>
  <b:Gender>M</b:Gender>
  <b:HireDate>2012-01-01T00:00:00</b:HireDate>
  <b:HireSource />
  <b:HomePhone>5555551111</b:HomePhone>
  <b:HourlyOrSalaried>H</b:HourlyOrSalaried>
  <b:I9Verification>P</b:I9Verification>
  <b:JobCode>SALES</b:JobCode>
  <b:JobGroup />
  <b:LastName>Tester</b:LastName>
  <b:LocalWorkInTaxResidentStatus />
  <b:LocationCode>NY</b:LocationCode>
  <b:MailStop />
  <b:MaritalStatus />
  <b:MiddleName />
  <b:NextPerformanceReviewDate>2013-01-01T00:00:00</b:NextPerformanceReviewDate>
  <b:NextSalaryReviewDate>2013-01-01T00:00:00</b:NextSalaryReviewDate>
  <b:OtherPhone i:nil="true" />
  <b:OtherPhoneExtension i:nil="true" />
  <b:OtherPhoneType i:nil="true" />
  <b:OtherRate1>1.5<b/:OtherRate1>
  <b:OtherRate2 i:nil="true" />
  <b:OtherRate3 i:nil="true" />
  <b:OtherRate4 i:nil="true" />
  <b:OrgLevel1 />
  <b:OrgLevel2 />
  <b:OrgLevel3 />
  <b:OrgLevel4 />
  <b:PayAutomatically>false</b:PayAutomatically>
  <b:PayGroup>UPC</b:PayGroup>
  <b:PayRate>50000</b:PayRate>
  <b:PayRateType>Y</b:PayRateType>
  <b:PayScaleCode>ABC</b:PayScaleCode>
  <b:PreferredFirstName />
  <b:Prefix />
  <b:Project />
  <b:ResidentCounty i:nil="true" />
  <b:ResidentJurisdiction i:nil="true" />
  <b:ResidentStateAdditionalAllowances>0</b:ResidentStateAdditionalAllowances>
  <b:ResidentStateAdditionalAmountWithheld>0</b:ResidentStateAdditionalAmountWithheld>
  <b:ResidentStateEmployeeClaimsExempt>false</b:ResidentStateEmployeeClaimsExempt>
  <b:ResidentStateFilingStatus>NY</b:ResidentStateFilingStatus>
  <b:ResidentStateTotalAllowancesClaimed>0</b:ResidentStateTotalAllowancesClaimed>
  <b:SSN>101111001</b:SSN>
  <b:ScheduledHours>40</b:ScheduledHours>
  <b:SelfServiceProperties xmlns:c="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
  <c:KeyValueOfstringstring>
  <c:Key />
  <c:Value />
  </c:KeyValueOfstringstring>
  </b:SelfServiceProperties>
  <b:SeniorityDate>2012-01-01T00:00:00</b:SeniorityDate>
  <b:ShiftCode />
  <b:ShiftGroup />
  <b:StateGeographicCode />
  <b:StateOccupationalCode />
  <b:StateOrProvince>NY</b:StateOrProvince>
  <b:StepNo>1</b:StepNo>
  <b:Suffix />
  <b:Supervisor i:nil="true" />
  <b:TimeClock />
  <b:WorkExtension />
  <b:WorkPhone>5555551111</b:WorkPhone>
  <b:WorkStateAdditionalAllowances>0</b:WorkStateAdditionalAllowances>
  <b:WorkStateAdditionalAmountWithheld>0</b:WorkStateAdditionalAmountWithheld>
  <b:WorkStateDisabilityPlanType />
  <b:WorkStateEmployeeClaimsExempt>false</b:WorkStateEmployeeClaimsExempt>
  <b:WorkStateFilingStatus />
  <b:WorkStatePlan />
  <b:WorkStateTotalAllowancesClaimed>0</b:WorkStateTotalAllowancesClaimed>
  <b:ZipOrPostalCode>10968</b:ZipOrPostalCode>
  </b:Employee>
  </entities>
  </NewHireUsa>
  </s:Body>
  </s:Envelope>