Okta React SDK
Okta React SDK makes it easy to integrate react-router with Okta's OpenID Connect API.
This library currently supports:
Prerequisites
- If you do not already have a Developer Edition Account, you can create one at https://developer.okta.com/signup/.
- If you don't have a React app, or are new to React, please continue with the React Quickstart guide. It will walk you through the creation of a React app, creating routes, and other application development essentials.
Add an OpenID Connect Client in Okta
In Okta, applications are OpenID Connect clients that can use Okta Authorization servers to authenticate users. Your Okta Org already has a default authorization server, so you just need to create an OIDC client that will use it.
- Log into the Okta Developer Dashboard, click Applications then Add Application.
- Choose Single Page App (SPA) as the platform, then submit the form the default values, which should look like this:
Setting | Value |
---|---|
App Name | My SPA App |
Base URIs | http://localhost:{port} |
Login redirect URIs | http://localhost:{port}/implicit/callback |
Grant Types Allowed | Implicit |
After you have created the application there are two more values you will need to gather:
Setting | Where to Find |
---|---|
Client ID | In the applications list, or on the "General" tab of a specific application. |
Org URL | On the home screen of the developer dashboard, in the upper right. |
These values will be used in your React application to setup the OpenID Connect flow with Okta.
Installation
This library is available through npm. To install it, simply add it to your project:
npm install --save @okta/okta-react
Usage
okta-react
works directly with react-router
and provides four additional components:
- Security - (required) Allows you to supply your OpenID Connect client configuration.
- SecureRoute - (required) A normal
Route
except authentication is needed to render the component. - ImplicitCallback - (required) Handles the implicit flow callback. This will parse the tokens and store them automatically.
Create Routes
Here are the minimum requirements for a working example:
- / - Anyone can access the home page
- /protected - Protected is only visible to authenticated users
- /implicit/callback - This is where auth is handled for you after redirection
// src/App.js ;;;;; ;
Show Login and Logout Buttons
In the relevant location in your application, you will want to provide Login
and Logout
buttons for the user. You can show/hide the correct button by using the auth.isAuthenticated()
method. For example:
// src/Home.js ;; ;
Use the Access Token
When your users are authenticated, your React application has an access token that was issued by your Okta Authorization server. You can use this token to authenticate requests for resources on your server or API. As a hypothetical example, let's say you have an API that provides messages for a user. You could create a MessageList
component that gets the access token and uses it to make an authenticated request to your server.
Here is what the React component could look like for this hypothetical example:
;;; ;
Reference
Security
Security is the top-most component of okta-react. This is where most of the configuration is provided.
Configuration options
-
issuer (required) - The OpenId Connect
issuer
-
client_id (required) - The OpenId Connect
client_id
-
redirect_uri (required) - Where the callback handler is hosted
-
scope (optional): Reserved or custom claims to be returned in the tokens
-
response_type (optional): Desired token grant types
-
onAuthRequired (optional)
-
auth (optional) - Provide an Auth object instead of the options above. This is helpful when integrating
okta-react
with external libraries that need access to the tokens.Accepts a callback to make a decision when authentication is required. If this is not supplied,
okta-react
redirects to Okta. This callback will receiveauth
andhistory
parameters. This is triggered when:auth.login
is called- SecureRoute is accessed without authentication
Example
Example with Auth object
// src/App.js ;;;;; ; ; ;
SecureRoute
SecureRoute
ensures that a route is only rendered if the user is authenticated. If the user is not authenticated, it calls onAuthRequired
if it exists, otherwise, it redirects to Okta.
ImplicitCallback
ImplicitCallback
handles the callback after the redirect. By default, it parses the tokens from the uri, stores them, then redirects to /
. If a SecureRoute
caused the redirect, then the callback redirects to the secured route.
withAuth
withAuth
provides a way for components to make decisions based on auth state. It injects an auth
prop into the component.
auth
auth
provides methods that allow managing tokens and auth state. All of the methods return Promises.
auth.isAuthenticated()
Returns true
or false
, depending on whether the user has an active access or id token.
auth.getUser()
Returns the result of the OpenID Connect /userinfo
endpoint if an access token exists.
auth.getIdToken()
Retrieves the id token from storage if it exists.
auth.getAccessToken()
Retrieves the access token from storage if it exists.
auth.login(fromUri, additionalParams)
Calls onAuthRequired
or redirects to Okta if onAuthRequired
is undefined. This method accepts a fromUri
parameter to push the user to after successful authentication, and an optional additionalParams
object.
For more information on additionalParams
, see the auth.redirect
method below.
auth.logout(uri)
Terminates the user's session in Okta and clears all stored tokens. Accepts an optional uri
parameter to push the user to after logout.
auth.redirect(additionalParams)
Performs a full-page redirect to Okta with optional request parameters.
The additionalParams
are mapped to Okta's /authorize
request parameters. This will override any existing configuration. As an example, if you have an Okta sessionToken
, you can bypass the full-page redirect by passing in this token. This is recommended when using the Okta Sign-In Widget. Simply pass in a sessionToken
into the redirect
method as follows:
auth.redirect;
Note: For information on obtaining a
sessionToken
using the Okta Sign-In Widget, please see therenderEl()
example.
auth.handleAuthentication()
Parses tokens from the url and stores them.
Development
- Clone the repo:
git clone git@github.com:okta/okta-oidc-js.git
- Install the dependencies with lerna (install with
npm i lerna -g
):lerna bootstrap
- Navigate into the
okta-react
package:cd packages/okta-react
- Make your changes to
okta-react/src/
- Set the following environment variables:
ISSUER
- your authorization serverCLIENT_ID
- the client id of your appUSERNAME
- username of org user, needed if you want to run testsPASSWORD
- password of org user, needed if you want to run tests
- Start a sample server:
npm start
Commands
Command | Description |
---|---|
npm start |
Start the sample app using the SDK |
npm test |
Run integration tests |
npm run lint |
Run eslint linting tests |