Instructions for

Sign users in to your web app using the redirect model

Add authentication with Okta's redirect model (opens new window) to your server-side web app. This example uses Okta as the user store.

Learning outcomes

Create an integration that represents your app in your Okta org.
Add dependencies and configure your app to use Okta redirect authentication.
Test user sign in flow.

Sample code

Note: For single-page (browser) apps, see Sign users in to your SPA using the redirect model. For servers returning non-HTML API responses, see Protect your API endpoints.

Set up Okta

Set up your Okta org. The Okta command-line interface (CLI) is the quickest way to do this. If you don't want to install the CLI, you can manually sign up for an org (opens new window) instead.

Install Okta CLI (opens new window).
If you don't already have a free Okta developer account:
1. Open your terminal.
2. Run okta register, and enter your first name, last name, email address, and country.
3. Click or tap Activate in the account activation email that is sent to the email address that you gave.
  
  Tip: If you don't receive the confirmation email sent as part of the creation process, check your spam filters for an email from noreply@okta.com
4. Find your new domain and a link to set your password in the email:
```
Your Okta Domain: https://dev-xxxxxxx.okta.com
To set your password open this link:
https://dev-xxxxxxx.okta.com/welcome/xrqyNKPCZcvxL1ouKUoh
```
5. Set the password for your org by opening the link and following the instructions. Your Okta domain is returned, similar to the following:
```
New Okta Account created!
Your Okta Domain: https://dev-xxxxxxx.okta.com
```
6. Make a note of your Okta domain. Use it wherever ${yourOktaDomain} appears in this guide.
Run okta login to connect to your org if you didn't create one in the last step (successfully creating an Okta org also signs you in). You need the URL of your org, which is https:// followed by your Okta domain, and an API/access token.

Note: If you're using an existing org, verify that API Access Management is enabled: Open your Admin Console, go to Security > API, and verify that an Authorization Servers tab is present. If not, choose one of the following:

Create a developer account and org with Okta CLI.

Contact your support team to enable the feature in your org.

Use the Admin Console to create your app integrations instead of the CLI.

All accounts created with Okta CLI are developer accounts.

Create an Okta integration for your app

An application integration represents your app in your Okta org. The integration configures how your app integrates with the Okta services including: which users and groups have access, authentication policies, token refresh requirements, redirect URLs, and more. The integration includes configuration information required by the app to access Okta.

To create your app integration in Okta using the CLI:

Create the app integration by running:
```
okta apps create web
```
Tip: If Okta CLI returns the error "Your Okta Org is missing a feature required to use the Okta CLI: API Access Management," you're not using an Okta developer account. To resolve this, see Set up Okta.
Enter Quickstart when prompted for the app name.
Specify the required Redirect URI values:
- Redirect URI: http://localhost:3000/authorization-code/callback
- Post Logout Redirect URI: http://localhost:3000
The Okta CLI creates an .okta.env file with export statements containing the Client ID, Client Secret, and Issuer. Keep this safe as you use it later to configure your web app.

At this point, you can move to the next step: Creating your app. If you want to set up the integration manually, or find out what the CLI just did for you, read on.

Sign in to your Okta organization (opens new window) with your administrator account.
Click the Admin button on the top right of the page.
Open the Applications configuration pane by selecting Applications > Applications.
Click Create App Integration.
Select a Sign-in method of OIDC - OpenID Connect, then click Next.
Select an Application type of Web Application, then click Next.
Note: If you choose an inappropriate application type, it can break the sign-in or sign-out flows by requiring the verification of a client secret, which is something that public clients don't have.
Enter an App integration name.
Enter the Sign-in redirect URIs for local development, such as http://localhost:xxxx/authorization-code/callback.
Enter the Sign-out redirect URIs for both local development, such as http://localhost:xxxx/signout/callback. For more information on callback URIs, see Define callback route.
In the Assignments section, define the type of Controlled access for your app. Select the Everyone group for now. For more information, see the Assign app integrations (opens new window) topic in the Okta product documentation.
Click Save to create the app integration. The configuration pane for the integration opens after it's saved. Keep this pane open as you copy some values when configuring your app.

Create app

In this section you create a sample web app and add redirect authentication using your new app integration.

Create a new project

Make sure that you have a recent version of Node (opens new window) and npm (opens new window) installed.
Create an express application named okta-express-quickstart using the following command. This creates an express application that uses pug as the view engine.
```
npx express-generator --view=pug okta-express-quickstart
cd okta-express-quickstart
npm install
```

Note: This guide uses express v4.16.1, express-session v1.17.2, passport v0.5.2, and passport-openidconnect v0.1.1.

Note: If you're using the Okta CLI, you can also run okta start express to create an app. This command creates an OIDC app in Okta, downloads the okta-express-sample (opens new window), and configures it to work with the OIDC app. This quickstart uses the basic Express starter app instead, as it's easier to understand the Okta-specific additions if you work through them yourself.

Add packages

Add the required dependencies for using the Okta SDK with your web app.

Use express-session, passport, and passport-openidconnect in your Node Express application. Add the npm packages by running the following command:

npm install express-session@1.17 passport@0.5 passport-openidconnect@0.1

Configure your app

Our app uses information from the Okta integration that we created earlier to configure communication with the API: Client ID, Client Secret, and Issuer.

You can configure the properties of your application with configuration files, environment variables, or other framework-specific techniques.

In our quickstart, we do this via the passport-openidconnect package, which requires an instance of a Strategy object with configuration properties. You will set the issuer, authorizationURL, tokenURL, userInfoURL, clientID, and clientSecret properties inside that object using your own values.

The code changes to configure Okta are shown below.

Add the necessary require calls into your main app.js file, just below the existing require calls.

const session = require('express-session');
const passport = require('passport');
const { Strategy } = require('passport-openidconnect');

Add the OIDC passport setup just below the existing view engine setup lines (just below app.use(express.static(path.join(__dirname, 'public')));, for example):

app.use(session({
  secret: 'CanYouLookTheOtherWay',
  resave: false,
  saveUninitialized: true
}));

app.use(passport.initialize());
app.use(passport.session());

// set up passport
passport.use('oidc', new Strategy({
  issuer: 'https://${yourOktaDomain}/oauth2/default',
  authorizationURL: 'https://${yourOktaDomain}/oauth2/default/v1/authorize',
  tokenURL: 'https://${yourOktaDomain}/oauth2/default/v1/token',
  userInfoURL: 'https://${yourOktaDomain}/oauth2/default/v1/userinfo',
  clientID: '${yourClientID}',
  clientSecret: '${yourClientSecret}',
  callbackURL: 'http://localhost:3000/authorization-code/callback',
  scope: 'openid profile'
}, (issuer, profile, done) => {
  return done(null, profile);
}));

passport.serializeUser((user, next) => {
  next(null, user);
});

passport.deserializeUser((obj, next) => {
  next(null, obj);
});

Replace the placeholders in the above code with your domain, and with your values from the .okta.env file.

Note: If you use okta start express to create an app, it has an .okta.env file in it that looks a bit different. That's because it's configured to use dotenv (opens new window) to load its configuration from this file.

Find your config values

If you don't have your configuration values handy, you can find them in the Admin Console (choose Applications > Applications and find the application integration that you created earlier):

Client ID: Found on the General tab in the Client Credentials section.
Client Secret: Found on the General tab in the Client Credentials section.
Okta Domain: Found in the global header located in the upper-right corner of the dashboard. Click the down arrow next to your email address and in the dropdown box that appears, move your pointer over the domain name. Click the Copy to clipboard icon that appears to copy the domain.

Note: Your Okta domain is different from your admin domain. Your Okta domain doesn't include -admin, for example, https://dev-133337.okta.com.

To authenticate a user, your web app redirects the browser to the Okta-hosted sign-in page. This usually happens from a sign-in action such as clicking a button or when a user visits a protected page.

Add the sign-in and sign-out functionality to the app.js file, just below the app.use('/users', usersRouter); line:

app.use('/login', passport.authenticate('oidc'));

app.use('/authorization-code/callback',
  passport.authenticate('oidc', { failureRedirect: '/error' }),
  (req, res) => {
    res.redirect('/profile');
  }
);

app.post('/logout', (req, res) => {
  req.logout();
  req.session.destroy();
  res.redirect('/');
});

Update the existing router.get() call inside routes/index.js file to pass on the authenticated variable, like so:

router.get('/', function(req, res, next) {
  res.render('index', { authenticated: req.isAuthenticated() });
});

Add buttons to support sign-in and sign-out flows to the views/layout.pug file. Display either the sign-in or sign-out button based on the current authenticated state.

if authenticated
    form(method="post", action="/logout")
      button(type="submit") Logout
else
    form(method="get", action="/login")
      button(type="submit") Login

After successful authentication Okta redirects back to the app with an authorization code that's then exchanged for an ID and access token that you can use to confirm sign in status. Later we look at displaying some of the returned user information in the app.

Note: To customize the Okta sign-in form, see Style the Okta-hosted Sign-In Widget.

Define a callback route

Get info about the user

After the user signs in, Okta returns some of their profile information to your app, such as those shown in the /userinfo response example. One use of this information is updating your user interface, for example to display the customer's name.

The default profile items (called claims) returned by Okta include the user's email address, name, and preferred username. The claims that you see may differ depending on the scopes requested by your app. See Configure your app.

Add the following code to handle the /profile route in app.js, just below the previous code you added:
```
app.use('/profile', (req, res) => {
  res.render('profile', { user: req.user });
});
```

Add a new template file called views/profile.pug that contains the following code:

extends layout

block content
  h2= "My Profile"
  br
  div
    p Hello, #{user.displayName}.

Test your integration by starting your server and signing in a user.

Run the following command to start your app:

npm start

Open a browser and navigate to http://localhost:3000. You are redirected to Okta to sign in. When you return to the /profile page, it should display your user information.

Configure required authentication

Your app can require authentication for the entire site or just for specific routes. Routes that don't require authentication are accessible without signing in, which is also called anonymous access.

Require authentication for everything

Some apps require user authentication for all routes, for example a company intranet.

Note: See Add packages for the required dependencies that you need for using the Okta SDK with your web app.

Add middleware to app.js to protect all the routes in your app:

function ensureLoggedIn(req, res, next) {
  if (req.isAuthenticated()) {
    return next();
  }
  res.redirect('/login')
}

app.use(ensureLoggedIn());

Require authentication for a specific route

Your website may have a protected portion that is only available to authenticated users.

Add middleware to app.js that protects a specific route, then add it to the specific routes that you want to protect:

function ensureLoggedIn(req, res, next) {
  if (req.isAuthenticated()) {
    return next();
  }
  res.redirect('/login')
}

...

app.use('/profile', ensureLoggedIn, (req, res) => {
  res.render('profile', { user: req.user });
});

Allow anonymous access

Your website may enable anonymous access for some content but require a user to sign in for other content or to take some other action. For example, an ecommerce site might allow a user to browse anonymously and add items to a cart, but require a user to sign in for checkout and payment.

Next steps

Edit This Page On GitHub