Generic OAuth2 rule

Authenticates a client by delegating the authentication to an OAuth2 provider. This rule authenticates requests that don't contain credentials for other authentication policies, such as an API Key. The Snaplex redirects the request to the OAuth provider to start the authentication flow. Successful authentication returns an access token that the rule uses to perform one or more requests to get information about the client, such as the ID and assigned role. Finally, a session cookie is returned to the client, and the client is redirected back to the requested URL. Subsequent requests authenticate based on the session cookie instead of repeating the OAuth flow. This implementation is based on the authorization code flow from Okta and supports OpenId Connect providers.
Note: The Generic OAuth2 rule also supports OAuth 1.0.

Rule requirements

  • All Authentication policies require the Authorize By Role rule to authenticate the caller correctly. For example, you can configure this rule to add the role admin to the client and then configure the Authorize By Role rule to authorize users with that role.
  • Users must enable cookies in their browser for this rule to work with OAuth providers.

Verified providers

SnapLogic verified the following authentication providers for this rule:

This rule might work with other authentication providers not listed above but has not been tested and verified.

OAuth 2.0 framework for authorization code grant type

The OAuth 2.0 Authorization Code grant flow is a way for an the client to request an authorization code from an authorization server with the involvement of a user. This flow is suitable for scenarios where the client application needs to access resources on behalf of a user.

  • The OAuth 2.0 Authorization Code flow enables a client application to access other services securely. This is done by authenticating the user's credentials without directly exposing the user's password to the client application. As the resource owner only authenticates with the authorization server, the resource owner's credentials are never shared with the client.
  • The client application requests an authorization code from the authorization server, which the user approves.
  • The client then exchanges the authorization code for an access token, which is used to access protected resources on the user's behalf.

OAuth roles

  • Client: The client is an application that requests access to resources on another resource server. The client redirects the user to the authorization server for authentication and authorization.
  • Resource Owner (User): The user who owns the resources to which the client application is requesting access.
  • Authorization Server: The authorization server authenticates the user's identity and issues authorization codes and access tokens to the application once authorization is granted.

Authorization code grant flow

  • Client Registration: The application is registered with the Identity Provider such as Ping Identity, Okta, Github, Salesforce or Azure which issues a Client ID, Client Secret and Redirect URI. These credentials are used to authenticate the application to the Identity Provider.
  • Rule Configuration: Field settings of the rule for the endpoint includes:
    • OpenID Discovery Document URL
    • Login URL
    • JWS Algorithm
    • Access Token URL
    • Client ID and Client Secret
    • Redirect URI
  • Authorization Request: When the application needs to access resources on behalf of a user, it redirects the user to the Identity Provider's authorization endpoint, including its client ID and client secret where the authorization server sends the authorization code.
  • User Authentication and Authorization: The user authenticates with the Identity Provider and grants permission to the application to access their resources. If the user approves, the Identity Provider redirects the user back to the client application with an authorization code.
  • Token Request: The client application receives the authorization code and sends a request to the Identity Provider's token endpoint to exchange the authorization code for an access token.
  • Token Issuance: The Identity Provider validates the authorization code and the client's credentials. If valid, the Identity Provider issues an access token to the client application.
  • Resource Access: The client application uses the access token to access protected resources on behalf of the user. The access token is included in the authorization header of the HTTP request.

Rule execution order

The Generic OAuth2 rule executes after other authentication policies, specifically those based on the client providing a token in the request, like the API Key or Callout Authenticator policies.

Field Description
When this rule should be applied An expression that defines one or more conditions that must be true for the rule to execute.

Default value: N/A

Example: The expression request.method == "POST" causes the rule to execute only on POST requests.

Use OpenID Connect

Select to use an OpenID Connect (OIDC) vendor as the 3rd-party IdP.

Default value: Deselected

Example: GitHub Selected
OpenID Discovery Document URL

Required. The OIDC discovery URL.
Login URL

Required. The login URL for the client.
JWS Algorithm

The algorithm used to generate the JSON Web Service token. You can find this in the Discovery Document URL to determine which algorithm is supported: id_token_signing_alg_values_supported

Select one of the following algorithm types:
  • HS256
  • HS384
  • HS512
  • RS256
  • RS384
  • RS512

Default value: RS256
Required Scopes

Required. The list of OAuth2 scopes required to get information about a user. See OAuth 2.0 Scopes for details.

Scope The name of the OAuth2 scope.

Example: user, token, session
Access Token URL

Required. The OAuth2 provider’s access token URL. The response from this token URL will be stored in $token and can be referenced in User Info URL below.

Example: https://github.com/login/oauth/access_token
Client ID

Required. The ID of the application registered with the OAuth2 provider.

Example: [email protected]
Client Secret

Required. The client secret for the application registered with the OAuth2 provider.
Redirect URI The URI of the Snaplex load-balancer appended with /api/1/rest/oauth2/callback

Example: https://groundplex.example.com/api/1/rest/oauth2/callback
User Info URL #1-2 These sections describe the HTTP GET requests this rule should make to get information about a user.
Note:
  • Limitation: The User Info URLfield and settings do not support expressions that use the asset or request variables.
  • User Info URL #2 is optional.
Trust all certificates Trust all certificates for expired or self-assigned certificates.
Note: Enabling this option bypasses the certificate validation process. The request will successfully proceed if the upstream URL provides an invalid certificate (expired or self-assigned) during the SSL handshake.

Default value: False/Not selected
Target Path The location to store the result of the request in the working object as a JSON-Path.
Note: If you leave this field blank, the URL is not called.

Example: $user
URL The destination for the request.

Example: https://idp.example.com/userhttps://api.github.com/user
Query Parameters The query parameters (name and value) to add into the URL.
Headers The headers (name and value) to include in the request.

Example: Authorization
Extract User Info

Required. Specifies how to extract information about the user from the working object.
User ID Expression

Required. An expression that returns a string to be used as the user ID.

Example: $user.email
Roles Expression

Required. An expression that returns the list of roles this user is in.

Example: $user.groups.map(group => group.name)
Session: Time-To-Live in Seconds

Required. The number of seconds for which the session is active.

Default value: 86400

Example: 90000
OAuth State: Time-To-Live in Seconds

Required. The number of seconds for which the Oauth state is active.

Default value: 300

Example: 1000
Description Use this rule to authenticate a client by delegating the authentication to an OAuth2 provider.

Default value: Authorizes requests using specified OAuth service.

Session management

The OAuth2.0 rule might require consideration for active session management from an administrative point of view. A network issue or company rule might necessitate overriding the Time-to-Live settings. For this purpose, the following APIs allow a SnapLogic Org admin the ability to list session details and delete sessions as needed:

Purpose API Call
List all sessions GET <Load_Balancer>/<JCC_Host>/api/1/rest/rule/session
List a specific session GET <Load_Balancer>/<JCC_Host>/api/1/rest/rule/session/<Session_Id>
Delete a specific session DEL <Load_Balancer>/<JCC_Host>/api/1/rest/rule/session/<Session_Id>
Delete all sessions DEL <Load_Balancer>/<JCC_Host>/api/1/rest/rule/session
Important: These APIs do not apply to the Time-To-Live settings in the Callout Authenticator API rule.
The session management details returned includes the session ID and user or client details upon making the call. Below is the sample response upon using the GET HTTP method:
[
         {
         "type": "TaskSession$OauthSession",
         "username": "105450719975802175246",
         "roles": [
         "openid",
         "email",
         "profile"
         ],
         "session_id": "0f9eb160-b5ed-4cba-94ea-b5a3ae1fc9e0",
         "expires_at": 1718323653745
         },
         {
         "type": "TaskSession$OauthSession",
         "username": "105450719975802175246",
         "roles": [
         "openid",
         "email",
         "profile"
         ],
         "session_id": "79258c26-e361-46c5-9588-5301434a738a",
         "expires_at": 1718323838403
         }
         ]
Note:
  • If no session is created and an API for the session ID is called, the response returned contains an empty list.
  • A session ID that’s been previously deleted will return a 404 status code upon using GET request.