@asgardeo/auth-react 0.2.9 → 0.2.13
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/README.md +92 -58
- package/dist/main.js +44 -44
- package/dist/src/api.d.ts.map +1 -1
- package/dist/src/models.d.ts +23 -0
- package/dist/src/models.d.ts.map +1 -1
- package/dist/src/reducer.d.ts.map +1 -1
- package/dist/tsconfig.tsbuildinfo +18 -18
- package/package.json +2 -2
- package/src/api.ts +5 -2
- package/src/models.ts +23 -0
- package/src/reducer.ts +4 -2
package/README.md
CHANGED
|
@@ -11,10 +11,9 @@
|
|
|
11
11
|
## Table of Content
|
|
12
12
|
|
|
13
13
|
- [Introduction](#introduction)
|
|
14
|
-
- [
|
|
14
|
+
- [Prerequisite](#prerequisite)
|
|
15
15
|
- [Getting Started](#getting-started)
|
|
16
16
|
- [Try Out the Sample Apps](#try-out-the-sample-apps)
|
|
17
|
-
- [Browser Compatibility](#browser-compatibility)
|
|
18
17
|
- [APIs](#apis)
|
|
19
18
|
- [AuthProvider](#authprovider)
|
|
20
19
|
- [SecureRoute](#secureroute)
|
|
@@ -50,7 +49,7 @@
|
|
|
50
49
|
- [CustomGrantConfig](#customgrantconfig)
|
|
51
50
|
- [Custom Grant Template Tags](#custom-grant-template-tags)
|
|
52
51
|
- [DecodedIDTokenPayload](#decodedidtokenpayload)
|
|
53
|
-
- [HttpRequestConfig](#
|
|
52
|
+
- [HttpRequestConfig](#httprequestconfig)
|
|
54
53
|
- [Develop](#develop)
|
|
55
54
|
- [Prerequisites](#prerequisites)
|
|
56
55
|
- [Installing Dependencies](#installing-dependencies)
|
|
@@ -61,7 +60,71 @@
|
|
|
61
60
|
|
|
62
61
|
Asgardeo Auth React SDK for JavaScript allows React applications to use OIDC or OAuth2 authentication in a simple and secure way. By using Asgardeo and the Asgardeo Auth React SDK, developers will be able to add identity management to their React applications fast and secure.
|
|
63
62
|
|
|
64
|
-
|
|
63
|
+
To enable authentication for this sample, we are using Asgardeo as the Identity Provider.
|
|
64
|
+
|
|
65
|
+
## Prerequisite
|
|
66
|
+
|
|
67
|
+
Create an organization in Asgardeo if you don't already have one. The organization name you choose will be referred to as `<org_name>` throughout this document.
|
|
68
|
+
|
|
69
|
+
## Try Out the Sample Apps
|
|
70
|
+
|
|
71
|
+
### 1. Create an Application in Asgardeo
|
|
72
|
+
|
|
73
|
+
Before trying out the sample apps, you need to create an application in **Asgardeo**.
|
|
74
|
+
|
|
75
|
+
1. Navigate to [**Asgardeo Console**](https://console.asgardeo.io/login) and click on **Applications** under **Develop** tab
|
|
76
|
+
|
|
77
|
+
2. Click on **New Application** and then **Single Page Application**.
|
|
78
|
+
|
|
79
|
+
3. Enter **Sample** as the name of the app and add the redirect URL(s). You can find the relevant redirect URL(s) of each sample app in the [Running the sample apps](#2-running-the-sample-apps) section.
|
|
80
|
+
|
|
81
|
+
4. Click on Register. You will be navigated to management page of the **sample** application.
|
|
82
|
+
|
|
83
|
+
5. Add `https://localhost:5000` (or whichever the URL your app is hosted on) to **Allowed Origins** under **Access** tab and check **Public client** option.
|
|
84
|
+
|
|
85
|
+
6. Click on **Update** at the bottom.
|
|
86
|
+
|
|
87
|
+
7. Copy the configuration from the Asgardeo React Quickstart guide to your React application as shown in the above code snippet.
|
|
88
|
+
|
|
89
|
+
### 2. Running the sample apps
|
|
90
|
+
|
|
91
|
+
1. Download the sample from the given link in the Asgardeo Console.
|
|
92
|
+
|
|
93
|
+
2. Update configuration file `src/config.json` with your registered app details.
|
|
94
|
+
|
|
95
|
+
**Note:** You will only have to paste in the `clientID`(**OAuth Client Key**) generated for the application you registered.
|
|
96
|
+
|
|
97
|
+
Read more about the SDK configurations [here](#configuration) .
|
|
98
|
+
|
|
99
|
+
```json
|
|
100
|
+
{
|
|
101
|
+
"clientID": "",
|
|
102
|
+
"serverOrigin": "https://api.asgardeo.io/t/<org_name>",
|
|
103
|
+
"signInRedirectURL": "https://localhost:5000",
|
|
104
|
+
"signOutRedirectURL": "https://localhost:5000"
|
|
105
|
+
}
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
3. Build and deploy the apps by running the following command at the root directory.
|
|
109
|
+
|
|
110
|
+
```bash
|
|
111
|
+
npm install && npm start
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
4. Navigate to [`https://localhost:5000`](https://localhost:5000) (or whichever the URL you have hosted the sample app).
|
|
115
|
+
|
|
116
|
+
#### Basic React Sample
|
|
117
|
+
|
|
118
|
+
- Download the Sample: [samples/asgardeo-react-app](https://github.com/asgardeo/asgardeo-auth-react-sdk/releases/latest/download/asgardeo-react-app.zip)
|
|
119
|
+
|
|
120
|
+
- Find More Info: [README](/samples/asgardeo-react-app/README.md)
|
|
121
|
+
|
|
122
|
+
- **Redirect URL(s):**
|
|
123
|
+
- `https://localhost:5000`
|
|
124
|
+
|
|
125
|
+
## Getting Started
|
|
126
|
+
|
|
127
|
+
### 1. Installing the Package
|
|
65
128
|
|
|
66
129
|
Install the library from the npm registry.
|
|
67
130
|
|
|
@@ -69,7 +132,7 @@ Install the library from the npm registry.
|
|
|
69
132
|
npm install --save @asgardeo/auth-react
|
|
70
133
|
```
|
|
71
134
|
|
|
72
|
-
|
|
135
|
+
### 2. Import `AuthProvider`, `useAuthContext` and Provide Configuration Parameters
|
|
73
136
|
|
|
74
137
|
```TypeScript
|
|
75
138
|
// The SDK provides a provider that can be used to carry out the authentication.
|
|
@@ -82,7 +145,7 @@ const config = {
|
|
|
82
145
|
signInRedirectURL: "https://localhost:5000/sign-in",
|
|
83
146
|
signOutRedirectURL: "https://localhost:5000/dashboard",
|
|
84
147
|
clientID: "client ID",
|
|
85
|
-
serverOrigin: "https://
|
|
148
|
+
serverOrigin: "https://api.asgardeo.io/t/<org_name>"
|
|
86
149
|
};
|
|
87
150
|
|
|
88
151
|
// Encapsulate your components with the `AuthProvider`.
|
|
@@ -111,45 +174,10 @@ const Dashboard = (): ReactElement => {
|
|
|
111
174
|
</div>
|
|
112
175
|
);
|
|
113
176
|
}
|
|
114
|
-
|
|
115
|
-
}
|
|
116
|
-
|
|
117
177
|
```
|
|
118
178
|
|
|
119
179
|
[Learn more](#apis).
|
|
120
180
|
|
|
121
|
-
## Try Out the Sample Apps
|
|
122
|
-
|
|
123
|
-
### 1. Create a Service Provider
|
|
124
|
-
|
|
125
|
-
Before trying out the sample apps, you need to a create a service provider in the Identity Server.
|
|
126
|
-
|
|
127
|
-
1. So, navigate to `https://localhost:9443/carbon` and click on `Add` under `Service Providers` in the left-hand menu panel.
|
|
128
|
-
|
|
129
|
-
2. Enter `Sample` as the name of the app and click on `Register`.
|
|
130
|
-
|
|
131
|
-
3. Then, expand the `Inbound Authentication Configuration` section. Under that, expand `OAuth/OpenID Connect Configuration` section and click on `Configure`.
|
|
132
|
-
|
|
133
|
-
4. Under `Allowed Grant Types` uncheck everything except `Code` and `Refresh Token`.
|
|
134
|
-
|
|
135
|
-
5. Enter the Callback URL(s). You can find the relevant callback URL(s) of each sample app in the [Running the sample apps](#2.-running-the-sample-apps) section.
|
|
136
|
-
|
|
137
|
-
6. Check `Allow authentication without the client secret`.
|
|
138
|
-
|
|
139
|
-
7. Click `Add` at the bottom.
|
|
140
|
-
|
|
141
|
-
8. Copy the `OAuth Client Key`.
|
|
142
|
-
|
|
143
|
-
9. Enable CORS for the client application by following this guide (https://is.docs.wso2.com/en/5.11.0/learn/cors/).
|
|
144
|
-
|
|
145
|
-
### 2. Running the sample apps
|
|
146
|
-
|
|
147
|
-
Build the apps by running the following command at the root directory.
|
|
148
|
-
|
|
149
|
-
```
|
|
150
|
-
npm run build
|
|
151
|
-
```
|
|
152
|
-
|
|
153
181
|
<!-- ## Browser Compatibility
|
|
154
182
|
|
|
155
183
|
The SDK supports all major browsers and provides polyfills to support incompatible browsers. If you want the SDK to run on Internet Explorer or any other old browser, you can use the polyfilled script instead of the default one.
|
|
@@ -328,7 +356,7 @@ This uses an iFrame to check if there is an active user session in the identity
|
|
|
328
356
|
|
|
329
357
|
To dispatch a token request, the `[signIn()](#signIn)` or this `trySignInSilently()` method should be called by the page/component rendered by the redirect URL.
|
|
330
358
|
|
|
331
|
-
This returns a promise that resolves with a `[BasicUserInfo](#BasicUserInfo)` object following a successful sign in. If the user is not signed into the
|
|
359
|
+
This returns a promise that resolves with a `[BasicUserInfo](#BasicUserInfo)` object following a successful sign in. If the user is not signed into the Asgardeo, then the promise resolves with the boolean value of `false`.
|
|
332
360
|
|
|
333
361
|
The `sign-in` hook is used to fire a callback function after signing in is successful. Check the [on()](#on) section for more information.
|
|
334
362
|
|
|
@@ -357,7 +385,7 @@ signOut();
|
|
|
357
385
|
|
|
358
386
|
#### Description
|
|
359
387
|
|
|
360
|
-
This method ends the user session at the
|
|
388
|
+
This method ends the user session at the identity server and logs the user out.
|
|
361
389
|
|
|
362
390
|
The `sign-out` hook is used to fire a callback function after signing out is successful. Check the [on()](#on) section for more information.
|
|
363
391
|
|
|
@@ -377,8 +405,13 @@ httpRequest(config: `HttpRequestConfig`): Promise<HttpResponse>;
|
|
|
377
405
|
|
|
378
406
|
#### Arguments
|
|
379
407
|
|
|
380
|
-
1. config: `HttpRequestConfig`
|
|
381
|
-
A config object with the settings necessary to send http requests. This object is similar to the `AxiosRequestConfig
|
|
408
|
+
1. config: `[HttpRequestConfig](#httpRequestConfig)`
|
|
409
|
+
A config object with the settings necessary to send http requests. This object is similar to the `AxiosRequestConfig` but provides these additional attributes:
|
|
410
|
+
|
|
411
|
+
|Attribute|Type|Default|Description|
|
|
412
|
+
|--|--|--|--|
|
|
413
|
+
|`attachToken`|`boolean`|`true`|If set to `true`, the token will be attached to the request header.|
|
|
414
|
+
|`shouldEncodeToFormData`|`boolean`|`false`|If set to `true`, the request body will be encoded to `FormData`. The body (specified by the `data` attribute) should be a Javascript object. |
|
|
382
415
|
|
|
383
416
|
#### Returns
|
|
384
417
|
|
|
@@ -386,7 +419,7 @@ A Promise that resolves with the response.
|
|
|
386
419
|
|
|
387
420
|
#### Description
|
|
388
421
|
|
|
389
|
-
This method is used to send http requests to the
|
|
422
|
+
This method is used to send http requests to the identity server. The developer doesn't need to manually attach the access token since this method does it automatically.
|
|
390
423
|
|
|
391
424
|
If the `storage` type is set to `sessionStorage` or `localStorage`, the developer may choose to implement their own ways of sending http requests by obtaining the access token from the relevant storage medium and attaching it to the header. However, if the `storage` is set to `webWorker`, this is the _ONLY_ way http requests can be sent.
|
|
392
425
|
|
|
@@ -405,7 +438,7 @@ const requestConfig = {
|
|
|
405
438
|
"Content-Type": "application/scim+json"
|
|
406
439
|
},
|
|
407
440
|
method: "GET",
|
|
408
|
-
url: "https://
|
|
441
|
+
url: "https://api.asgardeo.io/scim2/me"
|
|
409
442
|
};
|
|
410
443
|
|
|
411
444
|
return httpRequest(requestConfig)
|
|
@@ -471,7 +504,7 @@ A Promise that resolves either with the response or the [`BasicUserInfo`](#Basic
|
|
|
471
504
|
|
|
472
505
|
#### Description
|
|
473
506
|
|
|
474
|
-
This method allows developers to use custom grants provided by their Identity
|
|
507
|
+
This method allows developers to use custom grants provided by their Identity Providers. This method accepts an object that has the following attributes as the argument.
|
|
475
508
|
|
|
476
509
|
The `custom-grant` hook is used to fire a callback function after a custom grant request is successful. Check the [on()](#on) section for more information.
|
|
477
510
|
|
|
@@ -691,7 +724,7 @@ If you are using TypeScript, you may want to use the `Hooks` enum that consists
|
|
|
691
724
|
| `"end-user-session"` | `endUserSession()` | A boolean value indicating if the process was successful or not |
|
|
692
725
|
| `"custom-grant"` | `customGrant()` | Returns the response from the custom grant request. |
|
|
693
726
|
|
|
694
|
-
**When the user signs out, the user is taken to the identity server's logout page and then redirected back to the SPA on successful
|
|
727
|
+
**When the user signs out, the user is taken to the identity server's logout page and then redirected back to the SPA on successful logout. Hence, developers should ensure that the `"sign-out"` hook is called when the page the user is redirected to loads.**
|
|
695
728
|
|
|
696
729
|
#### Example
|
|
697
730
|
|
|
@@ -845,14 +878,15 @@ initialize(config);
|
|
|
845
878
|
|
|
846
879
|
### AuthStateInterface
|
|
847
880
|
|
|
848
|
-
| Attribute | Type | Description
|
|
849
|
-
| :---------------- | :-------- |
|
|
850
|
-
| `allowedScopes` | `string` | The scopes that are allowed for the user.
|
|
851
|
-
| `displayName` | `string` | The display name of the user.
|
|
852
|
-
| `email` | `string` | The email address of the user.
|
|
853
|
-
| `isAuthenticated` | `boolean` | Specifies if the user is authenticated or not.
|
|
854
|
-
| `isLoading` | `boolean` | Specifies if the authentication requests are loading.
|
|
855
|
-
| `username` | `string` | The username of the user.
|
|
881
|
+
| Attribute | Type | Description |
|
|
882
|
+
| :---------------- | :-------- | :------------------------------------------------------------------------ |
|
|
883
|
+
| `allowedScopes` | `string` | The scopes that are allowed for the user. |
|
|
884
|
+
| `displayName` | `string` | The display name of the user. |
|
|
885
|
+
| `email` | `string` | The email address of the user. |
|
|
886
|
+
| `isAuthenticated` | `boolean` | Specifies if the user is authenticated or not. |
|
|
887
|
+
| `isLoading` | `boolean` | Specifies if the authentication requests are loading. |
|
|
888
|
+
| `username` | `string` | The username of the user. |
|
|
889
|
+
| `sub` | `string` | The `uid` corresponding to the user to whom the ID token belongs to. |
|
|
856
890
|
|
|
857
891
|
### AuthReactConfig
|
|
858
892
|
|
|
@@ -867,7 +901,7 @@ initialize(config);
|
|
|
867
901
|
| `prompt` | Optional | `string` | "" | Specifies the prompt type of an OIDC request |
|
|
868
902
|
| `responseMode` | Optional | `ResponseMode` | `"query"` | Specifies the response mode. The value can either be `query` or `form_post` |
|
|
869
903
|
| `scope` | Optional | `string[]` | `["openid"]` | Specifies the requested scopes. |
|
|
870
|
-
| `serverOrigin` | Required | `string` | "" | The origin of the Identity Provider. eg: `https://www.asgardeo.io
|
|
904
|
+
| `serverOrigin` | Required | `string` | "" | The origin of the Identity Provider. eg: `https://www.asgardeo.io/t/<org_name>` |
|
|
871
905
|
| `endpoints` | Optional | `OIDCEndpoints` | [OIDC Endpoints Default Values](#oidc-endpoints) | The OIDC endpoint URLs. The SDK will try to obtain the endpoint URLS | using the `.well-known` endpoint. If this fails, the SDK will use these endpoint URLs. If this attribute is not set, then the default endpoint URLs will be | used. However, if the `overrideWellEndpointConfig` is set to `true`, then this will override the endpoints obtained from the `.well-known` endpoint. |
|
|
872
906
|
| `overrideWellEndpointConfig` | Optional | `boolean` | `false` | If this option is set to `true`, then the `endpoints` object will override endpoints obtained | from the `.well-known` endpoint. If this is set to `false`, then this will be used as a fallback if the request to the `.well-known` endpoint fails. |
|
|
873
907
|
| `wellKnownEndpoint` | Optional | `string` | `"/oauth2/token/.well-known/openid-configuration"` | The URL of the `.well-known` endpoint. |
|