search

asgardeo / asgardeo-auth-react-sdk

To maintain the implementation of Asgardeo React authentication SDK
Apache License 2.0
35 stars 84 forks source link
hacktoberfest

readme

Asgardeo Auth React SDK

Builder Stackoverflow Join the chat at https://discord.gg/wso2 License Twitter

Table of Content

Introduction

Asgardeo Auth React SDK allows React applications to use OpenID Connect - OIDC authentication with Asgardeo as the Consumer Identity and Access Management(CIAM) Provider. The SDK supports following capabilities

Prerequisite - Register your application in Asgardeo

  1. Register to Asgardeo and create an organization if you don't already have one. The organization name you choose will be referred to as <org_name> throughout this document.
  2. Register a Single Page Application in Asgardeo to obtain necessary keys to integrate your application with Asgardeo. You will obtain a client_ID from Asgardeo for your application which will need to embed later in your application for the integration.

Getting Started

Follow this guide to integrate Asgardeo to your own React Application. To try out the sample apps, use this guide.

1. Installing the Package

Run the following command to install @asgardeo/auth-react from the npm registry.

npm install @asgardeo/auth-react --save

2. Import AuthProvider and Provide Configuration Parameters

Asgardeo React SDK exposes the AuthProvider component, which helps you easily integrate Asgardeo to your application.

First, import the AuthProvider component from @asgardeo/auth-react. where you applications root component is defined.

Note Typically the root component of a react app is defined in the index.* file.

import { AuthProvider } from "@asgardeo/auth-react";

Then, wrap your root component with the AuthProvider.

import React from "react";
import { AuthProvider } from "@asgardeo/auth-react";

const config = {
     signInRedirectURL: "https://localhost:3000/sign-in",
     signOutRedirectURL: "https://localhost:3000/dashboard",
     clientID: "<client_ID>",
     baseUrl: "https://api.asgardeo.io/t/<org_name>",
     scope: [ "openid","profile" ]
};

export const MyApp = (): ReactElement => {
    return (
        <AuthProvider config={ config }>
            <App />
        </AuthProvider>
    )
}

Note You can refer to the details of AuthProvider config here

Once the root component is wrapped with AuthProvider, useAuthContext() hook can be used anywhere within the application to implement user authentication capabilities in the application.

Using APIs

Best practices when using APIs

Asgardeo Auth React SDK is built on top of Asgardeo Auth SPA SDK, a base library. Hence, almost all the usable APIs from Auth SPA SDK are re-exported from Asgardeo Auth React SDK and you don't need to import dependencies from the base library to your application.

Warning IDE or Editor auto import may sometimes import certain APIs from @asgardeo/auth-spa, change them back manually.

Click here for Tips: Do's When importing a component from Asgardeo React SDK

#### DO ✅ ```TypeScript import { AsgardeoSPAClient } from "@asgardeo/auth-react"; ``` #### When including React SDK as a dependency: ##### DO ✅ ```json // In package.json dependencies: { "@asgardeo/auth-react": "^2.0.0" } ```

useAuthContext() hook

The useAuthContext() hook provided by the SDK could be used to implement the necessary authentication functionalities and access the session state that contains information such as a unique identifier for the authenticated user.

Import the useAuthContext() hook from @asgardeo/auth-react.

import { useAuthContext } from "@asgardeo/auth-react";

And then inside your components, you can access the context as follows

const { state, signIn, signOut } = useAuthContext();

Few common methods that you will require when implementing authentication capabilities in your application.

The state object will contain attributes such as whether a user is currently logged in, the username of the currently logged-in user etc.

Note You can refer to the detailed API documentation here

Add a Login/Logout Button

You can use the signIn() method from useAuthContext() to easily implement a login button.

<button onClick={ () => signIn() }>Login</button>

Similarly to the above step, we can use the signOut() method from useAuthContext() to implement a logout button.

<button onClick={() => signOut()}>Logout</button>

Clicking on Login button will take the user to Asgardeo login page. Upon successful signIn(), the user will be redirected to the app (based on the specified signInRedirectURL) and the state.isAuthenticated will be set to true.

Clicking on Logout button will sign out the user and will be redirected to signOutRedirectURL and the state.isAuthenticated will be set to false.

Note Instead of buttons you can use the signIn() & signOut() methods from the SDK to implement any preffered user-experience in your application

You can use the state.isAuthenticated attribute to check the authenticated status of the user.

Show Authenticated User's Information

The following code snippet demonstrates the usage of the state object, together with signIn() and signOut() methods from the context.

import React from "react";
import { useAuthContext } from "@asgardeo/auth-react";

function App() {

  const { state, signIn, signOut } = useAuthContext();

  return (
    <div className="App">
      {
        state.isAuthenticated
          ? (
            <div>
              <ul>
                <li>{state.username}</li>
              </ul>

              <button onClick={() => signOut()}>Logout</button>
            </div>
          )
          : <button onClick={() => signIn()}>Login</button>
      }
    </div>
  );
}

export default App;

Add Routing

If your application needs routing, the SDK provides a multiple approaches to secure routes in your application. You can read more about routing capabilities in Asgardeo here.

API Documentation

Additionally to above, Asgardeo offers a wide range of APIs that you can use to integrate and make use of Asgardeo within your React Application. You can refer to a detailed API documentation here.

Sample Apps

Sample React Apps offered by Asgardeo will allow you to take Asgardeo for a spin without having to setup your own application. You can see how to setup sample apps here.

Develop

Prerequisites

Installing Dependencies

The repository is a mono repository. The SDK repository is found in the lib directory. You can install the dependencies by running the following command at the root.

yarn build

Contribute

Please read Contributing to the Code Base for details on our code of conduct, and the process for submitting pull requests to us.

Reporting issues

We encourage you to report issues, improvements, and feature requests creating Github Issues.

Important: And please be advised that security issues must be reported to security@wso2com, not as GitHub issues, in order to reach the proper audience. We strongly advise following the WSO2 Security Vulnerability Reporting Guidelines when reporting the security issues.

License

This project is licensed under the Apache License 2.0. See the LICENSE file for details.