OAuth 2.0 authentication
App Configuration:
An App (type Web) must be registered e.g. at Google or Microsoft.
Following URIs must be defined as redirect URI:
http://localhost/oaurcv ... for autologon/reverselogon
https://server:port/oaurid ... for logon, manage, status, web, and web destinations
http://localhost/oautsr ... for local testing
https://server:port/oautsr ... for remote testing
Server configuration:
One or more special groups (names must starts with "O_", e.g. O_MS or O_GO) must be defined via menu, "Configuration", "New OAuth Group".
The string behind "O_" is referred as (authentication) provider (e.g. MS or GO).
These groups must contain following keywords (see App Configuration above):
AUTH_ENDPOINT ... OAuth 2.0 authorization endpoint e.g. https://login.microsoftonline.com/organizations/oauth2/v2.0/authorize
JWKS_URI ... URI to download public keys for id_token verification
CLIENT_ID ... Application (client) ID
EMAIL_CLAIM ... Name of claim (field) within id_token to be used for authentication (optional, default is email)
- The content must have email format. Examples of claims are: email, preferred_username, upn, verified_primary_email.
- Optional claims must be configured as necessary (e.g. preferred_username, upn), for MS see "Token configuration" in the Azure portal.
Keyword PROXY:address:port ... for manage entries (optional): to define the proxy when loading OAuth keys
- if keyword PROXY is not specified: The default system settings will be used.
- if PROXY:no ... direct access, no proxy will be used.
Keywords in reverselogon, logon, manage, status, web, and web destinations routing entry:
OA2:grouplist ... grouplist is a list of OAuth groups (names must start with "O_") separated by |
- If the authentication provider requested by the client is not defined at the server, the last entry in the list at the server will be selected as fallback.
OA2U:EmailAddresses ... optional, users who are authorized for OAuth 2.0 authentication
Keywords in logon, manage, status, web, and web destinations routing entry:
CKGRP:cookiegroup ... optional, to configure cookie handling. A detailed description can be found here.
OA2REDIR:uri ... uri (only https://server:port) used by the authentication server as redirect URI (don't forget to configure the App as mentioned above).
- Not for autologon/reverselogon configurations because in that case the redirect URI is http://localhost
SELACC ... forces account selection (optional).
Additional the user can append the string "-selacc" to the URL to force account selection, e.g. https://www.mycomp.com/-selacc
To configure provider selection via a web page and additional optional keywords see here.
The string "OA2-issuer" is stored as Issuer and it can be checked via the ISS keyword.
A list of active OAuth 2.0 sessions is shown here.
A description of the state values is shown via tool tip (mouse over "State" values) or can be found here
For security reasons routing entries using OTP should have the UID field specified to be able to link session objects to a specific routing entry.
Hints for server configuration (currently only for autologon/reverselogon configurations):
If at the same time certificate authentication with keyword CCR is configured: To allow fallback to OAuth 2.0 authentication the keyword CCNRQ must be specified.
At the server certificate, TOTP, and OA2 authentication can be configured at the same time:
Then the client selects the type of authentication.
====================================================================================================================================
Message Flow for logon, manage, status, web, and web destinations:
(1) The ApplicGate server is accessed via a web browser.
(2) The ApplicGate server responds with a redireect URI to access the authentication server.
The keyword OA2REDIR must be defined at the server.
(3) The web browser redirects to the authentication server.
(4) The web browser communicates with the authentication server for authentication,
with or without user interaction (depends on the configuration).
(5) When the authentication is successful the authentication server sends an id_token to the web browser (as redirection).
(6) The web browser redirects the id_token to the ApplicGate server.
(7) The ApplicGate server checks the id_token (clientid, signature etc.) and checks if the provided email is authorized.
If all checks are ok, a session object will be created.
(8) The Applicgate server sends back the result of the check.
(1)Start
+--------------+ +------------+ +--------------+
| | | |--(1)------->| |
| |<-------(3)--| |<-------(2)--| |
| (4) |--(4)------->| Web | | ApplicGate |
|Authentication|<-------(4)--| Browser | | Server |
| Server |--(5)------->| |--(6)------->| (7) |
| | | |<------(8)---| |
+--------------+ +------------+ +--------------+
(8)Result
====================================================================================================================================
Client configuration (autologon/reverselogon configurations):
Keywords in autologon routing entry:
OA2:provider ... authentication by the specified provider, provider is optional, provider without leading "O_" but group O_provider must exist at the server
- e.g. MS for Microsoft (group O_MS must exist at the server).
SELACC ... forces account selection (optional).
In ApplicGate VPN clients started via ClickOnce these keywords may be selected via the Stop&Restart menu.
See also ClickOnce Support.
On the ApplicGate client the manage routing entry (where the autologon session will be started) must be accessed via localhost (127.0.0.1 or [:1])
====================================================================================================================================
Example for Routing Table at AppGW0 ... central server of the Remote Service Platform:
SourceIP ;GatewayIP ;GatewayPort;GatewayIP2 ;DestinationIP;DestinationPort;Expiration;Type ;UID;Comment;eMail
* ;1.2.3.4 ;777 ;reverselogon;client|mgmt ;* ;* ;SSL:srv.cer,OA2:O_MS,OA2U:*@x.com ;1.0;comment;mike@x.com
Example for Routing Table at APPGW1 ... client logs on to AppGW0:
SourceIP ;GatewayIP ;GatewayPort;GatewayIP2 ;DestinationIP;DestinationPort;Expiration;Type ;UID;Comment ;eMail
autologon;client|mgmt; ;* ;1.2.3.4 ;777 ;* ;SSLTARGET:NoCheck,OA2,SELACC ;1.0;myComment;mike@x.com
====================================================================================================================================
Message Flow for autologon/reverselogon configurations:
(1) The autologon session is started via a web browser.
The ApplicGate client must be accessed via localhost (127.0.0.1 or [:1]), any TCP port is supported.
(2) The ApplicGate client requests OAuth2 authentication (Google or MS) from the ApplicGate server.
(3) The ApplicGate server responds with the URI to access the authentication server.
(4) The ApplicGate client forwards this URI to the web browser (as redirection).
(5) The web browser redirects to the authentication server.
(6) The web browser communicates with the authentication server for authentication,
with or without user interaction (depends on the configuration).
(7) When the authentication is successful the authentication server sends an id_token to the web browser (as redirection).
(8) The web browser redirects the id_token to the ApplicGate client.
(9) The ApplicGate client forwards this id_token to the ApplicGate server.
(10) The ApplicGate server checks the id_token (clientid, signature etc.) and checks if the provided email is authorized.
If all checks are ok, a session object will be created.
(11) The Applicgate server sends back the result of the check.
(12) The Applicgate client presents the result to the web browser.
(1)Start
+--------------+ +------------+ +------------+ +--------------+
| | | |--(1)------->| |--(2)------->| |
| |<-------(5)--| |<-------(4)--| |<-------(3)--| |
| (6) |--(6)------->| Web | | ApplicGate | | ApplicGate |
|Authentication|<-------(6)--| Browser | | Client | | Server |
| Server |--(7)------->| |--(8)------->| |--(9)------->| (10) |
| | | |<------(12)--| |<------(11)--| |
+--------------+ +------------+ +------------+ +--------------+
(12)Result
====================================================================================================================================
Keys for Token Verification:
The ApplicGate server needs the public keys to verify the ID token.
The keys are downloaded automatically as defined by the keyword JWKS_URI in the special group, e.g.
login.microsoftonline.com and/or
www.googleapis.com
and refreshed short after midnight.
The keys are cached in files e.g. Keys-MS.json and Keys-GO.json in the default directory of ApplicGate.
Therefore, the ApplicGate server must be allowed to access servers via port 443 or a proxy must be defined (see system, IE or Edge setting).
Optional: The proxy can be defined via keyword PROXY (overrides system settings).
If this is not possible the local key files must be updated by other means once a day between 0:30 and 23:30 local time.
Remark:
- Via Tools OAuth 2.0 you can force the download of the keys.
