Contribute Auth For APIs
If you find a bug with one of the existing providers feel free to use these steps to submit a PR with a fix. Thank you!
βStep 0: A quick overview of how provider templates work in Nango
Support for the OAuth flow of different providers in Nango is implemented with templates: A small config that tells Nango how to perform the OAuth flow for the specific provider.
All Integration Templates of Nango live in a single file called providers.yaml.
Most templates only need to make use of 2-3 configuration keys, but in some cases you might need more.
The most commonly used configuration options are:
provider-slug: # Shorthand for the provider, ideally the provider's name. Must be unique. Kebab case.
##########
# Mandatory fields
##########
auth_mode: OAUTH2 # Either OAUTH1 (for OAuth 1.0a) or OAUTH2
authorization_url: https://${connectionConfig.params.subdomain}.gitlab.com/oauth/authorize # The URL of the authorization page for the OAuth service (supports string interpolation)
token_url: https://${connectionConfig.params.subdomain}.gitlab.com/oauth/token # The URL for the token request (supports string interpolation)
##########
# Optional fields
##########
authorization_params: # Additional parameters to pass along in the authorization step
response_type: code
token_params: # Additional parameters to pass along in the token request
mycoolparam: value
refresh_url: https://api.example.com/oauth/refresh # The URL to use for refreshing the access token (only if different from token_url)
scope_separator: ',' # String to use to separate scopes. Defaults to ' ' (1 space) if not provided
# Metadata capture
redirect_uri_metadata:
- subdomain # Save the 'subdomain' query parameter value returned in the Redirect URI (Connection Metadata)
token_response_metadata:
- scopes # Save the 'scopes' query parameter value returned in the token response (Connection Metadata)
You can configure some Connection Metadata, which is additional metadata that you want to capture during the OAuth flow and store in the Connection.
βStep 1: Add your new provider to providers.yaml
Fork the repo and edit the providers.yaml file as explained above to add support for the new provider. The API documentation should contain all the details you need on the OAuth flow to complete this step.
We are here if you need help with this.
βStep 2: Test your new provider
Some OAuth providers are very restrictive with callback URIs and require https
or donβt allow localhost
as a domain/URL. This can make it very hard to test
things locally.
The easiest workaround we found is to use this simple service: https://redirectmeto.com.
With this the Nango localhost callback URL becomes
https://redirectmeto.com/http://localhost:3003/oauth/callback
and you will
need to update the NANGO_CALLBACK_URL
in the .env
file:
NANGO_CALLBACK_URL=https://redirectmeto.com/http://localhost:3003/oauth/callback
To test your new provider:
Start the docker containers:
docker compose up
The docker compose configuration in the root of the repo docker-compose.yaml
will run 2 containers.
- Postgres DB
- Nango Server
To propagate your changes after editing the providers.yaml
file, run:
docker compose restart nango-server # Force a restart, which will load in the yaml again
docker compose run nango-server cat packages/shared/providers.yaml # print the contents of the providers file from inside the container
When you are ready to test your new provider template:
β1. Add your client credentials to the local Nango Server
Open the local dashboard in your browser and add a new Integration with your freshly added provider (it should show up in the provider dropdown).
β2. Trigger the OAuth Flow
Run an OAuth flow on the local dashboard.
You can modify the ports in the docker compose if there are any conflicts with other local services on your host machine.
β3. Check the access token in the dashboard
If all goes well you should see your new Connection in the Connections list in the dashboard.
Check the Connection details and make sure all looks as expected (access token, refresh token, metadata).
βStep 3: Add your integration to the Documentation
Add a file named <provider_slug>.mdx
(e.g. github.md
) corresponding to your
new integration to the docs/integrations/all
folder. You can check out check out
asana for an example.
Also, add your new documentation page to docs/mint.json
in the Integrations
group (in alphabetical order).
βStep 4: Submit your PR
Submit your PR with the new provider to the Nango repo. Please thoroughly test the integration.
Thanks a lot for your contribution!! β€οΈ
βNeed help?
Ask any question on the Slack community.