Gateway Authentication using AAD involves installing a Gateway Pluggable Authentication and Authorization (PAA) module on the Gateway, and having the clients send an AAD JWT token to the gateway to perform Auth. In this phase, a separate Username and Password will still be sent to authenticate the host access.
Client Workflow
When a connection is made to an application with a gateway, and that gateway uses AAD, the client requests an access token for Gateway Auth. Note that in the normal configuration, this will be silent. Workspot will already have an identity token, from the initial login, and possibly already have the access token, depending on whether we have different access tokens for Control login vs RDP access.
Cookie-based RDP authentication
The RDP protocol contains an alternate method of sending credentials to the gateway. This is referred to as a “cookie” and will be sent to the PAA module.
Windows
Windows will send the cookie via the “GatewayEncryptedAuthCookie” property of MsTscAx.
FreeRDP
FreeRDP supports the gatewayaccesstoken RDP property.
Errors
These are the error codes that the Windows client gets from the RDP plugin, for the freerdp code there could be different (raw) errors.
Failure in Authentication
Error: 50331701 (0x3000035)
Microsoft message: Your computer can't connect to the remote computer because the cookie was rejected by the Remote Desktop Gateway server. Contact your network administrator for assistance.
Workspot message: Your Azure credentials were rejected by the Remote Desktop Gateway. This could be a temporary error. Try again or contact your network administrator.
Failure in Authorization
Error: 50331656 (0x3000008)
Microsoft message: Your computer can't connect to the remote computer because an error occurred on the remote computer that you want to connect to. Contact your network administrator for assistance.
Workspot message: You are not authorized for access through the configured Remote Desktop Gateway. Contact your network administrator for assistance.
Mismatched AAD Gateway.
Error: 50331703 (0x3000037)
Microsoft message: Your computer can't connect to the remote computer because the Remote Desktop Gateway server is expecting an authentication method different from the one attempted. Contact your network administrator for assistance.
If the local config is for AAD
Workspot message: Your Remote Desktop Gateway is not configured for Azure authentication. Contact your network administrator for assistance.
If the Workspot config is for AD
Workspot message: Your Remote Desktop Gateway expects Azure authentication. Contact your network administrator for assistance.
Gateway service stopped.
Error: 50331661
Microsoft message: Your computer can't connect to the remote computer because the Remote Desktop Gateway server is temporarily unavailable. Try reconnecting later or contact your network administrator for assistance.
Workspot message: Your Remote Desktop Gateway is temporarily not available. Try again later or contact your network administrator for assistance.
Operation
Authentication requests
The authentication phase will strictly determine if the credentials are valid AAD credentials. Specifically, if the token and request are well formed, and the token is valid (signed, date good, etc).
Authorization
This is two phases.
Authorize Connection determines if the user is allowed to access this gateway. We will do this by comparing the UPN in the request to the allowed domains. If the domain from the UPN in the list is valid, then this phase passes.
Authorize Resource determines if the target is authorized. For now, we will compare the Configured Target to the Rdp Target. If this matches, then the phase succeeds. Note: Until the Configured Target is signed by control, this comparison adds no additional security.
Optionally, this host could be signed by Control, which would provide an added measure of security as to who can access which host. Specifically, this is useful for larger enterprises. If Control signs the “Configured Host”, then clients will be able to access ONLY the host that they are configured for via Control. If using a signed host, the Gateway can then validate the signature from Control. Note: This may be overkill for now, but we will build this into the architecture anyway, for future security enhancements.
Security Overview
Workspot Client obtains a JWT token from the Microsoft MSAL (AAD) libraries. To do this, the user proves their identity via whatever criteria is set up for AAD, including MFA. This token is signed by Microsoft.
Workspot client gets hostname.
Client contacts the gateway via TLS, for which a signed valid certificate is needed. No certificate warnings are allowed.
The (JWT, Hostname, and Hostname Signature) is packaged into a JSON message and is passed to the gateway via the TLS channel
The gateway service passes the token to the client in three phases.
Authenticate
The Plugin validates the token using the MSAL libraries. This checks the signature, timestamp, etc.
The appid is then checked to make sure it is the proper Workspot appid, which is the same for all customers.
Authorize-Connection
The plugin checks to make sure that the tenant ID is the one configured for this client.
Authorize -Resource – The client checks the signature of the host passed in via the JSON message. This is then checked against the host passed in through the RDP protocol. If there is a mismatch, then the connection fails.
If any of these tests fail, then the connection is denied.
Installation of Workspot AAD plugin
Run the installer in administrative privilege.
Note: During installation RD gateway service will get restarted.
Configure AAD Token
Need to create a .json file with the customer tenant ID. The name can be anything.
Copy the file to any location. In this example, we copied to the gateway plugin installation directory.
Open command prompt in Admin privilege. Change the directory to
“C:\Program Files\Workspot\gatewayPlugin” and run configure.bat <zzz.json file path>
To update the Tenant ID of the customer, then update the .json file and re-run the above command again.
To get information related to the Plugin version, authentication, and authorization dll or Tenant ID run info.bat from the GatewayPlugin folder.
AAD authentication log created in C:\program data\Workspot\gatewayPlugin\logs folder.
Configure OKTA Token
As like AAD token, we need to create a .json file with the customer’s Okta URL and Okta API Key. The name can be anything.
{
"mfa-provider":"okta",
"okta-url":https://dev-694851.okta.com”,
"okta-apikey":"00iThy_038GumI3GoChiefsc7ksE2kBqpZv7cyGjm9",
} Save the file to any location.
Open command prompt in Admin privilege. Change the directory to
“C:\Program Files\Workspot\gatewayPlugin” and run configure.bat <xyz.json file path>
To update the Okta details, update the .json file and re-run the above command again.
To get information related to the Plugin version, authentication, and authorization dll or Tenant ID run info.bat from the GatewayPlugin folder.