> ## Documentation Index
> Fetch the complete documentation index at: https://ngrok.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# OAuth Action
> The OAuth action restricts access to only authorized users by enforcing OAuth through an identity provider of your choice.
export const YouTubeEmbed = ({className, title, videoId, ...props}) => {
return
;
};
This page relates to requiring OAuth for visitors to access your endpoints.
To configure OAuth and SSO providers for signing into the ngrok dashboard, see [the dashboard SSO documentation](/iam/sso).
The OAuth Traffic Policy action restricts access to your endpoints to only authorized users by enforcing OAuth through an identity provider of your choice.
## Configuration reference
The [Traffic Policy](/traffic-policy/) configuration reference for this action.
### Supported phases
`on_http_request`
### Type
`oauth`
### Configuration fields
The name of the *OAuth* identity provider to be used for authentication.
Unique authentication identifier for this provider.
Used to scope the session cookie and to target this provider in login and logout paths.
See [Special paths](#special-paths).
Your OAuth app's client ID.
Leave this empty if you want to use ngrok's managed application.
Your OAuth app's client secret.
Leave this empty if you want to use a managed application.
A list of additional scopes to request when users authenticate with the identity provider.
A map of additional URL parameters to apply to the authorization endpoint URL.
Defines the maximum lifetime of a session regardless of activity.
Defines the period of inactivity after which a user's session is automatically ended, requiring re-authentication.
How often should ngrok refresh data about the authenticated user from the identity provider.
Allow CORS preflight requests to bypass authentication checks.
Enable this if the endpoint needs to be accessible via CORS.
Sets the allowed domain for the auth cookie.
### Special paths
#### Logging users in
To start an OAuth authentication flow explicitly—for example, from a "Log in" button or link—redirect users to `/ngrok/login`.
After a successful authentication, ngrok redirects the user to `/`.
To send the user to a specific path after login, include the `redirect_path` parameter:
```
/ngrok/login?redirect_path=/dashboard
```
If you've configured `auth_id` to identify this provider, include it in the URL:
```
/ngrok/login?auth_id=my-provider&redirect_path=/dashboard
```
If the IdP supports it, ngrok instructs it to force re-authentication—users must re-enter their credentials even if they already have an active IdP session.
#### Logging users out
To end a user's session—for example, from a "Log out" button or link—redirect users to `/ngrok/logout`.
This clears the ngrok session cookie.
If you've configured `auth_id`, include it in the URL to target the correct provider:
```
/ngrok/logout?auth_id=my-provider
```
When using the Google OAuth 2.0/OIDC provider in Chrome with a [managed profile](https://support.google.com/chrome/a/answer/188446), `/ngrok/logout` only clears the ngrok session cookie; it does not end the Google/IdP session maintained by the browser.
Users may be silently re-authenticated on the next request.
To fully sign out, sign out of Chrome or Google (or use a non-managed profile or Incognito) in addition to calling `/ngrok/logout`.
### Events
When this action is enabled, it populates the following fields in the [`http_request_complete.v0`](/obs/events/reference/#http-request-complete) event:
* `oauth.app_client_id`
* `oauth.decision`
* `oauth.user.id`
* `oauth.user.name`
### Supported providers
ngrok currently supports the following OAuth providers (see the Integration Guides for more details).
In some instances, ngrok has a [managed application](#managed-applications) that allows you to configure OAuth without setting up your own application in your provider.
This is useful for testing and development, but when you move into production, use your own custom application in your specific provider.
| Provider | Provider Identifier | Managed App Available | Integration Guide |
| --------- | ------------------- | --------------------- | ---------------------------------------------------- |
| Amazon | `amazon` | no | [Documentation](/integrations/oauth/oauth/) |
| Facebook | `facebook` | no | [Documentation](/integrations/oauth/facebook-oauth) |
| GitHub | `github` | yes | [Documentation](/integrations/oauth/github-oauth) |
| GitLab | `gitlab` | yes | [Documentation](/integrations/oauth/gitlab-oauth) |
| Google | `google` | yes | [Documentation](/integrations/oauth/google-oauth) |
| LinkedIn | `linkedin` | yes | [Documentation](/integrations/oauth/linkedin-oauth) |
| Microsoft | `microsoft` | yes | [Documentation](/integrations/oauth/microsoft-oauth) |
| Twitch | `twitch` | yes | [Documentation](/integrations/oauth/twitch-oauth) |
### Required scopes
This is a list of the minimum required scopes for each provider.
You can use this when configuring your identity provider.
These are not required when using the ngrok managed applications.
| Provider | Scopes |
| --------- | ---------------------------------------------------------------------------------------------------- |
| Amazon | `profile` |
| Facebook | `email` |
| Github | `read:org`, `read:user` |
| Gitlab | `email`, `openid`, `profile` |
| Google | `https://www.googleapis.com/auth/userinfo.email`, `https://www.googleapis.com/auth/userinfo.profile` |
| LinkedIn | `r_emailaddress`, `r_liteprofile` |
| Microsoft | `User.Read` |
| Twitch | `user:read:email` |
## Try it out
See the list of [supported providers](#supported-providers) for step-by-step integration guides.
## Behavior
### Callback URL
When you create your own OAuth app, you must specify a callback (or redirect) URL to the OAuth provider.
When using ngrok's OAuth action, the callback URL is always:
```
https://idp.ngrok.com/oauth2/callback
```
### Authentication
When an unauthenticated request is made to an OAuth-protected endpoint, it returns a redirect response that begins an authentication flow with the configured identity provider.
The original URI path is saved so that users can be redirected to it if they successfully authenticate.
**If the user fails to authenticate with the identity provider**, ngrok will display an error describing the failure returned by the identity provider and prompt them to try logging in again.
**If the user successfully authenticates with the identity provider**, ngrok will take the following actions:
* Sets a [session cookie](#cookies) to avoid repeating the authentication flow again.
* Redirects the user to the original URI path they were attempting to access before the authentication flow began.
If no such URI path was captured, they are redirected to `/`.
* Continue processing the rest of the Traffic Policy actions.
### Continuous authorization
When an authenticated user makes a request, ngrok will sometimes refresh a user's data from the identity provider (email, name, etc.) and re-evaluate authorization constraints.
This refresh is executed as a back channel request to the identity provider; it is transparent to the user and they do not go through a re-authentication flow.
The following circumstances trigger refresh and authorization re-evaluation:
* On a periodic interval defined by the [`userinfo_refresh_interval`](/traffic-policy/actions/oauth/#configuration-fields) parameter.
* If you update the OAuth configuration of the endpoint either in the agent or through the dashboard.
* If you update the OAuth configuration of the endpoint.
If a previously authenticated user becomes unauthorized because their identity provider information changed or because the OAuth action configuration changed, they are presented an error and are prompted to try logging in again.
### Managed applications
Managed applications allow you to use ngrok's OAuth action without setting up your own OAuth apps with the identity providers.
More practically, this means you can use the OAuth action without configuring a client id and client secret.
Managed applications are great for getting started but they have some limitations.
* They are [only available for some identity providers](#supported-providers).
* You may not pass custom scopes when using a managed application.
* The [upstream headers](/gateway/http/#upstream-headers) `ngrok-auth-oauth-access-token` and `ngrok-auth-oauth-refresh-token` are not sent to your application.
### Traffic identities
ngrok's [Traffic Identities](/traffic-policy/identities/) feature can be used to observe
all of the authenticated user activity across your account in the ngrok
dashboard or via API. Whenever a user authenticates or accesses an endpoint
with a configured OIDC action, their Traffic Identity record is created or updated.
You may also use Traffic Identities to remotely log a user out by [revoking a
session](/traffic-policy/identities/#revoke-sessions).
### Cookies
This action sets two cookies in its operation.
Cookie values are opaque to the upstream service and must not be modified.
| Cookie | Description |
| --------- | --------------------------------------- |
| `session` | Used to track an authenticated user. |
| `nonce` | Used to secure the authentication flow. |
### Non-terminating action
This is a **Non-terminating action**. It does not return a response, and will allow Traffic Policy processing to continue to the next Action in the chain. All **Cloud Endpoint** Traffic Policies must end with a terminating action. This requirement does not apply to **Agent Endpoints**.
## Examples
### Using a managed provider
The following [Traffic Policy](/traffic-policy/) configuration will provide your app with a Google authentication step.
```yaml policy.yml theme={null}
on_http_request:
- actions:
- type: oauth
config:
provider: google
```
```json policy.json theme={null}
{
"on_http_request": [
{
"actions": [
{
"type": "oauth",
"config": {
"provider": "google"
}
}
]
}
]
}
```
You can replace the `provider` value with any of the [supported providers](/traffic-policy/actions/oauth/#supported-providers) that have a managed app available.
### Restricting access to certain users
See [this authentication example](/traffic-policy/examples/add-authentication/#conditional-access-using-oauth-variables) to learn how to restrict access based on OAuth result variables.
### Using a Custom Provider
If you need more control than what a managed provider can offord you then you
can bring your own provider.
#### Google Example
```yaml policy.yml theme={null}
on_http_request:
- actions:
- type: oauth
config:
provider: google
client_id: '{your oauth client id}'
client_secret: '{your oauth client secret}'
scopes:
- https://www.googleapis.com/auth/userinfo.profile
- https://www.googleapis.com/auth/userinfo.email
```
```json policy.json theme={null}
{
"on_http_request": [
{
"actions": [
{
"type": "oauth",
"config": {
"provider": "google",
"client_id": "{your oauth client id}",
"client_secret": "{your oauth client secret}",
"scopes": [
"https://www.googleapis.com/auth/userinfo.profile",
"https://www.googleapis.com/auth/userinfo.email"
]
}
}
]
}
]
}
```
#### GitHub Example
```yaml policy.yml theme={null}
on_http_request:
- actions:
- type: oauth
config:
provider: github
client_id: '{your app''s oauth client id}'
client_secret: '{your app''s oauth client secret}'
scopes:
- read:user
- read:org
```
```json policy.json theme={null}
{
"on_http_request": [
{
"actions": [
{
"type": "oauth",
"config": {
"provider": "github",
"client_id": "{your app's oauth client id}",
"client_secret": "{your app's oauth client secret}",
"scopes": [
"read:user",
"read:org"
]
}
}
]
}
]
}
```
#### GitLab Example
```yaml policy.yml theme={null}
on_http_request:
- actions:
- type: oauth
config:
provider: gitlab
client_id: '{your app''s oauth client id}'
client_secret: '{your app''s oauth client secret}'
scopes:
- openid
- profile
- email
```
```json policy.json theme={null}
{
"on_http_request": [
{
"actions": [
{
"type": "oauth",
"config": {
"provider": "gitlab",
"client_id": "{your app's oauth client id}",
"client_secret": "{your app's oauth client secret}",
"scopes": [
"openid",
"profile",
"email"
]
}
}
]
}
]
}
```
#### LinkedIn Example
```yaml policy.yml theme={null}
on_http_request:
- actions:
- type: oauth
config:
provider: linkedin
client_id: '{your app''s oauth client id}'
client_secret: '{your app''s oauth client secret}'
scopes:
- r_emailaddress
- r_liteprofile
```
```json policy.json theme={null}
{
"on_http_request": [
{
"actions": [
{
"type": "oauth",
"config": {
"provider": "linkedin",
"client_id": "{your app's oauth client id}",
"client_secret": "{your app's oauth client secret}",
"scopes": [
"r_emailaddress",
"r_liteprofile"
]
}
}
]
}
]
}
```
#### Microsoft Example
```yaml policy.yml theme={null}
on_http_request:
- actions:
- type: oauth
config:
provider: microsoft
client_id: '{your app''s oauth client id}'
client_secret: '{your app''s oauth client secret}'
scopes:
- openid
- email
- profile
```
```json policy.json theme={null}
{
"on_http_request": [
{
"actions": [
{
"type": "oauth",
"config": {
"provider": "microsoft",
"client_id": "{your app's oauth client id}",
"client_secret": "{your app's oauth client secret}",
"scopes": [
"openid",
"email",
"profile"
]
}
}
]
}
]
}
```
#### Twitch Example
```yaml policy.yml theme={null}
on_http_request:
- actions:
- type: oauth
config:
provider: twitch
client_id: '{your app''s oauth client id}'
client_secret: '{your app''s oauth client secret}'
scopes:
- user:read:email
- openid
```
```json policy.json theme={null}
{
"on_http_request": [
{
"actions": [
{
"type": "oauth",
"config": {
"provider": "twitch",
"client_id": "{your app's oauth client id}",
"client_secret": "{your app's oauth client secret}",
"scopes": [
"user:read:email",
"openid"
]
}
}
]
}
]
}
```
#### Amazon Example
```yaml policy.yml theme={null}
on_http_request:
- actions:
- type: oauth
config:
provider: amazon
client_id: '{your app''s oauth client id}'
client_secret: '{your app''s oauth client secret}'
scopes:
- profile
```
```json policy.json theme={null}
{
"on_http_request": [
{
"actions": [
{
"type": "oauth",
"config": {
"provider": "amazon",
"client_id": "{your app's oauth client id}",
"client_secret": "{your app's oauth client secret}",
"scopes": [
"profile"
]
}
}
]
}
]
}
```
#### Facebook Example
```yaml policy.yml theme={null}
on_http_request:
- actions:
- type: oauth
config:
provider: facebook
client_id: '{your app''s oauth client id}'
client_secret: '{your app''s oauth client secret}'
scopes:
- email
```
```json policy.json theme={null}
{
"on_http_request": [
{
"actions": [
{
"type": "oauth",
"config": {
"provider": "facebook",
"client_id": "{your app's oauth client id}",
"client_secret": "{your app's oauth client secret}",
"scopes": [
"email"
]
}
}
]
}
]
}
```
## Action result variables
The following variables are made available for use in subsequent expressions and
CEL interpolations after the action has run. Variable values will only apply
to the last action execution, results are not concatenated.
Code for an error that occurred during the invocation of an action.
Message for an error that occurred during the invocation of an action.
Unique identifier for the ngrok Identity entity.
Email address of the authorized user from the provider.
Name for the authorized user from the provider.
Identifier for the authorized user from the provider.
The current Identity session identifier for this request.
The access token from the provider.
The refresh token from the provider.
Timestamp when the current session will expire.
Returns true when the session timed out.
Returns true when the current session reached the max duration.
Returns true when ngrok updates the user information on the identity.