# authc-spa-js
## Installation
From the CDN:
```html
```
Using [npm](https://npmjs.org):
```sh
npm install authc-spa-js
```
## Getting Started
### Authc Configuration
Create a **Single Page Application** in the [Authc Dashboard](https://manage.authc.io/#/applications).
> **If you're using an existing application**, verify that you have configured the following settings in your Single Page Application:
>
> - Click on the "Settings" tab of your application's page.
> - Ensure that "Token Endpoint Authentication Method" under "Application Properties" is set to "None"
> - Scroll down and click on the "Show Advanced Settings" link.
> - Under "Advanced Settings", click on the "OAuth" tab.
> - Ensure that "JsonWebToken Signature Algorithm" is set to `RS256` and that "OIDC Conformant" is enabled.
Next, configure the following URLs for your application under the "Application URIs" section of the "Settings" page:
- **Allowed Callback URLs**: `http://localhost:3000`
- **Allowed Logout URLs**: `http://localhost:3000`
- **Allowed Web Origins**: `http://localhost:3000`
> These URLs should reflect the origins that your application is running on. **Allowed Callback URLs** may also include a path, depending on where you're handling the callback (see below).
Take note of the **Client ID** and **Domain** values under the "Basic Information" section. You'll need these values in the next step.
### Creating the client
Create an `AuthcClient` instance before rendering or initializing your application. You should only have one instance of the client.
```js
import createAuthcClient from 'authc-spa-js'
// or, you can just instantiate the client on it's own
import { AuthcClient } from 'authc-spa-js'
// with async/await
const authc = await createAuthcClient({
domain: '',
client_id: '',
redirect_uri: ''
})
// with promises
createAuthcClient({
domain: '',
client_id: '',
redirect_uri: ''
}).then((authc) => {
// ...
})
const authc = new AuthcClient({
domain: '',
client_id: '',
redirect_uri: ''
})
// if you do this, you'll need to check the session yourself
try {
await authc.getTokenSilently()
}
catch (error) {
if (error.error !== 'login_required')
throw error
}
```
### 1 - Login
```html
```
```js
// with async/await
// redirect to the Universal Login Page
document.getElementById('login').addEventListener('click', async () => {
await authc.loginWithRedirect()
})
// in your callback route ()
window.addEventListener('load', async () => {
const redirectResult = await authc.handleRedirectCallback()
// logged in. you can get the user profile like this:
const user = await authc.getUser()
console.log(user)
})
// with promises
// redirect to the Universal Login Page
document.getElementById('login').addEventListener('click', () => {
authc.loginWithRedirect().catch(() => {
// error while redirecting the user
})
})
// in your callback route ()
window.addEventListener('load', () => {
authc.handleRedirectCallback().then((redirectResult) => {
// logged in. you can get the user profile like this:
authc.getUser().then((user) => {
console.log(user)
})
})
})
```
### 2 - Calling an API
```html
```
```js
// with async/await
document.getElementById('call-api').addEventListener('click', async () => {
const accessToken = await authc.getTokenSilently()
const result = await fetch('https://myapi.com', {
method: 'GET',
headers: {
Authorization: `Bearer ${accessToken}`
}
})
const data = await result.json()
console.log(data)
})
// with promises
document.getElementById('call-api').addEventListener('click', () => {
authc
.getTokenSilently()
.then(accessToken =>
fetch('https://myapi.com', {
method: 'GET',
headers: {
Authorization: `Bearer ${accessToken}`
}
})
)
.then(result => result.json())
.then((data) => {
console.log(data)
})
})
```
### 3 - Logout
```html
```
```js
import createAuthcClient from 'authc-spa-js'
document.getElementById('logout').addEventListener('click', () => {
authc.logout()
})
```
You can redirect users back to your app after logging out. This URL must appear in the **Allowed Logout URLs** setting for the app in your [Authc Dashboard](https://manage.authc.io):
```js
authc.logout({
returnTo: 'https://your.custom.url.example.com/'
})
```
### Data caching options
The SDK can be configured to cache ID tokens and access tokens either in memory or in local storage. The default is in memory. This setting can be controlled using the `cacheLocation` option when creating the Authc client.
To use the in-memory mode, no additional options need are required as this is the default setting. To configure the SDK to cache data using local storage, set `cacheLocation` as follows:
```js
await createAuthcClient({
domain: '',
client_id: '',
redirect_uri: '',
cacheLocation: 'localstorage' // valid values are: 'memory' or 'localstorage'
})
```
**Important:** This feature will allow the caching of data **such as ID and access tokens** to be stored in local storage. Exercising this option changes the security characteristics of your application and **should not be used lightly**. Extra care should be taken to mitigate against XSS attacks and minimize the risk of tokens being stolen from local storage.
#### Creating a custom cache
The SDK can be configured to use a custom cache store that is implemented by your application. This is useful if you are using this SDK in an environment where more secure token storage is available, such as potentially a hybrid mobile app.
To do this, provide an object to the `cache` property of the SDK configuration.
The object should implement the following functions. Note that all of these functions can optionally return a Promise or a static value.
| Signature | Return type | Description |
| -------------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `get(key)` | Promise