OAuth Connectors

Introduction to OAuth connectors

OAuth is an open-standard authorization protocol or framework that describes how unrelated servers and services can safely allow authenticated access to their assets without actually sharing the initial, related, single logon credential. This is also known as secure, third-party, user-agent, delegated authorization.

In a process flow, three process actions (connectors) are available for OAuth. They can be used, for example, to leverage the Microsoft Graph API (Azure, Office 365, Microsoft 365) on behalf of a user instead of a service account.

• Introduction to OAuth connectors
• Example of OAuth connectors in a process flow
• Configure an OAuth server for an OAuth connector
• OAuth server login connector
• OAuth user login connector
• Connect OAuth user login connector to Azure
• OAuth refresh token connector

Example of OAuth connectors in a process flow

This visualization in the modeler shows the two types of grant flows (OAuth user login connector and the OAuth server login connector) in a process flow:

Example: two types of grant flows in a process flow

Configure an OAuth server for an OAuth connector

The OAuth connectors need a connection to an OAuth server. See OAuth servers.

OAuth server login connector

Indicium Universal GUI

Starting point Universal GUI	Starting point Win/Web GUI	Starting point system flow (Indicium)	System flow action
-	-	+	+

In a process flow, you can use the process action OAuth user server connector to retrieve an OAuth 2.0 authorization code. This connector uses the client credentials grant type that requires no user interaction or consent, though it may deviate regarding supported scopes or require some form of preemptive administrator consent.

Input options
Scope	A scope will override the OAuth server settings.

Output options
Access token	The access token string as issued by the authorization server.
Expires in	Recommended. This parameter contains the duration of time the access token is granted for.
Token type	At this moment, only bearer is supported.
Status code	The status code of the executed action. 0 - Successful -1 - Unsuccessful (unknown) -2 - Unsuccessful (no configuration) -3 - Unsuccessful (no scope)

OAuth user login connector

Starting point Universal GUI	Starting point Win/Web GUI	Starting point system flow (Indicium)	System flow action
-	-	+	-

In a process flow, you can use the process action OAuth user login connector to retrieve an OAuth 2.0 authorization code, by redirecting a user to an external identity platform. This process action type always uses the authorization code grant type, which requires user interaction.

See also Connect the OAuth user login connector to Azure.

Input options
Scope	A scope will override the OAuth server settings.
UsePrompt	Optional. - Default: True = always consent necessary by user. - False = no consent asked. If the user has not been authorized before, an error may occur.

Configuration options	Where to apply
OAuthRedirectURI	Application setting IAM	Use this extended property to change the standard OAuth connector redirect URI (http://localhost/oauth-callback). Use it, for example, to change HTTP to HTTPS.

Output options
Access token	The access token string as issued by the authorization server.
Granted scopes	If the scope the user granted is identical to the scope the app requested, this parameter is optional. If the granted scope is different from the requested scope, such as if the user modified the scope, then this parameter is required.
Expires in	Recommended. This parameter contains the duration of time the access token is granted for.
Refresh token	Optional. If the access token will expire, then it is useful to return a refresh token which applications can use to obtain another access token. However, to obtain a refresh token offline access needs to be enabled in the configuration.
Token type	At this moment, only bearer is supported.

OAuth user login connector status codes
0 - Successful.
-1 Unsuccessful, cause unknown.
-2 Unsuccessful, aborted. The user has aborted the login screen.
-3 Unsuccessful, connection error with the OAuth server.
-5 Unsuccessful, unsupported token type. The token response is not a bearer token.

Connect OAuth user login connector to Azure

To connect the OAuth user login connector to your Azure environment:

1. In the Azure portal, search for Azure Active Directory and open this service.

   Open Azure Active Directory

2. In the menu at the left, open the menu item App registrations.

3. Press New registration.

   

4. Register your application. The standard redirect is Web and:

   • For Windows GUI (2-tier) the URL is http://localhost/oauth-callback. To change the standard, use the OAuthRedirectURI extended property in IAM.
   • For Windows GUI (3-tier) Universal GUI the URL is <indicium URL>/oauth-callback. For example: https://myserver/indicium/oauth-callback.

   Register your application

5. Press Register.

6. In your new application, at the Client credentials, select Add a certificate or secret.

   Add certificate or secret

7. Add a New client secret and copy its Value.

   New client secret

   After refreshing this page, the value is hidden:

   Client secret after page refresh

   The Application (client) ID is now displayed under Essentials:

   Application client ID (fully visible in your Azure portal)

8. Press Endpoints for an overview of all the token and authorization endpoints. The Thinkwise Platform uses:

   • OAuth 2.0 authorization endpoint (v2).
   • OAuth 2.0 token endpoint (v2).

   

9. In the Software Factory, navigate to the menu Models > Model overview > tab Branches > tab OAuth servers.

10. Add Scope User.Read (Microsoft Graph).

    Scope for Oauth server for Azure

    In the Developer ribbon, you can view the result in the Process flow monitor, after executing the Oauth connector process step:

    Result after executing OAuth connector

OAuth refresh token connector

Starting point Universal GUI	Starting point Win/Web GUI	Starting point system flow (Indicium)	System flow action
-	-	+	+

In a process flow, the process action OAuth refresh token connector can request a new access token for OAuth if the old one is expired. This connector uses a refresh call, which removes the need for user interaction with the OAuth server every time the access token expires.

Input options
Refresh token	The refresh token, received by the OAuth user login connector.

Output options
Access token	The new access token string, issued by the OAuth server.
Granted scopes	The scopes returned by the OAuth Server. If the granted scope is identical to the scope the app requested, this parameter is optional. If the granted scope differs from the requested scope, for example, if the user modified the scope, then this parameter is mandatory.
Expires in	Recommended. The lifetime of the new access token in seconds.
Refresh token	Optional. If the OAuth server allows the refresh token to be used only once, a new refresh token is obtained for the next time the OAuth refresh token refreshes the access token.
Token type	At the moment, only bearer is supported.

OAuth refresh token status codes
0 - Successful.
-1 Unsuccessful, cause unknown.
-2 Unsuccessful, no OAuth server configured.
-3 Unsuccessful, input data is missing.