Generic OAuth2 rule

Authorizes a client by delegating to an OAuth2 or an OpenID Connect (OIDC) provider. Both types of provider issue access tokens for calling APIs on behalf of the user without sharing credentials. For OIDC, a call to the access token URL returns the ID token, which is a JSON Web Token (JWT) that includes the user login and identity.

This rule authorizes requests that don't contain other credentials, such as an API Key. The fields available in the rule differ depending on whether you enable OpenId Connect or just use OAuth2. Refer to OAuth2 rule fields or OpenID Connect rule fields for details. Learn more about the difference between OAuth2 and OpenId Connect.

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.

Rule requirements

  • All Authentication policies require the Authorize By Role rule to authorize the caller. For OIDC, the list of scopes becomes roles and you would need to authorize one. If the open discovery document doesn't define a role, APIM defaults to the openid role.
  • Users must enable cookies in their browser for this rule to work with OAuth or OIDC providers.

Verified providers

SnapLogic follows the RFC standard (link) and has 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 authorization code flow

This rule implementation is based on the OAuth2 Authorization Code Flow and also supports OAuth 1.0. The following participate in the authorization flow:

  • Client application: In this case, APIM 3.0 is the client. When a user requests an endpoint with a Generic OAuth2 rule applied, the Snaplex redirects the request to the login URL for authentication and authorization.
  • Resource Owner (User): The user who owns the resources for which the client application is requesting access.
  • Authorization Server: The Identity provider authenticates the user's identity and issues authorization codes and access tokens to the client application.

The steps required to use Oauth2 include:

  • 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 authorization header of the HTTP request includes the access token.

OpenID Connect authorization flow

You can configure the Generic OAuth2 Rule to use OpenID Connect (OIDC) to authenticate and authorize users. The authorization flow begins when a Service consumer requests a Service endpoint through a browser. The Snaplex sends the caller to the Identity Provider (IdP) to sign in. This service could be Google, Azure, or any organization that supports OIDC through an identity provider. If not logged in, the Service consumer logs into the IdP.

If the consumer is calling an endpoint for the first time, the IdP might prompt the caller to share certain information. Once the consumer is authenticated and given any necessary consent, the IdP sends an ID token back to the browser. This ID token securely confirms the caller's identity. Tokens have expiration times and are encoded to prevent tampering.

OpenID Connect requires different values to configure the Generic OAuth2 Rule. The following identifies the parties and steps in the OIDC flow:

  • Authentication Request: The Snaplex receiving a request directs the user to the OIDC IdP, requesting authentication. This is typically done through a browser redirect.
  • Authentication: On the first request, the IdP prompts the user to authenticate by entering a username and password.
  • Authorization: If the user hasn't already granted the client permission to access their data, the IdP asks them for consent.
  • Authentication Response: After successful authentication and authorization, the IdP redirects the user back to the Snaplex. This redirect includes an authorization code, which is passed in the URL.
  • Token Request: Using the authorization code, the Snaplex makes a request directly to the IdP to exchange the code for an ID token and an access token.
  • Token Response: The IdP sends the ID token and access token to the Snaplex.
  • ID Token: The JSON Web Token (JWT) that contains information about who the user is, when they authenticated, and how long the token is valid.
  • Access Token: This is a bearer token that the client can use to access protected resources on behalf of the user. For OIDC, it often allows the client to retrieve more information about the user from the IdP.
  • Discovery Document: A document that contains all the endpoints provided by OpenID Connect Providers. It always has the suffix .well-known/openid-configuration.

Recommendations for OpenID Connect

To use OpenID Connect with the Generic OAuth2 rule, we recommend the following:

  • Consult the official documentation of your OIDC Provider and follow security best practices when implementing authentication and authorization mechanisms.
  • Keep your OIDC implementation updated.
  • Implement a logout mechanism that clears tokens from the client and optionally logs the user out of the OIDC provider.
  • Always use HTTPS.
  • Handle tokens securely by not exposing them unnecessarily and using secure cookie policies and storage mechanisms.
  • Before going live, thoroughly test the OIDC flow from the user’s perspective, and verify that Service validates tokens correctly.
  • Document the authentication process for users or developers that will consume your API. This should include details on how to obtain tokens, how to use them with your API, and any relevant information about token expiration and renewal.

Rule fields

The following describe the Generic OAuth2 rule fields for: