Skip to content

Latest commit

 

History

History
129 lines (91 loc) · 6.91 KB

README.md

File metadata and controls

129 lines (91 loc) · 6.91 KB
Raw

React OIDC

Wrapper for oidc-client-js, to be used in React apps.

Quick start

You should read the slow start and Routing Considerations too

yarn add react-oidc

You will need the config for the UserManager class.

Example using react-router

import { makeAuthenticator, makeUserManager, Callback } from 'react-oidc'

// supply this yourself
import App from '../layouts/App'
import userManagerConfig from '../config'

const userManager = makeUserManager(userManagerConfig)
const AppWithAuth = makeAuthenticator({
  userManager: userManager,
  signinArgs: {
    state: {
      foo: 15
    }
  }
})(App)

export default () => (
  <Router>
    <Switch>
      <Route
        path="/callback"
        render={routeProps => (
          <Callback
            onSuccess={user => {
              // `user.state` will reflect the state that was passed in via signinArgs.
              routeProps.history.push('/')
            }}
            userManager={userManager}
          />
        )}
      />
      <AppWithAuth />
    </Switch>
  </Router>
)

Slow start

There are 3 main parts to this library:

  • makeUserManager function;
  • makeAuthenticator function;
  • Callback component

makeUserManager(config)

Param Type Required Default Value Description
config object (UserManagerSettings) Yes undefined Config object to pass to UserManager

Helper utility to create a UserManager instance.

makeAuthenticator(params)(<ProtectedApp />)

Param Type Required Default Value Description
userManager UserManager Yes undefined UserManager instance (the result of makeUserManager())
placeholderComponent Component No null Optional component to render while auth state is being retrieved

This is a higher-order function that accepts a UserManager instance, and optionally a placeholder component to render when user auth state is being retrieved. It returns a function that accepts a React component. This component should contain all components that you want to be protected by your authentication. Ultimately you will get back a component that either renders the component you passed it (if the user is authenticated), or redirects to the OIDC login screen as defined by the Identity Provider.

The lifecycle of this component is as follows:

  1. The component is constructed with a fetching flag set to true.

  2. On mount, the .getUser() method from UserManager is called. If the user is already authenticated, it will set the fetching flag to false and render the component you passed it.

  3. If the user is not authenticated or their token has expired, the user will be redirected to the login URL (defined by the Identity Provider) and the fetching flag will be set to false.

  4. Upon successful authentication with the Identity Provider, the user will be redirected to the redirect_uri. You should render the Callback component at this location.

Note on the fetching flag

The fetching flag is set to true initially because of the asynchronous nature of .getUser(). There is a need to ensure that we do not redirect to the login page whilst getUser is resolving. Without some way of knowing when the user auth state query is complete, we would end up always redirecting to the login page.

<Callback />

Prop Type Required Default Value Description
userManager UserManager Yes undefined UserManager instance (the result of makeUserManager())
children Component No null Optional component to render at the redirect page
onError function No undefined Optional callback if there is an error from the Promise returned by .signinRedirectCallback()
onSuccess function No undefined Optional callback when the Promise from .signinRedirectCallback() resolves

The Callback component will call the .signinRedirectCallback() method from UserManager and if successful, call the onSuccess prop. On error it will call the onError prop. You should pass the same instance of UserManager that you passed to makeAuthenticator.

<UserData />

This component exposes the data of the authenticated user. If you are familiar with React's Context API (the official v16.3.x one), this component is just a Context.

<UserData.Consumer>
  {context => <p>{context.user.id_token}</p>}
</UserData.Consumer>

Render prop function

Argument (key of context) Type Description
signOut function Call this to sign the current user out
user User This is the User object from oidc-client
userManager UserManager UserManager instance from oidc-client

Routing considerations

This library is deliberately unopinionated about routing, however there are restrictions from the oidc-client library that should be considered.

  1. There will be url redirects. It is highly recommended to use a routing library like react-router to help deal with this.

  2. The redirect_uri should match eagerly. You should not render the result of makeAuthenticator()() at the location of the redirect_uri. If you do, you will end up in a redirect loop that ultimately leads you back to the authentication page. In the quick start above, a Switch from react-router is used, and the Callback component is placed before AppWithAuth. This ensures that when the user is redirected to the redirect_uri, AppWithAuth is not rendered. Once the user data has been loaded into storage, onSuccess is called and the user is redirected back to a protected route. When AppWithAuth loads now, the valid user session is in storage and the protected routes are rendered.