Setup external authentication with OAuth2.0
OAuth (short for "Open Authorization") is an open standard for access delegation, commonly used as a way for internet users to grant websites or applications access to their information on other websites without requiring the provision of passwords, as defined by Wikipedia. This article will outline the necessary configurations to integrate an OAuth authorization service, focusing on its implementation using Google as the service provider.
Before integrating an authorization service, it's important to set up the authorization provider. The setup procedure varies depending on the chosen provider. For the purposes of this article, Google will serve as the example provider; however, most OAuth service providers can be used (some notable providers).
Below is a visual representation of the OAuth process when used to get information from a google docs server:
Once a provider is chosen and configured, the next step involves navigating to the "webservice & comet" tab located in the resource pane of the modeler project. Within this tab, the OAuth 2.0 authorization folder is accessible, serving as the designated area for configuring the client-side Authorization Service utilized by the authentication node within the flowcharts. To add a service, access the context menu of the OAuth folder through either right-clicking or selecting the three dots and choosing "add."
Name
A unique name used in only in the modeler for identification.
The details needed for the server depend on the Grant type chosen, this type of authentication and communication used by the API. WEM supports the following grant types:
Authorization Code
Client Credentials
JSON Web Token
With the authorization code grant a code is exchanged for an access token where the user gets a chance to see what information access is requested. The user sees the authorization prompt and approves the app's request. The user is redirected back to the application with an authorization code in the query string, the application then exchanges the authorization code for an access token that unlocks the client application.
Authorization endpoint
Token endpoint
Scope
In the case of the Client Credentials grant, the application requests an access token to access its own data or functionalities outside of the context of a user. This grant type is typically used by clients to access information or functionalities pertaining to the application itself, rather than those associated with a specific user.
Token endpoint
Endpoint used to request a token used to validate the login to the client. The client credentials are used for validation.
Scope
JWTs can be used as OAuth 2.0 Bearer Tokens to encode all relevant parts of an access token into the access token itself instead of having to store them in a database. The JWT Type enables creating a custom JWT claims.
When configuring the JWT definition, the initial step involves setting the token endpoint, which denotes the URL to which the JWT is dispatched. Following this, the subsequent step entails establishing the JWT Claims. A claim manifests as a name and value pair, wherein the name consistently assumes a string format, while the value may encompass any JSON value or expression. Two distinct types of claims exist:
Registered: standard claims registered with the Internet Assigned Numbers Authority (IANA) and defined by the JWT specification to ensure interoperability with third-party, or external, applications. OIDC standard claims are reserved claims like:
iss (issuer): Issuer of the JWT
sub (subject): Subject of the JWT (the user)
aud (audience): Recipient for which the JWT is intended
exp (expiration time): Time after which the JWT expires
nbf (not before time): Time before which the JWT must not be accepted for processing
iat (issued at time): Time at which the JWT was issued; can be used to determine age of the JWT
jti (JWT ID): Unique identifier; can be used to prevent the JWT from being replayed (allows a token to be used only once)
Custom: consists of non-registered public or private claims. Public claims are collision-resistant while private claims are subject to possible collisions.
Within the client details, inclusion of the Client ID and secret are imperative for secure communication with the client. This setup is configured on a per-portal basis, enabling the utilization of different IDs and Secrets as required. In this section, you can specify the redirect URLs for different portals and runtimes of the application. These URLs typically adhere to the following syntax:
Preview: https://preview.wem.io/*projectID*/auth/oauth2/
Staging: http://*projectName*.staging.wem.io/auth/oauth2/
Live: http://*projectName*.live.wem.io/auth/oauth2/
When utilizing an OAuth service for login, an access token is automatically generated and exchanged between the authorization server and resource server. This access or bearer token can be mapped to a field for use in custom webservices or when using JWT grant with custom headers.
The complete response of the authorization to the Oauth2 service can be mapped to a text field, this will contain the entire response returned from the service. This can be useful for debugging issues.
Initially, an OAuth client ID Credentials must be established in the (Google) Cloud Console, along with the setup or selection of an API. Once the API is obtained, proceed to the credentials section, where you can navigate to OAuth 2.0 Client IDs. Alternatively, you can create a new one using the "create credentials" option, specifying "OAuth client ID" as the type, and choosing a name for identification purposes.
The next step is setting up the JavaScript origins and the Authorized redirect URIs. The JavaScript origins is the hostnames of the WEM project in preview, staging and live:
Preview: https://preview.wem.io Staging: http://wemdocumentation.staging.wem.io/ Live: http://wemdocumentation.live.wem.io/
The authorized redirect URIs is where you are redirected after the authentication by google. The path will be appended with the authorization code for access and can’t contain URL fragments, relative paths, or wildcards, and can’t be a public IP address. In the testcase this will be:
Preview: https://preview.wem.io/49367/auth/oauth2/oauth-2.0-playground Staging: http://wemdocumentation.staging.wem.io/ Live: http://wemdocumentation.live.wem.io/auth/oauth2/oauth-2-playground/
When the client, the provider and Oauth definition is set up the Oauth service can be used in the modeler. There are two main ways to use the Oauth implementation in a project; with a authentication node or with a http request node using the Oauth as authentication provider.
The authentication node can be used to authorize the application access to a API or to allow the project to perform actions on the resource provider or to check if a user has access to certain information. In the image below is an implementation where the Auth node is used to give the application access to certain actions on the provider service.
In the following example the Oauth authorization is used to set up a GET request for a list of files in a google docs account. We set up the definition with the google examples talked about earlier:
Grant type
Authorization Code
Authorization endpoint
Token endpoint
Scope
The next step is setting up the authorization service in google docs, for this you can use the talked about method earlier, there you find the client details and add them to the Oauth definition in the modeler.
If the token field has not been created yet that would be the next step as this is where the Access token is mapped. The service also needs a response field to store the response and use it further in the application. For this specific example we also create a list to store the information received from google docs. In this case that is a FileType, MimeType, and Name field.
This section involves creating the flowchart and setting up the necessary nodes for our service. The final result will resemble the following:
First, we set up a landing page from which the request is initiated, and its results are displayed upon completion. This corresponds to the OAuth node shown in the image above.
On this page we want have a button to start send the request and a datafield to show the results when we return.
The next node is the HTTP request node that handles the request to google docs and handles the OAuth authentication.
For the url we put the scope and endpoint of the google drive API service, in this case "https://www.googleapis.com/drive/v3/file" this lets the webservice know where to start. The request is a GET request and the default timeout is good enough. The Follow redirect should be toggled on as this is needed for the authentication, which is set to OAuth 2 with the Oauth definition made earlier as the provider. The only property left is the response body that can be written to the response field made earlier.
Next step is connecting the exits to the next node, for this solution a failed and a success node is created. These nodes just have to show the the response body to be able to see if it was successful and can be removed after set up is done.
The import node Datasource is the response body from the step before. Now we run the project and webservice, if this is set up correctly the response body can be used to create the import node mapping.
Now connect up the import node back to the original Oauth node with the data-grid and run the service. When everything is setup correctly he result can look like this:
Server endpoint used for sign in authentication. This is the start page to login into the provider service. For google this is:
Endpoint used to exchange the authorization code for a access token used to validate the login to the client. For google this is:
The scope is a space-delimited list of permissions in string format, used to limit an application's access to a user's account. For google you can find examples here:
The scope is a space-delimited list of permissions in string format, used to limit an application's access to a user's account. For google you can find examples here:
In this case we want to use a specific google service scope called:
