Skip to content

Commit 0b8dcef

Browse files
liliankasemzmmille2
liliankasem
authored and
zmmille2
committed
Updating README's
1 parent daa9dec commit 0b8dcef

File tree

2 files changed

+147
-67
lines changed

2 files changed

+147
-67
lines changed

‎README.md

Lines changed: 55 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -2,18 +2,52 @@
22

33
![build status](https://reactaad.visualstudio.com/_apis/public/build/definitions/1c71aebc-1683-48cd-9ab2-8663e6a4ec55/5/badge)
44

5-
## Overview
65
React AAD MSAL is a library to easily integrate the Microsoft Authentication Library with Azure Active Directory in your React app quickly and reliably. The library focuses on flexibility, allowing you to define how you want to interact with logins and logouts.
76

8-
## Sample Application
9-
A sample React-based Single Page Application (SPA) that uses this component is available in the [sample folder](sample/README.md).
7+
## Features
8+
9+
React AAD MSAL is a library that allows you to easily integrate auth using Azure Active Directory into your React application. The library focuses on flexibility, allowing you to define how you want to interact with logins and logouts.
10+
11+
The React AAD MSAL library provides the following features:
12+
13+
* Login using Azure Active Directory
14+
- create your own function that handles how login (using this AzureAD component) is trigger in your react app
15+
- create your own function that handles the login success. The AzureAD library will call this function when login is complete to pass back the user info.
16+
* Logout callback
17+
- create your own function to handle how logout (using this AzureAD component) is trigger in your react app
18+
* Optional use of redux store containing the token and user information returned from Active Directory
19+
20+
## Getting Started //TODO
21+
22+
### Prerequisites
23+
24+
(ideally very short, if any)
25+
26+
- OS
27+
- Library version
28+
- ...
29+
30+
### Installation
31+
32+
(ideally very short)
33+
34+
- npm install [package name]
35+
- mvn install
36+
- ...
37+
38+
### Quickstart
39+
(Add steps to get up and running quickly)
40+
41+
1. git clone [repository clone url]
42+
2. cd [respository name]
43+
3. ...
1044

1145
## Setup
1246
In the render module of your component, make sure to create an AzureAD component with the arguments you need. This uses the functions that you will define. Once the user is successfully authenticated, the component will render the JSX returned by the `authenticatedFunction`, which in this case is called `logoutCallback`. This is where you should put the secure, user-specific parts of your app. `loginCallback` and `printUserInfo` can be any user defined functions.
1347

1448
Find the assignment for ClientID and replace the value with the Application ID for your application from the azure portal. The authority is the sign-in/signup policy for your application. Graph scopes is a list of scope URLs that you want to grant access to. You can find more information on the [active directory MSAL single page app azure sample](https://github.com/Azure-Samples/active-directory-b2c-javascript-msal-singlepageapp).
1549

16-
```javascript
50+
``` jsx
1751
// ...
1852

1953
return (
@@ -66,7 +100,7 @@ Find the assignment for ClientID and replace the value with the Application ID f
66100
## Login
67101
To login, first create a callback function for the AzureAD component to consume. This function will be called when the component loads, and it will pass in the function to be called when the user wants to login. In this case, we create a button that will log the user in.
68102
69-
```javascript
103+
``` javascript
70104
import AzureAD from 'AzureAD'
71105
72106
loginCallback = (login) => {
@@ -78,14 +112,10 @@ loginCallback = (login) => {
78112
79113
Once they're logged in, the AzureAD library will call another function given with an `IUserInfo` instance. You can do whatever you want with this, but you should store it. In this example, we just print it out to console.
80114

81-
```javascript
82-
// ...
83-
115+
``` javascript
84116
printUserInfo = (userInfo) => {
85117
console.log(userInfo)
86118
};
87-
88-
// ...
89119
```
90120
91121
Once you've set this up, you should be able to set up a button to login that will hit an AAD instance. To set up your instance, check out the documentation on [Azure Active Directory](https://docs.microsoft.com/en-us/azure/active-directory/get-started-azure-ad) and on how to connect an [Identity Provider](https://docs.microsoft.com/en-us/azure/active-directory-b2c/active-directory-b2c-setup-msa-app) for that AAD instance.
@@ -94,7 +124,7 @@ Once you've set this up, you should be able to set up a button to login that wil
94124
95125
Logging out is just as easy.
96126
97-
```javascript
127+
``` jsx
98128
logoutCallback = (logout) => {
99129
return (
100130
<div>
@@ -107,17 +137,13 @@ logoutCallback = (logout) => {
107137
108138
You can, of course, include a component in either of these functions. This allows you to gate which view of your application users get, based on whether or not they are authenticated.
109139
110-
## Samples
111-
112-
If you want to run examples of this library out of the box, feel free to go to [the samples repo](https://reactaad.visualstudio.com/react-aad-msal/). There you'll find a couple implementations that leverage the library, as well as a tutorial of how to set up Azure Active Directory with an Identity Provider.
113-
114140
## Integrating with a Redux Store
115141
116142
The Azure AD component optionally accepts a ```reduxStore``` prop. On successful login, Azure AD will dispatch an action of type ```AAD_LOGIN_SUCCESS``` to the provided store, containing the token and user information returned from Active Directory. It does the same for logout events, but the action will not contain a payload.
117143
118144
Import your store into the file rendering the AzureAD component and pass it in:
119145
120-
```javascript
146+
``` jsx
121147
<AzureAD
122148
reduxStore={store}
123149
clientID={'<Application ID for your application>'}
@@ -132,7 +158,7 @@ Import your store into the file rendering the AzureAD component and pass it in:
132158
133159
Add a case to handle ```AAD_LOGIN_SUCCESS``` and ```AAD_LOGOUT_SUCCESS``` actions in a reducer file:
134160
135-
```javascript
161+
``` javascript
136162
const initialState = {
137163
aadResponse: null,
138164
};
@@ -147,4 +173,15 @@ const sampleReducer = (state = initialState, action) => {
147173
return state;
148174
}
149175
};
150-
```
176+
```
177+
178+
## Demo
179+
180+
A sample React-based Single Page Application (SPA) that uses this component is available in the [sample folder](sample/README.md). There you'll find a couple implementations that leverage the library, as well as a tutorial of how to set up Azure Active Directory with an Identity Provider.
181+
182+
## Resources //TODO
183+
184+
- [Azure Active Directory](https://docs.microsoft.com/en-us/azure/active-directory/get-started-azure-ad)
185+
- [MSAL Documentation](https://htmlpreview.github.io/?https://raw.githubusercontent.com/AzureAD/microsoft-authentication-library-for-js/dev/docs/index.html)
186+
- [AAD v2 Scopes](https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-v2-scopes)
187+
- [AAD B22 Setup MSA App](https://docs.microsoft.com/en-us/azure/active-directory-b2c/active-directory-b2c-setup-msa-app)

‎sample/README.md

Lines changed: 92 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -1,30 +1,8 @@
1-
# react-aad-msal Sample App
1+
# React AAD MSAL Sample App
22

33
This repository contains a sample react application that demonstrates how to use the [`react-aad-msal`](https://www.npmjs.com/package/react-aad-msal) node module, an Azure Activity Directory react component.
44

5-
## Features
6-
7-
React AAD MSAL is a library that allows you to easily integrate auth using Azure Active Directory into your React application. The library focuses on flexibility, allowing you to define how you want to interact with logins and logouts.
8-
9-
The React AAD MSAL library provides the following features:
10-
11-
* Login using Azure Active Directory
12-
- create your own function that handles how login (using this AzureAD component) is trigger in your react app
13-
- create your own function that handles the login success. The AzureAD library will call this function when login is complete to pass back the user info.
14-
* Logout callback
15-
- create your own function to handle how logout (using this AzureAD component) is trigger in your react app
16-
* Optional use of redux store containing the token and user information returned from Active Directory
17-
185
## Getting Started
19-
- Build the `react-aad-msal` component: `npm install && npm run build`
20-
- create a `.env.local` file, with the following variables:
21-
```
22-
REACT_APP_AAD_APP_CLIENT_ID=<client id guid>
23-
REACT_APP_AUTHORITY=<authority url (optional)>
24-
```
25-
- Run the sample application: `npm install && npm run start`
26-
27-
The sample site should launch in a Web browser.
286

297
### Prerequisites
308

@@ -40,7 +18,6 @@ Documentation for AAD B2C Application:
4018

4119
https://docs.microsoft.com/en-us/azure/active-directory-b2c/active-directory-b2c-app-registration
4220

43-
<<<<<<< HEAD
4421
## Getting Started
4522

4623
*NOTE: in order to successfully build and run this sample, be sure to complete the prerequisite steps above.
@@ -56,51 +33,56 @@ An Azure Active Directory application must first be setup and configured.*
5633

5734
The sample site should launch in a Web browser.
5835

59-
=======
60-
>>>>>>> Added sample app
6136
### Quickstart
6237

63-
1. `git clone [repository clone url]`
38+
1. `git clone https://github.com/Azure-Samples/react-aad-msal.git`
6439
2. `cd react-aad-msal`
65-
3. `npm install`
66-
4. Setup a `.env` file with the following items:
67-
- `REACT_APP_AAD_APP_CLIENT_ID`
68-
- `REACT_APP_AUTHORITY`
69-
5. `npm start`
40+
3. Build the `react-aad-msal` component:
41+
- `npm install && npm run build`
42+
4. Create a `.env.local` file, with the following variables:
43+
```
44+
REACT_APP_AAD_APP_CLIENT_ID=<client id guid>
45+
REACT_APP_AUTHORITY=<authority url (optional)>
46+
```
47+
5. Run the sample application `npm install && npm run start`
48+
49+
The sample site should launch in a Web browser.
7050
71-
## Demo
51+
## Sample Application Details
7252
73-
This sample demonstrates how to use the `Popup` auth method. As well as how to use the (optional) redux store.
53+
This sample demonstrates how to use the `Popup` and `Redirect` auth methods. As well as how to use the (optional) redux store.
7454
7555
To run this sample, you just need to provide your `REACT_APP_AAD_APP_CLIENT_ID` and (optionally) `REACT_APP_AUTHORITY`.
7656
77-
``` javascript
57+
``` jsx
7858
<AzureAD
7959
clientID={process.env.REACT_APP_AAD_APP_CLIENT_ID}
8060
authority={process.env.REACT_APP_AUTHORITY}
81-
...
61+
// ...
8262
>
8363
```
8464

65+
### SampleAppButtonLaunch.js - Popup Sample
66+
8567
Type is set to `LoginType.Popup`.
8668

87-
``` javascript
69+
``` jsx
8870
<AzureAD
89-
...
71+
// ...
9072
type={LoginType.Popup}
91-
...
73+
// ...
9274
>
9375
```
9476

9577
And we also provide a reduxStore (setup in our `reduxStore.js` file).
9678

97-
``` javascript
79+
``` jsx
9880
import { basicReduxStore } from './reduxStore';
9981

10082
<AzureAD
101-
...
83+
// ...
10284
reduxStore={basicReduxStore}
103-
...
85+
// ...
10486
>
10587
```
10688

@@ -116,15 +98,76 @@ For our `unauthenticatedFunction` property, we setup a function that returns a b
11698

11799
``` javascript
118100
unauthenticatedFunction = loginFunction => {
119-
return (
120-
<button style={buttonStyle} onClick={loginFunction}>Login</button>
121-
);
101+
return (
102+
<button className="Button" onClick={loginFunction}>Login</button>
103+
);
104+
}
105+
```
106+
107+
For our `authenticatedFunction` property, we setup a function that returns a button that uses the logout function provided by our AzureAD component.
108+
109+
``` javascript
110+
authenticatedFunction = (logout) => {
111+
return (<div>
112+
You're logged in!
113+
<br />
114+
<br />
115+
<button onClick={logout} className="Button">Logout</button>
116+
<br />
117+
</div>) ;
118+
}
119+
```
120+
121+
### SampleAppRedirectOnLaunch.js - Redirect Sample
122+
123+
Type is set to `LoginType.Redirect`.
124+
125+
``` jsx
126+
<AzureAD
127+
// ...
128+
type={LoginType.Redirect}
129+
// ...
130+
>
131+
```
132+
133+
For our `userInfoCallback` property, we setup a function that just saved the userInfo we get back to state.
134+
135+
``` javascript
136+
userJustLoggedIn = receivedUserInfo => {
137+
this.setState({ userInfo: receivedUserInfo })
122138
}
123139
```
124140
125-
//TODO: Logout documentation
141+
For our `unauthenticatedFunction` property, we setup a function that returns a a div that lets the user know we are going to redirect them, and uses the login function provided by our AzureAD component to complete the login in a new window.
126142
127-
## Resources
143+
``` javascript
144+
unauthenticatedFunction = loginFunction => {
145+
if (this.state.redirectEnabled && !this.interval) {
146+
this.interval = setInterval(() => {
147+
if (this.state.counter > 0) {
148+
this.setState({ counter: this.state.counter - 1 });
149+
} else {
150+
this.clearRedirectInterval();
151+
this.setState({ redirectEnabled: false });
152+
loginFunction();
153+
}
154+
}, 1000);
155+
}
156+
157+
if (this.state.redirectEnabled) {
158+
return (<div>Redirecting in {this.state.counter} seconds...</div>);
159+
}
160+
161+
return (<div />);
162+
};
163+
```
164+
165+
For our `authenticatedFunction` property, we setup a function that returns a button that uses the logout function provided by our AzureAD component.
128166
129-
- Link to react-aad-msal library github
130-
- Link to react-aad-msal npm page
167+
``` javascript
168+
authenticatedFunction = logout => {
169+
return (<div><button onClick={() => {
170+
logout();
171+
}} className="Button">Logout</button></div>);
172+
}
173+
```

0 commit comments

Comments
 (0)