# OAuth2 SaaS integrations support two OAuth2 flows: - [Authorization Code (opens in a new tab)](https://oauth.net/2/grant-types/authorization-code/): `oauth2_authorization_code` - [Client Credentials (opens in a new tab)](https://oauth.net/2/grant-types/client-credentials/): `oauth2_client_credentials` This Authentication Code flow has the following configuration values: - `authorization_request`: The request to build the URL that is presented to the user to authenticate this connection. - `token_request`: The request made to retrieve the access token after the authorization code is returned via the `/oauth/callback` endpoint. - `refresh_request` ( _optional_): The request to refresh an access token. - `expires_in` ( _optional_): The lifetime of an access token (in seconds). This is used if the OAuth2 workflow in use does not provide expiration information ( [RFC 6749 Section 5.1 (opens in a new tab)](https://datatracker.ietf.org/doc/html/rfc6749#section-5.1)). The Client Credential flow has all these values except for `authorization_request` since it is not required for this flow. ## Sample configuration [Permalink for this section](/content/docs/integrations/saas-integrations/developer-reference/saas-oauth2#sample-configuration/index.html) Each OAuth2 request is fully configurable to account for the different ways the parameters can be mapped to a request. The following examples demonstrate the requests generated from sample configuration files. ### OAuth2 Authorization Code example ``` authentication: strategy: oauth2_authorization_code configuration: authorization_request: ... token_request: ... refresh_request: ... ``` ### Authorization request [Permalink for this section](/content/docs/integrations/saas-integrations/developer-reference/saas-oauth2#authorization-request/index.html) ``` authorization_request: method: GET path: /auth/authorize query_params: - name: client_id value: - name: redirect_uri value: - name: response_type value: code - name: scope value: - name: state value: ``` The above `authentication_request` will generate the following: ``` https:///auth/authorize?client_id=&redirect_uri=&response_type=code&scope=&state= ``` The placeholders are sourced from the values defined in the [`connector_params`](/content/docs/integrations/saas-integrations/developer-reference/saas-config#integration-params/index.html) of your SaaS config. The `` placeholder is generated automatically with each authorization request. This authorization URL can be retrieved by calling: ``` https://{{domain}}/api/v1/connection/{{connection_key}}/authorize ``` ### Token request [Permalink for this section](/content/docs/integrations/saas-integrations/developer-reference/saas-oauth2#token-request/index.html) ``` token_request: method: POST path: /oauth/token query_params: - name: client_id value: - name: client_secret value: - name: grant_type value: authorization_code - name: code value: ``` The `` placeholder is defined automatically by Fides. The above `token_request` configuration generates the following: ``` https:///oauth_token?client_id=&client_secret=&grant_type=authorization_code&code= ``` This request is called automatically after Fides receives a callback response to the `https://{{domain}}/api/v1/oauth/callback` endpoint. #### Refresh request [Permalink for this section](/content/docs/integrations/saas-integrations/developer-reference/saas-oauth2#refresh-request/index.html) ``` refresh_request: method: POST path: /oauth/token query_params: - name: client_id value: - name: client_secret value: - name: grant_type value: refresh_token - name: refresh_token value: ``` The `` placeholder is defined automatically by Fides. The above `refresh_request` configuration generates the following: ``` GET https:///oauth_token?client_id=&client_secret=&grant_type=refresh_token&refresh_token= ``` This is called automatically when the `access_token` is about to expire. The expiration is usually defined in the response to the token request. If the expiration is not returned by the API, it can be specified manually by setting the `expires_in` field (which is defined in seconds): ``` authentication: strategy: oauth2_authorization_code configuration: expires_in: 3600 authorization_request: ... token_request: ... refresh_request: ... ``` ## Usage checklist [Permalink for this section](/content/docs/integrations/saas-integrations/developer-reference/saas-oauth2#usage-checklist/index.html) To use OAuth2 as a connection strategy, the following must be configured first: ### For all OAuth2 flows [Permalink for this section](/content/docs/integrations/saas-integrations/developer-reference/saas-oauth2#for-all-oauth2-flows/index.html) #### Per-connector configuration [Permalink for this section](/content/docs/integrations/saas-integrations/developer-reference/saas-oauth2#per-connector-configuration/index.html) - Fides must be able to connect to the SaaS provider (Outreach, Salesforce, etc.). - A **Client ID** and **Client Secret** must be generated within the SaaS provider’s admin console. - This is dependent on the individual SaaS provider. Refer to the provider's documentation. - The connector using OAuth2 is configured using the steps for [how to configure a SaaS connector](/content/docs/integrations/saas-integrations/developer-reference/saas-config/index.html). ### Additional steps for authentication code flow [Permalink for this section](/content/docs/integrations/saas-integrations/developer-reference/saas-oauth2#additional-steps-for-authentication-code-flow/index.html) #### One-time configuration [Permalink for this section](/content/docs/integrations/saas-integrations/developer-reference/saas-oauth2#one-time-configuration/index.html) - A callback server or network rules are required to forward the callback response from the SaaS providers to an instance of Fides. This is dependent on the user environment where Fides is deployed, and is out of scope for this documentation. - These incoming requests must be routed to `https://{{host}}/api/v1/oauth/callback`. #### Per-connector configuration [Permalink for this section](/content/docs/integrations/saas-integrations/developer-reference/saas-oauth2#per-connector-configuration-1/index.html) - The **Redirect URI** must be registered within the SaaS provider's admin console. - The OAuth2 workflow is initialized by following the URL returned from `https://{{domain}}/api/v1/connection/{{connection_key}}/authorize`. ## OAuth2 authentication code flow diagram [Permalink for this section](/content/docs/integrations/saas-integrations/developer-reference/saas-oauth2#oauth2-authentication-code-flow-diagram/index.html)