en-US/about_PSUKG_Authentication.help.txt
|
TOPIC about_PSUKG_Authentication SHORT DESCRIPTION Explains authentication and session management in the PSUKG module. LONG DESCRIPTION The PSUKG module uses OAuth 2.0 client credentials flow for authentication with the UKG HR Service Delivery API. This topic covers authentication concepts, best practices, and session management. Authentication Flow 1. Connect-UKG retrieves an OAuth 2.0 access token using client credentials 2. The token is stored in a script-scoped session variable 3. All subsequent API calls automatically include the token 4. The token is automatically refreshed 60 seconds before expiry 5. Disconnect-UKG clears the session and token Required Credentials To authenticate, you need three pieces of information from UKG: Application ID: Identifies your registered application in the UKG system. Application Secret: A secret key that proves your application's identity. This should be kept secure and never committed to source control. Client ID: Identifies your specific tenant/company within UKG. Authentication Methods The module supports two authentication methods: SecureString (Recommended): Uses PowerShell's SecureString type to protect the secret in memory. $secret = Read-Host -AsSecureString -Prompt "Enter Application Secret" Connect-UKG -ApplicationId "app123" -ApplicationSecret $secret -ClientId "client456" Plain Text (Testing Only): Accepts the secret as plain text. Only use this for testing or scripts where the secret is retrieved from a secure credential store. Connect-UKG -ApplicationId "app123" -ApplicationSecretPlainText "secret789" -ClientId "client456" Region and Environment Selection You must specify the region and optionally the environment: Regions: - EU: European region (Default) - US: United States region - UKG_ATL: UKG Atlanta data center - UKG_TOR: UKG Toronto data center Environments: - Production: Live environment (Default) - Staging: Testing/staging environment Example: Connect-UKG -ApplicationId "app123" -ApplicationSecret $secret ` -ClientId "client456" -Region US -Environment Staging Custom Endpoints For custom or on-premises deployments, you can specify custom URLs: # Custom API and token endpoints Connect-UKG -ApplicationId "app123" -ApplicationSecret $secret -ClientId "client456" ` -BaseUrl "https://custom.api.endpoint.com/api/v2" ` -TokenUrl "https://custom.token.endpoint.com/oauth2/token" Session Management The module maintains a session in the $Script:UKGSession variable. View Current Session: Get-UKGSession Returns information about the active session including: - Connected status - Region and environment - Base URL - Token expiration time (without exposing the token itself) Close Session: Disconnect-UKG Clears the session and removes the access token from memory. Token Lifecycle Access tokens have a limited lifetime (typically 3600 seconds / 1 hour). Automatic Refresh: The module automatically refreshes tokens 60 seconds before expiration. You don't need to manually manage token refresh. Token Storage: Tokens are stored in memory only, in a script-scoped variable. They are never written to disk or logged. Token Security: - Tokens are not displayed in verbose output - Get-UKGSession does not expose the token - Disconnect-UKG clears the token from memory Security Best Practices 1. Use SecureString for Production: Always use the -ApplicationSecret parameter with SecureString in production environments. 2. Never Hardcode Secrets: Don't hardcode secrets in scripts. Use one of these approaches: - Read-Host -AsSecureString for interactive scripts - Windows Credential Manager for stored credentials - Azure Key Vault, AWS Secrets Manager, or similar for cloud deployments - Environment variables retrieved at runtime 3. Limit Token Lifetime: Call Disconnect-UKG when you're done to clear tokens from memory. 4. Use Appropriate Environments: Use Staging for testing, Production for live operations. 5. Secure Credential Storage: On Windows, use Export-Clixml with -Force to securely store credentials: # Save credentials (one-time setup) $secret = Read-Host -AsSecureString -Prompt "Enter secret" $cred = New-Object PSCredential("ApplicationId", $secret) $cred | Export-Clixml -Path "$env:USERPROFILE\.ukgcred" -Force # Load credentials in scripts $cred = Import-Clixml -Path "$env:USERPROFILE\.ukgcred" Connect-UKG -ApplicationId $cred.UserName ` -ApplicationSecret $cred.Password ` -ClientId "client456" -Region EU Multi-Tenant Scenarios If you manage multiple UKG tenants, you can only maintain one active session at a time. To switch tenants: # Connect to first tenant Connect-UKG -ApplicationId "app1" -ApplicationSecret $secret1 -ClientId "client1" # Perform operations... # Switch to second tenant Disconnect-UKG Connect-UKG -ApplicationId "app2" -ApplicationSecret $secret2 -ClientId "client2" # Perform operations... Troubleshooting Authentication Invalid Credentials: Error: "Invalid client credentials" Solution: Verify ApplicationId, ApplicationSecret, and ClientId are correct. Wrong Region/Environment: Error: "Connection timeout" or "Unable to resolve hostname" Solution: Verify you're using the correct Region and Environment parameters. Token Expired: The module automatically handles token expiration. If you encounter token errors, try disconnecting and reconnecting. Network Issues: Ensure your network allows HTTPS connections to UKG API endpoints. Check firewall and proxy settings. EXAMPLES Example 1: Secure Interactive Authentication # Prompt for secret interactively $secret = Read-Host -AsSecureString -Prompt "Enter Application Secret" # Connect with SecureString Connect-UKG -ApplicationId "app123" ` -ApplicationSecret $secret ` -ClientId "client456" ` -Region EU ` -Environment Production # Verify connection Get-UKGSession # Perform work... Get-UKGEmployee -All # Clean up Disconnect-UKG Example 2: Stored Credentials (Windows) # First-time setup: Store credentials $secret = Read-Host -AsSecureString -Prompt "Enter Application Secret" $credential = New-Object PSCredential("app123", $secret) $credential | Export-Clixml -Path "$env:USERPROFILE\.ukgcred" # Subsequent use: Load and connect $cred = Import-Clixml -Path "$env:USERPROFILE\.ukgcred" Connect-UKG -ApplicationId $cred.UserName ` -ApplicationSecret $cred.Password ` -ClientId "client456" ` -Region EU Example 3: Staging Environment Testing # Connect to staging for testing $secret = Read-Host -AsSecureString Connect-UKG -ApplicationId "app123" ` -ApplicationSecret $secret ` -ClientId "client456" ` -Region EU ` -Environment Staging # Test operations in staging $testEmployee = New-UKGEmployee -Email "test@example.com" ` -FirstName "Test" ` -LastName "User" ` -EmployeeNumber "TEST001" # Clean up test data Remove-UKGEmployee -Id $testEmployee.id Disconnect-UKG Example 4: Custom Endpoint # Connect to custom on-premises deployment $secret = Read-Host -AsSecureString Connect-UKG -ApplicationId "app123" ` -ApplicationSecret $secret ` -ClientId "client456" ` -BaseUrl "https://ukg.internal.company.com/api/v2" ` -TokenUrl "https://auth.internal.company.com/oauth2/token" Example 5: Session Management # Connect Connect-UKG -ApplicationId "app123" -ApplicationSecret $secret -ClientId "client456" # Check session status $session = Get-UKGSession Write-Host "Connected to: $($session.BaseUrl)" Write-Host "Token expires: $($session.TokenExpiry)" # Work with API Get-UKGEmployee -All # Disconnect when done Disconnect-UKG # Verify disconnection $session = Get-UKGSession if (-not $session.Connected) { Write-Host "Successfully disconnected" } KEYWORDS Authentication, OAuth, Token, Session, Security, Connect, Credentials SEE ALSO about_PSUKG Connect-UKG Disconnect-UKG Get-UKGSession |