OAuth 2.0/OpenID 1.0 for LogicNets v7.4+

This document details authentication and authorization functionality available in LogicNets from v7.4+. Implementation details for this functionality may be different than that for older LogicNets releases. For additional information, see Authentication and Authorization Overview and OAUTH2.0/OpenID 1.0.

OpenID Connect/OAuth 2.0/SMART App Launch Frameworks

The LogicNets system implements the OpenID Connect 1.0 authentication specification (https://openid.net/specs/openid-connect-core-1_0.html). OpenID Connect 1.0 is a simple identity layer on top of the OAuth 2.0 [RFC 6749] protocol. It enables clients to verify the identity of the end user based on the authentication performed by an authorization server. It also allows clients to obtain basic profile information about the end user in an interoperable and REST-like manner.

For background, the OAuth 2.0 Authorization Framework [RFC 6749] and OAuth 2.0 Bearer Token Usage [RFC 6750] specifications provide a general framework for third-party applications to obtain and use limited access to HTTP resources. They define mechanisms to obtain and use access tokens to access resources but do not define standard methods to provide identity information. Notably, without profiling OAuth 2.0, a client is incapable of providing information about the authentication of an end user. Readers are expected to be familiar with these specifications.

OpenID Connect implements authentication as an extension to the OAuth 2.0 authorization process. Clients use this extension by including the OpenID scope value in the authorization request. The responding server returns authentication information in a JSON Web Token (JWT) called an ID Token. OAuth 2.0 authentication servers implementing OpenID Connect are also referred to as OpenID Providers (OPs). OAuth 2.0 clients using OpenID Connect are referred to as Relying Parties (RPs).

The LogicNets system implements the RP and the OP roles detailed in the OpenID Connect 1.0 specification (https://openid.net/specs/openid-connect-core-1_0.html). The OP is also known as an Identity Provider (IdP) and the Relying Party is also known as the (OpenID) client.

The LogicNets system also implements the SMART-App-Launch Framework (http://hl7.org/fhir/smart-app-launch/), which is based on the OAuth2.0 specification and used in Healthcare to connect third-party applications to Electronic Health Record (EHR) data and to allow apps to be launched from an EHR system.

LogicNets Application Authentication and Authorization

The LogicNets runtime and the LogicNets logon system component implement the authentication and authorization of a LogicNets application, even when a remote IdP is used. The author/modeler of the application does not need to be concerned about this functionality.

The LogicNets infrastructure supports both local users and remote users.

• Local users are managed on the same LogicNets instance as the application, and the authentication and authorization happen within the same instance.
• LogicNets also supports remote users. For this, the application instance connects with an external/remote IdP using the OpenID Connect protocol. The application instance acts as an RP, and the user authentication happens on the remote IdP/OP. The application instance performs the authorization based on the user group memberships reported back by the OP.

The logon component shows a selection form when both local and remote IdPs are configured or when multiple remote IdPs are configured.

The system omits the selection form when only one remote IdP is configured. The application instance logon component redirects immediately to this remote IdP for authentication. The remote IdP can also be a LogicNets instance.

First-time Login with Local Credentials

The next sequence diagram shows the flow between the user, the application, and the logon component when the application has authentication enabled and the user uses a local account. Since the user has not logged in before, the system asks the user to enter their credentials.

Diagram Key:

• Green arrows show the steps that are visible in the browser (visible to the user).
• Black arrows show the LogicNets runtime and system components logic.
• Blue arrows show the application-specific logic.

Single Sign-on with a Local User Account

The next diagram shows the flow when the system has authenticated the user. The system uses a cookie to store the authentication id in the client’s browser. The cookie has the scope of the host name and company name (e.g. 'https://hostname/companyname') and is browser-session bounded. Note, the cookie is shared between all tabs of a browser; please check your browser for the exact details when a browser session ends.

First-time Login using a Remote IdP

The next sequence diagram shows the flow between the application, application-instance logon component, and a remote IdP. In this diagram, the remote IdP is also a LogicNets instance acting as the OP. The application-instance logon component acts as an RP.

Single Sign-on with a Remote User Account

The next sequence diagram shows the flow between the applications, application-instance logon components, and a remote IdP. In this diagram, the remote IdP is also a LogicNets instance acting as the OP. The application-instance logon components acts as an RP. This diagram shows the use case when the user logged on previously and the system skips the step of entering the user’s credentials. In this diagram, the two applications are hosted on two different application instances.

LogicNets as OpenID Provider

LogicNets can be configured as the OP. As a starting point, the client (RP) can obtain the LogicNets OpenID Provider Configuration information (see https://openid.net/specs/openid-connect-discovery-1_0.html) via 'https://<host-name>/<company|tenant>/.well-known/openid-configuration'.

As result, the system returns the list of available endpoints and other meta data. The system supports the following endpoints (starting with 'HTTPS://<host-name>/<company|tenant>/oauth2token').

Endpoint	Description
/authorize	This starts the OAuth flow.
/token	This is the endpoint to retrieve initial and refreshed access, id, and refresh tokens.
/logout	This is the endpoint to log out a user.
/keys	This is the API endpoint to retrieve all active signing public keys.
/introspect	This is the API endpoint to check the active status of an access token or refresh token.
/userinfo	This is the API endpoint to retrieve the information about the authenticated user.

Client Registration

A server user must be created at the OpenID Provider instance before the IdP Client (RP) can use LogicNets as an OP. This can be done via AccessManagement (HTTPS://<host-name>/<company|tenant>/AccessManagement). The system will generate a client id and secret, and you need to copy both to the IdP Client. The client secret is only visible during the creation process. The LogicNets OP supports confidential clients, so the client can protect the client secret.

Authorize Endpoint

The LogicNets system supports the Authorization Code Flow, which means that the the system authenticates the user and returns an authorization code to the client using the authorize endpoint. This authorization code can be exchanged with an access token, id token, and refresh token through the token endpoint.

Authorize Request Parameters

Parameter	Description
response_type	REQUIRED. OAuth 2.0 Response Type value that determines the authorization processing flow to be used, including what parameters are returned from the endpoints used. The value must be code since LogicNets uses the Authorization Code Flow.
scope	REQUIRED. Space-delimited, case-sensitive list of scopes. The supported scopes are listed below.
client_id	REQUIRED. OAuth 2.0 Client Identifier created during the client-registration step.
redirect_uri	REQUIRED. LogicNets will redirect to this URI after the authentication is finished (not-) successfully. The URI should use the HTTPS scheme. The OP will add parameters to this URI to return the results (see authorize-response).
state	RECOMMENDED. An opaque value used to maintain the state between the request and the callback.
nonce	OPTIONAL. A string value used to associate a client session with an ID token and mitigate replay attacks. The value is passed through unmodified from the Authentication Request to the ID Token. Sufficient entropy MUST be present in the nonce values used to prevent attackers from guessing values.
prompt	OPTIONAL. If left empty the OP tries to use single sign-on (when the authentication session is not yet timed-out (see below for more information)). If the authentication session is timed out the user is forced to enter their credentials. 'login' will force the user to enter their credentials on that request, negating single sign-on. 'create' will open the request-access page to allow the user to sign up for an account. After signing up, the user returns to the application with the newly created account.
max_age	OPTIONAL. Maximum Authentication Age specifies the allowable elapsed time in seconds since the last time the end user was actively authenticated by the OP. If the elapsed time is greater than this value, the OP will attempt to actively re-authenticate the end user. The max_age hint is also passed to the next OP/IdP when IdPs are chained (see below).
login_hint	OPTIONAL. Hint to the OP about the login identifier the end user might use to log in (if necessary). This hint can be used by an RP if it first asks the end user for their email address (or other identifier) and then wants to pass that value as a hint to the OP. LogicNets uses this hint to prefill the user-name input box. The login_hint is also passed to the next OP/IdP when IdPs are chained (see below). The system also compares the login_hint with the currently-logged-in user. If they do not match, the system aborts the single sign-on and the LogicNets OP forces the user to enter their credentials.
iss	OPTIONAL. Issuer identifier. If the LogicNets OP is used as a proxy to other (remote) IdPs this parameter identifies the remote IdP base URL or, in the case of SMART-on-FHIR, it Identifies the EHR's FHIR endpoint. The iss value must be equal to one of the configured valid iss-uris in the LogicNets client-OpenID-configuration (see “LogicNets as Relying Party”). The LogicNets OP uses this value to obtain additional details about the remote IdP or EHR, including its authorization URL. This value is stored in the access token. The application can use this information to access the FHIR Server (iss). See http://hl7.org/fhir/smart-app-launch/ for more information.
launch	OPTIONAL. An opaque identifier for this specific launch and any EHR context associated with it. This parameter is passed to the EHR/remote IdP at authorization time. See http://hl7.org/fhir/smart-app-launch/ for more information.
alert	OPTIONAL. Currently, only ‘not_authorized’ is supported. This is used by the application to indicate to the authorized endpoint why the application asks for re-authentication. ‘not_authorized’ is used to indicate that the authenticated user is not authorized to use this application. The authorized endpoint displays a proper message to the user and forces the user to enter the credentials (SSO is ignored).
username	OPTIONAL. The username and password parameters are used as credentials to authenticate the user without showing a logon form or use the active SSO authentication session.
pw	OPTIONAL. The username and pw parameters are used as credentials to authenticate the user without showing a logon-form or use the active SSO authentication session.
action	OPTIONAL The authorize endpoint can also be used to open the user’s account page, to open a change password form. This can be controlled via the ‘action’ parameter. logout – log out the active authentication session account – show the user’s account page access – show the request access page reset_password | change_password | confirm_account | custom – internal modes
license_code	OPTIONAL. This parameter can contain a license code created via the LogicNets AccessManagement license manager. The license is attached to the authenticated user when the system supplies a valid and active license code.

Supported Scope

Scope	Description
openid	The id_token is returned when the token endpoint is called.
profile	This scope value requests access to the end user's default profile claims, which are email, company, name, family_name, given_name, middle_name, preferred_username, locale, and updated_at.
legacy_profile	This scope value requests access to legacy/deprecated first_name and last_name claims. These claims were supported until v7.4.2 and were then replaced by the OpenID Connect claims given_name and family_name.
email	This scope value requests access to the email claims.
phone	This scope value requests access to the phone_number claims.
groups	This scope value requests access to the groups and groups_str claims.
category.<category>	This scope value requests access to the roles claim. The roles claim will list all user roles of the authenticated user for the specific category (of an application). The category value is equal to the project name of the application and can also be found in the PackageInstaller.

Based on the current authentication state and the configuration the authorize request will do the following:

1. Automatically authentication the user, or
2. Redirect to a remote IdP directly, or
3. Show logon controls to user.

The user is automatically authenticated when:

• the authentication session (single-sign-on) is not expired.
• the authentication session is not logged out by the user.
• the authentication session is not older than the provided max_age parameter.

The LogicNets OpenID provider will redirect directly to a remote IdP when automatic authentication is not possible and there is only one remote IdP configured and usage of local user accounts is disabled.

The LogicNets OpenID provider will show logon controls if the user is not automatically logged on and there are more than 1 remote IdPs configured or the usage of local user accounts is enabled.

When the authorize-request is finished (successfully or failed) the system calls the provided redirect URI with the authentication-response parameters.

Authentication Response Parameters

These parameters are added to the redirect URI when the authorization step is finished.

Parameter	Description
state	This is equal to the state parameter passed in the authorize request.
code	(success case) The authorization code that must be used by the IdP client to obtain the tokens via the token endpoint. The authorization code expires after 5 minutes and can only be used once.
session_state	-not released yet- (success case) Used for session management (see https://openid.net/specs/openid-connect-session-1_0.html). JSON [RFC7159] string that represents the end user's login state at the OP. This value is opaque to the RP.
error	(error case) OAuth 2.0 error code.
error_description	(error case) Human-readable ASCII encoded text description of the error.

Token Endpoint

The RP can retrieve the tokens after the authorize endpoint is returned to the RP (client). The client retrieves the tokens via a back-channel (server-to-server) using the LogicNets token endpoint. The client sends the parameters to the token endpoint using the HTTP POST method and the Form Serialization (application/x-www-form-urlencoded). Tokens could be leaked--causing causing security leaks--if the parameters were sent via the request query parameters.

The token endpoint is protected against unauthorized access, so the client id and client secret must be passed for authentication. The client id and client secret can be passed via the POST body or via the request-authorization header.

Token Request Parameters

Parameter	Description
client_id	REQUIRED. OAuth 2.0 Client Identifier created during the client-registration step. This should be the same client id as the one passed to the authorization endpoint. Note: This is OPTIONAL if client_assertion_type='urn:ietf:params:oauth:client-assertion-type:jwt-bearer'.
client_secret	REQUIRED. OAuth 2.0 Client secret created during the client-registration step.
redirect_uri	OPTIONAL. Redirect URI, which is also passed to the authorize endpoint.
grant_type	REQUIRED. This must be either ‘authorization_code’, ‘refresh_token’, or 'client_credentials'. When ‘authorization_code’ is passed the ‘code’ parameter must be filled. The token endpoint returns the tokens that are generated during the authentication step (using the authorize endpoint). When ‘refresh_token’ is passed the ‘refresh_token’ parameter must be filled with a refresh token that is received from a previous call to the token endpoint. You can use the client credentials flow (OAuth 2.0 RFC 6749) with the client_credentials grant type.
code	REQUIRED when grant_type=’authorization_code’. This parameter must contain the code received via the authorization-endpoint callback. This code can only be used immediately after the callback is called.
refresh_token	REQUIRED when grant_type=’refresh_code’. This parameter must contain the refresh_token received in an earlier call to the token endpoint. The call should only succeed when the refresh_token is not expired.
client_assertion_type	REQUIRED when the client_assertion parameter is set. When used, the client_assertion_type must be set to 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer' and the client_assertion must contain a valid JWT token. See RFC 7523: JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants for more information.
client_assertion	REQUIRED when client_assertion_type parameter is set. This must contain a valid JWT token.

Successful Token Response

The token request returns an HTTP status code 200 when the request was handled successfully. In a successful response, the following data is returned in a JSON format.

Parameter	Description
access_token	The access token that can be used to authenticate a client in outbound Web API calls.
token_type	“bearer”
refresh_token	Refresh tokens that can be used to retrieve new access and id tokens when they are expired.
expires_in	The number of seconds until the access token expires.
id_token	JWT OpenID connects compatible ID tokens. This token is only part of the response if the ‘openid’ scope is passed to the initial call to the authorize endpoint. This id token contains all known information about the authenticated user.

Failed Token Response

In case of an error, a non-200 HTTP status code us returned with a JSON response that includes an error id and error description.

Parameter	Description
error	This is the OAuth 2.0 error code.
error_description	This is a human-readable ASCII encoded text description of the error.

Possible Errors

Status Code	Error	Description
401	invalid_client	client_id and/or secret are not correct.
400	invalid_client	client_id does not match with the client id belonging to the code or refresh_code.
400	invalid_request	Code not found.
400	invalid_request	User is logged out.
400	invalid_request	Authentication/keep-me-logged-on session is expired.
500	invalid_request	Internal error during updating state.
400	invalid_request	Token is retrieved too late.
400	invalid_request	Token already retrieved earlier.
400	invalid_request	Redirect URIs do not match.
401	invalid_client	The client_assertion_type is invalid.
401	invalid_grant	client_assertion is not a JWT token.
401	invalid_grant	Missing iss (issuer) claim.
401	invalid_grant	Sub (subject) is not equal to the client_id.
401	invalid_grant	Audience validation failed (the aud claim must be equal to the LogicNets server URL).
401	invalid_grant	Grant is expired.

Introspect Endpoint

You can use the introspect endpoint to validate a token. This endpoint returns whether the passed token is still active. The introspect endpoint is protected against unauthorized access, so the client id and client secret must be passed for authentication. The client id and client secret can be passed via the POST body or via the request-authorization header. Tokens could be leaked (causing security leaks) if the parameters were sent via the request query parameters.

Introspect Request Parameters

Parameter	Description
client_id	REQUIRED. OAuth 2.0 Client Identifier created during the client-registration step. The same client id that was passed to the authorization endpoint must be used.
client_secret	REQUIRED. OAuth 2.0 Client secret created during the client-registration step.
token	REQUIRED. access-token, id-token, or refresh-token received earlier from a LogicNets token endpoint.
token_hint	OPTIONAL. The following values are supported ‘access_token’, ‘id_token’, or ‘refresh_token’.

Successful Introspect Response

The introspect request returns an HTTP status code 200 when the request was handled successfully. In a successful response, the following data is returned in a JSON format.

Parameter	Description
active	This is true when the token is correct and still active. Otherwise, the value will be false when the token is no longer active, when the token is expired (or in case of a refresh token when the authentication session is expired), when the related authentication session is logged out, when the token does not exist, when the token is not created for this client id, when the token structure is not correct, or when the token signature cannot be verified. The inactive reason is not returned for security reasons, however, the reason is logged by the OpenID provider.
exp	(Only if the token is active.) Expiration time on or after which the token is no longer valid. Its value is a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time.
iat	(Only in case the token is active) Time at which the token was issued. Its value is a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time.

Failed Introspect Response

In case of an error, a non-200 HTTP status code is returned with a JSON response that includes an error id and error description.

Parameter	Description
error	This is the OAuth 2.0 error code.
error_description	This is the human-readable ASCII encoded text description of the error.

Possible Errors

Status Code	Error	Description
401	invalid_client	client_id and/or secret are not correct.
400	invalid_request	Missing token.

Userinformation Endpoint

You can use the userinformation endpoint to retrieve information about the logged-on user. This endpoint returns similar claims as those present in the id token. The userinformation endpoint is protected against unauthorized access, so a valid access token must be present as a bearer token in the authorization header for authentication.

Successful Userinformation Response

The userinformation request returns an HTTP status code 200 when the request was handled successfully. In the response, the sub-claim is always returned and based on the authorized scope also other claims, such as email, name, and given_name.

Failed Userinformation Response

In case of an error, a non-200 HTTP status code is returned with a JSON response that includes an error id and error description.

Parameter	Description
error	This is the OAuth 2.0 error code.
error_description	This is the human-readable ASCII encoded text description of the error.

Possible Errors

Status Code	Error	Description
401	invalid_token	The bearer token must be an access token.
401	invalid_token	The access token signature is not valid.
401	invalid_token	Unknown access token.
401	invalid_token	The access token authentication session is logged out.
401	invalid_token	The access token is expired.
401	invalid_token	Missing bearer token.

End-session/Log-out Endpoint

The LogicNets OpenID provider also provides an end-session endpoint to log out the user (authentication session). The current active authentication session is logged out when this endpoint is called via the browser. The user is asked to authenticate again when the authorization endpoint is accessed after this call. The token-introspect returns active='false' when a token is passed that is created using the authentication session. The token endpoint returns an error when a refresh token is used that is created using the authentication session.

End-session Request Parameters

Parameter	Description
post_logout_redirect_uri	OPTIONAL. This is used to redirect back to the client after sign out. The LogicNets OpenID provider will show a message that the user is logged out when no post_logout_redirect_uri is specified.
state	OPTIONAL. If a valid post_logout_redirect_uri is passed, then the client may also send a state parameter. This will be returned to the client as a query string parameter after the user is signed out. This is typically used by clients to round-trip state across the redirect.
id_token_hint	OPTIONAL. An id_token can be passed to log out a specific authentication session that belongs to the passed id token. If left empty, the authentication cookie is used to identify the session that must be logged out.

Authentication Timeout/Keep-Me-Logged-In Timeout

The LogicNets OpenID Provider supports single sign-on, so the user does not need to authenticate again when their last authentication happened recently. The single sign-on information is stored in a browser cookie called ‘authenticationid’ and it is protected against theft using constantly changing session-pin cookies. By default, the authentication cookie uses the SameSite ‘lax’ setup, which means that the cookie is not shared between parent and iframes but is shared between browser tabs. The SameSite settings should be changed via System Configuration to support single sign-on i.c.w. iframes. To support iframes the SameSite should be set to ‘none’.

The authentication session time-out is equal to the configured session time-out (default: 240 minutes). The timeout is extended every time the authorize endpoint is accessed via the browser before the authentication session is expired. The authentication session time-out is also extended when the token endpoint is used to refresh the tokens. The authentication session is also ended when the end-session endpoint is called.

Authentication of Outbound and Inbound Web APIs

Most Web APIs are protected against unauthorized access. LogicNets supports different kinds of authentication methods for outbound and inbound Web API calls.

Inbound authentication for Web APIs always happens via the HTTP-authorization header. LogicNets supports both basic and bearer authorization headers. LogicNets supports two types of bearer tokens:

• private_key_jwt, which is similar to client authentication in https://openid.net/specs/openid-connect-core-1_0.html#ClientAuthentication.
• access token

The access token is the access token received from the token endpoint. The private_key_jwt is a JWT token that is signed with a private key that only the client has. The public key is stored at the Web-API endpoint. Using AccessManagement on the Web-API endpoint, a public and private key can be generated for a server user. The public key is stored and the private is only available during generation and needs to be copied to the client of the Web API.

Authentication for outbound Web APIs can be configured in the call-webservice part, which supports basic, bearer, and manual authorization headers. It also provides the option to use the access token of the currently logged-in user.

JWT Token Format

LogicNets accepts JWT tokens generated by LogicNets or by clients as long as the user-id/client-id is equal to a user created in AccessManagement. For information about the valid JWT format required by LogicNets, see How to Use the OAuth 2.0 Client Credentials Flow Using RS256-signed JWT Bearer. See RFC 7523: JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants for additional information.