> For the complete documentation index, see [llms.txt](https://docs.wem.io/platform/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.wem.io/platform/wemmodeler/services-and-integration/authentication-providers/oauth-2.0.md). # OAuth 2.0 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](https://en.wikipedia.org/wiki/List_of_OAuth_providers)). Below is a visual representation of the OAuth process when used to get information from a google docs server:

## Add Service 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."

## OAuth definition ### Basic Settings

Setting	Description
Name	A unique name used in only in the modeler for identification.

### Server Details 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 #### Authorization Code 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.

Setting	Description
Authorization endpoint	Server endpoint used for sign in authentication. This is the start page to login into the provider service. For google this is: https://accounts.google.com/o/oauth2/auth
Token endpoint	Endpoint used to exchange the authorization code for a access token used to validate the login to the client. For google this is: https://oauth2.googleapis.com/token
Scope	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: https://developers.google.com/identity/protocols/oauth2/scopes#oauth2

#### Client Credentials 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.

Setting	Description
Token endpoint	Endpoint used to request a token used to validate the login to the client. The client credentials are used for validation.
Scope	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: https://developers.google.com/identity/protocols/oauth2/scopes#oauth2

#### JSON Web Token (JWT) JWTs can be used as OAuth 2.0 [Bearer Tokens](https://oauth.net/2/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)](https://www.iana.org/assignments/jwt/jwt.xhtml) and defined by the [JWT specification](https://tools.ietf.org/html/rfc7519) 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. ### Client Details 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: * Staging: http\://\*projectName\*.staging.wem.io/auth/oauth2/ * Live: http\://\*projectName\*.live.wem.io/auth/oauth2/ **Portal configuration (JWT grant only)** When the **JSON Web Token** grant type is selected, two extra fields appear on each portal configuration: **Signing algorithm** and **Signature**. Together they determine how the JWT that WEM sends to the token endpoint is signed, so that the authorization server can verify that the request genuinely came from your portal. The **Signing algorithm** defines both the cryptographic algorithm used to sign the JWT and what the accompanying **Signature** field should contain. Pick the option that matches what you configured on the authorization server side: | Signing algorithm | Signature contents | When to use | | ----------------- | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | HMAC SHA 256 | A shared password (client secret) | Symmetric signing: the same secret is used by WEM to sign the JWT and by the authorization server to verify it. Choose this when the authorization server expects a client secret. | | RSA SHA 256 | A certificate | Asymmetric signing using RSA with SHA-256. WEM signs the JWT with the private key of the selected certificate; the authorization server verifies it using the matching public key. | | RSA SHA 512 | A certificate | Asymmetric signing using RSA with SHA-512. Functionally identical to RSA SHA 256, but using the stronger SHA-512 hash. Use this when the authorization server requires it. | ### Map Output 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. ## Set up the (Google) Authorization 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: \ Staging: \ Live: 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: \ Staging: \ Live: [http://wemdocumentation.live.wem.io/auth/oauth2/oauth-2-playground/](http://wemdocumentation.live.wem.io/)

## Back to the modeler 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. ### Authentication node 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.

### Getting access from google 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: #### Server settings: | Setting | Value | | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Grant type | Authorization Code | | Authorization endpoint | | | Token endpoint | | | Scope |

In this case we want to use a specific google service scope called:

| 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. ### Preparing the datamodel 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. ### The flowchart and its interactions 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 "" 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:

--- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.wem.io/platform/wemmodeler/services-and-integration/authentication-providers/oauth-2.0.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.