Basic Authentication

In some scenarios it may be desired to implement a service account with Basic authentication. This can be advantageous when integrating with 3rd party workflow engines like Azure Logic Apps or Service Now that provide generic REST/Webhook support, but do not support a more advanced daemon authentication method such as SCRAM-SHA512.

NOTE: basic authentication is not compatible with solutions using Active Directory Integrated Authentication, because it requires IIS to support Anonymous access, delegating authentication to the app itself. Basic authentication may be used with deployments implementing SAML or OIDC authentication.

SECURITY WARNING

• Basic authentication should only be used when SCRAM authentication is unsupported, such as when calling a Service Panel form from a generic webhook workflow. Basic authentication is not as secure as SCRAM for the following reasons:
  • It does not provide mutual authentication. The server authenticates the client, but not vice-versa. This risk can be mitigated by configuring the client to validate the server's TLS certificate, and only connect to a trusted host.
  • It sends the full username and password in headers with every request. This risk can be mitigated by avoiding use of any SSL terminating proxies so that a single trusted TLS channel is used end-to-end.
• Unlike SCRAM, which automatically authenticates to the highly privileged Writer role, Basic authentication will only include the roles selected in the Service Account configuration. Roles created for use with basic authentication should follow principles of least privilege.

Creating Service Accounts

1. Login to Identity Panel as a member of the built-in Admin role.
2. Go to Settings / Extensions and add a Basic Authentication configuration strip.
3. Within the Basic Auth module add Service Account strips, entire required account names, and associate roles.
4. Save Settings
5. For each Service Account press "Create or Reset Password"
6. Copy the password to a safe location (it will only be displayed once)
   

Removing Service Accounts

1. Option 1: Delete the account from the Basic Authentication strip and press Save
   NOTE: This will not remove the User record (which may be referenced by request logs, history, etc.). Instead, it will no longer be possible to log in with the removed service account.
2. Option 2: Disable the Basic Authentication Extension.
   NOTE: It is possible to reset passwords for a disabled extension, but accounts will not be available for login. Disable the provider if you intend to re-enable the same service account.

IMPORTANT: Once a basic authentication service account is created, that name is permanently reserved. If you delete the account strip and then create a new strip with the same account name, it will not be possible to set a usable password for the new account, and you must enter a new account name that has never been used.

Security Features

Identity Panel uses the following security best practices to maximize the security of Basic Authentication.

• It is only possible to create a crypto-secure randomly generated password, and the generated password is very long (512 bytes)
• Each service account has a dedicated 512 byte salt value
• Each service account uses a random work factor between 4000 and 8000 hashing iterations
• The user password is not stored directly. Instead, a stored key is produced by hashing the salt and password repeatedly with SHA512 up to the specified work factor
• Failed login attempts are rate-limited to two attempts per second
• A failed login attempt will log a Warning message visible on the Web console feed from the Identity Panel dashboard. These messages are also retrievable via reporting
• Basic authentication does not produce a cookie session. The Authorization header must be included on every request
• Identity Panel does not accept any requests over HTTP, only HTTPS

Sample Usage

The following sample script illustrates a Rest API call using PowerShell and Basic auth.

NOTE: The PowerShell Invoke-WebRequest cmdlet does not include the auth header on the first request if using the -Credentials parameter. It expects to receive a 401 unauthorized response before adding the Authorization header.

Like many restful services, Identity Panel deviates from the Basic Auth RFC by not automatically returning a 401 unauthorized for an unauthenticated request. This is because many of the API endpoints may have meaningful handling of anonymous access, and so return either status 200 or status 403 forbidden. For this reason, when calling Identity Panel from PowerShell with Basic Auth, you must manually construct the Authorization Header.

$user = '--service account name--'
$pass = '--service account passsword--'
$encodedCreds = [System.Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes("$($user):$($pass)"))

$Headers = @{
    'Authorization' = "Basic $encodedCreds";
    'X-Api-Key' = '--api key from install service page--';
    'X-Tenant' = '--tenant id from install service page--'; # Optional if using custom domain
    'Content-Type' = 'application/json'
}

$test = Invoke-WebRequest -Uri 'https://example.identitypanel.com/api/schedules/status?nopoll=true' -Headers $Headers