npm package: @ist-group/web-skolid
Description: A library for SkolID interaction within a SPA.
Author: Henrik Cooke
Latest version: 11.2.3

# SKOLID-WEB-LIB

A library for SkolID interaction within a SPA.

## Installation

`yarn add @ist-group/web-skolid`

Copy the files in the public folder of this module to a routable path in your application. If the finals paths for these files aren't in the root of your application they need to be configured in the Session/Sign Providers/Managers.

## Development

`yarn start`

# Usage

## Authentication and session management

With Context

```tsx
import { SessionProvider, SessionContext } from "@ist-group/web-skolid";

const Root = () => (
  <SessionProvider
    environment={settings.skolid.environment}
    clientId={settings.skolid.clientId}
    scope={settings.skolid.scope}
    automaticSilentRenew
  >
    <div>
      My application
      <App />
    </div>
  </SessionProvider>
);

const App = () => {
  const session = React.useContext(SessionContext);

  if (session.loading) {
    return <progress />;
  }

  if (!session.user) {
    return (
      <div>
        Not logged in: <button onClick={() => session.login()}>Login</button>
      </div>
    );
  }

  return (
    <div>
      Logged in as {session.user.profile.name}:{" "}
      <button onClick={() => session.logout()}>Logout</button>
    </div>
  );
};

ReactDOM.render(<Root />, document.getElementById("root"));
```

## Silent renew

Silent renew is a way to fetch a new access_token before the old one expires. This feature is off by default but may be enabled if your application doesn't have high LOA demands.

## Signing

Signing is supported which can be used by:

```javascript
import { SignProvider } from "@ist-group/web-skolid";

const Root = () => {
  const session = React.useContext(SessionContext);

  return (
    <SignProvider environment={settings.skolid.environment} user={session.user}>
      {(signManager) => <button onClick={() => signManager.sign("text", "data")}>Sign</button>}
    </SignProvider>
  );
};
```

## Impersonation

Exchanges an access token for one subject to an access token for another subject. LOA, authentication time and token lifetime is transferred from the actor token.

```typescript
const { accessToken, error, loading } = useImpersonationAccessToken({
  accessToken: actorSession.accessToken,
  subjectId: selectedIdentity?.id,
  skip: !useImpersonation,
  clientId: settings.clientId,
  environment: settings.skolidEnvironment
});
```

Remarks:

- The client needs have the grant type `impersonation` enabled.
- If no subject id is provided no access token is returned.
- To allow "silent refresh" the output (access token and loading) is unchanged even when the input access token argument is changed as long as the subject id remains the same.

# IdP configuration

The default paths this library uses:

- Redirect: /#/signin-callback#
- Logout: /#/signout
- Post logout: /#/logout-callback#
- Silent renew and session monitoring: /silent-callback.html

## Hosted in a subfolder

If the SPA is hosted in a subfolder in a domain. Use the `basePath` prop to customize the callbacks.

For example:

```tsx
import { SessionProvider } from "@ist-group/web-skolid";

const Root = () => (
  <SessionProvider
    environment={settings.skolid.environment}
    clientId={settings.skolid.clientId}
    scope={settings.skolid.scope}
    basePath="/path"
    >
    {({ user, loading, login, logout, manager }) => { ... }
  </SessionProvider>
);
```