Generic OAuth2 rule
This rule implementation is based on the authorization code flow from Okta and also supports OAuth 1.0 and OpenId Connect (OIDC) providers. This page describes the OAuth 2.0 flow, refer to OIDC authentication for recommendations on using OIDC.
Rule requirements
- All Authentication policies require the Authorize By Role rule to authorize the caller. 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:
Other authentication providers might be compatible, but haven't been tested and verified by SnapLogic.
OAuth 2.0 framework for authorization code grant type
The OAuth 2.0 Authorization Code grant flow allows a client application to authenticate a user without requiring the user's password.
OAuth roles include:
- Client application: In this case, APIM 3.0 is the client. The Snaplex redirects user requests to an endpoint with a Generic OAuth 2.0 rule to the authorization server for authentication and authorization.
- Resource Owner (User): The user who owns the resources for which the client application is requesting access.
- Authorization Server: The authorization server authenticates the user's identity and .
The following describe how those roles interact in the Authorization Code flow:
- Client Registration: You register the SnapLogic URL as a client application with an identity provider (IdP) such as Ping Identity, Okta, Github, Salesforce or Azure. The IdP issues a Client ID, Client Secret and Redirect URI that you use to configure the Generic OAuth 2.0 rule. After receiving a request to an endpoint where this rule applies, the Snaplex uses these values to communicate and authenticate with the IdP.
- Authorization Request: To access resources on behalf of a user, the Snaplex redirects the user to the Identity Provider's authorization endpoint. The request includes the SnapLogic client ID and client secret.
- User Authentication and Authorization: The user authenticates with the Identity Provider and grants permission to access their resources. If the user approves, the IdP redirects the user back to the Snaplex with an authorization code.
- Token Request: The Snaplex receives the authorization code and sends a request to the IdP'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.
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 |
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:
Select one of the following algorithm types:
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. |
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:
|
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 |
[
{
"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
}
]
- 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.