# Auth

[View on Github](https://github.com/CartoDB/carto-react-template)

{% hint style="warning" %}
**Note:** We are reducing our investment in CARTO for React and currently we discourage users from starting new projects with it.

CARTO for React is an opinionated framework with pre-built components and templates. This greatly speeds up the process to create React-based applications, but customization options are limited.

If you need further customization in React, or you want to build geospatial applications using **Vue, Angular, or any other Javascript-based framework**, we recommend going directly to the main CARTO for Developers documentation, including [CARTO + deck.gl](https://github.com/CartoDB/gitbook-documentation/blob/master/carto-for-developers/key-concepts/carto-for-deck.gl), which allows for maximum flexibility and scalability.
{% endhint %}

| Package           | Version                                                                                                                         | Downloads                                                                                                                          |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| @carto/react-auth | [![version](https://img.shields.io/npm/v/@carto/react-auth.svg?style=flat-square)](https://npmjs.org/package/@carto/react-auth) | [![downloads](https://img.shields.io/npm/dt/@carto/react-auth.svg?style=flat-square)](https://npmjs.org/package/@carto/react-auth) |

This package contains some OAuth utilities for implementing authentication and authorization against the CARTO 2 platform. If you are building an application with CARTO 3, you should use [Auth0 React SDK](https://auth0.com/docs/quickstart/spa/react) instead of this package.

## Components <a href="#components" id="components"></a>

### **OAuthCallback**

React component to attend OAuth callbacks on `/oauthCallback`. Ensure you include that specific route in your application.

* **Example**:

```jsx
import { OAuthCallback } from "@carto/react-auth";

// inside the proper routing config...
const routes = [
  /* ...some other routes and */
  { path: "/oauthCallback", element: <OAuthCallback /> },
];
```

## Functions <a href="#functions" id="functions"></a>

### **useOAuthLogin**

Hook to perform login against CARTO, with OAuth implicit flow and using a popup.

* **Input**:

| Param                      | Type             | Description                                |
| -------------------------- | ---------------- | ------------------------------------------ |
| oauthApp                   | `Object`         | OAuth parameters                           |
| oauthApp.clientId          | `string`         | Application client ID                      |
| oauthApp.scopes            | `Array.<string>` | Scopes to request                          |
| oauthApp.authorizeEndPoint | `string`         | Authorization endpoint                     |
| onParamsRefreshed          | `function`       | Function to call when params are refreshed |

* **Returns**: `function` - A function to trigger oauth with a popup
* **Example**:

```jsx
import { useOAuthLogin } from "@carto/react-auth";

const oauthApp = {
  clientId: "YOUR_OAUTH_CLIENT_ID",
  scopes: ["user:profile"],
  authorizeEndPoint: "https://carto.com/oauth2/authorize",
};

const onParamsRefreshed = (oauthParams) => {
  if (oauthParams.error) {
    console.error(`OAuth error: ${oauthParams.error}`);
  } else {
    console.log(oauthParams);
  }
};

const [handleLogin] = useOAuthLogin(oauthApp, onParamsRefreshed);
// handleLogin function should be later handled from UI to trigger the flow
```

**Tip:** Check CARTO for React templates for CARTO 2 for examples using this hook, where oauthApp data is managed within Redux store. For example, this is the [Login page](https://github.com/CartoDB/carto-react-template/blob/master/template-base-2/template/src/components/views/Login.js).