@asgardeo/auth-react 5.2.4 → 5.2.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/README.md +247 -0
- package/package.json +2 -1
package/dist/README.md
ADDED
|
@@ -0,0 +1,247 @@
|
|
|
1
|
+
# Asgardeo Auth React SDK
|
|
2
|
+
|
|
3
|
+
|
|
4
|
+
[](https://stackoverflow.com/questions/tagged/wso2is)
|
|
5
|
+
[](https://discord.gg/wso2)
|
|
6
|
+
[](https://github.com/wso2/product-is/blob/master/LICENSE)
|
|
7
|
+
[](https://twitter.com/intent/follow?screen_name=wso2)
|
|
8
|
+
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
## Table of Content
|
|
12
|
+
|
|
13
|
+
- [Introduction](#introduction)
|
|
14
|
+
- [Prerequisite](#prerequisite)
|
|
15
|
+
- [Getting Started](#getting-started)
|
|
16
|
+
- [Using APIs](#using-apis)
|
|
17
|
+
- [Best practices when using APIs](#best-practices-when-using-apis)
|
|
18
|
+
- [`useAuthContext()` hook](#useauthcontext-hook)
|
|
19
|
+
- [Add a Login/Logout Button](#add-a-loginlogout-button)
|
|
20
|
+
- [Show Authenticated User's Information](#show-authenticated-users-information)
|
|
21
|
+
- [Add Routing](#add-routing)
|
|
22
|
+
- [API Documentation](#api-documentation)
|
|
23
|
+
- [Sample Apps](#sample-apps)
|
|
24
|
+
- [Develop](#develop)
|
|
25
|
+
- [Contribute](#contribute)
|
|
26
|
+
- [License](#license)
|
|
27
|
+
|
|
28
|
+
## Introduction
|
|
29
|
+
|
|
30
|
+
Asgardeo Auth React SDK allows React applications to use [OpenID Connect - OIDC](https://openid.net/specs/openid-connect-core-1_0.html) authentication with [Asgardeo](https://wso2.com/asgardeo) as the Consumer Identity and Access Management(CIAM) Provider. The SDK supports following capabilities
|
|
31
|
+
- [Authenticate users](#add-a-loginlogout-button)
|
|
32
|
+
- [Show Authenticated User's Information](#show-authenticated-users-information)
|
|
33
|
+
- [Retrieve Additional User Information](/API.md#getbasicuserinfo)
|
|
34
|
+
- [Secure Components](/API.md#3-authenticatedcomponent)
|
|
35
|
+
- [Send HTTP Requests to Asgardeo](/API.md#httprequest)
|
|
36
|
+
|
|
37
|
+
## Prerequisite - Register your application in Asgardeo
|
|
38
|
+
|
|
39
|
+
1. Register to [Asgardeo](https://wso2.com/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.
|
|
40
|
+
2. [Register a Single Page Application in Asgardeo](https://wso2.com/asgardeo/docs/guides/applications/register-single-page-app/#register-the-app) 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.
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
## Getting Started
|
|
44
|
+
|
|
45
|
+
Follow this guide to integrate Asgardeo to your own React Application. To try out the sample apps, use [this guide](/SAMPLE_APPS.md).
|
|
46
|
+
|
|
47
|
+
### 1. Installing the Package
|
|
48
|
+
|
|
49
|
+
Run the following command to install `@asgardeo/auth-react` from the npm registry.
|
|
50
|
+
|
|
51
|
+
```bash
|
|
52
|
+
npm install @asgardeo/auth-react --save
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
### 2. Import [`AuthProvider`](/API.md#authprovider) and Provide [Configuration Parameters](/API.md#authreactconfig)
|
|
56
|
+
|
|
57
|
+
Asgardeo React SDK exposes the `AuthProvider` component, which helps you easily integrate Asgardeo to your application.
|
|
58
|
+
|
|
59
|
+
First, import the `AuthProvider` component from `@asgardeo/auth-react.` where you applications root component is defined.
|
|
60
|
+
|
|
61
|
+
> **Note**
|
|
62
|
+
> Typically the root component of a react app is defined in the index.* file.
|
|
63
|
+
|
|
64
|
+
```TypeScript
|
|
65
|
+
import { AuthProvider } from "@asgardeo/auth-react";
|
|
66
|
+
```
|
|
67
|
+
Then, wrap your root component with the `AuthProvider`.
|
|
68
|
+
|
|
69
|
+
```TypeScript
|
|
70
|
+
import React from "react";
|
|
71
|
+
import { AuthProvider } from "@asgardeo/auth-react";
|
|
72
|
+
|
|
73
|
+
const config = {
|
|
74
|
+
signInRedirectURL: "https://localhost:3000/sign-in",
|
|
75
|
+
signOutRedirectURL: "https://localhost:3000/dashboard",
|
|
76
|
+
clientID: "<client_ID>",
|
|
77
|
+
baseUrl: "https://api.asgardeo.io/t/<org_name>",
|
|
78
|
+
scope: [ "openid","profile" ]
|
|
79
|
+
};
|
|
80
|
+
|
|
81
|
+
export const MyApp = (): ReactElement => {
|
|
82
|
+
return (
|
|
83
|
+
<AuthProvider config={ config }>
|
|
84
|
+
<App />
|
|
85
|
+
</AuthProvider>
|
|
86
|
+
)
|
|
87
|
+
}
|
|
88
|
+
```
|
|
89
|
+
> **Note**
|
|
90
|
+
> You can refer to the [details of `AuthProvider` `config` here](/API.md#authreactconfig)
|
|
91
|
+
|
|
92
|
+
Once the root component is wrapped with AuthProvider, [`useAuthContext()` hook](#useauthcontext-hook) can be used anywhere within the application to implement user authentication capabilities in the application.
|
|
93
|
+
|
|
94
|
+
## Using APIs
|
|
95
|
+
|
|
96
|
+
### Best practices when using APIs
|
|
97
|
+
|
|
98
|
+
Asgardeo Auth React SDK is built on top of [Asgardeo Auth SPA SDK](https://github.com/asgardeo/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.
|
|
99
|
+
|
|
100
|
+
- The only SDK that should be listed in the app dependencies is `@asgardeo/auth-react`.
|
|
101
|
+
- Always import APIs from `@asgardeo/auth-react`.
|
|
102
|
+
|
|
103
|
+
>**Warning**
|
|
104
|
+
>IDE or Editor auto import may sometimes import certain APIs from `@asgardeo/auth-spa`, change them back manually.
|
|
105
|
+
|
|
106
|
+
<details><summary><strong>Click here for Tips:</strong> Do's When importing a component from Asgardeo React SDK</summary>
|
|
107
|
+
<p>
|
|
108
|
+
|
|
109
|
+
#### DO ✅
|
|
110
|
+
```TypeScript
|
|
111
|
+
import { AsgardeoSPAClient } from "@asgardeo/auth-react";
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
#### When including React SDK as a dependency:
|
|
115
|
+
|
|
116
|
+
##### DO ✅
|
|
117
|
+
```json
|
|
118
|
+
// In package.json
|
|
119
|
+
|
|
120
|
+
dependencies: {
|
|
121
|
+
"@asgardeo/auth-react": "^2.0.0"
|
|
122
|
+
}
|
|
123
|
+
```
|
|
124
|
+
</p>
|
|
125
|
+
</details>
|
|
126
|
+
|
|
127
|
+
---
|
|
128
|
+
### `useAuthContext()` hook
|
|
129
|
+
|
|
130
|
+
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.
|
|
131
|
+
|
|
132
|
+
Import the `useAuthContext()` hook from `@asgardeo/auth-react`.
|
|
133
|
+
```Typescript
|
|
134
|
+
import { useAuthContext } from "@asgardeo/auth-react";
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
And then inside your components, you can access the context as follows
|
|
138
|
+
```Typescript
|
|
139
|
+
const { state, signIn, signOut } = useAuthContext();
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
Few common methods that you will require when implementing authentication capabilities in your application.
|
|
143
|
+
- [`signIn`](API.md#signin) - Initiate a login request to Asgardeo, process the response to obtain authentication response.
|
|
144
|
+
- [`signOut`](API.md#signout) - Logout the user from Asgardeo and clear any authentication data from the SDK storage.
|
|
145
|
+
- [`isAuthenticated`](API.md#isauthenticated) - Check whether there is an authenticated user session. Based on the result you can decide to change the application view/behaviour.
|
|
146
|
+
- [`getBasicUserInfo`](API.md#getbasicuserinfo) - Get authenticated user's basic information from the authentication response.
|
|
147
|
+
- [`getDecodedIDToken`](API.md#getdecodedidtoken) - Get the decoded `id_token` obtained in the authentication response. From there you can derive more information such as additional user-attributes.
|
|
148
|
+
- [`getIDToken`](API.md#getidtoken) - Get the `id_token` (JWT) obtained in the authentication response.
|
|
149
|
+
- [`getAccessToken`](API.md#getaccesstoken) - Get the `access_token` obtained in the authentication response.
|
|
150
|
+
- [`refreshAccessToken`](API.md#refreshaccesstoken) - Get the `refresh_token` obtained in the authentication response.
|
|
151
|
+
- [`getHttpClient`](API.md#gethttpclient) - Get an HttpClient instance so that the you can make RESTful calls to the backend, where the client will attach the necessary Authorization headers to the request.
|
|
152
|
+
|
|
153
|
+
The [`state`](API.md##authstateinterface) object will contain attributes such as whether a user is currently logged in, the username of the currently logged-in user etc.
|
|
154
|
+
|
|
155
|
+
>**Note**
|
|
156
|
+
>You can refer to the [detailed API documentation here](/API.md)
|
|
157
|
+
|
|
158
|
+
---
|
|
159
|
+
### Add a Login/Logout Button
|
|
160
|
+
|
|
161
|
+
You can use the `signIn()` method from `useAuthContext()` to easily implement a **login button**.
|
|
162
|
+
```Typescript
|
|
163
|
+
<button onClick={ () => signIn() }>Login</button>
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
Similarly to the above step, we can use the `signOut()` method from `useAuthContext()` to implement a **logout button**.
|
|
167
|
+
```Typescript
|
|
168
|
+
<button onClick={() => signOut()}>Logout</button>
|
|
169
|
+
```
|
|
170
|
+
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`.
|
|
171
|
+
|
|
172
|
+
Clicking on **Logout button** will sign out the user and will be redirected to `signOutRedirectURL` and the `state.isAuthenticated` will be set to `false`.
|
|
173
|
+
|
|
174
|
+
> **Note**
|
|
175
|
+
> Instead of buttons you can use the `signIn()` & `signOut()` methods from the SDK to implement any preffered user-experience in your application
|
|
176
|
+
|
|
177
|
+
You can use the `state.isAuthenticated` attribute to check the authenticated status of the user.
|
|
178
|
+
|
|
179
|
+
---
|
|
180
|
+
### Show Authenticated User's Information
|
|
181
|
+
|
|
182
|
+
The following code snippet demonstrates the usage of the `state` object, together with `signIn()` and `signOut()` methods from the context.
|
|
183
|
+
```Typescript
|
|
184
|
+
import React from "react";
|
|
185
|
+
import { useAuthContext } from "@asgardeo/auth-react";
|
|
186
|
+
|
|
187
|
+
function App() {
|
|
188
|
+
|
|
189
|
+
const { state, signIn, signOut } = useAuthContext();
|
|
190
|
+
|
|
191
|
+
return (
|
|
192
|
+
<div className="App">
|
|
193
|
+
{
|
|
194
|
+
state.isAuthenticated
|
|
195
|
+
? (
|
|
196
|
+
<div>
|
|
197
|
+
<ul>
|
|
198
|
+
<li>{state.username}</li>
|
|
199
|
+
</ul>
|
|
200
|
+
|
|
201
|
+
<button onClick={() => signOut()}>Logout</button>
|
|
202
|
+
</div>
|
|
203
|
+
)
|
|
204
|
+
: <button onClick={() => signIn()}>Login</button>
|
|
205
|
+
}
|
|
206
|
+
</div>
|
|
207
|
+
);
|
|
208
|
+
}
|
|
209
|
+
|
|
210
|
+
export default App;
|
|
211
|
+
```
|
|
212
|
+
---
|
|
213
|
+
### Add Routing
|
|
214
|
+
|
|
215
|
+
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.md#securing-routes-with-asgardeo).
|
|
216
|
+
|
|
217
|
+
---
|
|
218
|
+
### API Documentation
|
|
219
|
+
|
|
220
|
+
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](/API.md).
|
|
221
|
+
|
|
222
|
+
## Sample Apps
|
|
223
|
+
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](/SAMPLE_APPS.md).
|
|
224
|
+
|
|
225
|
+
## Develop
|
|
226
|
+
|
|
227
|
+
### Prerequisites
|
|
228
|
+
- `Node.js` (version 10 or above).
|
|
229
|
+
- `yarn` package manager.
|
|
230
|
+
|
|
231
|
+
### Installing Dependencies
|
|
232
|
+
The repository is a mono repository. The SDK repository is found in the [lib](/lib/) directory. You can install the dependencies by running the following command at the root.
|
|
233
|
+
|
|
234
|
+
```bash
|
|
235
|
+
yarn build
|
|
236
|
+
```
|
|
237
|
+
|
|
238
|
+
## Contribute
|
|
239
|
+
Please read [Contributing to the Code Base](http://wso2.github.io/) for details on our code of conduct, and the process for submitting pull requests to us.
|
|
240
|
+
|
|
241
|
+
### Reporting issues
|
|
242
|
+
We encourage you to report issues, improvements, and feature requests creating [Github Issues](https://github.com/asgardeo/asgardeo-auth-react-sdk/issues).
|
|
243
|
+
|
|
244
|
+
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.
|
|
245
|
+
|
|
246
|
+
## License
|
|
247
|
+
This project is licensed under the Apache License 2.0. See the [LICENSE](LICENSE) file for details.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@asgardeo/auth-react",
|
|
3
|
-
"version": "5.2.
|
|
3
|
+
"version": "5.2.5",
|
|
4
4
|
"description": "Asgardeo Auth React SDK for React Applications.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"WSO2",
|
|
@@ -63,6 +63,7 @@
|
|
|
63
63
|
"@typescript-eslint/eslint-plugin": "^5.47.0",
|
|
64
64
|
"@typescript-eslint/parser": "^5.47.0",
|
|
65
65
|
"babel-loader": "^9.1.0",
|
|
66
|
+
"copy-webpack-plugin": "^13.0.0",
|
|
66
67
|
"core-js": "^3.26.1",
|
|
67
68
|
"eslint": "^8.30.0",
|
|
68
69
|
"eslint-plugin-import": "^2.26.0",
|